583 lines
24 KiB
Markdown
583 lines
24 KiB
Markdown
# 分佣系统表结构设计
|
|
|
|
> **版本**: 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张表的完整设计 | - |
|