csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

add: 提交部分表设计

Browse Source 
update: 1.所有model嵌入gorm公用model 2.所有model嵌入BaseModel
This commit is contained in:
huang
2025-12-15 11:32:33 +08:00
parent 4455b39e42
commit ad946af5ee
21 changed files with 1109 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

582
docs/优化说明/分佣表结构设计.md Normal file
View File

@@ -0,0 +1,582 @@
# 分佣系统表结构设计
> **版本**: v1.0
> **最后更新**: 2025-11-28
> **依据文档**:
> - `docs/优化说明/分佣正确逻辑.md`
> - `docs/优化说明/分佣正确逻辑补充.md`
## 设计原则
1. **无外键约束**: 表之间不建立数据库外键,关联通过 ID 字段手动维护
2. **软删除**: 所有表支持软删除,使用 `deleted_at` 字段
3. **审计字段**: 所有表包含 `created_at`、`updated_at` 时间戳
4. **操作留痕**: 关键操作记录操作人 ID
5. **数据完整性**: 关键业务数据通过代码层面保证一致性
---
## 1. 返佣梯度模板表
**用途**: 预设的返佣梯度模板,提供初始配置值,可被多个代理引用
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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 | 软删除时间 |
---
## 2. 返佣梯度条目表
**用途**: 模板中的具体梯度条目,定义每个梯度的判断目标和返佣规则
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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`: 销售数量存储个数,销售金额存储分
---
## 3. 代理商-套餐-返佣规则快照表
**用途**: 代理商分销套餐时生成的返佣规则快照,独立于模板,允许个性化调整
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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 | 软删除时间 |
---
## 4. 代理商返佣规则梯度条目表
**用途**: 代理商快照规则中的具体梯度条目(从模板复制或自定义)
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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 | 软删除时间 |
---
## 5. 佣金记录表
**用途**: 记录每一笔佣金的生成、状态变化、金额计算等核心信息
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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`: 客户退款导致回溯
---
## 6. 佣金解冻凭证表
**用途**: 记录运营提交的解冻凭证,支持批量解冻操作
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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 | 软删除时间 |
---
## 7. 佣金解冻凭证明细表
**用途**: 解冻凭证中的每条 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 | 更新时间 |
---
## 8. 提现申请表
**用途**: 代理商的提现申请记录
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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 | 软删除时间 |
---
## 9. 提现审批记录表
**用途**: 提现申请的审批流程记录,支持多级审批和操作留痕
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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'` 的记录代表最终放款操作
---
## 10. 提现-佣金关联表
**用途**: 关联提现申请和具体的佣金记录,支持一次提现包含多笔佣金
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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 | 创建时间 |
---
## 11. 代理商佣金账户表
**用途**: 代理商的佣金账户余额和统计信息(实时显示分佣金额)
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| 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` 字段的累加(负数)
---
## 补充说明
### 1. 需要在现有表中新增的字段
#### sims (卡表)
```sql
-- 如果卡表需要支持分佣,可能需要添加:
ALTER TABLE sims ADD COLUMN related_agent_id BIGINT; -- 关联的销售代理商
ALTER TABLE sims ADD COLUMN related_package_id BIGINT; -- 关联的销售套餐
ALTER TABLE sims ADD COLUMN sale_channel VARCHAR(50); -- 销售渠道
```
#### packages (套餐表)
```sql
-- 如果套餐表需要标记是否参与分佣:
ALTER TABLE packages ADD COLUMN enable_commission BOOLEAN DEFAULT false; -- 是否启用分佣
ALTER TABLE packages ADD COLUMN cost_price BIGINT; -- 成本价(分为单位)
```
### 2. 关键业务规则
#### 佣金生成规则
1. 每日巡检检查 ICCID 的卡状态、充值金额、三无校验(仅号卡)
2. 根据代理商的返佣规则快照判断是否命中梯度
3. 根据返佣时效决定生成 `frozen` 或 `normal` 状态的佣金
4. 长期返佣每月重复生成,直到达到终止条件
#### 解冻流程
1. 运营导入 ICCID/号码列表和凭证文件
2. 输入解冻密码(可扩展为双人校验)
3. 系统匹配佣金记录,校验三无条件(仅号卡)
4. 批量更新状态: `frozen` → `normal` 或 `invalid`
#### 提现流程
1. 代理商发起提现申请,选择可提现佣金
2. 佣金状态批量更新: `normal` → `withdraw_pending`
3. 多级审批(可配置)
4. 审批通过后,操作人执行放款,记录凭证
5. 佣金状态更新: `withdraw_pending` → `withdrawn`
#### 回溯机制
1. 客户退款导致佣金需要扣回
2. 检查代理账户可用余额:
- 余额充足: 直接扣减,生成负数佣金记录
- 余额不足: 支持负数余额,下次佣金自动抵扣
3. 更新对应佣金记录状态为 `clawback`
### 3. 数据导出需求
#### 无效佣金导出
```sql
SELECT
cr.record_no,
cr.agent_id,
cr.related_identifier,
cr.commission_amount,
cr.invalid_reason,
cr.invalidated_at,
cr.invalidated_by
FROM commission_records cr
WHERE cr.status = 'invalid'
AND cr.deleted_at IS NULL
ORDER BY cr.invalidated_at DESC;
```
#### 驳回清单导出
```sql
SELECT
wr.request_no,
wr.agent_id,
wr.withdrawal_amount,
wr.reject_reason,
wa.approver_name,
wa.approved_at
FROM commission_withdrawal_requests wr
JOIN commission_withdrawal_approvals wa ON wr.id = wa.request_id
WHERE wr.status = 'rejected'
AND wa.action = 'reject'
AND wr.deleted_at IS NULL
ORDER BY wa.approved_at DESC;
```
#### 代理佣金梯度导出
```sql
SELECT
apcr.agent_id,
apcr.package_id,
apcr.rule_name,
acti.tier_level,
acti.judgment_target,
acti.rebate_type,
acti.rebate_value
FROM agent_package_commission_rules apcr
JOIN agent_commission_tier_items acti ON apcr.id = acti.rule_id
WHERE apcr.agent_id = :agent_id
AND apcr.deleted_at IS NULL
AND acti.deleted_at IS NULL
ORDER BY apcr.package_id, acti.tier_level;
```
### 4. 常量定义建议
在 `pkg/constants/constants.go` 中建议定义:
```go
// 卡类型
const (
CardTypePhone = "phone_card" // 号卡
CardTypeIoT = "iot_card" // 物联网卡
)
// 判断类型
const (
JudgmentTypeSalesQuantity = "sales_quantity" // 套餐销售数量
JudgmentTypeSalesAmount = "sales_amount" // 套餐销售金额
)
// 返佣时效
const (
RebateTimingImmediate = "immediate" // 即可返佣
RebateTimingDelayed = "delayed" // 延迟返佣
)
// 返佣条件类型
const (
RebateConditionAccumulated = "accumulated_recharge" // 累计充值
RebateConditionSingle = "single_recharge" // 一次充值
)
// 返佣属性
const (
RebateTypePercentage = "percentage" // 比例金额
RebateTypeFixed = "fixed" // 固定金额
)
// 长期终止方式
const (
TerminationTypeMonthCount = "month_count" // 指定月数
TerminationTypeEndDate = "end_date" // 指定日期
)
// 佣金状态
const (
CommissionStatusFrozen = "frozen" // 已冻结
CommissionStatusNormal = "normal" // 正常
CommissionStatusInvalid = "invalid" // 无效
CommissionStatusWithdrawPending = "withdraw_pending" // 提取申请中
CommissionStatusWithdrawRejected = "withdraw_rejected" // 提取驳回
CommissionStatusWithdrawn = "withdrawn" // 已提取
CommissionStatusClawback = "clawback" // 已回溯
)
// 标识符类型
const (
IdentifierTypeICCID = "iccid" // ICCID
IdentifierTypePhoneNumber = "phone_number" // 号码
)
// 凭证来源
const (
VoucherSourceCarrierOfficial = "carrier_official" // 运营商官方
VoucherSourceUpstreamChannel = "upstream_channel" // 上游渠道
VoucherSourceOther = "other" // 其他
)
// 解冻结果
const (
UnfreezeResultSuccess = "success" // 成功
UnfreezeResultFailed = "failed" // 失败
UnfreezeResultNotFound = "not_found" // 未找到
)
// 提现申请状态
const (
WithdrawalStatusPending = "pending" // 待审批
WithdrawalStatusApproved = "approved" // 已批准
WithdrawalStatusRejected = "rejected" // 已驳回
WithdrawalStatusPaid = "paid" // 已放款
WithdrawalStatusFailed = "failed" // 放款失败
)
// 审批操作
const (
ApprovalActionApprove = "approve" // 批准
ApprovalActionReject = "reject" // 驳回
ApprovalActionPay = "pay" // 放款
)
```
---
## ER 关系图
```
┌─────────────────────────────────┐
│ commission_tier_templates │ 返佣梯度模板
│ - id (PK) │
│ - template_code (UK) │
└─────────────────┬───────────────┘
│ 1
│
│ N
┌─────────────────┴───────────────┐
│ commission_tier_items │ 梯度条目
│ - id (PK) │
│ - template_id (FK) │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ agent_package_commission_rules │ 代理返佣规则快照
│ - id (PK) │
│ - agent_id │
│ - package_id │
└─────────────────┬───────────────┘
│ 1
│
│ N
┌─────────────────┴───────────────┐
│ agent_commission_tier_items │ 代理梯度条目
│ - id (PK) │
│ - rule_id (FK) │
└─────────────────┬───────────────┘
│
│
│ 被引用
┌─────────────────┴───────────────┐
│ commission_records │ 佣金记录
│ - id (PK) │
│ - rule_id │
│ - tier_item_id │
│ - related_identifier │
└───┬─────────────────────────┬───┘
│ │
│ N │ N
│ │
┌───┴─────────────────────┐ ┌┴─────────────────────────────┐
│ commission_unfreeze │ │ commission_withdrawal_records│
│ _voucher_items │ │ - request_id │
│ - voucher_id │ │ - commission_record_id │
│ - commission_record_id │ └┬─────────────────────────────┘
└─────────────────────────┘ │
│ N
│
┌─────────┴──────────────────────┐
│ commission_withdrawal_requests │
│ - id (PK) │
│ - agent_id │
└───┬────────────────────────────┘
│ 1
│
│ N
┌───────────┴─────────────────────────┐
│ commission_withdrawal_approvals │
│ - request_id (FK) │
│ - approver_id │
└─────────────────────────────────────┘
┌─────────────────────────────────┐
│ agent_commission_accounts │ 代理佣金账户
│ - agent_id (UK) │
│ - available_amount │
│ - frozen_amount │
└─────────────────────────────────┘
```
---
## 版本历史
| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2025-11-28 | 初始版本,包含11张表的完整设计 | - |

464
docs/表设计/整合.md Normal file
View File

@@ -0,0 +1,464 @@
## 代理商/店铺表
| 字段名 | 说明 |
| --- | --- |
| 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` 字段的累加(负数)
---