整理开发文档

2026-08-19 16:20:33 +08:00
parent 233ed0af3b
commit 62353a6800
21 changed files with 0 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 杜康好客 · v3.4.14 mini-user 门店体验 + 小程序可配置 + 测试白名单
+
+> **2026-08-06** · **开发中** · PRD §0.6 · mini-user `3.4.14` · **未发版**
+
+## 范围
+
+| 项 | 交付 |
+|----|------|
+| 门头照 | **固定 4:3 区域**；`aspectFit` 缩放完整显示（不裁剪）；标题信息卡固定接在门头下方 |
+| 门店详情·套餐 | 仅完整标题纵向列表；点击进入详情 |
+| 套餐详情页 | 实底导航让出胶囊区；内容区顶/左右留白；有图在门店名下；无图直接菜品 |
+| **系统设置·微信小程序** | Logo / 资质图 / 客服电话 / C 端 H5 / Mock 验证码 **可配置**，经 `client-config` 下发 |
+| **测试白名单** | 全局手机号名单；账号/门店/订单/核销打标；不计四条结算；合并商品/门店可见性手机号；HQ 独立管理模块 |
+
+## 页面路由
+
+| 路径 | 参数 |
+|------|------|
+| `pages/store-detail/index` | `id` 门店 ID |
+| `pages/store-package-detail/index` | `storeId` · `index` 套餐序号（0-based） |
+
+数据：复用 `GET /stores/:id` 内嵌 `packages[]`，详情页按 index 取项。
+
+## 系统设置（微信小程序配置）
+
+HQ → 系统设置 → **微信小程序配置**。启动时空缺键用 shared-types 默认值补种。
+
+| 配置键 | 说明 |
+|--------|------|
+| `USER_H5_URL` | C 端 H5 落地页（推广码等） |
+| `BRAND_LOGO_OSS_BASE` | Logo OSS 根路径（说明用） |
+| `BRAND_LOGO_URL` / `_WIDE_` / `_MARK_` | 方形 / 长方形 / 图标 Logo |
+| `MINI_USER_STATIC_OSS_BASE` | 小程序静态资源根路径 |
+| `QUALIFICATION_DISCLOSURE_URL` | 资质公示长图 |
+| `CUSTOMER_SERVICE_PHONE` | 总部客服电话 |
+| `MOCK_SMS_FIXED_CODE` | Mock 短信固定验证码（仅 MOCK_SMS 开启） |
+
+**下发**：`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 位置不随图高变化
+- [ ] 门店详情套餐区仅标题列表，标题完整展示、可换行
+- [ ] 点击套餐进入详情页，字段完整；返回回到门店详情
+- [ ] 无套餐时不展示区块；index 非法时友好提示
+- [ ] HQ 微信小程序配置可改 Logo/电话/落地页/Mock 码；保存后 client-config 立即生效（无需重启）
+- [ ] mini-user 登录/我的/客服/分享图读取配置；未配置时回退代码默认常量
+- [ ] HQ「白名单管理」可增删手机号；可查看测试账号记录
+- [ ] 页顶三 Checkbox 控制短信/微信/支付跳过真实验证，与 `MOCK_*` 同源立即生效
+- [ ] 业务列表「过滤测试账号」勾选后不含测试数据
+- [ ] 旧可见性手机号已导入；限测商品/门店仅全局名单可见
+- [ ] 测试流水不进四条账单与门店打款
+
+## HQ 开发计划
+
+创建版本 `v3.4.14`（`IN_PROGRESS`），关联本迭代任务。发版前再合并发布。