# API OpenMagic Database Outline

## 1. 数据库总结构

采用双库：

- `oneapi_core`
- `api_openmagic_biz`

原则：

- One API 原生表不混入业务自定义字段
- 自定义业务全部沉淀到 `api_openmagic_biz`

---

## 2. `oneapi_core`

职责：

- 用户令牌
- 渠道/上游
- 模型
- 分组
- 请求日志
- 用量
- 额度

处理策略：

- 尽量少改 One API 原生表
- 通过业务库补充产品逻辑

---

## 3. `api_openmagic_biz` 初版业务表

### 3.1 用户扩展

#### `om_user_profile`

用途：

- 存放用户附加资料

建议字段：

- `id`
- `oneapi_user_id`
- `email`
- `mobile`
- `display_name`
- `user_type`
- `status`
- `source_channel`
- `created_at`
- `updated_at`

### 3.2 套餐

#### `om_plan`

用途：

- 套餐定义

建议字段：

- `id`
- `code`
- `name`
- `plan_type`
- `billing_cycle`
- `price`
- `currency`
- `quota_amount`
- `daily_limit`
- `rpm_limit`
- `status`
- `created_at`

### 3.3 订阅

#### `om_subscription`

用途：

- 用户月度套餐关系

建议字段：

- `id`
- `user_id`
- `plan_id`
- `status`
- `start_at`
- `end_at`
- `renewal_mode`
- `quota_total`
- `quota_used`
- `created_at`
- `updated_at`

### 3.4 订单

#### `om_order`

用途：

- 统一订单主表

建议字段：

- `id`
- `order_no`
- `user_id`
- `plan_id`
- `order_type`
- `amount`
- `currency`
- `status`
- `pay_channel`
- `created_at`
- `paid_at`

### 3.5 支付记录

#### `om_payment`

用途：

- 记录支付回调和网关流水

建议字段：

- `id`
- `order_id`
- `channel`
- `transaction_id`
- `amount`
- `status`
- `payload`
- `created_at`
- `updated_at`

### 3.6 余额与发放

#### `om_balance_ledger`

用途：

- 用户余额/额度流水

建议字段：

- `id`
- `user_id`
- `change_type`
- `amount`
- `balance_after`
- `ref_type`
- `ref_id`
- `remark`
- `created_at`

### 3.7 邀请

#### `om_referral_code`

用途：

- 用户邀请链接

建议字段：

- `id`
- `user_id`
- `code`
- `status`
- `created_at`

#### `om_referral_event`

用途：

- 访问、注册、首单、奖励归因

建议字段：

- `id`
- `referral_code_id`
- `event_type`
- `target_user_id`
- `order_id`
- `reward_amount`
- `metadata`
- `created_at`

### 3.8 活动与渠道

### 3.9 上游认证档案

#### `om_upstream_auth_profile`

用途：

- 存放上游模型供应商的认证方式配置
- 作为 One API 原生渠道表之外的业务层扩展
- 支持以后接入 OAuth / refresh token / custom header 等非静态 API key 模式

建议字段：

- `id`
- `name`
- `provider`
- `auth_type`
- `base_url`
- `model_scope`
- `status`
- `credential_json`
- `token_expires_at`
- `last_refresh_at`
- `refresh_status`
- `notes`
- `created_at`
- `updated_at`

当前支持的 `auth_type`：

- `api_key`
- `service_account`
- `oauth_refresh_token`
- `custom_header`

当前策略：

- OAuth 档案只作为 standby 能力存在
- 不直接同步进 One API 生产路由
- 需要后续实现 refresh connector 后，才允许切到 `active`

#### `om_campaign`

用途：

- 营销活动定义

建议字段：

- `id`
- `code`
- `name`
- `status`
- `landing_url`
- `start_at`
- `end_at`
- `created_at`

#### `om_campaign_event`

用途：

- 记录活动曝光、点击、注册、付费

建议字段：

- `id`
- `campaign_id`
- `event_type`
- `source`
- `channel`
- `user_id`
- `visitor_id`
- `metadata`
- `created_at`

### 3.9 企业线索

#### `om_enterprise_lead`

用途：

- 企业合作咨询线索

建议字段：

- `id`
- `company_name`
- `contact_name`
- `email`
- `mobile`
- `team_size`
- `requirement`
- `status`
- `created_at`
- `updated_at`

---

## 4. 数据流方向

### 注册

- 用户注册
- 创建 One API 用户
- 写入 `om_user_profile`

### 充值

- 创建 `om_order`
- 支付成功
- 写入 `om_payment`
- 写入 `om_balance_ledger`
- 同步 One API 额度/余额

### 订阅

- 购买月卡
- 创建/更新 `om_subscription`
- 发放本期额度

### 邀请

- 访问邀请链接
- 写 `om_referral_event`
- 首单后发放邀请奖励

---

## 5. 当前表设计原则

- 先把最小闭环跑起来
- 不急于一次性建过多复杂表
- 表结构优先服务：
  - 充值
  - 订阅
  - 邀请
  - 活动
  - 企业咨询