feat(ops): add global test whitelist and exclude test accounts from settlement

Unify product/store visibility on HQ whitelist, mark isTest snapshots, and fix SUPER_ADMIN access for the new module.

杜康好客-v3.4.14-mini-user门店体验开发文档.md

@@ -1,4 +1,4 @@
-# 杜康好客 · v3.4.14 mini-user 门店体验 + 小程序可配置项
+# 杜康好客 · v3.4.14 mini-user 门店体验 + 小程序可配置 + 测试白名单
 
 > **2026-08-06** · **开发中** · PRD §0.6 · mini-user `3.4.14` · **未发版**
 
@@ -10,6 +10,7 @@
 | 门店详情·套餐 | 仅完整标题纵向列表；点击进入详情 |
 | 套餐详情页 | 实底导航让出胶囊区；内容区顶/左右留白；有图在门店名下；无图直接菜品 |
 | **系统设置·微信小程序** | Logo / 资质图 / 客服电话 / C 端 H5 / Mock 验证码 **可配置**，经 `client-config` 下发 |
+| **测试白名单** | 全局手机号名单；账号/门店/订单/核销打标；不计四条结算；合并商品/门店可见性手机号；HQ 独立管理模块 |
 
 ## 页面路由
 
@@ -37,6 +38,36 @@ HQ → 系统设置 → **微信小程序配置**。启动时空缺键用 shared
 **下发**：`GET /common/client-config` 增加 `userH5Url`、`brandLogoUrl`、`brandLogoWideUrl`、`brandLogoMarkUrl`、`qualificationDisclosureUrl`、`customerServicePhone`。  
 `MOCK_SMS_FIXED_CODE` 仅服务端 Mock 短信读取，不下发客户端。
 
+## 测试白名单（统一）
+
+### 规则
+
+| 规则 | 说明 |
+|------|------|
+| 源真相 | HQ「白名单管理」维护 `common_test_whitelist_phone`；名单内手机号 = 测试账号 |
+| 可见性 | 商品/门店 `visibilityWhitelistEnabled` 开启后，C 端仅当观众手机号 ∈ 全局名单可见/可购（不再用分实体 `*_visibility_phone`） |
+| 打标 | `User` / `StoreAccount` / `PartnerAccount` / `Store` / `Order` / `RedeemRecord` 的 `isTest` |
+| 不计账 | 测试核销不产生 `StorePayout`；酒厂/物流/合伙人账单排除 `isTest` 流水 |
+| 验证旁路 | 页顶 Checkbox ↔ `MOCK_SMS` / `MOCK_WECHAT` / `MOCK_PAY`（勾选 = 不做真实验证） |
+
+### API
+
+| 路径 | 说明 |
+|------|------|
+| `GET/POST /admin/test-whitelist/phones` | 名单列表 / 新增 |
+| `PATCH/DELETE /admin/test-whitelist/phones/:id` | 改备注 / 删除 |
+| `GET /admin/test-whitelist/accounts` | 测试账号记录（type=user\|store_account\|partner\|store\|order） |
+| `GET /admin/test-whitelist/phones/:id/linked` | 单号关联实体 |
+| `POST /admin/test-whitelist/migrate-visibility` | 旧可见性手机号导入 |
+
+业务列表查询参数：`excludeTest=true` 排除测试数据。
+
+### HQ
+
+- 路由 `/test-whitelist`：验证旁路 + 手机号名单 + 测试账号记录
+- 用户/订单/门店/门店账号/合伙人/核销：「过滤测试账号」复选框；列表「测试」Tag
+- 商品/门店：保留「仅白名单可见」开关，去掉分实体手机号编辑
+
 ## ACC
 
 - [ ] 门头区高度固定（4:3）；图片 aspectFit 完整缩放；标题 section 位置不随图高变化
@@ -45,6 +76,11 @@ HQ → 系统设置 → **微信小程序配置**。启动时空缺键用 shared
 - [ ] 无套餐时不展示区块；index 非法时友好提示
 - [ ] HQ 微信小程序配置可改 Logo/电话/落地页/Mock 码；保存后 client-config 立即生效（无需重启）
 - [ ] mini-user 登录/我的/客服/分享图读取配置；未配置时回退代码默认常量
+- [ ] HQ「白名单管理」可增删手机号；可查看测试账号记录
+- [ ] 页顶三 Checkbox 控制短信/微信/支付跳过真实验证，与 `MOCK_*` 同源立即生效
+- [ ] 业务列表「过滤测试账号」勾选后不含测试数据
+- [ ] 旧可见性手机号已导入；限测商品/门店仅全局名单可见
+- [ ] 测试流水不进四条账单与门店打款
 
 ## HQ 开发计划