## 代理商/店铺表

| 字段名 | 说明 |
| --- | --- |
| id | 主键id |
| name | 代理商名称/店铺名称 |
| parent_shop_id | 上级代理/店铺 ID |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 账号表

| 字段名称 | 说明 |
| --- | --- |
| id | 主键ID |
| username | 用户名 |
| phone | 手机号 |
| password | 密码(用MD5加密) |
| user_type | 用户类型 1 root 2 平台/运营 3 代理 4 企业 |
| shop_id | 店铺ID 该账号绑定到哪个店铺下的 |
| parent_id | 账号上级(应当移除) |
| status | 0 禁用 1启用 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 角色表

| 字段名称 | 说明 |
| --- | --- |
| id | 主键ID |
| role_name | 角色名称 |
| role_desc | 角色描述 |
| role_type | 角色类型 1 超级 2 代理 3 企业 |
| status | 0 禁用 1启用 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 权限表(菜单/按钮/操作)

| 字段名称 | 说明 |
| --- | --- |
| id | 主键ID |
| perm_name | 权限名称 |
| perm_type | 权限类型 1 菜单 2 按钮 |
| url | 权限路径 菜单 按钮 |
| parent_id | 上级ID |
| perm_code | 权限编码 |
| sort | 排序 |
| status | 0 禁用 1启用 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 账号-角色表

| 字段名 | 说明 |
| --- | --- |
| id | 主键ID |
| account_id | 账号ID |
| role_id | 角色ID |
| status | 0 禁用 1启用 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---


## 角色-权限表

| 字段名 | 说明 |
| --- | --- |
| id | 主键ID |
| role_id | 角色ID |
| perm_id | 权限ID |
| status | 0 禁用 1启用 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 套餐系列(套餐分类)

| 字段名 | 说明 |
| --- | --- |
| id | 主键ID |
|code|套餐系列编码|
| name | 套餐系列名称 |
|type|业务套餐类型 流量卡,号卡|
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

**说明**
- `type`: 用以区分业务, 流量卡只能使用流量卡套餐 号卡只能使用号卡套餐
---

## 套餐表

| 字段名 | 说明 |
| --- | --- |
| id | 主键ID |
|code|套餐编码|
|套餐系列code|套餐系列code|
|type|套餐类型 叠加包/月卡套餐/自然月套餐/|
| name | 套餐名称 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

**说明**:
- `judgment_target`: 销售数量存储个数,销售金额存储分
---

## 代理/店铺套餐表

| 字段名 | 说明 |
| --- | --- |
| id | 主键ID |
| shop_id | 代理/店铺ID |
| 套餐系列名称 | 套餐系列名称 |
| 套餐系列ID | 套餐系列的主键ID |
| 套餐code | 套餐编码 |
| 套餐名称 | 套餐名称 |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 流量卡表

| 字段名 | 说明 |
| --- | --- |
| id | 主键ID |
| created_at | 创建时间 |
| updated_at | 更新时间 |
| creator | 创建人(创建人ID) |
| updater | 更新人(更新人ID) |
| deleted_at | 删除时间 (为null为没有删除) |

---

## 返佣梯度模板表

**用途**: 预设的返佣梯度模板,提供初始配置值,可被多个代理引用

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| template_name | VARCHAR(100) | NOT NULL | 模板名称 |
| template_code | VARCHAR(50) | NOT NULL UNIQUE | 模板编码(唯一标识) |
| description | TEXT | NULL | 模板说明 |
| card_type | VARCHAR(20) | NOT NULL | 卡类型: `phone_card`(号卡) / `iot_card`(物联网卡) |
| judgment_type | VARCHAR(20) | NOT NULL | 判断类型: `sales_quantity`(套餐销售数量) / `sales_amount`(套餐销售金额) |
| rebate_timing | VARCHAR(20) | NOT NULL | 返佣时效: `immediate`(即可返佣) / `delayed`(延迟返佣) |
| rebate_condition_type | VARCHAR(20) | NOT NULL | 返佣条件类型: `accumulated_recharge`(累计充值) / `single_recharge`(一次充值) |
| rebate_condition_amount | BIGINT | NOT NULL | 返佣条件目标值(分为单位) |
| require_sanwu_check | BOOLEAN | NOT NULL DEFAULT false | 是否三无校验(仅号卡需要,物联网卡不需要) |
| is_long_term | BOOLEAN | NOT NULL DEFAULT false | 是否长期返佣 |
| termination_type | VARCHAR(20) | NULL | 长期终止方式: `month_count`(指定月数) / `end_date`(指定日期) |
| termination_value | VARCHAR(50) | NULL | 终止值: 月数(如"36")或日期(如"2026-11-20") |
| is_active | BOOLEAN | NOT NULL DEFAULT true | 是否启用 |
| created_by | BIGINT | NOT NULL | 创建人 ID |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

---

## 返佣梯度条目表

**用途**: 模板中的具体梯度条目,定义每个梯度的判断目标和返佣规则

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| template_id | BIGINT | NOT NULL | 关联模板 ID |
| tier_level | INT | NOT NULL | 梯度等级(从1开始递增) |
| judgment_target | BIGINT | NOT NULL | 判断目标值(数量或金额,金额以分为单位) |
| rebate_type | VARCHAR(20) | NOT NULL | 返佣属性: `percentage`(比例金额) / `fixed`(固定金额) |
| rebate_value | BIGINT | NOT NULL | 返佣假定值(比例用万分比,如1000=10%;固定金额用分) |
| max_cap_amount | BIGINT | NULL | 封顶金额(分为单位,NULL表示无封顶) |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

**说明**:
- `rebate_value`: 比例类型存储万分比(10000=100%, 1000=10%),固定金额存储分
- `judgment_target`: 销售数量存储个数,销售金额存储分

---

## 代理商-套餐-返佣规则快照表

**用途**: 代理商分销套餐时生成的返佣规则快照,独立于模板,允许个性化调整

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| agent_id | BIGINT | NOT NULL | 代理商 ID |
| package_id | BIGINT | NOT NULL | 套餐 ID |
| template_id | BIGINT | NULL | 原始模板 ID(可为空,表示自定义规则) |
| rule_name | VARCHAR(100) | NOT NULL | 规则名称 |
| card_type | VARCHAR(20) | NOT NULL | 卡类型: `phone_card` / `iot_card` |
| judgment_type | VARCHAR(20) | NOT NULL | 判断类型 |
| rebate_timing | VARCHAR(20) | NOT NULL | 返佣时效 |
| rebate_condition_type | VARCHAR(20) | NOT NULL | 返佣条件类型 |
| rebate_condition_amount | BIGINT | NOT NULL | 返佣条件目标值(分) |
| require_sanwu_check | BOOLEAN | NOT NULL DEFAULT false | 是否三无校验 |
| is_long_term | BOOLEAN | NOT NULL DEFAULT false | 是否长期返佣 |
| termination_type | VARCHAR(20) | NULL | 长期终止方式 |
| termination_value | VARCHAR(50) | NULL | 终止值 |
| is_active | BOOLEAN | NOT NULL DEFAULT true | 是否启用 |
| created_by | BIGINT | NOT NULL | 创建人 ID |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

---

## 代理商返佣规则梯度条目表

**用途**: 代理商快照规则中的具体梯度条目(从模板复制或自定义)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| rule_id | BIGINT | NOT NULL | 关联规则 ID |
| tier_level | INT | NOT NULL | 梯度等级 |
| judgment_target | BIGINT | NOT NULL | 判断目标值 |
| rebate_type | VARCHAR(20) | NOT NULL | 返佣属性 |
| rebate_value | BIGINT | NOT NULL | 返佣假定值 |
| max_cap_amount | BIGINT | NULL | 封顶金额 |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

---

## 佣金记录表

**用途**: 记录每一笔佣金的生成、状态变化、金额计算等核心信息

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| record_no | VARCHAR(50) | NOT NULL UNIQUE | 佣金记录号(业务唯一标识) |
| agent_id | BIGINT | NOT NULL | 代理商 ID |
| package_id | BIGINT | NOT NULL | 套餐 ID |
| rule_id | BIGINT | NOT NULL | 返佣规则 ID |
| tier_item_id | BIGINT | NOT NULL | 梯度条目 ID |
| related_identifier | VARCHAR(50) | NOT NULL | 关联标识符(ICCID 或号码) |
| identifier_type | VARCHAR(20) | NOT NULL | 标识符类型: `iccid` / `phone_number` |
| card_type | VARCHAR(20) | NOT NULL | 卡类型: `phone_card` / `iot_card` |
| billing_month | VARCHAR(7) | NOT NULL | 计费月份(格式: YYYY-MM) |
| judgment_type | VARCHAR(20) | NOT NULL | 判断类型 |
| judgment_value | BIGINT | NOT NULL | 判断实际值(数量或金额) |
| rebate_timing | VARCHAR(20) | NOT NULL | 返佣时效 |
| rebate_type | VARCHAR(20) | NOT NULL | 返佣属性 |
| rebate_base_amount | BIGINT | NOT NULL | 返佣基数(成本价,分) |
| rebate_rate | BIGINT | NULL | 返佣比例(万分比,仅比例类型) |
| commission_amount | BIGINT | NOT NULL | 佣金金额(分) |
| status | VARCHAR(20) | NOT NULL | 状态: `frozen`(已冻结) / `normal`(正常) / `invalid`(无效) / `withdraw_pending`(提取申请中) / `withdraw_rejected`(提取驳回) / `withdrawn`(已提取) / `clawback`(已回溯) |
| freeze_reason | TEXT | NULL | 冻结原因 |
| invalid_reason | TEXT | NULL | 无效原因 |
| clawback_reason | TEXT | NULL | 回溯原因 |
| clawback_amount | BIGINT | NOT NULL DEFAULT 0 | 回溯金额(分,负数表示扣减) |
| is_long_term | BOOLEAN | NOT NULL DEFAULT false | 是否长期返佣 |
| long_term_month_index | INT | NULL | 长期返佣月份索引(第几个月) |
| frozen_at | TIMESTAMP | NULL | 冻结时间 |
| unfrozen_at | TIMESTAMP | NULL | 解冻时间 |
| unfrozen_by | BIGINT | NULL | 解冻操作人 ID |
| invalidated_at | TIMESTAMP | NULL | 标记无效时间 |
| invalidated_by | BIGINT | NULL | 标记无效操作人 ID |
| clawback_at | TIMESTAMP | NULL | 回溯时间 |
| clawback_by | BIGINT | NULL | 回溯操作人 ID |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

**状态流转说明**:
- `frozen` → `normal`: 解冻
- `frozen` → `invalid`: 巡检发现不满足条件
- `normal` → `withdraw_pending`: 提交提现申请
- `withdraw_pending` → `withdrawn`: 审批通过
- `withdraw_pending` → `withdraw_rejected`: 审批驳回
- `withdraw_rejected` → `normal`: 问题解决后恢复
- `withdrawn` → `clawback`: 客户退款导致回溯

---

## 佣金解冻凭证表

**用途**: 记录运营提交的解冻凭证,支持批量解冻操作

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| voucher_no | VARCHAR(50) | NOT NULL UNIQUE | 凭证批次号 |
| voucher_source | VARCHAR(50) | NOT NULL | 凭证来源: `carrier_official`(运营商官方) / `upstream_channel`(上游渠道) / `other`(其他) |
| voucher_file_url | TEXT | NULL | 凭证文件 URL |
| billing_month | VARCHAR(7) | NOT NULL | 结算月份 |
| total_count | INT | NOT NULL DEFAULT 0 | 凭证包含总数 |
| unfrozen_count | INT | NOT NULL DEFAULT 0 | 成功解冻数量 |
| failed_count | INT | NOT NULL DEFAULT 0 | 解冻失败数量 |
| unfreeze_password | VARCHAR(100) | NULL | 解冻密码(加密存储) |
| status | VARCHAR(20) | NOT NULL | 状态: `pending`(待处理) / `processing`(处理中) / `completed`(已完成) / `failed`(失败) |
| process_started_at | TIMESTAMP | NULL | 处理开始时间 |
| process_completed_at | TIMESTAMP | NULL | 处理完成时间 |
| created_by | BIGINT | NOT NULL | 创建人 ID |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

---

## 佣金解冻凭证明细表

**用途**: 解冻凭证中的每条 ICCID/号码记录

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| voucher_id | BIGINT | NOT NULL | 关联凭证 ID |
| identifier | VARCHAR(50) | NOT NULL | ICCID 或号码 |
| identifier_type | VARCHAR(20) | NOT NULL | 标识符类型: `iccid` / `phone_number` |
| commission_record_id | BIGINT | NULL | 关联佣金记录 ID(匹配后填充) |
| sanwu_check_passed | BOOLEAN | NULL | 三无校验是否通过 |
| traffic_usage | BIGINT | NULL | 流量用量(字节) |
| voice_usage | BIGINT | NULL | 语音用量(秒) |
| sms_usage | INT | NULL | 短信用量(条) |
| unfreeze_result | VARCHAR(20) | NOT NULL | 解冻结果: `success`(成功) / `failed`(失败) / `not_found`(未找到) |
| fail_reason | TEXT | NULL | 失败原因 |
| unfrozen_at | TIMESTAMP | NULL | 解冻时间 |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |


---

## 提现申请表

**用途**: 代理商的提现申请记录

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| request_no | VARCHAR(50) | NOT NULL UNIQUE | 提现申请单号 |
| agent_id | BIGINT | NOT NULL | 代理商 ID |
| withdrawal_amount | BIGINT | NOT NULL | 提现金额(分) |
| available_balance | BIGINT | NOT NULL | 申请时可用余额(分) |
| bank_account_name | VARCHAR(100) | NOT NULL | 收款账户名 |
| bank_account_number | VARCHAR(50) | NOT NULL | 收款账号 |
| bank_name | VARCHAR(100) | NOT NULL | 开户行 |
| status | VARCHAR(20) | NOT NULL | 状态: `pending`(待审批) / `approved`(已批准) / `rejected`(已驳回) / `paid`(已放款) / `failed`(放款失败) |
| reject_reason | TEXT | NULL | 驳回原因 |
| paid_amount | BIGINT | NULL | 实际放款金额(分) |
| paid_at | TIMESTAMP | NULL | 放款时间 |
| paid_by | BIGINT | NULL | 放款操作人 ID |
| payment_voucher_url | TEXT | NULL | 放款凭证 URL |
| transaction_no | VARCHAR(100) | NULL | 支付流水号 |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |
| deleted_at | TIMESTAMP | NULL | 软删除时间 |

---

## 提现审批记录表

**用途**: 提现申请的审批流程记录,支持多级审批和操作留痕

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| request_id | BIGINT | NOT NULL | 关联提现申请 ID |
| approval_level | INT | NOT NULL | 审批级别(1,2,3...) |
| approver_id | BIGINT | NOT NULL | 审批人 ID |
| approver_name | VARCHAR(100) | NOT NULL | 审批人姓名 |
| action | VARCHAR(20) | NOT NULL | 操作: `approve`(批准) / `reject`(驳回) / `pay`(放款) |
| comment | TEXT | NULL | 审批意见 |
| approved_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 审批时间 |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |


**说明**:
- 每次审批操作(批准/驳回/放款)都会插入一条记录
- `approval_level` 用于区分多级审批流程
- `action='pay'` 的记录代表最终放款操作

---

## 提现-佣金关联表

**用途**: 关联提现申请和具体的佣金记录,支持一次提现包含多笔佣金

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| request_id | BIGINT | NOT NULL | 关联提现申请 ID |
| commission_record_id | BIGINT | NOT NULL | 关联佣金记录 ID |
| commission_amount | BIGINT | NOT NULL | 佣金金额(分) |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |

---

## 代理商佣金账户表

**用途**: 代理商的佣金账户余额和统计信息(实时显示分佣金额)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGSERIAL | PRIMARY KEY | 主键 |
| agent_id | BIGINT | NOT NULL UNIQUE | 代理商 ID |
| total_earned | BIGINT | NOT NULL DEFAULT 0 | 累计获得佣金(分) |
| frozen_amount | BIGINT | NOT NULL DEFAULT 0 | 冻结中金额(分) |
| available_amount | BIGINT | NOT NULL DEFAULT 0 | 可提现金额(分) |
| withdrawn_amount | BIGINT | NOT NULL DEFAULT 0 | 已提现金额(分) |
| invalid_amount | BIGINT | NOT NULL DEFAULT 0 | 无效佣金金额(分) |
| clawback_amount | BIGINT | NOT NULL DEFAULT 0 | 已回溯金额(分) |
| pending_withdrawal_amount | BIGINT | NOT NULL DEFAULT 0 | 提现申请中金额(分) |
| last_withdrawal_at | TIMESTAMP | NULL | 最后提现时间 |
| created_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL DEFAULT CURRENT_TIMESTAMP | 更新时间 |

**字段计算规则**:
- `available_amount` = 状态为 `normal` 的佣金总和
- `frozen_amount` = 状态为 `frozen` 的佣金总和
- `pending_withdrawal_amount` = 状态为 `withdraw_pending` 的佣金总和
- `withdrawn_amount` = 状态为 `withdrawn` 的佣金总和
- `invalid_amount` = 状态为 `invalid` 的佣金总和
- `clawback_amount` = 所有 `clawback_amount` 字段的累加(负数)

---