team/ycc-proxy-server

Fork 0

Files

liangzai 3440744179 first commit

2025-11-27 13:09:54 +08:00

97 KiB

Raw Blame History

新代理系统完整文档

文档说明

本文档详细记录了新代理系统的完整链路、业务逻辑、数据表结构、API接口和配置说明，用于后续系统调整和维护。

文档版本: v1.0
最后更新: 2024年
维护人员: 开发团队

一、系统概述

1.1 系统定位

新代理系统是一个三级代理分销系统，用户只能通过邀请码成为代理，支持邀请码管理、推广、收益分配、升级和提现等完整业务流程。

1.2 核心特性

三级代理体系：普通(Level 1) → 黄金(Level 2) → 钻石(Level 3)
团队结构管理：钻石代理作为团队首领，管理整个团队
邀请码机制：用户不能自主成为代理，只能通过邀请码成为代理
- 平台发放钻石邀请码：管理员生成，用户使用后成为钻石代理（只能使用一次，使用后立即失效）
- 代理发放邀请码：代理生成，用户使用后成为该代理的下级（普通邀请码可以无限使用）
- 邀请链接/二维码：代理生成，用户通过链接注册成为该代理的下级
灵活的价格体系：代理可自定义推广价格，系统自动计算收益
智能收益分配：自动计算代理收益和上级返佣
升级机制：支持自主付费升级和钻石代理升级下级
税费管理：月度累计提现，自动计算税费
实名认证：提现前必须完成实名认证（三要素核验，无需审核）

1.3 技术架构

框架: Go-Zero
数据库: MySQL
缓存: Redis
支付: 支付宝、微信支付
加密: AES加密（手机号、身份证号）

二、数据表结构

2.1 核心数据表

2.1.1 agent（代理基本信息表）

字段	类型	说明
id	bigint	主键ID
user_id	bigint	用户ID（唯一）
level	tinyint	代理等级：1=普通，2=黄金，3=钻石
region	varchar(50)	区域（可选）
mobile	varchar(50)	手机号（加密）
wechat_id	varchar(100)	微信号（可选）
team_leader_id	bigint	团队首领ID（钻石代理的ID）
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态：0=未删除，1=已删除
version	bigint	版本号（乐观锁）

索引:

PRIMARY KEY (id)
UNIQUE KEY uk_user_id (user_id)
KEY idx_mobile (mobile)
KEY idx_level (level)
KEY idx_team_leader_id (team_leader_id)

2.1.2 agent_wallet（代理钱包表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID（唯一）
balance	decimal(10,2)	可用余额
frozen_balance	decimal(10,2)	冻结余额
total_earnings	decimal(10,2)	累计收益
withdrawn_amount	decimal(10,2)	已提现金额
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

2.1.4 agent_relation（代理关系表）

字段	类型	说明
id	bigint	主键ID
parent_id	bigint	上级代理ID
child_id	bigint	下级代理ID
relation_type	tinyint	关系类型：1=直接关系，2=已脱离
detach_reason	varchar(200)	脱离原因
detach_time	datetime	脱离时间
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

关系类型说明:

relation_type = 1: 直接关系（正常上下级）
relation_type = 2: 已脱离（升级后脱离直接关系）

唯一约束:

UNIQUE KEY uk_parent_child_type (parent_id, child_id, relation_type)

2.1.5 agent_link（推广链接表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID
user_id	bigint	用户ID
product_id	bigint	产品ID
link_identifier	varchar(200)	链接标识（加密）
set_price	decimal(10,2)	设定价格
actual_base_price	decimal(10,2)	实际底价（基础底价+等级加成）
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

唯一约束:

UNIQUE KEY uk_agent_product_price (agent_id, product_id, set_price, del_state)

2.1.6 agent_order（代理订单表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID
order_id	bigint	订单ID
product_id	bigint	产品ID
order_amount	decimal(10,2)	订单金额（SetPrice）
set_price	decimal(10,2)	设定价格
actual_base_price	decimal(10,2)	实际底价
price_cost	decimal(10,2)	提价成本
agent_profit	decimal(10,2)	代理收益
process_status	tinyint	处理状态：0=待处理，1=处理成功，2=处理失败
process_time	datetime	处理时间
process_remark	varchar(500)	处理备注
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

处理状态说明:

process_status = 0: 待处理（订单创建后）
process_status = 1: 处理成功（收益已分配）
process_status = 2: 处理失败

2.1.7 agent_commission（代理佣金表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID
order_id	bigint	订单ID
product_id	bigint	产品ID
amount	decimal(10,2)	佣金金额（代理收益）
status	tinyint	状态：1=已发放
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

2.1.8 agent_rebate（代理返佣表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	获得返佣的代理ID
source_agent_id	bigint	来源代理ID（产生订单的代理）
order_id	bigint	订单ID
product_id	bigint	产品ID
rebate_type	tinyint	返佣类型：1=直接上级返佣，2=钻石上级返佣，3=黄金上级返佣
level_bonus	decimal(10,2)	等级加成金额
rebate_amount	decimal(10,2)	返佣金额
status	tinyint	状态：1=已发放
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

返佣类型说明:

rebate_type = 1: 直接上级返佣（普通代理的等级加成给直接上级）
rebate_type = 2: 钻石上级返佣（给钻石上级的返佣）
rebate_type = 3: 黄金上级返佣（给黄金上级的返佣）

2.1.9 agent_upgrade（代理升级表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID
from_level	tinyint	原等级
to_level	tinyint	目标等级
upgrade_type	tinyint	升级类型：1=自主付费，2=钻石升级下级
upgrade_fee	decimal(10,2)	升级费用
rebate_amount	decimal(10,2)	返佣金额（给原直接上级）
rebate_agent_id	bigint	返佣代理ID（原直接上级）
operator_agent_id	bigint	操作代理ID（钻石升级下级时使用）
order_no	varchar(100)	支付订单号
status	tinyint	状态：1=待处理，2=已完成，3=已失败
remark	varchar(500)	备注
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

升级类型说明:

upgrade_type = 1: 自主付费升级（代理自己付费）
upgrade_type = 2: 钻石升级下级（钻石代理操作，免费）

2.1.10 agent_withdrawal（代理提现表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID
withdraw_no	varchar(100)	提现单号（唯一）
payee_account	varchar(100)	收款账户（支付宝账号）
payee_name	varchar(100)	收款人姓名
amount	decimal(10,2)	提现金额
tax_amount	decimal(10,2)	税费金额
actual_amount	decimal(10,2)	实际到账金额
status	tinyint	状态：1=待审核，2=审核通过，3=审核拒绝，4=提现中，5=提现成功，6=提现失败
remark	varchar(500)	备注
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

状态说明:

status = 1: 待审核（代理申请后）
status = 2: 审核通过（管理员审核通过，准备转账）
status = 3: 审核拒绝（管理员拒绝）
status = 4: 提现中（已调用支付宝转账接口，处理中）
status = 5: 提现成功（转账成功）
status = 6: 提现失败（转账失败）

2.1.11 agent_withdrawal_tax（代理提现扣税表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID
withdrawal_id	bigint	提现记录ID
year_month	bigint	年月（格式：YYYYMM，如202401）
withdrawal_amount	decimal(10,2)	提现金额
taxable_amount	decimal(10,2)	应税金额
tax_rate	decimal(5,4)	税率
tax_amount	decimal(10,2)	税费金额
actual_amount	decimal(10,2)	实际到账金额
tax_status	tinyint	扣税状态：1=待扣税，2=已扣税
tax_time	datetime	扣税时间
remark	varchar(500)	备注
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

扣税状态说明:

tax_status = 1: 待扣税（提现申请后）
tax_status = 2: 已扣税（提现成功后）

2.1.12 agent_config（代理系统配置表）

字段	类型	说明
id	bigint	主键ID
config_key	varchar(100)	配置键（唯一）
config_value	varchar(500)	配置值
config_type	varchar(50)	配置类型：price=价格，bonus=等级加成，upgrade=升级费用，rebate=返佣，tax=税费
description	varchar(500)	配置描述
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

配置键列表:

base_price: 基础底价
system_max_price: 系统价格上限
price_threshold: 提价标准阈值
price_fee_rate: 提价手续费比例
level_1_bonus: 普通代理等级加成（6元）
level_2_bonus: 黄金代理等级加成（3元）
level_3_bonus: 钻石代理等级加成（0元）
upgrade_to_gold_fee: 升级为黄金费用（199元）
upgrade_to_diamond_fee: 升级为钻石费用（980元）
upgrade_to_gold_rebate: 升级为黄金返佣（139元）
upgrade_to_diamond_rebate: 升级为钻石返佣（680元）
tax_rate: 税率（默认0.06，即6%）
tax_exemption_amount: 免税额度（默认0）

2.1.13 agent_product_config（代理产品配置表）

字段	类型	说明
id	bigint	主键ID
product_id	bigint	产品ID（唯一）
product_name	varchar(100)	产品名称
base_price	decimal(10,2)	基础底价（可覆盖系统配置）
system_max_price	decimal(10,2)	系统价格上限（可覆盖系统配置）
price_threshold	decimal(10,2)	提价标准阈值（可选，覆盖系统配置）
price_fee_rate	decimal(5,4)	提价手续费比例（可选，覆盖系统配置）
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

2.1.14 agent_real_name（代理实名认证表）

字段	类型	说明
id	bigint	主键ID
agent_id	bigint	代理ID（唯一）
name	varchar(50)	真实姓名
id_card	varchar(50)	身份证号（加密）
mobile	varchar(50)	手机号（加密）
verify_time	datetime	验证时间（三要素验证通过时间，NULL表示未验证）
create_time	datetime	创建时间
update_time	datetime	更新时间
delete_time	datetime	删除时间
del_state	tinyint	删除状态
version	bigint	版本号

验证说明:

verify_time IS NULL: 未验证（未通过三要素核验或未提交）
verify_time IS NOT NULL: 已通过（三要素核验通过，可以提现）

重要：实名认证改为三要素核验，无需人工审核。提交实名认证信息后，系统自动进行三要素核验（姓名、身份证号、手机号），核验通过后自动设置 verify_time，无需管理员审核。

2.2 数据表关系图

agent (代理表)
├── agent_wallet (钱包表) 1:1
├── agent_link (推广链接表) 1:N
├── agent_order (代理订单表) 1:N
├── agent_relation (关系表) 1:N (作为parent_id)
│   └── agent_relation (关系表) 1:N (作为child_id)
├── agent_commission (佣金表) 1:N
├── agent_rebate (返佣表) 1:N (作为agent_id)
│   └── agent_rebate (返佣表) 1:N (作为source_agent_id)
├── agent_upgrade (升级表) 1:N
├── agent_withdrawal (提现表) 1:N
│   └── agent_withdrawal_tax (扣税表) 1:N
└── agent_real_name (实名认证表) 1:1

三、核心业务规则

3.1 代理等级体系

3.1.1 等级定义

等级	数值	名称	说明
Level 1	1	普通代理	初始等级，所有新代理默认等级
Level 2	2	黄金代理	中级等级，可通过付费或钻石升级获得
Level 3	3	钻石代理	最高等级，团队首领，可通过付费获得

3.1.2 等级加成规则

等级	等级加成	说明
普通代理	+6元	实际底价 = 基础底价 + 6元
黄金代理	+3元	实际底价 = 基础底价 + 3元
钻石代理	+0元	实际底价 = 基础底价

计算公式:

实际底价 = 基础底价 + 等级加成

3.2 团队结构规则

3.2.1 团队定义

团队: 由一个钻石代理作为首领，及其所有下级代理组成的层级关系链
团队首领: 必须是钻石代理，每个团队有且仅有一个首领
团队关系: 通过 team_leader_id 字段关联，所有团队成员指向同一个钻石代理

3.2.2 上下级关系约束

核心原则:

下级不能比上级等级高: 下级等级必须 ≤ 上级等级
同级不能作为上下级（除了普通代理）: 黄金和钻石不能作为同级上下级
钻石 → 黄金禁止: 钻石代理不能直接管理黄金代理（特殊规则）

允许的关系:

普通 → 普通 ✓（同级普通允许）
黄金 → 普通 ✓（上级等级高于下级）
钻石 → 普通 ✓（上级等级高于下级）
钻石 → 黄金 ✓（上级等级高于下级，但实际禁止，见规则3）

禁止的关系:

普通 → 黄金 ✗（下级等级高于上级）
普通 → 钻石 ✗（下级等级高于上级）
黄金 → 黄金 ✗（同级不能作为上下级）
钻石 → 钻石 ✗（同级不能作为上下级）
黄金 → 钻石 ✗（下级等级高于上级）
钻石 → 黄金 ✗（特殊规则禁止）

3.2.3 升级规则

核心规则: 代理升级后，其所有下级（直接+间接）会跟随该代理。

升级场景:

普通 → 黄金:
- 升级后必须脱离直接上级关系（因为黄金等级高于普通，或与黄金同级）
- 保留团队关系（通过团队首领钻石代理）
- 仍属于原团队
- 所有下级（直接+间接）继续跟随该代理
黄金 → 钻石:
- 独立成为新团队
- 成为新团队的首领（team_leader_id = 自己）
- 所有下级（直接+间接）跟随该代理到新团队
普通 → 钻石:
- 独立成为新团队
- 成为新团队的首领
- 所有下级（直接+间接）跟随该代理到新团队

3.2.4 升级方法和费用规则

升级方式:

钻石代理升级下级:
- 钻石代理可以将下级的普通代理升级为黄金代理
- 升级方式: 钻石代理操作，无需被升级代理付费
- 限制: 只能升级普通代理为黄金代理
代理自主付费升级:
- 普通代理可以付费升级为黄金代理（199元）
- 普通代理可以付费升级为钻石代理（980元）
- 黄金代理可以付费升级为钻石代理（980元）

升级费用和返佣规则:

升级类型	升级费用	直接上级返佣	说明
普通→黄金	199元	139元	付费后立即返佣给直接上级
普通→钻石	980元	680元	付费后立即返佣给直接上级
黄金→钻石	980元	680元	付费后立即返佣给直接上级
钻石升级下级（普通→黄金）	免费	无	钻石代理操作，被升级代理无需付费

重要规则:

✅ 返佣给原直接上级: 即使升级后脱离直接上下级关系，返佣仍然给原直接上级
✅ 返佣时机: 付费成功后立即返佣，然后执行升级操作
✅ 升级流程: 付费 → 返佣给直接上级 → 升级 → 根据情况脱离关系

3.3 价格体系规则

3.3.1 价格计算公式

实际底价 = 基础底价 + 等级加成
代理收益 = 设定价格 - 实际底价 - 提价成本
提价成本 = (设定价格 - 提价阈值) × 提价手续费比例（当设定价格 > 提价阈值时）

3.3.2 价格约束

最低价格: 实际底价（基础底价 + 等级加成）
最高价格: 系统价格上限（或产品配置的价格上限）
价格范围: 实际底价 ≤ 设定价格 ≤ 系统价格上限

3.3.3 提价成本计算

当设定价格 ≤ 提价阈值: 提价成本 = 0
当设定价格 > 提价阈值: 提价成本 = (设定价格 - 提价阈值) × 提价手续费比例

3.4 收益分配规则

3.4.1 代理收益

代理收益 = 设定价格 - 实际底价 - 提价成本

分配流程:

订单支付成功后，触发 AgentService.AgentProcess
计算代理收益并发放到代理钱包
创建 agent_commission 记录
更新 agent_wallet 余额和累计收益

3.4.2 等级加成返佣分配

普通代理（等级加成6元）:

优先级1: 给直接上级（最多3元）
- 如果直接上级存在，分配3元给直接上级
- 剩余金额 = 6 - 3 = 3元
优先级2: 给钻石上级（剩余金额全部）
- 查找上级链中的钻石代理
- 如果找到，剩余金额全部给钻石上级
优先级3: 给黄金上级（最多3元，如果钻石上级不存在）
- 如果钻石上级不存在，查找黄金上级
- 如果找到，最多分配3元给黄金上级
- 如果剩余金额 > 3元，超出部分归平台
优先级4: 都没有，剩余金额归平台

黄金代理（等级加成3元）:

全部给钻石上级（如有）
如果找不到钻石上级，归平台

钻石代理（等级加成0元）:

无返佣分配

3.4.3 返佣记录

所有返佣都会记录到 agent_rebate 表，包含:

获得返佣的代理ID
来源代理ID（产生订单的代理）
返佣类型（1=直接上级，2=钻石上级，3=黄金上级）
返佣金额
等级加成金额

3.5 提现规则

3.5.1 提现条件

实名认证: 必须完成实名认证且三要素核验已通过（verify_time 不为空）
余额充足: 钱包余额 >= 提现金额
账户信息: 必须提供支付宝账号和收款人姓名

3.5.2 税费计算规则

计算公式:

本月累计提现金额 = 查询本月所有已提现金额之和
剩余免税额度 = 免税额度 - 本月累计提现金额

如果 本次提现金额 <= 剩余免税额度:
    应税金额 = 0
    税费 = 0
否则:
    应税金额 = 本次提现金额 - 剩余免税额度
    税费 = 应税金额 × 税率

实际到账金额 = 提现金额 - 税费

示例:

免税额度: 1000元
税率: 6%
本月已提现: 800元
本次提现: 500元

计算:

剩余免税额度 = 1000 - 800 = 200元
本次提现500元 > 剩余免税额度200元
应税金额 = 500 - 200 = 300元
税费 = 300 × 6% = 18元
实际到账 = 500 - 18 = 482元

3.5.3 提现流程

代理申请提现:
- 验证实名认证状态
- 验证余额
- 计算税费
- 冻结余额
- 创建提现记录和扣税记录
管理员审核:
- 审核通过: 调用支付宝转账接口
- 审核拒绝: 解冻余额，返回余额
转账处理:
- 转账成功: 解冻并扣除余额，更新扣税状态
- 转账失败: 解冻余额，返回余额
- 处理中: 保持提现中状态，后续轮询更新

四、完整链路流程

4.1 通过邀请码成为代理链路

重要规则：用户不能自主成为代理，只能通过邀请码成为代理。成为代理的唯一途径包括：

平台发放钻石邀请码
代理发放邀请码
代理邀请链接/二维码

┌─────────────────────────────────────────────────────────────┐
│ 1. 用户通过邀请码申请成为代理                               │
│    API: POST /api/v1/agent/apply                           │
│    Logic: ApplyForAgentLogic                               │
│    - 必须提供邀请码（必填）                                 │
│    - 如果没有邀请码，直接拒绝                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 验证手机验证码                                           │
│    - 从Redis读取验证码                                      │
│    - 验证码校验                                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 用户注册/绑定（如需要）                                  │
│    - 检查用户是否存在                                       │
│    - 不存在则注册新用户                                     │
│    - 临时用户则绑定为正式用户                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 检查是否已是代理                                         │
│    - 检查是否已是代理（agent表）                            │
│    - 如果已是代理，直接拒绝                                 │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 验证邀请码                                               │
│    - 查询邀请码是否存在                                     │
│    - 验证邀请码状态（未使用、未过期）                       │
│    - 获取邀请码信息（目标等级、发放代理ID）                 │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 创建代理记录                                             │
│    - 根据邀请码的target_level设置代理等级                   │
│    - 如果是代理发放的邀请码，建立上下级关系                 │
│    - 如果是平台发放的钻石邀请码，独立成团队                 │
│    - 初始化钱包                                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 更新邀请码状态                                           │
│    - **钻石邀请码**：状态更新为"已使用"（status=1），使用后立即失效│
│    - **普通邀请码**：不更新状态，保持未使用（status=0），可继续使用│
│    - 记录使用用户ID和代理ID（用于统计）                     │
│    - 记录使用时间                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 生成并返回Token                                          │
│    - 生成JWT Token                                          │
│    - 返回给前端                                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 完成（无需审核，直接成为代理）                            │
│    - 代理记录已创建                                          │
│    - 钱包已初始化                                            │
│    - 关系已建立（如有上级）                                  │
│    - 团队首领已设置                                          │
│    - 微信号和区域为可选字段                                  │
└─────────────────────────────────────────────────────────────┘

4.2 推广链接生成链路

┌─────────────────────────────────────────────────────────────┐
│ 1. 代理生成推广链接                                         │
│    API: POST /api/v1/agent/link/generate                   │
│    Logic: GeneratingLinkLogic                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 获取代理信息                                             │
│    - 从Token获取用户ID                                      │
│    - 查询 agent 表                                          │
│    - 验证代理身份                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 获取系统配置                                             │
│    - base_price（基础底价）                                  │
│    - system_max_price（系统价格上限）                        │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 计算实际底价                                             │
│    实际底价 = 基础底价 + 等级加成                            │
│    - 普通代理: +6元                                         │
│    - 黄金代理: +3元                                         │
│    - 钻石代理: +0元                                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 验证设定价格范围                                         │
│    - 实际底价 ≤ 设定价格 ≤ 系统价格上限                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 检查是否已存在相同链接                                   │
│    - 查询 agent_link 表                                      │
│    - 条件: agent_id + product_id + set_price + del_state=0  │
│    - 如果存在，直接返回已有链接                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 生成推广链接标识                                         │
│    - 构建 AgentIdentifier 结构                              │
│      { AgentID, ProductID, SetPrice }                       │
│    - JSON序列化                                              │
│    - AES加密生成 LinkIdentifier                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 保存推广链接                                             │
│    - 插入 agent_link 表                                     │
│    - 记录 agent_id, product_id, link_identifier             │
│    - 记录 set_price, actual_base_price                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 9. 返回加密后的 LinkIdentifier                             │
│    - 前端使用此标识生成推广链接                             │
└─────────────────────────────────────────────────────────────┘

4.3 订单处理与收益分配链路

┌─────────────────────────────────────────────────────────────┐
│ 1. 用户通过推广链接下单                                     │
│    API: POST /api/v1/pay/payment                           │
│    Logic: PaymentLogic                                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 解析推广链接标识                                         │
│    - 解密 LinkIdentifier                                    │
│    - 解析 AgentIdentifier                                   │
│    - 获取 AgentID, ProductID, SetPrice                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 查询推广链接信息                                         │
│    - 查询 agent_link 表                                      │
│    - 验证链接有效性                                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 创建订单记录                                             │
│    - 插入 order 表                                           │
│    - 记录订单金额（SetPrice）                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 创建代理订单记录                                         │
│    - 插入 agent_order 表                                    │
│    - OrderAmount = SetPrice                                 │
│    - SetPrice = 设定价格                                    │
│    - ActualBasePrice = 实际底价（基础底价+等级加成）        │
│    - PriceCost = 提价成本                                   │
│    - AgentProfit = 代理收益（SetPrice - ActualBasePrice - PriceCost）│
│    - ProcessStatus = 0（待处理）                            │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 用户支付订单                                             │
│    - 调用支付宝/微信支付接口                                 │
│    - 生成支付订单                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 支付成功回调                                             │
│    - 支付宝/微信支付回调                                     │
│    - 验证签名                                               │
│    - 更新订单状态                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 触发代理订单处理                                         │
│    Service: AgentService.AgentProcess                       │
│    - 检查是否是代理订单                                     │
│    - 检查订单是否已处理（防重复）                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 9. 获取代理信息和系统配置                                   │
│    - 查询 agent 表                                          │
│    - 获取代理等级                                           │
│    - 获取系统配置（base_price等）                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 10. 使用事务处理订单（开始事务）                            │
│     - 计算实际底价和代理收益                                │
│     - 计算提价成本                                          │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 11. 更新代理订单状态                                        │
│     - ProcessStatus = 1（处理成功）                         │
│     - ProcessTime = 当前时间                                │
│     - ProcessRemark = "处理成功"                            │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 12. 发放代理佣金                                            │
│     - 创建 agent_commission 记录                            │
│     - 更新 agent_wallet                                     │
│       Balance += AgentProfit                                │
│       TotalEarnings += AgentProfit                          │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 13. 分配等级加成返佣                                        │
│     - 根据代理等级分配返佣                                  │
│     - 普通代理（6元）: 给直接上级3元，剩余给钻石/黄金上级   │
│     - 黄金代理（3元）: 全部给钻石上级                       │
│     - 钻石代理（0元）: 无返佣                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 14. 记录返佣                                                │
│     - 创建 agent_rebate 记录                                │
│     - 更新上级钱包余额                                      │
│     - 记录返佣类型和金额                                    │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 15. 提交事务（完成）                                        │
└─────────────────────────────────────────────────────────────┘

4.4 代理升级链路

4.4.1 自主付费升级链路

┌─────────────────────────────────────────────────────────────┐
│ 1. 代理申请升级                                             │
│    API: POST /api/v1/agent/upgrade/apply                    │
│    Logic: ApplyUpgradeLogic                                 │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 验证升级条件                                             │
│    - 验证当前等级和目标等级                                 │
│    - 普通→黄金: ✓                                           │
│    - 普通→钻石: ✓                                           │
│    - 黄金→钻石: ✓                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 计算升级费用和返佣                                       │
│    - 普通→黄金: 199元，返佣139元                            │
│    - 普通→钻石: 980元，返佣680元                            │
│    - 黄金→钻石: 980元，返佣680元                            │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 查找原直接上级                                           │
│    - 查询 agent_relation 表                                 │
│    - RelationType = 1（直接关系）                           │
│    - 用于返佣                                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 创建升级记录                                             │
│    - 插入 agent_upgrade 表                                  │
│    - UpgradeType = 1（自主付费）                            │
│    - Status = 1（待处理）                                   │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 返回升级ID和订单号                                       │
│    - 用于支付                                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 用户支付升级费用                                         │
│    - 调用支付接口                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 支付成功回调                                             │
│    - 触发升级处理                                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 9. 执行升级操作                                             │
│    Service: AgentService.ProcessUpgrade                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 10. 返佣给原直接上级（开始事务）                            │
│     - 更新上级钱包余额                                      │
│     - Balance += RebateAmount                               │
│     - TotalEarnings += RebateAmount                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 11. 更新代理等级                                            │
│     - agent.Level = toLevel                                 │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 12. 检查是否需要脱离直接上级关系                           │
│     - 检查升级后等级是否高于上级                            │
│     - 检查是否同级（黄金/钻石）                             │
│     - 检查是否钻石→黄金（禁止）                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
        ┌───────────────────────────────┐
        │ 需要脱离关系                  │
        └───────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 13. 脱离直接上级关系                                        │
│     - 更新 agent_relation 表                                │
│     - RelationType = 2（已脱离）                            │
│     - DetachReason = "upgrade"                               │
│     - DetachTime = 当前时间                                  │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 14. 更新团队首领                                            │
│     - 如果升级为钻石: team_leader_id = 自己                 │
│     - 如果升级为黄金: 查找上级链中的钻石代理                 │
│     - 更新所有下级的 team_leader_id                          │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 15. 更新升级记录状态                                        │
│     - Status = 2（已完成）                                  │
│     - Remark = "升级成功"                                    │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 16. 提交事务（完成）                                        │
└─────────────────────────────────────────────────────────────┘

4.4.2 钻石升级下级链路

┌─────────────────────────────────────────────────────────────┐
│ 1. 钻石代理升级下级                                         │
│    API: POST /api/v1/agent/upgrade/subordinate              │
│    Logic: UpgradeSubordinateLogic                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 验证权限                                                 │
│    - 必须是钻石代理（Level = 3）                            │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 验证下级等级                                             │
│    - 只能是普通代理（Level = 1）                            │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 验证关系                                                 │
│    - 必须是直接下级                                         │
│    - 查询 agent_relation 表                                 │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 验证目标等级                                             │
│    - 只能升级为黄金（toLevel = 2）                          │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 创建升级记录                                             │
│    - 插入 agent_upgrade 表                                  │
│    - UpgradeType = 2（钻石升级下级）                        │
│    - UpgradeFee = 0（免费）                                 │
│    - RebateAmount = 0（无返佣）                             │
│    - OperatorAgentId = 操作者代理ID                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 执行升级操作                                             │
│    Service: AgentService.ProcessUpgrade                      │
│    - 更新下级等级为黄金                                     │
│    - 脱离直接上级关系（如需要）                             │
│    - 更新团队首领（保持原团队首领）                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 更新升级记录状态                                        │
│    - Status = 2（已完成）                                   │
│    - Remark = "钻石代理升级下级成功"                        │
└─────────────────────────────────────────────────────────────┘

4.5 提现链路

┌─────────────────────────────────────────────────────────────┐
│ 1. 代理申请提现                                             │
│    API: POST /api/v1/agent/withdrawal/apply                  │
│    Logic: ApplyWithdrawalLogic                              │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 验证实名认证                                             │
│    - 查询 agent_real_name 表                                │
│    - verify_time 必须不为空（三要素核验已通过）             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 验证提现金额                                             │
│    - Amount > 0                                             │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 验证钱包余额                                             │
│    - Balance >= Amount                                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 计算税费                                                 │
│    - 查询本月累计提现金额                                   │
│    - 计算剩余免税额度                                       │
│    - 计算应税金额                                           │
│    - 计算税费 = 应税金额 × 税率                             │
│    - 计算实际到账金额 = 提现金额 - 税费                     │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 生成提现单号                                             │
│    - 格式: WD + timestamp + agentId                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 使用事务处理提现申请（开始事务）                         │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 8. 冻结余额                                                 │
│    - FrozenBalance += Amount                                │
│    - Balance -= Amount                                      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 9. 创建提现记录                                             │
│    - 插入 agent_withdrawal 表                               │
│    - Status = 1（待审核）                                   │
│    - 记录 PayeeAccount, PayeeName                           │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 10. 创建扣税记录                                            │
│     - 插入 agent_withdrawal_tax 表                          │
│     - TaxStatus = 1（待扣税）                                │
│     - 记录 YearMonth, TaxableAmount, TaxAmount              │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 11. 提交事务（完成）                                        │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 12. 管理员审核提现                                          │
│     API: POST /api/v1/admin/agent/withdrawal/audit          │
│     Logic: AdminAuditWithdrawalLogic                        │
└─────────────────────────────────────────────────────────────┘
                        ↓
        ┌───────────────────────────────┐
        │ 审核通过（Status=2）          │
        └───────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 13. 更新提现状态为提现中                                    │
│     - Status = 4（提现中）                                  │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 14. 调用支付宝转账接口                                      │
│     - AliTransfer(account, name, amount, remark, outBizNo)  │
└─────────────────────────────────────────────────────────────┘
                        ↓
        ┌───────────────┬───────────────┬───────────────┐
        │ 转账成功      │ 转账失败      │ 处理中        │
        │ (SUCCESS)     │ (FAIL)        │ (DEALING)     │
        └───────────────┴───────────────┴───────────────┘
                ↓               ↓               ↓
    ┌───────────────┐  ┌───────────────┐  ┌───────────────┐
    │ 15. 更新状态  │  │ 15. 更新状态  │  │ 15. 保持状态  │
    │ Status = 5    │  │ Status = 6    │  │ Status = 4    │
    │ (提现成功)    │  │ (提现失败)    │  │ (提现中)      │
    └───────────────┘  └───────────────┘  └───────────────┘
                ↓               ↓
    ┌───────────────┐  ┌───────────────┐
    │ 16. 解冻并扣  │  │ 16. 解冻余额  │
    │ 除余额        │  │ 返回余额      │
    │ - FrozenBalance│ │ - FrozenBalance│
    │   -= Amount    │ │   -= Amount    │
    │ - WithdrawnAmount│ │ - Balance     │
    │   += Amount    │ │   += Amount    │
    └───────────────┘  └───────────────┘
                ↓
    ┌───────────────┐
    │ 17. 更新扣税  │
    │ 状态          │
    │ TaxStatus = 2 │
    │ (已扣税)      │
    └───────────────┘

4.6 实名认证链路

┌─────────────────────────────────────────────────────────────┐
│ 1. 代理提交实名认证信息                                       │
│    API: POST /api/v1/agent/real_name                          │
│    Logic: RealNameAuthLogic                                   │
│    - 姓名、身份证号、手机号                                   │
│    - 验证码（手机号验证码）                                   │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 验证代理身份                                               │
│    - 从Token获取用户ID                                        │
│    - 查询 agent 表                                            │
│    - 验证手机号是否匹配                                       │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 验证手机验证码                                             │
│    - 从Redis读取验证码                                        │
│    - 验证码校验                                               │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 三要素核验（自动）                                        │
│    - 调用 VerificationService.ThreeFactorVerification        │
│    - 核验姓名、身份证号、手机号是否一致                       │
│    - 核验通过：继续流程                                       │
│    - 核验失败：返回错误                                       │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 加密敏感信息                                              │
│    - 加密身份证号                                            │
│    - 加密手机号                                              │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. 保存实名认证记录（开始事务）                              │
│    - 检查是否已有记录                                         │
│    - 如有记录：更新姓名、身份证号、手机号、verify_time        │
│    - 如无记录：创建新记录，设置 verify_time = 当前时间        │
│    - verify_time 不为空表示已通过三要素核验                   │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. 提交事务（完成）                                          │
│    - 返回成功，实名认证完成                                   │
│    - 可以申请提现                                            │
└─────────────────────────────────────────────────────────────┘

重要说明：

实名认证改为三要素核验，无需人工审核
核验通过后自动设置 verify_time，无需管理员操作
verify_time 不为空即表示已通过认证，可以提现

五、关键代码逻辑

5.1 AgentService 核心方法

5.1.1 AgentProcess（订单处理）

文件: app/main/api/internal/service/agentService.go

功能: 处理代理订单，分配收益和返佣

核心逻辑:

func (s *AgentService) AgentProcess(ctx context.Context, order *model.Order) error {
    // 1. 检查是否是代理订单
    agentOrder, err := s.AgentOrderModel.FindOneByOrderId(ctx, order.Id)
    if err != nil {
        if errors.Is(err, model.ErrNotFound) {
            return nil // 不是代理订单
        }
        return err
    }

    // 2. 检查订单是否已处理（防重复）
    if agentOrder.ProcessStatus == 1 {
        return nil
    }

    // 3. 获取代理信息和系统配置
    agent, err := s.AgentModel.FindOne(ctx, agentOrder.AgentId)
    basePrice, err := s.getConfigFloat(ctx, "base_price")

    // 4. 使用事务处理
    return s.AgentWalletModel.Trans(ctx, func(transCtx context.Context, session sqlx.Session) error {
        // 4.1 计算实际底价和代理收益
        levelBonus := s.getLevelBonus(agent.Level)
        actualBasePrice := basePrice + float64(levelBonus)
        priceCost := s.calculatePriceCost(agentOrder.SetPrice, priceThreshold, priceFeeRate)
        agentProfit := agentOrder.SetPrice - actualBasePrice - priceCost

        // 4.2 更新代理订单状态
        agentOrder.ProcessStatus = 1
        s.AgentOrderModel.UpdateWithVersion(transCtx, session, agentOrder)

        // 4.3 发放代理佣金
        s.giveAgentCommission(transCtx, session, agentOrder.AgentId, order.Id, order.ProductId, agentProfit)

        // 4.4 分配等级加成返佣
        if levelBonus > 0 {
            s.distributeLevelBonus(transCtx, session, agent, order.Id, order.ProductId, float64(levelBonus), levelBonus)
        }

        return nil
    })
}

5.1.2 distributeLevelBonus（等级加成返佣分配）

功能: 根据代理等级分配等级加成返佣给上级链

核心逻辑:

func (s *AgentService) distributeLevelBonus(ctx context.Context, session sqlx.Session, agent *model.Agent, orderId, productId int64, levelBonus float64, levelBonusInt int64) error {
    // 钻石代理：等级加成为0，无返佣分配
    if agent.Level == 3 {
        return nil
    }

    // 黄金代理：等级加成3元，全部给钻石上级
    if agent.Level == 2 {
        diamondParent, err := s.findDiamondParent(ctx, agent.Id)
        if diamondParent != nil {
100002            return s.giveRebate(ctx, session, diamondParent.Id, agent.Id, orderId, productId, levelBonus, levelBonusInt, 2)
        }
        return nil
    }

    // 普通代理：等级加成6元，按规则分配给上级链
    if agent.Level == 1 {
        return s.distributeNormalAgentBonus(ctx, session, agent, orderId, productId, levelBonus, levelBonusInt)
    }

    return nil
}

5.1.3 ProcessUpgrade（代理升级处理）

功能: 处理代理升级，包括返佣、关系脱离、团队首领更新

核心逻辑:

func (s *AgentService) ProcessUpgrade(ctx context.Context, agentId, toLevel int64, upgradeType int64, upgradeFee, rebateAmount float64, orderNo string, operatorAgentId int64) error {
    return s.AgentWalletModel.Trans(ctx, func(transCtx context.Context, session sqlx.Session) error {
        // 1. 获取代理信息
        agent, err := s.AgentModel.FindOne(transCtx, agentId)

        // 2. 如果是自主付费升级，处理返佣
        if upgradeType == 1 {
            parent, err := s.findDirectParent(transCtx, agentId)
            if parent != nil && rebateAmount > 0 {
                s.giveRebateForUpgrade(transCtx, session, parent.Id, agentId, rebateAmount)
            }
        }

        // 3. 更新代理等级
        agent.Level = toLevel

        // 4. 检查是否需要脱离直接上级关系
        needDetach, err := s.needDetachFromParent(transCtx, agent, toLevel)
        if needDetach {
            s.detachFromParent(transCtx, session, agentId)
        }

        // 5. 如果升级为钻石，独立成新团队
        if toLevel == 3 {
            agent.TeamLeaderId = sql.NullInt64{Int64: agentId, Valid: true}
            s.updateChildrenTeamLeader(transCtx, session, agentId, agentId)
        } else {
            // 更新团队首领（查找上级链中的钻石代理）
            teamLeaderId, _ := s.findTeamLeaderId(transCtx, agentId)
            if teamLeaderId > 0 {
                agent.TeamLeaderId = sql.NullInt64{Int64: teamLeaderId, Valid: true}
            }
        }

        // 6. 更新代理记录
        s.AgentModel.UpdateWithVersion(transCtx, session, agent)

        return nil
    })
}

5.1.4 calculateTax（税费计算）

功能: 计算提现税费，基于月度累计和免税额度

核心逻辑:

func calculateTax(ctx context.Context, agentId int64, amount float64, yearMonth int64) (*TaxInfo, error) {
    // 1. 获取税率配置（默认6%）
    taxRate := 0.06
    config, _ := AgentConfigModel.FindOneByConfigKey(ctx, "tax_rate")
    if config != nil {
        taxRate = parseFloat(config.ConfigValue)
    }

    // 2. 查询本月已提现金额
    taxRecords, _ := AgentWithdrawalTaxModel.FindAll(...)
    monthlyTotal := sum(taxRecords.WithdrawalAmount)

    // 3. 获取免税额度配置（默认0）
    exemptionAmount := 0.0
    exemptionConfig, _ := AgentConfigModel.FindOneByConfigKey(ctx, "tax_exemption_amount")
    if exemptionConfig != nil {
        exemptionAmount = parseFloat(exemptionConfig.ConfigValue)
    }

    // 4. 计算应税金额
    remainingExemption := exemptionAmount - monthlyTotal
    taxableAmount := amount
    if remainingExemption > 0 {
        if amount <= remainingExemption {
            taxableAmount = 0  // 完全免税
        } else {
            taxableAmount = amount - remainingExemption  // 部分免税
        }
    }

    // 5. 计算税费和实际到账金额
    taxAmount := taxableAmount * taxRate
    actualAmount := amount - taxAmount

    return &TaxInfo{
        TaxableAmount: taxableAmount,
        TaxRate:       taxRate,
        TaxAmount:     taxAmount,
        ActualAmount:  actualAmount,
    }, nil
}

六、API接口列表

6.1 前端接口（agent.api）

6.1.1 公开接口（无需登录）

接口	方法	路径	说明
获取推广链接数据	GET	`/api/v1/agent/link`	根据LinkIdentifier获取推广链接信息
通过邀请码申请成为代理	POST	`/api/v1/agent/apply`	用户通过邀请码申请成为代理（必须提供邀请码）

6.1.2 需要登录的接口

接口	方法	路径	说明
~~查询代理申请状态~~	~~GET~~	~~`/api/v1/agent/audit/status`~~	~~查询当前用户的代理申请审核状态（已废弃：无需审核）~~
查看代理信息	GET	`/api/v1/agent/info`	获取当前代理的详细信息
生成推广链接	POST	`/api/v1/agent/generating_link`	生成产品推广链接
获取产品配置	GET	`/api/v1/agent/product_config`	获取代理可配置的产品价格信息
获取团队统计	GET	`/api/v1/agent/team/statistics`	获取团队统计数据
获取下级列表	GET	`/api/v1/agent/subordinate/list`	分页查询直接下级列表
获取收益信息	GET	`/api/v1/agent/revenue`	获取钱包余额和收益信息
获取佣金记录	GET	`/api/v1/agent/commission/list`	分页查询佣金记录
获取返佣记录	GET	`/api/v1/agent/rebate/list`	分页查询返佣记录
获取升级记录	GET	`/api/v1/agent/upgrade/list`	分页查询升级记录
申请升级	POST	`/api/v1/agent/upgrade/apply`	自主付费升级
钻石升级下级	POST	`/api/v1/agent/upgrade/subordinate`	钻石代理升级下级
获取提现列表	GET	`/api/v1/agent/withdrawal/list`	分页查询提现记录
申请提现	POST	`/api/v1/agent/withdrawal/apply`	申请提现
实名认证	POST	`/api/v1/agent/real_name`	提交实名认证信息（三要素核验，自动通过）

6.2 后台管理接口（admin_agent.api）

接口	方法	路径	说明
代理分页查询	GET	`/api/v1/admin/agent/list`	分页查询代理列表
~~代理审核~~	~~POST~~	~~`/api/v1/admin/agent/audit`~~	~~审核代理申请（已废弃：通过邀请码直接成为代理，无需审核）~~
推广链接分页查询	GET	`/api/v1/admin/agent/link/list`	分页查询推广链接
代理订单分页查询	GET	`/api/v1/admin/agent/order/list`	分页查询代理订单
代理佣金分页查询	GET	`/api/v1/admin/agent/commission/list`	分页查询佣金记录
代理返佣分页查询	GET	`/api/v1/admin/agent/rebate/list`	分页查询返佣记录
代理升级记录分页查询	GET	`/api/v1/admin/agent/upgrade/list`	分页查询升级记录
代理提现分页查询	GET	`/api/v1/admin/agent/withdrawal/list`	分页查询提现记录
代理提现审核	POST	`/api/v1/admin/agent/withdrawal/audit`	审核提现申请
代理实名认证分页查询	GET	`/api/v1/admin/agent/real_name/list`	分页查询实名认证记录
~~代理实名认证审核~~	~~POST~~	~~`/api/v1/admin/agent/real_name/audit`~~	~~审核实名认证（已废弃：改为三要素核验，无需审核）~~
系统配置查询	GET	`/api/v1/admin/agent/config`	查询系统配置
系统配置更新	POST	`/api/v1/admin/agent/config/update`	更新系统配置
产品配置分页查询	GET	`/api/v1/admin/agent/product_config/list`	分页查询产品配置
产品配置更新	POST	`/api/v1/admin/agent/product_config/update`	更新产品配置

七、系统配置说明

7.1 系统配置项（agent_config表）

配置键	配置类型	默认值	说明
`base_price`	price	-	基础底价（系统默认）
`system_max_price`	price	-	系统价格上限
`price_threshold`	price	-	提价标准阈值
`price_fee_rate`	price	-	提价手续费比例（0-1之间的小数）
`level_1_bonus`	bonus	6	普通代理等级加成（元）
`level_2_bonus`	bonus	3	黄金代理等级加成（元）
`level_3_bonus`	bonus	0	钻石代理等级加成（元）
`upgrade_to_gold_fee`	upgrade	199	升级为黄金费用（元）
`upgrade_to_diamond_fee`	upgrade	980	升级为钻石费用（元）
`upgrade_to_gold_rebate`	rebate	139	升级为黄金返佣（元）
`upgrade_to_diamond_rebate`	rebate	680	升级为钻石返佣（元）
`tax_rate`	tax	0.06	税率（默认6%，即0.06）
`tax_exemption_amount`	tax	0	免税额度（元，默认0）

7.2 产品配置项（agent_product_config表）

每个产品可以单独配置以下参数，覆盖系统默认配置：

字段	说明
`base_price`	产品基础底价（覆盖系统配置）
`system_max_price`	产品价格上限（覆盖系统配置）
`price_threshold`	产品提价标准阈值（可选，覆盖系统配置）
`price_fee_rate`	产品提价手续费比例（可选，覆盖系统配置）

7.3 配置优先级

产品配置 > 系统配置
- 如果产品配置了 base_price，使用产品配置
- 如果产品未配置，使用系统配置
系统配置 > 代码默认值
- 如果系统配置存在，使用系统配置
- 如果系统配置不存在，使用代码中的默认值

八、数据流转图

8.1 订单处理数据流

用户下单
    ↓
创建 order 记录
    ↓
创建 agent_order 记录（ProcessStatus=0）
    ↓
用户支付
    ↓
支付成功回调
    ↓
调用 AgentService.AgentProcess
    ↓
┌─────────────────────────────────────┐
│ 事务开始                              │
│ 1. 计算实际底价 = 基础底价 + 等级加成 │
│ 2. 计算提价成本                       │
│ 3. 计算代理收益                       │
│ 4. 更新 agent_order (ProcessStatus=1) │
│ 5. 创建 agent_commission 记录        │
│ 6. 更新 agent_wallet (Balance, TotalEarnings) │
│ 7. 分配等级加成返佣                   │
│    - 创建 agent_rebate 记录           │
│    - 更新上级 agent_wallet            │
│ 事务提交                              │
└─────────────────────────────────────┘

8.2 升级处理数据流

代理申请升级
    ↓
创建 agent_upgrade 记录（Status=1）
    ↓
用户支付升级费用
    ↓
支付成功回调
    ↓
调用 AgentService.ProcessUpgrade
    ↓
┌─────────────────────────────────────┐
│ 事务开始                              │
│ 1. 返佣给原直接上级（如需要）         │
│    - 更新上级 agent_wallet            │
│ 2. 更新 agent.Level                  │
│ 3. 检查是否需要脱离关系               │
│    - 更新 agent_relation (RelationType=2) │
│ 4. 更新团队首领                       │
│    - 更新 agent.TeamLeaderId         │
│    - 更新所有下级的 TeamLeaderId     │
│ 5. 更新 agent_upgrade (Status=2)     │
│ 事务提交                              │
└─────────────────────────────────────┘

8.3 提现处理数据流

代理申请提现
    ↓
验证实名认证和余额
    ↓
计算税费
    ↓
┌─────────────────────────────────────┐
│ 事务开始                              │
│ 1. 冻结余额                          │
│    - agent_wallet.FrozenBalance += Amount │
│    - agent_wallet.Balance -= Amount   │
│ 2. 创建 agent_withdrawal 记录        │
│    (Status=1, 待审核)                │
│ 3. 创建 agent_withdrawal_tax 记录    │
│    (TaxStatus=1, 待扣税)              │
│ 事务提交                              │
└─────────────────────────────────────┘
    ↓
管理员审核
    ↓
审核通过（Status=2）
    ↓
调用支付宝转账接口
    ↓
转账成功/失败/处理中
    ↓
┌─────────────────────────────────────┐
│ 事务开始                              │
│ 1. 更新 agent_withdrawal.Status      │
│ 2. 解冻并扣除余额（成功）             │
│    - agent_wallet.FrozenBalance -= Amount │
│    - agent_wallet.WithdrawnAmount += Amount │
│ 3. 更新 agent_withdrawal_tax.TaxStatus │
│ 事务提交                              │
└─────────────────────────────────────┘

九、关键算法说明

9.1 团队统计递归算法

func getTeamMembers(agentId int64) []int64 {
    teamMembers := []int64{agentId}  // 包括自己
    
    var collectChildren func(int64)
    collectChildren = func(parentId int64) {
        // 查找直接下级（relation_type=1）
        relations := findDirectChildren(parentId)
        for _, relation := range relations {
            teamMembers = append(teamMembers, relation.ChildId)
            collectChildren(relation.ChildId)  // 递归
        }
    }
    
    collectChildren(agentId)
    return teamMembers
}

9.2 查找上级链算法

// 查找直接上级
func findDirectParent(agentId int64) *Agent {
    relation := findRelation(childId=agentId, relationType=1)
    return findAgent(relation.ParentId)
}

// 查找钻石上级（向上递归）
func findDiamondParent(agentId int64) *Agent {
    currentId := agentId
    maxDepth := 100
    depth := 0
    
    for depth < maxDepth {
        parent := findDirectParent(currentId)
        if parent == nil {
            return nil
        }
        if parent.Level == 3 {  // 钻石
            return parent
        }
        currentId = parent.Id
        depth++
    }
    return nil
}

9.3 价格计算算法

// 计算实际底价
func calculateActualBasePrice(agentLevel int64, basePrice float64) float64 {
    levelBonus := getLevelBonus(agentLevel)  // 6, 3, 0
    return basePrice + float64(levelBonus)
}

// 计算提价成本
func calculatePriceCost(setPrice, priceThreshold, priceFeeRate float64) float64 {
    if setPrice <= priceThreshold {
        return 0
    }
    return (setPrice - priceThreshold) * priceFeeRate
}

// 计算代理收益
func calculateAgentProfit(setPrice, actualBasePrice, priceCost float64) float64 {
    return setPrice - actualBasePrice - priceCost
}

十、注意事项和最佳实践

10.1 数据一致性

事务使用: 所有涉及多表更新的操作必须使用事务
- 订单处理（agent_order, agent_commission, agent_wallet, agent_rebate）
- 升级处理（agent, agent_relation, agent_wallet, agent_upgrade）
- 提现处理（agent_withdrawal, agent_withdrawal_tax, agent_wallet）
乐观锁: 所有更新操作使用 version 字段进行乐观锁控制
- 使用 UpdateWithVersion 方法
- 更新失败时重试或提示用户
防重复处理:
- 订单处理前检查 agent_order.ProcessStatus
- 升级处理前检查 agent_upgrade.Status

10.2 性能优化

批量查询: 避免N+1查询问题
- 列表查询时批量获取产品名称、代理信息等
索引使用:
- agent_relation: idx_parent_relation, idx_child_relation
- agent_rebate: idx_order_rebate_type
- agent_order: idx_process_status
递归深度限制:
- 查找上级链时设置最大深度（如100层）
- 防止无限循环

10.3 错误处理

配置缺失: 配置项不存在时使用默认值
- 税率默认6%
- 等级加成使用代码中的固定值
关系异常:
- 找不到上级时，返佣归平台
- 升级时找不到直接上级，跳过返佣
余额不足:
- 提现前验证余额
- 使用事务确保余额扣减的原子性

10.4 安全考虑

数据加密:
- 手机号、身份证号使用AES加密存储
- 推广链接标识加密传输
权限控制:
- 代理只能查看自己的数据
- 管理员需要认证和授权
金额精度:
- 使用 decimal(10,2) 类型存储金额
- 计算时注意浮点数精度问题

十一、常见问题解答

11.1 升级后关系脱离规则

Q: 为什么普通代理升级为黄金后要脱离直接上级关系？

A: 根据关系约束规则：

下级不能比上级等级高
同级不能作为上下级（除了普通代理）
如果直接上级是普通代理，升级后黄金等级高于普通，必须脱离
如果直接上级是黄金/钻石，升级后同级，也必须脱离

11.2 返佣分配规则

Q: 普通代理的6元等级加成如何分配？

A: 按优先级分配：

给直接上级（根据上级等级：钻石6元，黄金3元，普通2元）
剩余金额给钻石上级（如有）
如果无钻石上级，给黄金上级（最多3元）
都没有，剩余归平台

11.3 团队归属

Q: 升级后团队归属如何变化？

普通→黄金：仍属于原团队（通过team_leader_id指向原钻石代理）
黄金→钻石：独立成新团队（team_leader_id指向自己）
普通→钻石：独立成新团队（team_leader_id指向自己）

11.4 税费计算

Q: 税费如何计算？

查询本月累计提现金额
计算剩余免税额度 = 免税额度 - 本月累计
如果本次提现 <= 剩余免税额度，免税
否则，应税金额 = 本次提现 - 剩余免税额度
税费 = 应税金额 × 税率

十二、后续优化建议

12.1 功能扩展

多级返佣: 支持更多层级的返佣分配
业绩统计: 增加团队业绩统计和排行榜
消息通知: 收益到账、升级成功等消息推送

12.2 性能优化

缓存策略:
- 系统配置缓存
- 团队统计数据缓存
- 代理信息缓存
异步处理:
- 订单处理异步化
- 团队统计异步计算

12.3 监控和日志

关键操作日志:
- 订单处理日志
- 升级操作日志
- 提现操作日志
性能监控:
- 订单处理耗时
- 数据库查询耗时
- 接口响应时间

附录

A. 数据表索引说明

详见 deploy/sql/agent_system_migration.sql 文件中的索引定义。

B. API接口详细定义

详见 app/main/api/desc/front/agent.api 和 app/main/api/desc/admin/admin_agent.api 文件。

C. 代码文件清单

Service层: app/main/api/internal/service/agentService.go
Logic层: app/main/api/internal/logic/agent/*.go
Model层: app/main/model/agent*.go
API定义: app/main/api/desc/front/agent.api, app/main/api/desc/admin/admin_agent.api

文档结束

97 KiB Raw Blame History Unescape Escape

新代理系统完整文档

文档说明

目录

一、系统概述

1.1 系统定位

1.2 核心特性

1.3 技术架构

二、数据表结构

2.1 核心数据表

2.1.1 agent（代理基本信息表）

2.1.2 agent_wallet（代理钱包表）

2.1.4 agent_relation（代理关系表）

2.1.5 agent_link（推广链接表）

2.1.6 agent_order（代理订单表）

2.1.7 agent_commission（代理佣金表）

2.1.8 agent_rebate（代理返佣表）

2.1.9 agent_upgrade（代理升级表）

2.1.10 agent_withdrawal（代理提现表）

2.1.11 agent_withdrawal_tax（代理提现扣税表）

2.1.12 agent_config（代理系统配置表）

2.1.13 agent_product_config（代理产品配置表）

2.1.14 agent_real_name（代理实名认证表）

2.2 数据表关系图

三、核心业务规则

3.1 代理等级体系

3.1.1 等级定义

3.1.2 等级加成规则

3.2 团队结构规则

3.2.1 团队定义

3.2.2 上下级关系约束

3.2.3 升级规则

3.2.4 升级方法和费用规则

3.3 价格体系规则

3.3.1 价格计算公式

3.3.2 价格约束

3.3.3 提价成本计算

3.4 收益分配规则

3.4.1 代理收益

3.4.2 等级加成返佣分配

3.4.3 返佣记录

3.5 提现规则

3.5.1 提现条件

3.5.2 税费计算规则

3.5.3 提现流程

四、完整链路流程

4.1 通过邀请码成为代理链路

4.2 推广链接生成链路

4.3 订单处理与收益分配链路

4.4 代理升级链路

4.4.1 自主付费升级链路

4.4.2 钻石升级下级链路

4.5 提现链路

4.6 实名认证链路

五、关键代码逻辑

5.1 AgentService 核心方法

5.1.1 AgentProcess（订单处理）

5.1.2 distributeLevelBonus（等级加成返佣分配）

5.1.3 ProcessUpgrade（代理升级处理）

5.1.4 calculateTax（税费计算）

六、API接口列表

6.1 前端接口（agent.api）

6.1.1 公开接口（无需登录）

6.1.2 需要登录的接口

6.2 后台管理接口（admin_agent.api）

七、系统配置说明

7.1 系统配置项（agent_config表）

7.2 产品配置项（agent_product_config表）

7.3 配置优先级

八、数据流转图

8.1 订单处理数据流

8.2 升级处理数据流

8.3 提现处理数据流

九、关键算法说明

9.1 团队统计递归算法

9.2 查找上级链算法

9.3 价格计算算法

十、注意事项和最佳实践

10.1 数据一致性

10.2 性能优化

97 KiB

Raw Blame History