ycc-proxy-server/新代理系统检查清单.md

# 新代理系统完整检查清单

## 检查说明

本文档提供新代理系统的完整检查方案，按照业务流程顺序组织，确保系统逻辑正确性和完整性。

**检查原则**：
1. 按照业务流程顺序检查（从注册到提现）
2. 先检查核心链路，再检查辅助功能
3. 每个检查点包含：功能点、关键逻辑、预期结果
4. 重点关注数据一致性、事务完整性、边界条件

---

## 一、基础数据检查

### 1.1 数据表结构
- [ ] 确认所有新表已创建（参考 `deploy/sql/agent_system_migration.sql`）
- [ ] 检查表结构是否与文档一致
- [ ] 验证索引是否正确创建
- [ ] 确认所有表都有 `id`, `create_time`, `update_time`, `delete_time`, `del_state`, `version` 字段

**关键表**：
- `agent` - 代理基本信息
- `agent_wallet` - 代理钱包
- `agent_relation` - 代理关系
- `agent_link` - 推广链接
- `agent_order` - 代理订单
- `agent_commission` - 代理佣金
- `agent_rebate` - 代理返佣
- `agent_upgrade` - 代理升级
- `agent_withdrawal` - 代理提现
- `agent_withdrawal_tax` - 提现扣税
- `agent_config` - 系统配置
- `agent_product_config` - 产品配置
- `agent_real_name` - 实名认证
- `agent_invite_code` - 邀请码

### 1.2 系统配置初始化
- [ ] 检查 `agent_config` 表是否有基础配置数据
- [ ] 验证关键配置项是否存在：
  - `base_price` - 基础底价
  - `system_max_price` - 系统价格上限
  - `level_1_bonus` - 普通代理等级加成（6元）
  - `level_2_bonus` - 黄金代理等级加成（3元）
  - `level_3_bonus` - 钻石代理等级加成（0元）
  - `upgrade_to_gold_fee` - 升级为黄金费用（199元）
  - `upgrade_to_diamond_fee` - 升级为钻石费用（980元）
  - `tax_rate` - 税率（0.06）
  - `tax_exemption_amount` - 免税额度

---

## 二、核心业务流程检查

### 2.1 通过邀请码成为代理链路

**入口**：`POST /api/v1/agent/apply` 或 `POST /api/v1/agent/register/invite`

**检查点**：

#### 2.1.1 邀请码验证
- [ ] **文件**：`app/main/api/internal/logic/agent/applyforagentlogic.go`
- [ ] 验证邀请码必填（没有邀请码直接拒绝）
- [ ] 验证邀请码存在性（`agent_invite_code` 表）
- [ ] 验证邀请码状态（`status=0` 未使用）
- [ ] 验证邀请码是否过期（`expire_time`）
- [ ] 验证邀请码使用后状态更新为已使用（`status=1`）

#### 2.1.2 用户注册/绑定
- [ ] 检查用户是否存在（通过手机号查询）
- [ ] 不存在则注册新用户
- [ ] 临时用户则绑定为正式用户
- [ ] 验证手机号加密存储

#### 2.1.3 代理记录创建
- [ ] 检查是否已是代理（防止重复）
- [ ] 根据邀请码的 `target_level` 设置代理等级
- [ ] 创建 `agent` 记录
- [ ] 初始化 `agent_wallet`（余额为0）
- [ ] 可选字段处理：`region`, `wechat_id` 可以为空

#### 2.1.4 关系建立
- [ ] **代理发放的邀请码**：
  - [ ] 验证上级代理存在
  - [ ] 验证关系是否允许（下级等级不能高于上级）
  - [ ] 创建 `agent_relation` 记录（`relation_type=1` 直接关系）
  - [ ] 设置 `team_leader_id`（查找上级链中的钻石代理）
- [ ] **平台发放的钻石邀请码**：
  - [ ] 独立成团队（`team_leader_id = 自己`）

#### 2.1.5 邀请码状态更新
- [ ] 更新邀请码状态为已使用（`status=1`）
- [ ] 记录使用用户ID和代理ID
- [ ] 记录使用时间

#### 2.1.6 Token生成
- [ ] 生成JWT Token
- [ ] 返回给前端

**测试场景**：
1. 正常流程：使用有效邀请码注册
2. 边界条件：邀请码不存在、已使用、已过期
3. 重复注册：已是代理的用户再次申请
4. 关系验证：下级等级高于上级的情况

---

### 2.2 推广链接生成链路

**入口**：`POST /api/v1/agent/generating_link`

**检查点**：

#### 2.2.1 代理身份验证
- [ ] **文件**：`app/main/api/internal/logic/agent/generatinglinklogic.go`
- [ ] 从Token获取用户ID
- [ ] 查询 `agent` 表验证代理身份
- [ ] 非代理用户拒绝

#### 2.2.2 价格计算
- [ ] 获取系统配置（`base_price`, `system_max_price`）
- [ ] 计算实际底价 = 基础底价 + 等级加成
  - 普通代理：+6元
  - 黄金代理：+3元
  - 钻石代理：+0元
- [ ] 验证设定价格范围：`实际底价 ≤ 设定价格 ≤ 系统价格上限`

#### 2.2.3 链接生成
- [ ] 检查是否已存在相同链接（`agent_id + product_id + set_price`）
- [ ] 构建 `AgentIdentifier` 结构（`AgentID`, `ProductID`, `SetPrice`）
- [ ] JSON序列化并AES加密生成 `LinkIdentifier`
- [ ] 保存到 `agent_link` 表
- [ ] 记录 `set_price` 和 `actual_base_price`

**测试场景**：
1. 正常生成：有效代理生成推广链接
2. 价格验证：设定价格低于实际底价或高于系统上限
3. 重复链接：相同代理、产品、价格的链接复用

---

### 2.3 订单处理与收益分配链路

**入口**：`POST /api/v1/pay/payment` → 支付回调 → `AgentService.AgentProcess`

**检查点**：

#### 2.3.1 订单创建
- [ ] **文件**：`app/main/api/internal/logic/pay/paymentlogic.go`
- [ ] 解析推广链接标识（解密 `LinkIdentifier`）
- [ ] 查询 `agent_link` 表验证链接有效性
- [ ] 创建 `order` 记录（订单金额 = SetPrice）
- [ ] 创建 `agent_order` 记录：
  - `order_amount` = SetPrice
  - `set_price` = 设定价格
  - `actual_base_price` = 实际底价（基础底价+等级加成）
  - `price_cost` = 提价成本
  - `agent_profit` = 代理收益（SetPrice - ActualBasePrice - PriceCost）
  - `process_status` = 0（待处理）

#### 2.3.2 支付成功处理
- [ ] 支付回调验证签名
- [ ] 更新订单状态
- [ ] 触发 `AgentService.AgentProcess`

#### 2.3.3 代理订单处理
- [ ] **文件**：`app/main/api/internal/service/agentService.go` - `AgentProcess`
- [ ] 检查是否是代理订单（查询 `agent_order` 表）
- [ ] 检查订单是否已处理（`process_status=1` 防重复）
- [ ] 获取代理信息和系统配置
- [ ] 使用事务处理：
  - 更新 `agent_order` 状态为处理成功
  - 创建 `agent_commission` 记录
  - 更新 `agent_wallet`（`balance += agent_profit`, `total_earnings += agent_profit`）

#### 2.3.4 等级加成返佣分配
- [ ] **文件**：`app/main/api/internal/service/agentService.go` - `distributeLevelBonus`
- [ ] **普通代理（6元）**：
  - [ ] 给直接上级（最多3元）
  - [ ] 剩余给钻石上级（如有）
  - [ ] 如果无钻石上级，给黄金上级（最多3元）
- [ ] **黄金代理（3元）**：
  - [ ] 全部给钻石上级（如有）
- [ ] **钻石代理（0元）**：
  - [ ] 无返佣
- [ ] 创建 `agent_rebate` 记录
- [ ] 更新上级钱包余额

**测试场景**：
1. 正常订单：普通代理订单，验证收益和返佣分配
2. 防重复：已处理订单再次处理
3. 返佣分配：不同等级代理的返佣分配逻辑
4. 无上级：没有上级代理时的返佣处理

---

### 2.4 代理升级链路

#### 2.4.1 自主付费升级

**入口**：`POST /api/v1/agent/upgrade/apply`

**检查点**：
- [ ] **文件**：`app/main/api/internal/logic/agent/applyupgradelogic.go`
- [ ] 验证升级条件（普通→黄金、普通→钻石、黄金→钻石）
- [ ] 计算升级费用和返佣
- [ ] 查找原直接上级（用于返佣）
- [ ] 创建 `agent_upgrade` 记录（`status=1` 待处理）
- [ ] 支付成功后调用 `AgentService.ProcessUpgrade`
- [ ] **升级处理**：
  - [ ] 返佣给原直接上级（如需要）
  - [ ] 更新代理等级
  - [ ] 检查是否需要脱离直接上级关系
  - [ ] 更新团队首领（升级为钻石时独立成团队）
  - [ ] 更新所有下级的 `team_leader_id`

#### 2.4.2 钻石升级下级

**入口**：`POST /api/v1/agent/upgrade/subordinate`

**检查点**：
- [ ] **文件**：`app/main/api/internal/logic/agent/upgradesubordinatelogic.go`
- [ ] 验证权限（必须是钻石代理）
- [ ] 验证下级等级（只能是普通代理）
- [ ] 验证关系（必须是直接下级）
- [ ] 验证目标等级（只能升级为黄金）
- [ ] 创建升级记录（`upgrade_type=2`，`upgrade_fee=0`）
- [ ] 执行升级操作

**测试场景**：
1. 正常升级：普通→黄金，验证返佣和关系脱离
2. 升级为钻石：验证团队独立
3. 钻石升级下级：验证权限和限制
4. 关系脱离：升级后等级高于上级的情况

---

### 2.5 实名认证链路

**入口**：`POST /api/v1/agent/real_name`

**检查点**：
- [ ] **文件**：`app/main/api/internal/logic/agent/realnameauthlogic.go`
- [ ] 验证代理身份
- [ ] 验证手机号是否匹配
- [ ] 验证手机验证码
- [ ] 三要素核验（姓名、身份证号、手机号）
- [ ] 加密身份证号和手机号
- [ ] 保存实名认证记录（`verify_time` 不为空表示已通过）
- [ ] 无需人工审核，核验通过即生效

**测试场景**：
1. 正常认证：三要素核验通过
2. 核验失败：三要素不匹配
3. 手机号不匹配：与代理注册手机号不一致

---

### 2.6 提现链路

**入口**：`POST /api/v1/agent/withdrawal/apply`

**检查点**：

#### 2.6.1 提现申请
- [ ] **文件**：`app/main/api/internal/logic/agent/applywithdrawallogic.go`
- [ ] 验证实名认证（`verify_time` 不为空）
- [ ] 验证提现金额（> 0）
- [ ] 验证钱包余额（`balance >= amount`）
- [ ] 计算税费：
  - 查询本月累计提现金额
  - 计算剩余免税额度
  - 计算应税金额和税费
- [ ] 冻结余额（`frozen_balance += amount`, `balance -= amount`）
- [ ] 创建 `agent_withdrawal` 记录（`status=1` 待审核）
- [ ] 创建 `agent_withdrawal_tax` 记录（`tax_status=1` 待扣税）

#### 2.6.2 提现审核
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/adminauditwithdrawallogic.go`
- [ ] 审核通过：调用支付宝转账接口
- [ ] 审核拒绝：解冻余额
- [ ] 转账成功：解冻并扣除余额，更新扣税状态
- [ ] 转账失败：解冻余额

**测试场景**：
1. 正常提现：实名认证通过，余额充足
2. 税费计算：验证月度累计和免税额度
3. 余额不足：提现金额大于余额
4. 未实名：未完成实名认证

---

## 三、查询接口检查

### 3.1 代理信息查询
- [ ] **文件**：`app/main/api/internal/logic/agent/getagentinfologic.go`
- [ ] 查询代理基本信息
- [ ] 查询实名认证状态（`verify_time` 不为空）
- [ ] 处理可选字段（`region`, `wechat_id`）

### 3.2 收益信息查询
- [ ] **文件**：`app/main/api/internal/logic/agent/getrevenueinfologic.go`
- [ ] 查询钱包余额和累计收益
- [ ] 返回 `balance`, `frozen_balance`, `total_earnings`, `withdrawn_amount`

### 3.3 佣金记录查询
- [ ] **文件**：`app/main/api/internal/logic/agent/getcommissionlistlogic.go`
- [ ] 分页查询佣金记录
- [ ] 关联查询产品名称

### 3.4 返佣记录查询
- [ ] **文件**：`app/main/api/internal/logic/agent/getrebatelistlogic.go`
- [ ] 分页查询返佣记录
- [ ] 显示返佣类型和金额

### 3.5 团队统计查询
- [ ] **文件**：`app/main/api/internal/logic/agent/getteamstatisticslogic.go`
- [ ] 递归查询所有下级（直接+间接）
- [ ] 统计总人数、按等级统计
- [ ] 权限检查（只能查看自己团队）

### 3.6 下级列表查询
- [ ] **文件**：`app/main/api/internal/logic/agent/getsubordinatelistlogic.go`
- [ ] 分页查询直接下级
- [ ] 显示下级等级和信息

---

## 四、邀请码管理检查

### 4.1 生成邀请码
- [ ] **文件**：`app/main/api/internal/logic/agent/generateinvitecodelogic.go`
- [ ] 验证代理身份
- [ ] 生成唯一邀请码
- [ ] 设置目标等级（默认1=普通）
- [ ] 保存到 `agent_invite_code` 表

### 4.2 邀请码列表
- [ ] **文件**：`app/main/api/internal/logic/agent/getinvitecodelistlogic.go`
- [ ] 查询代理生成的邀请码
- [ ] 显示状态（未使用、已使用、已失效）

### 4.3 邀请链接
- [ ] **文件**：`app/main/api/internal/logic/agent/getinvitelinklogic.go`
- [ ] 生成邀请链接和二维码
- [ ] 链接包含邀请码信息

### 4.4 后台生成钻石邀请码
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/admingeneratediamondinvitecodelogic.go`
- [ ] 管理员生成钻石邀请码
- [ ] 目标等级为3（钻石）
- [ ] 无发放代理ID（平台发放）

---

## 五、后台管理接口检查

### 5.1 代理列表查询
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/admingetagentlistlogic.go`
- [ ] 分页查询代理列表
- [ ] 显示代理等级、实名状态
- [ ] 处理可选字段（`region`, `wechat_id`）

### 5.2 代理订单查询
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/admingetagentorderlistlogic.go`
- [ ] 分页查询代理订单
- [ ] 显示订单金额、代理收益、处理状态

### 5.3 系统配置管理
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/admingetagentconfiglogic.go`
- [ ] 查询系统配置
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/adminupdateagentconfiglogic.go`
- [ ] 更新系统配置

### 5.4 产品配置管理
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/admingetagentproductconfiglistlogic.go`
- [ ] 查询产品配置列表
- [ ] **文件**：`app/main/api/internal/logic/admin_agent/adminupdateagentproductconfiglogic.go`
- [ ] 更新产品配置

---

## 六、关键业务逻辑验证

### 6.1 关系约束验证
- [ ] 下级等级不能高于上级
- [ ] 同级不能作为上下级（除了普通代理）
- [ ] 钻石可以拥有黄金下级（钻石等级高于黄金）
- [ ] 升级后关系脱离逻辑（根据上级等级判断）

### 6.2 团队首领逻辑
- [ ] 钻石代理独立成团队（`team_leader_id = 自己`）
- [ ] 普通/黄金代理指向上级链中的钻石代理
- [ ] 升级为钻石时，所有下级跟随到新团队

### 6.3 价格计算逻辑
- [ ] 实际底价 = 基础底价 + 等级加成
- [ ] 提价成本计算（当设定价格 > 提价阈值时）
- [ ] 代理收益 = 设定价格 - 实际底价 - 提价成本

### 6.4 返佣分配逻辑
- [ ] 普通代理6元：直接上级3元，剩余给钻石/黄金上级
- [ ] 黄金代理3元：全部给钻石上级
- [ ] 钻石代理0元：无返佣

### 6.5 税费计算逻辑
- [ ] 月度累计提现金额查询
- [ ] 剩余免税额度计算
- [ ] 应税金额和税费计算

---

## 七、数据一致性检查

### 7.1 事务完整性
- [ ] 代理注册：用户创建、代理创建、钱包初始化、关系建立、邀请码更新在同一事务
- [ ] 订单处理：订单状态更新、佣金发放、返佣分配在同一事务
- [ ] 升级处理：等级更新、关系脱离、团队首领更新在同一事务
- [ ] 提现申请：余额冻结、提现记录、扣税记录在同一事务

### 7.2 乐观锁
- [ ] 所有更新操作使用 `version` 字段
- [ ] 使用 `UpdateWithVersion` 方法
- [ ] 更新失败时正确处理

### 7.3 防重复处理
- [ ] 订单处理前检查 `process_status`
- [ ] 升级处理前检查 `status`
- [ ] 邀请码使用后立即更新状态

---

## 八、边界条件和异常处理

### 8.1 边界条件
- [ ] 邀请码不存在、已使用、已过期
- [ ] 已是代理的用户再次申请
- [ ] 下级等级高于上级的情况
- [ ] 设定价格低于实际底价或高于系统上限
- [ ] 余额不足的提现申请
- [ ] 未完成实名认证的提现申请

### 8.2 异常处理
- [ ] 数据库操作失败的回滚
- [ ] 三要素核验失败的处理
- [ ] 支付回调失败的处理
- [ ] 转账失败的处理

---

## 九、性能和安全检查

### 9.1 性能优化
- [ ] 批量查询避免N+1问题
- [ ] 索引使用（`agent_relation`, `agent_rebate`, `agent_order`）
- [ ] 递归深度限制（查找上级链时）

### 9.2 安全考虑
- [ ] 手机号、身份证号加密存储
- [ ] 推广链接标识加密传输
- [ ] 权限控制（代理只能查看自己的数据）
- [ ] 金额精度（使用 `decimal` 类型）

---

## 十、测试建议

### 10.1 单元测试
- [ ] 价格计算函数
- [ ] 税费计算函数
- [ ] 返佣分配函数
- [ ] 关系验证函数

### 10.2 集成测试
- [ ] 完整注册流程
- [ ] 完整订单处理流程
- [ ] 完整升级流程
- [ ] 完整提现流程

### 10.3 压力测试
- [ ] 并发订单处理
- [ ] 并发提现申请
- [ ] 大量下级查询

---

## 检查顺序建议

1. **第一阶段**：基础数据检查（1.1, 1.2）
2. **第二阶段**：核心业务流程（2.1, 2.2, 2.3）
3. **第三阶段**：升级和实名认证（2.4, 2.5）
4. **第四阶段**：提现流程（2.6）
5. **第五阶段**：查询接口（三、四）
6. **第六阶段**：后台管理（五）
7. **第七阶段**：业务逻辑验证（六、七、八）
8. **第八阶段**：性能和安全（九）

---

**检查完成后，建议**：
1. 记录发现的问题
2. 修复问题后重新检查
3. 编写测试用例覆盖关键流程
4. 进行端到端测试验证