team/ycc-proxy-server
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3440744179b9883b055675336813c629f028bd71
ycc-proxy-server/新代理系统完整文档.md

1807 lines
97 KiB
Markdown
Raw Normal View History

first commit
2025-11-27 13:09:54 +08:00
# 新代理系统完整文档
## 文档说明
本文档详细记录了新代理系统的完整链路、业务逻辑、数据表结构、API接口和配置说明，用于后续系统调整和维护。
**文档版本**: v1.0
**最后更新**: 2024年
**维护人员**: 开发团队
---
## 目录
1. [系统概述](#一系统概述)
2. [数据表结构](#二数据表结构)
3. [核心业务规则](#三核心业务规则)
4. [完整链路流程](#四完整链路流程)
5. [关键代码逻辑](#五关键代码逻辑)
6. [API接口列表](#六api接口列表)
7. [系统配置说明](#七系统配置说明)
8. [数据流转图](#八数据流转图)
---
## 一、系统概述
### 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 上下级关系约束
**核心原则**:
1. **下级不能比上级等级高**: 下级等级必须 ≤ 上级等级
2. **同级不能作为上下级**（除了普通代理）: 黄金和钻石不能作为同级上下级
3. **钻石 → 黄金禁止**: 钻石代理不能直接管理黄金代理（特殊规则）
**允许的关系**:
- 普通 → 普通 ✓（同级普通允许）
- 黄金 → 普通 ✓（上级等级高于下级）
- 钻石 → 普通 ✓（上级等级高于下级）
- 钻石 → 黄金 ✓（上级等级高于下级，但实际禁止，见规则3）
**禁止的关系**:
- 普通 → 黄金 ✗（下级等级高于上级）
- 普通 → 钻石 ✗（下级等级高于上级）
- 黄金 → 黄金 ✗（同级不能作为上下级）
- 钻石 → 钻石 ✗（同级不能作为上下级）
- 黄金 → 钻石 ✗（下级等级高于上级）
- 钻石 → 黄金 ✗（特殊规则禁止）
#### 3.2.3 升级规则
**核心规则**: 代理升级后，其所有下级（直接+间接）会跟随该代理。
**升级场景**:
1. **普通 → 黄金**:
- 升级后必须脱离直接上级关系（因为黄金等级高于普通，或与黄金同级）
- 保留团队关系（通过团队首领钻石代理）
- 仍属于原团队
- 所有下级（直接+间接）继续跟随该代理
2. **黄金 → 钻石**:
- 独立成为新团队
- 成为新团队的首领（`team_leader_id = 自己`）
- 所有下级（直接+间接）跟随该代理到新团队
3. **普通 → 钻石**:
- 独立成为新团队
- 成为新团队的首领
- 所有下级（直接+间接）跟随该代理到新团队
#### 3.2.4 升级方法和费用规则
**升级方式**:
1. **钻石代理升级下级**:
- 钻石代理可以将下级的普通代理升级为黄金代理
- 升级方式: 钻石代理操作，无需被升级代理付费
- 限制: 只能升级普通代理为黄金代理
2. **代理自主付费升级**:
- 普通代理可以付费升级为黄金代理（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 代理收益
代理收益 = 设定价格 - 实际底价 - 提价成本
**分配流程**:
1. 订单支付成功后，触发 `AgentService.AgentProcess`
2. 计算代理收益并发放到代理钱包
3. 创建 `agent_commission` 记录
4. 更新 `agent_wallet` 余额和累计收益
#### 3.4.2 等级加成返佣分配
**普通代理（等级加成6元）**:
1. **优先级1**: 给直接上级（最多3元）
- 如果直接上级存在，分配3元给直接上级
- 剩余金额 = 6 - 3 = 3元
2. **优先级2**: 给钻石上级（剩余金额全部）
- 查找上级链中的钻石代理
- 如果找到，剩余金额全部给钻石上级
3. **优先级3**: 给黄金上级（最多3元，如果钻石上级不存在）
- 如果钻石上级不存在，查找黄金上级
- 如果找到，最多分配3元给黄金上级
- 如果剩余金额 > 3元，超出部分归平台
4. **优先级4**: 都没有，剩余金额归平台
**黄金代理（等级加成3元）**:
1. 全部给钻石上级（如有）
2. 如果找不到钻石上级，归平台
**钻石代理（等级加成0元）**:
- 无返佣分配
#### 3.4.3 返佣记录
所有返佣都会记录到 `agent_rebate` 表，包含:
- 获得返佣的代理ID
- 来源代理ID（产生订单的代理）
- 返佣类型（1=直接上级，2=钻石上级，3=黄金上级）
- 返佣金额
- 等级加成金额
### 3.5 提现规则
#### 3.5.1 提现条件
1. **实名认证**: 必须完成实名认证且三要素核验已通过（`verify_time` 不为空）
2. **余额充足**: 钱包余额 >= 提现金额
3. **账户信息**: 必须提供支付宝账号和收款人姓名
#### 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 提现流程
1. **代理申请提现**:
- 验证实名认证状态
- 验证余额
- 计算税费
- 冻结余额
- 创建提现记录和扣税记录
2. **管理员审核**:
- 审核通过: 调用支付宝转账接口
- 审核拒绝: 解冻余额，返回余额
3. **转账处理**:
- 转账成功: 解冻并扣除余额，更新扣税状态
- 转账失败: 解冻余额，返回余额
- 处理中: 保持提现中状态，后续轮询更新
---
## 四、完整链路流程
### 4.1 通过邀请码成为代理链路
**重要规则**：用户不能自主成为代理，只能通过邀请码成为代理。成为代理的唯一途径包括：
1. 平台发放钻石邀请码
2. 代理发放邀请码
3. 代理邀请链接/二维码
```
┌─────────────────────────────────────────────────────────────┐
│ 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`
**功能**: 处理代理订单，分配收益和返佣
**核心逻辑**:
```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（等级加成返佣分配）
**功能**: 根据代理等级分配等级加成返佣给上级链
**核心逻辑**:
```go
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（代理升级处理）
**功能**: 处理代理升级，包括返佣、关系脱离、团队首领更新
**核心逻辑**:
```go
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（税费计算）
**功能**: 计算提现税费，基于月度累计和免税额度
**核心逻辑**:
```go
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 配置优先级
1. **产品配置** > **系统配置**
- 如果产品配置了 `base_price`，使用产品配置
- 如果产品未配置，使用系统配置
2. **系统配置** > **代码默认值**
- 如果系统配置存在，使用系统配置
- 如果系统配置不存在，使用代码中的默认值
---
## 八、数据流转图
### 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 团队统计递归算法
```go
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 查找上级链算法
```go
// 查找直接上级
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 价格计算算法
```go
// 计算实际底价
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 数据一致性
1. **事务使用**: 所有涉及多表更新的操作必须使用事务
- 订单处理（agent_order, agent_commission, agent_wallet, agent_rebate）
- 升级处理（agent, agent_relation, agent_wallet, agent_upgrade）
- 提现处理（agent_withdrawal, agent_withdrawal_tax, agent_wallet）
2. **乐观锁**: 所有更新操作使用 `version` 字段进行乐观锁控制
- 使用 `UpdateWithVersion` 方法
- 更新失败时重试或提示用户
3. **防重复处理**:
- 订单处理前检查 `agent_order.ProcessStatus`
- 升级处理前检查 `agent_upgrade.Status`
### 10.2 性能优化
1. **批量查询**: 避免N+1查询问题
- 列表查询时批量获取产品名称、代理信息等
2. **索引使用**:
- `agent_relation`: `idx_parent_relation`, `idx_child_relation`
- `agent_rebate`: `idx_order_rebate_type`
- `agent_order`: `idx_process_status`
3. **递归深度限制**:
- 查找上级链时设置最大深度（如100层）
- 防止无限循环
### 10.3 错误处理
1. **配置缺失**: 配置项不存在时使用默认值
- 税率默认6%
- 等级加成使用代码中的固定值
2. **关系异常**:
- 找不到上级时，返佣归平台
- 升级时找不到直接上级，跳过返佣
3. **余额不足**:
- 提现前验证余额
- 使用事务确保余额扣减的原子性
### 10.4 安全考虑
1. **数据加密**:
- 手机号、身份证号使用AES加密存储
- 推广链接标识加密传输
2. **权限控制**:
- 代理只能查看自己的数据
- 管理员需要认证和授权
3. **金额精度**:
- 使用 `decimal(10,2)` 类型存储金额
- 计算时注意浮点数精度问题
---
## 十一、常见问题解答
### 11.1 升级后关系脱离规则
**Q**: 为什么普通代理升级为黄金后要脱离直接上级关系？
**A**: 根据关系约束规则：
- 下级不能比上级等级高
- 同级不能作为上下级（除了普通代理）
- 如果直接上级是普通代理，升级后黄金等级高于普通，必须脱离
- 如果直接上级是黄金/钻石，升级后同级，也必须脱离
### 11.2 返佣分配规则
**Q**: 普通代理的6元等级加成如何分配？
**A**: 按优先级分配：
1. 给直接上级（根据上级等级：钻石6元，黄金3元，普通2元）
2. 剩余金额给钻石上级（如有）
3. 如果无钻石上级，给黄金上级（最多3元）
4. 都没有，剩余归平台
### 11.3 团队归属
**Q**: 升级后团队归属如何变化？
**A**:
- 普通→黄金：仍属于原团队（通过team_leader_id指向原钻石代理）
- 黄金→钻石：独立成新团队（team_leader_id指向自己）
- 普通→钻石：独立成新团队（team_leader_id指向自己）
### 11.4 税费计算
**Q**: 税费如何计算？
**A**:
1. 查询本月累计提现金额
2. 计算剩余免税额度 = 免税额度 - 本月累计
3. 如果本次提现 <= 剩余免税额度，免税
4. 否则，应税金额 = 本次提现 - 剩余免税额度
5. 税费 = 应税金额 × 税率
---
## 十二、后续优化建议
### 12.1 功能扩展
1. **多级返佣**: 支持更多层级的返佣分配
2. **业绩统计**: 增加团队业绩统计和排行榜
3. **消息通知**: 收益到账、升级成功等消息推送
### 12.2 性能优化
1. **缓存策略**:
- 系统配置缓存
- 团队统计数据缓存
- 代理信息缓存
2. **异步处理**:
- 订单处理异步化
- 团队统计异步计算
### 12.3 监控和日志
1. **关键操作日志**:
- 订单处理日志
- 升级操作日志
- 提现操作日志
2. **性能监控**:
- 订单处理耗时
- 数据库查询耗时
- 接口响应时间
---
## 附录
### 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`
---
**文档结束**
Reference in New Issue Copy Permalink