xionggeshop/addons/shopro/tests/DIST_REGIONAL_TEST_FLOW.md

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

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

---

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

1. 一键重置（推荐）

# 清理旧数据 + 重新生成全部测试用户/配置
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. 分步执行

# 仅清理
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 时）

# 清理
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. 服务器验证：

# 从后台订单列表或数据库获取 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. 验证：

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

---

六、测试完成后清理

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

或 SQL：dist_regional_test_cleanup.sql