ycc-proxy-server/代理系统测试用例清单.md

# 代理系统测试用例清单

## 一、邀请下级代理测试

### 1.1 钻石代理邀请下级
- [ ] **钻石邀请普通代理**
  - 预期：建立上下级关系，普通代理的 team_leader_id 指向钻石代理
  - 验证：关系类型为直接关系，团队首领正确
  
- [ ] **钻石邀请黄金代理**
  - 预期：建立上下级关系，黄金代理的 team_leader_id 指向钻石代理
  - 验证：关系类型为直接关系，团队首领正确
  
- [ ] **钻石邀请钻石代理（不允许）**
  - 预期：拒绝，提示"代理等级不能高于上级代理"
  - 验证：邀请失败，无关系建立

### 1.2 黄金代理邀请下级
- [ ] **黄金邀请普通代理**
  - 预期：建立上下级关系，普通代理的 team_leader_id 指向上级钻石代理
  - 验证：关系类型为直接关系，团队首领正确（向上查找钻石）
  
- [ ] **黄金邀请黄金代理（不允许）**
  - 预期：拒绝，提示"代理等级不能高于上级代理"
  - 验证：邀请失败，无关系建立
  
- [ ] **黄金邀请钻石代理（不允许）**
  - 预期：拒绝，提示"代理等级不能高于上级代理"
  - 验证：邀请失败，无关系建立

### 1.3 普通代理邀请下级
- [ ] **普通邀请普通代理**
  - 预期：建立上下级关系，普通代理的 team_leader_id 向上查找钻石/黄金
  - 验证：关系类型为直接关系，团队首领正确
  
- [ ] **普通邀请黄金代理（不允许）**
  - 预期：拒绝，提示"代理等级不能高于上级代理"
  - 验证：邀请失败，无关系建立
  
- [ ] **普通邀请钻石代理（不允许）**
  - 预期：拒绝，提示"代理等级不能高于上级代理"
  - 验证：邀请失败，无关系建立

### 1.4 多层级邀请测试
- [ ] **钻石 → 黄金 → 普通（3层）**
  - 预期：3层关系链，所有代理的 team_leader_id 指向钻石
  - 验证：关系链正确，团队首领一致
  
- [ ] **钻石 → 普通 → 普通 → 普通（4层）**
  - 预期：4层关系链，所有代理的 team_leader_id 指向钻石
  - 验证：关系链正确，团队首领一致
  
- [ ] **钻石 → 普通 → 普通 → 普通 → 普通（5层）**
  - 预期：5层关系链，所有代理的 team_leader_id 指向钻石
  - 验证：关系链正确，团队首领一致

---

## 二、推广报告收益测试（等级加成返佣）

### 2.1 钻石代理推广报告
- [ ] **钻石代理自己推广的报告**
  - 等级加成：0元
  - 预期：无等级加成返佣，全部收益归自己
  - 验证：agent_rebate 表无记录，代理收益 = 设定价格 - 基础底价 - 提价成本

### 2.2 黄金代理推广报告
- [ ] **黄金代理（上级是钻石）推广报告**
  - 等级加成：3元
  - 预期：3元全部返佣给钻石上级
  - 验证：agent_rebate 表记录正确，钻石上级钱包增加3元
  
- [ ] **黄金代理（无上级/上级不是钻石）推广报告**
  - 等级加成：3元
  - 预期：返佣归平台（异常情况）
  - 验证：agent_rebate 表无记录

### 2.3 普通代理推广报告（等级加成6元）

#### 2.3.1 直接上级是钻石
- [ ] **普通代理（上级是钻石）推广报告**
  - 等级加成：6元
  - 预期：6元全部返佣给钻石上级
  - 验证：agent_rebate 表记录正确，钻石上级钱包增加6元

#### 2.3.2 直接上级是黄金
- [ ] **普通代理（上级是黄金，黄金上级是钻石）推广报告**
  - 等级加成：6元
  - 预期：
    - 3元给黄金上级（配置：normal_to_gold_rebate）
    - 3元给钻石上级（上上级）
  - 验证：agent_rebate 表有2条记录，金额分配正确

- [ ] **普通代理（上级是黄金，无钻石上级）推广报告**
  - 等级加成：6元
  - 预期：3元给黄金上级，剩余3元归平台
  - 验证：agent_rebate 表只有1条记录（3元给黄金），剩余归平台

#### 2.3.3 直接上级是普通（多层普通代理）
- [ ] **普通 → 普通 → 钻石（3层）**
  - 等级加成：6元
  - 预期：
    - 2元给直接上级普通（配置：normal_to_normal_rebate）
    - 4元给钻石上级（跳过中间普通，直接给钻石）
  - 验证：agent_rebate 表有2条记录，金额分配正确
  
- [ ] **普通 → 普通 → 普通 → 钻石（4层）**
  - 等级加成：6元
  - 预期：
    - 2元给直接上级普通
    - 4元给钻石上级（跳过中间所有普通代理）
  - 验证：agent_rebate 表有2条记录，金额分配正确
  
- [ ] **普通 → 普通 → 黄金（无钻石，3层）**
  - 等级加成：6元
  - 预期：
    - 2元给直接上级普通
    - 3元给黄金上级（配置：normal_to_gold_rebate_max）
    - 1元归平台（超出部分）
  - 验证：agent_rebate 表有2条记录，金额分配正确，剩余归平台
  
- [ ] **普通 → 普通 → 普通（全部是普通，无钻石/黄金）**
  - 等级加成：6元
  - 预期：
    - 2元给直接上级普通
    - 4元归平台（无钻石/黄金上级）
  - 验证：agent_rebate 表只有1条记录（2元），剩余归平台

---

## 三、升级代理收益测试

### 3.1 自主付费升级

#### 3.1.1 普通 → 黄金（199元）
- [ ] **普通代理升级为黄金（上级是钻石）**
  - 升级费用：199元
  - 返佣：139元给原直接上级
  - 预期：
    - 原直接上级（钻石）钱包增加139元
    - 升级后不脱离关系（钻石 > 黄金）
    - 仍属于原团队
  - 验证：升级成功，返佣记录在 agent_upgrade 表，钱包余额正确
  
- [ ] **普通代理升级为黄金（上级是黄金）**
  - 升级费用：199元
  - 返佣：139元给原直接上级（黄金）
  - 预期：
    - 原直接上级（黄金）钱包增加139元
    - 升级后脱离关系（同级不能作为上下级）
    - 保留团队关系（向上查找钻石）
  - 验证：升级成功，关系脱离，团队首领正确
  
- [ ] **普通代理升级为黄金（上级是普通）**
  - 升级费用：199元
  - 返佣：139元给原直接上级（普通）
  - 预期：
    - 原直接上级（普通）钱包增加139元
    - 升级后脱离关系（下级等级高于上级）
    - 保留团队关系（向上查找钻石/黄金）
  - 验证：升级成功，关系脱离，团队首领正确

#### 3.1.2 普通 → 钻石（980元）
- [ ] **普通代理升级为钻石（上级是钻石）**
  - 升级费用：980元
  - 返佣：680元给原直接上级（钻石）
  - 预期：
    - 原直接上级（钻石）钱包增加680元
    - 升级后脱离关系（同级不能作为上下级）
    - 独立成为新团队，team_leader_id = 自己
    - 所有下级跟随到新团队
  - 验证：升级成功，独立成团队，下级团队首领更新
  
- [ ] **普通代理升级为钻石（上级是黄金）**
  - 升级费用：980元
  - 返佣：680元给原直接上级（黄金）
  - 预期：
    - 原直接上级（黄金）钱包增加680元
    - 升级后脱离关系（下级等级高于上级）
    - 独立成为新团队，team_leader_id = 自己
    - 所有下级跟随到新团队
  - 验证：升级成功，独立成团队，下级团队首领更新
  
- [ ] **普通代理升级为钻石（上级是普通）**
  - 升级费用：980元
  - 返佣：680元给原直接上级（普通）
  - 预期：
    - 原直接上级（普通）钱包增加680元
    - 升级后脱离关系（下级等级高于上级）
    - 独立成为新团队，team_leader_id = 自己
    - 所有下级跟随到新团队
  - 验证：升级成功，独立成团队，下级团队首领更新

#### 3.1.3 黄金 → 钻石（980元）
- [ ] **黄金代理升级为钻石（上级是钻石）**
  - 升级费用：980元
  - 返佣：680元给原直接上级（钻石）
  - 预期：
    - 原直接上级（钻石）钱包增加680元
    - 升级后脱离关系（同级不能作为上下级）
    - 独立成为新团队，team_leader_id = 自己
    - 所有下级跟随到新团队
  - 验证：升级成功，独立成团队，下级团队首领更新
  
- [ ] **黄金代理升级为钻石（无上级）**
  - 升级费用：980元
  - 返佣：无
  - 预期：
    - 独立成为新团队，team_leader_id = 自己
    - 所有下级跟随到新团队
  - 验证：升级成功，独立成团队，下级团队首领更新

### 3.2 钻石升级下级（免费）
- [ ] **钻石升级下级（普通 → 黄金）**
  - 升级费用：免费
  - 返佣：无
  - 预期：
    - 被升级代理无需付费
    - 升级后根据原上级等级决定是否脱离关系
    - 保留团队关系
  - 验证：升级成功，费用为0，关系处理正确

---

## 四、升级后团队转移测试

### 4.1 普通 → 黄金升级（保留团队）

#### 4.1.1 上级是钻石（不脱离）
- [ ] **普通 → 黄金（上级是钻石），有下级**
  - 预期：
    - 不脱离关系
    - 保留原团队（team_leader_id 不变）
    - 所有下级（直接+间接）的 team_leader_id 不变
  - 验证：关系保留，所有下级团队首领不变

#### 4.1.2 上级是黄金（脱离关系）
- [ ] **普通 → 黄金（上级是黄金），有下级**
  - 预期：
    - 脱离直接上下级关系
    - 保留团队关系（向上查找钻石）
    - 所有下级（直接+间接）的 team_leader_id 不变
  - 验证：关系脱离（RelationType=2），所有下级团队首领不变

#### 4.1.3 上级是普通（脱离关系）
- [ ] **普通 → 黄金（上级是普通），有下级**
  - 预期：
    - 脱离直接上下级关系
    - 保留团队关系（向上查找钻石/黄金）
    - 所有下级（直接+间接）的 team_leader_id 不变
  - 验证：关系脱离，所有下级团队首领不变

### 4.2 升级为钻石（独立成新团队）

#### 4.2.1 普通 → 钻石
- [ ] **普通 → 钻石（上级是钻石），有下级**
  - 预期：
    - 脱离关系
    - 独立成新团队（team_leader_id = 自己）
    - 所有直接下级的 team_leader_id 更新为自己
    - 所有间接下级的 team_leader_id 更新为自己（递归）
  - 验证：
    - 升级代理的 team_leader_id = 自己
    - 所有下级（直接+间接）的 team_leader_id = 升级代理ID
    - 下级数量统计正确
  
- [ ] **普通 → 钻石（上级是黄金），有下级（2层）**
  - 预期：
    - 脱离关系
    - 独立成新团队
    - 直接下级跟随
    - 间接下级跟随
  - 验证：所有下级团队首领更新为新钻石
  
- [ ] **普通 → 钻石（上级是普通），有下级（3层以上）**
  - 预期：
    - 脱离关系
    - 独立成新团队
    - 所有层级的下级都跟随
  - 验证：所有下级团队首领更新为新钻石

#### 4.2.2 黄金 → 钻石
- [ ] **黄金 → 钻石（上级是钻石），有下级**
  - 预期：
    - 脱离关系
    - 独立成新团队
    - 所有下级跟随
  - 验证：所有下级团队首领更新为新钻石

### 4.3 复杂团队转移场景

#### 4.3.1 多层级团队
- [ ] **钻石A → 黄金B → 普通C → 普通D，B升级为钻石**
  - 预期：
    - B独立成新团队
    - C和D的 team_leader_id 更新为B
    - A的团队：只剩自己
    - B的团队：B、C、D
  - 验证：团队划分正确，关系链正确

#### 4.3.2 跨团队转移
- [ ] **钻石A → 普通B → 普通C，C升级为钻石**
  - 预期：
    - C独立成新团队
    - C无下级，团队只有C自己
    - A的团队：A、B
  - 验证：团队划分正确

#### 4.3.3 深度层级转移
- [ ] **钻石A → 普通B → 普通C → 普通D → 普通E，C升级为钻石**
  - 预期：
    - C独立成新团队
    - D和E的 team_leader_id 更新为C
    - A的团队：A、B
    - C的团队：C、D、E
  - 验证：团队划分正确，所有层级更新正确

---

## 五、综合测试场景

### 5.1 完整业务流程
- [ ] **创建团队 → 邀请下级 → 推广报告 → 收益分配 → 升级 → 团队转移**
  - 步骤：
    1. 创建钻石代理A
    2. A邀请黄金代理B
    3. B邀请普通代理C
    4. C邀请普通代理D
    5. D推广报告，验证收益分配
    6. C升级为黄金，验证关系变化
    7. B升级为钻石，验证团队转移
  - 验证：每个步骤的数据正确

### 5.2 收益统计测试
- [ ] **查询代理收益统计（包含佣金和返佣）**
  - 验证：agent_wallet 表的 Balance 和 TotalEarnings 正确
  
- [ ] **查询下级列表和统计**
  - 验证：下级数量、团队规模统计正确

### 5.3 边界情况测试
- [ ] **钻石代理无下级时升级（边界情况）**
  - 验证：独立成团队，team_leader_id = 自己
  
- [ ] **普通代理无上级时升级**
  - 验证：独立成团队，无返佣

- [ ] **多层普通代理链，无钻石/黄金上级**
  - 验证：收益分配正确（部分归平台）

---

## 六、数据验证检查点

### 6.1 关系表验证
- [ ] agent_relation 表的关系类型正确（1=直接关系，2=已脱离）
- [ ] 脱离关系时，DetachReason 和 DetachTime 正确记录

### 6.2 钱包验证
- [ ] agent_wallet 表的 Balance（可用余额）正确
- [ ] agent_wallet 表的 FrozenBalance（冻结余额）正确（如有）
- [ ] agent_wallet 表的 TotalEarnings（累计收益）正确

### 6.3 返佣记录验证
- [ ] agent_rebate 表的记录完整（推广报告返佣）
- [ ] agent_upgrade 表的返佣记录正确（升级返佣）
- [ ] 返佣金额计算正确

### 6.4 团队验证
- [ ] agent 表的 team_leader_id 正确指向钻石代理
- [ ] 升级后所有下级 team_leader_id 更新正确

### 6.5 订单和佣金验证
- [ ] agent_order 表记录完整
- [ ] agent_commission 表记录完整
- [ ] 佣金金额计算正确

---

## 七、测试数据准备建议

### 7.1 创建测试代理账号
建议准备以下测试账号（可用不同手机号）：

1. **钻石代理**：
   - 钻石A（团队首领，无上级）
   - 钻石B（团队首领，无上级）

2. **黄金代理**：
   - 黄金A（上级：钻石A）
   - 黄金B（上级：钻石A）
   - 黄金C（上级：钻石B）

3. **普通代理**：
   - 普通A（上级：钻石A）
   - 普通B（上级：黄金A）
   - 普通C（上级：普通B）
   - 普通D（上级：普通C）
   - 普通E（上级：普通D）

### 7.2 测试产品配置
- [ ] 确保有测试产品配置（agent_product_config 表）
- [ ] 配置基础底价、提价阈值、提价手续费比例

### 7.3 测试返佣配置
- [ ] normal_to_normal_rebate（默认2元）
- [ ] normal_to_gold_rebate（默认3元）
- [ ] normal_to_gold_rebate_max（默认3元）

---

## 八、测试执行顺序建议

1. **第一阶段**：基础功能测试
   - 邀请下级（各种组合）
   - 验证关系建立
   - 验证团队首领

2. **第二阶段**：收益分配测试
   - 推广报告
   - 收益计算
   - 返佣分配

3. **第三阶段**：升级功能测试
   - 自主付费升级
   - 钻石升级下级
   - 升级返佣

4. **第四阶段**：团队转移测试
   - 普通→黄金升级（保留团队）
   - 升级为钻石（独立成团队）
   - 复杂场景测试

5. **第五阶段**：综合测试
   - 完整业务流程
   - 边界情况
   - 数据一致性验证

---

## 注意事项

1. **开发环境**：测试时确保使用开发环境（ENV=development），可跳过验证码校验
2. **数据清理**：每次测试后建议清理测试数据，避免相互影响
3. **事务验证**：注意验证事务的一致性，确保要么全部成功，要么全部回滚
4. **并发测试**：如有需要，可进行并发场景测试（多代理同时升级等）
5. **日志记录**：测试过程中查看日志，确保业务流程正确