csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
bb9f0a3a1f2f33ca05b9bdf8d9ae259014cd7504
junhong_cmp_fiber/docs/优化说明/分佣表结构设计.md
huang ad946af5ee add: 提交部分表设计 
update: 1.所有model嵌入gorm公用model 2.所有model嵌入BaseModel
2025-12-15 11:32:33 +08:00

24 KiB
Raw Blame History

分佣系统表结构设计

版本: 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 (卡表)

-- 如果卡表需要支持分佣,可能需要添加:
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 (套餐表)

-- 如果套餐表需要标记是否参与分佣:
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. 数据导出需求

无效佣金导出

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;

驳回清单导出

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;

代理佣金梯度导出

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 中建议定义:

// 卡类型
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张表的完整设计 -
Reference in New Issue View Git Blame Copy Permalink