team/ycc-proxy-server
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08ff223ff82e2d11fcf12eaf28baae3de5113db8
ycc-proxy-server/新代理系统检查清单.md
liangzai 08ff223ff8 v1.0
2025-12-02 19:57:10 +08:00

17 KiB
Raw Blame History

新代理系统完整检查清单

检查说明

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

检查原则：

  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. 进行端到端测试验证