# 分佣系统表结构设计

> **版本**: 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张表的完整设计 | - |