# 分销 + 区域代理 联合手动测试流程

> 测试用户 ID 段：**910001 ~ 910009**  
> 统一登录密码：**Test@123456**  
> 默认测试区域：**贵州省 / 贵阳市 / 南明区**（area_id=520102）

---

## 一、脚本使用（服务器项目根目录执行）

### 1. 一键重置（推荐）

```bash
# 清理旧数据 + 重新生成全部测试用户/配置
php addons/shopro/tests/dist_regional_reset.php

# 指定测试商品
php addons/shopro/tests/dist_regional_reset.php --goods-id=195

# 不写入 mock 示例佣金（仅用户/代理/地址）
php addons/shopro/tests/dist_regional_reset.php --no-income

# 预览将删除的数据（不执行）
php addons/shopro/tests/dist_regional_reset.php --dry-run
```

### 2. 分步执行

```bash
# 仅清理
php addons/shopro/tests/regional_agent_cleanup_test_users.php --dry-run
php addons/shopro/tests/regional_agent_cleanup_test_users.php --confirm

# 仅生成
php addons/shopro/tests/regional_agent_setup_test_users.php
php addons/shopro/tests/regional_agent_setup_test_users.php --goods-id=195 --money=10000
```

### 3. SQL 方式（无法跑 PHP 时）

```bash
# 清理
mysql -u用户 -p 数据库 < addons/shopro/tests/dist_regional_test_cleanup.sql

# 初始化（备份方案，功能少于 PHP 脚本）
mysql -u用户 -p 数据库 < addons/shopro/tests/regional_agent_test_data.sql
```

---

## 二、测试账号一览

| 用户ID | 手机号 | 昵称 | 角色 |
|--------|--------|------|------|
| 910001 | 19900000011 | 区域-省级代理 | 贵州省区域代理 |
| 910002 | 19900000012 | 区域-市级代理 | 贵阳市区域代理 |
| 910003 | 19900000013 | 区域-区县代理 | 南明区区域代理 |
| 910004 | 19900000014 | 区域-买家主测 | 纯区域测试买家 |
| 910005 | 19900000015 | 区域-买家备用 | 备用买家 |
| 910006 | 19900000016 | 区域测-分销三级 | 钻石分销商 A |
| 910007 | 19900000017 | 区域测-分销二级 | 黄金分销商 B |
| 910008 | 19900000018 | 区域测-分销一级 | 白银分销商 C（直推） |
| 910009 | 19900000019 | 区域-买家D | **联合测试主买家** |

### 关系结构

```
分销链：910006(钻石A) ← 910007(黄金B) ← 910008(白银C) ← 910009(买家D)

区域代理：收货地址落在「贵州省/贵阳市/南明区」时
  → 910001 省 3%
  → 910002 市 2%
  → 910003 区县 1%
  （叠加模式 stack，默认配置）
```

**910006（19900000016）团队统计预期**（setup 脚本会自动刷新 `child_user_count*` / `child_agent_count*`）：

| 指标 | 预期值 |
|------|--------|
| 团队总人数 | 3（910007+910008+910009） |
| 一级成员 | 1（910007） |
| 二级成员 | 1（910008） |
| 团队分销商 | 2（910007、910008；910009 为买家非分销商） |

### 脚本自动配置

| 模块 | 配置项 | 测试值 |
|------|--------|--------|
| 分销 | commission_mode | differential（级差+管理奖） |
| 分销 | 等级档位 | 白银40/5% 黄金80/10% 钻石120/15% |
| 分销 | 复购 | 推荐人继续分佣 + 本人固定返现5元 |
| 分销 | 结算时机 | 支付后（payed） |
| 分销 | 团队统计 | 初始化后自动刷新（小程序「我的团队」可直接用） |
| 区域 | commission_mode | stack（省+市+区叠加） |
| 区域 | 等级比例 | 省3% / 市2% / 区县1% |
| 区域 | 结算时机 | 支付后（payed） |
| 商品 | regional_enable | 1（参与区域分佣） |
| 商品 | differential_enable / management_enable | 1（参与级差/管理奖） |

---

## 三、手动测试场景

### 场景 A：联合测试（分销 + 区域代理同时触发）★ 推荐

**目的：** 一笔订单同时验证两套分佣互不干扰。

1. 执行 `dist_regional_reset.php` 重置数据
2. 小程序用 **19900000019（买家D）** 登录
3. 选择脚本输出的测试商品，确认默认收货地址为「贵州省/贵阳市/南明区」
4. 余额支付完成
5. 服务器验证：

```bash
# 从后台订单列表或数据库获取 order_id、order_item_id
php addons/shopro/tests/commission_verify.php verify-item {订单明细ID}
php addons/shopro/tests/regional_agent_verify.php verify-order {订单ID}
```

6. 后台核对：
   - **分销 → 佣金明细**：910008/910007/910006 应有级差奖 + 管理奖
   - **区域代理 → 佣金明细**：910001/910002/910003 各一条区域佣金

**预期（实付 1000 元举例）：**

| 类型 | 受益人 | 预期 |
|------|--------|------|
| 级差奖 | 910008 白银C | 40 元 |
| 级差奖 | 910007 黄金B | 40 元 |
| 级差奖 | 910006 钻石A | 40 元 |
| 管理奖 | 910008 | 50 元（5%） |
| 管理奖 | 910007 | 100 元（10%） |
| 管理奖 | 910006 | 150 元（15%） |
| 区域 | 910001 省 | 30 元（3%） |
| 区域 | 910002 市 | 20 元（2%） |
| 区域 | 910003 区县 | 10 元（1%） |

> 实际金额以商品实付为准，比例不变。

---

### 场景 B：仅区域代理

**目的：** 不触发分销链，只测区域匹配。

1. 用 **19900000014（买家主测）** 登录下单（该用户无上级分销商）
2. 验证：

```bash
php addons/shopro/tests/regional_agent_verify.php verify-order {订单ID}
```

3. 预期：仅 910001/910002/910003 有区域佣金，分销佣金表无记录

---

### 场景 C：分销商自购

**目的：** 验证自购时级差跳过本人、管理奖本人仍拿。

1. 用 **19900000018（白银C）** 登录自己下单
2. 验证分销佣金：
   - 910008 **无级差奖**
   - 910007、910006 级差照常
   - 910008 **有管理奖**（5%）
3. 区域代理仍按收货地址匹配（若地址在测试区域）

---

### 场景 D：复购测试

**目的：** 第二单触发复购本人返现。

1. 用 **19900000019** 先下一单（首购）
2. 再下一单（复购）
3. 第二单预期：
   - 分销链级差+管理奖照常（repurchase_referrer_enable=1）
   - 买家D 额外获得 **5 元复购返现**（repurchase_self_enable=1）

---

### 场景 E：区域分佣模式切换

**目的：** 测试 stack / exclusive / differential 三种模式。

1. 后台 → 区域代理 → 代理设置 → 修改「分佣模式」
2. 清理上一单佣金或用新买家下单
3. 对比三种模式下省/市/区县佣金金额变化

| 模式 | 1000元实付预期（3%/2%/1%） |
|------|---------------------------|
| stack 叠加 | 省30 + 市20 + 区10 = 60 |
| exclusive 独占 | 仅区县 10 |
| differential 级差 | 省10 + 市10 + 区10 = 30 |

---

## 四、后台检查清单

- [ ] 区域代理 → 代理列表：910001~910003 状态正常、区域正确
- [ ] 区域代理 → 代理等级：省3%/市2%/区县1%
- [ ] 区域代理 → 佣金明细：订单号、佣金规则、结算状态
- [ ] 分销 → 分销商：910006~910008 等级与上下级正确
- [ ] 分销 → 佣金明细：award_type 区分级差/管理/复购
- [ ] 分销 → 分销设置：commission_mode=differential
- [ ] 分销 → 分销商品：测试商品已开启级差/管理/区域

---

## 五、常见问题

| 问题 | 处理 |
|------|------|
| 下单提示不在配送范围 | 脚本已自动配置运费模板；可再执行 `fix_dispatch_express_areas.sql` |
| 无区域佣金 | 检查订单 province_id/city_id/area_id 是否有值；商品 regional_enable=1 |
| 无分销佣金 | 检查 commission_mode、商品 differential_enable/management_enable |
| 一级佣金0%仍出现推广佣金 | 勿开启「关系链分佣」；级差模式下旧版 `repurchase_rate=5%` 不应再覆盖一级佣金（已修复） |
| 我的团队人数显示 0 | 运行 `dist_regional_reset.php` 会自动刷新；旧数据可手动跑 setup 脚本或见下方团队统计说明 |
| 区县佣金比例不对 | 检查代理是否设置了「单独佣金」覆盖等级配置 |
| 想清空重测 | `dist_regional_reset.php` 或 cleanup --confirm |

---

## 六、测试完成后清理

```bash
php addons/shopro/tests/regional_agent_cleanup_test_users.php --confirm
```

或 SQL：`dist_regional_test_cleanup.sql`