整理开发文档

2026-08-19 16:20:33 +08:00
parent 233ed0af3b
commit 62353a6800
21 changed files with 0 additions and 0 deletions
@@ -0,0 +1,161 @@
+# 杜康好客 · 业务知识库
+
+> **非需求文档**（不改规则请改 PRD）。新人/运营/客服速查。  
+> 事实源：[`v3-PRD`](./杜康好客-v3-PRD.md) · 验收：[`v3编码手册`](./杜康好客-v3编码手册.md)
+
+## 1. 概述
+
+**链路**：购酒 → 1:1 好客权益 → 门店核销（酒+餐）。
+
+| 角色 | 端 | 职责 |
+|------|-----|------|
+| C 用户 | mini-user / h5-user | 买酒、权益、核销、售后 |
+| 门店 | h5-shop | 扫码核销、营业、提现 |
+| 合伙人 | h5-partner | 拓店、辖区订单/账单 |
+| 总部 | admin-web | 开城、审核、结算、运营 |
+
+**常量**：权益额=`benefit_amount??price` · 门店结算=核销×**60%** · 佣金池≤**5%**(默认0%+3%) · 核销码**3min** · 同城≥**2瓶** · 跨城≥**6瓶** · 签约主体：山西领势酒业。
+
+---
+
+## 2. C 端（mini-user）
+
+- 四 Tab：首页/权益/门店/我的；微信登录+7天会话
+- 下单：选城→商品→地址→起购校验→微信支付→权益1:1
+- 权益：直接核销(≤总余额) / 单据核销(≤单据)；出码3分钟
+- 门店：仅 OPEN；详情含套餐/电话(脱敏可拨打)/两段营业时间
+- 订单 Tab：待付款/已付款/已完成；物流详情(签收照/拨号/ETA)
+- 售后：客服入口；发票/四类型工单按 PRD Wave 进度
+- 版本：`minClientVersion` 过低强制更新或退出
+- 「我的」头像昵称：`chooseAvatar` + `input type=nickname`（见下「踩坑」）
+
+### 踩坑 · 小程序 open-type 按钮点击无反应（必读，勿再回归）
+
+**现象**：「我的」完善资料弹层里点「选择头像」无反应（`open-type=chooseAvatar`）；同类还有 `getPhoneNumber` / `contact` / `share`。
+
+**根因**：弹层内容上写了 `onClick={(e) => e.stopPropagation()}`，Taro 编译为微信 **`catchtap`**，父级拦截后子级 `Button` 的原生 open-type **静默失效**。
+
+**硬规则**：
+
+| 规则 | 说明 |
+|------|------|
+| 弹层结构 | 遮罩 backdrop 单独绑关闭；**sheet 上禁止** `stopPropagation` / `catchtap` |
+| Button 内子节点 | `Image` 等加 `pointer-events: none`，勿抢触摸 |
+| 自检 | 凡含 `openType=` 的 Button，向上检查祖先有无 catch 类事件 |
+
+实现参照：`apps/mini-user/src/pages/mine/index.tsx`；Cursor 规则：`.cursor/rules/mini-user-weapp-opentype.mdc`。
+
+## 3. 门店端（h5-shop）
+
+- 登录绑定门店；首页扫码核销(微信 JSSDK)
+- 核销记录；今日汇总；到账金额×60%展示
+- 营业状态开关；Mine 门店信息
+- 套餐：列表编辑→提交 HQ 审核（v3.4.10）
+- iOS 微信：OAuth 后自动续扫（v3.4.13）；登录后须整页跳转（见下「踩坑」）
+
+### 踩坑 · iOS 微信 H5 扫码（必读，勿再回归）
+
+**现象**：手机号重新登录后点「扫码核销」提示「微信权限校验尚未完成…」；关掉 H5 再进就正常。
+
+**根因（不是系统相机权限）**：
+
+1. iOS 微信 WebView 对 JSSDK 验签用的是**本次 document 加载的入场 URL**（含 query），不是 SPA `pushState` 之后的 `location.href`。
+2. 登录 / OAuth 回跳常落在 `/login?code=…`，再 `navigate('/')` 进首页 → 签名 URL 与微信内部入场 URL 不一致 → `permission value is offline verifying` / invalid signature。
+3. 文案「等 1～2 秒再点」只覆盖「权限离线校验偏慢」的一小部分场景；**签名错了等多久都不行**，必须整页刷新或重新授权。
+
+**硬规则（编码）**：
+
+| 规则 | 说明 |
+|------|------|
+| iOS 登录/选店后 | 用 `location.replace(path)`（`hardNavigateInWechat`），禁止仅 React Router navigate |
+| iOS 签名 URL | `getJssdkSignUrl()` = 入场 URL，**保留** OAuth `code/state`；后端 `jssdk-config` 勿剔除 |
+| 已绑定微信 | 短信登录后**不要**再强制 OAuth（避免反复重置入场 URL） |
+| 扫码仍失败 | 弹窗引导「刷新页面」/「重新授权微信」，勿只提示再点一次 |
+
+实现：`packages/weixin-sdk/src/jssdk.ts` · `apps/h5-shop` 登录/选店/HomePage。
+
+## 4. 合伙人端（h5-partner）
+
+- 管理员 vs 推广员菜单裁剪；子账号 CRUD
+- 拓店：基本信息→照片→结算资质→(套餐)；一号多店确认
+- 门店列表/详情/套餐提审；辖区订单；账单 T+30
+- 暂停账号：发码前即拦截登录（v3.4.13）
+
+## 5. HQ（admin-web）
+
+| 菜单域 | 要点 |
+|--------|------|
+| 开城 | 城市、合伙人(全城/区域+佣金)、仓库 |
+| 商品 | SKU、上下架、详情模板 |
+| 门店 | 审核、套餐 Tab 直存/审核、合伙人列 |
+| 交易 | 订单、权益券、核销记录、推广码+metrics |
+| 财务 | 门店/合伙人/酒厂/物流账单；打款确认 |
+| 工单 | 售后四类型 + 技术支持(ST) + 开发计划 |
+| 系统 | 账号权限、客户端配置、企微机器人/消息推送 |
+| 日志 | HQ/用户/门店/合伙人/企微 |
+
+## 6. 商品与模板
+
+HQ 创建商品：名称/价格/权益额/箱规/香型/城市上架；详情模板(JSON 块)；资源 OSS。
+
+## 7. 活动 / 推广码
+
+HQ 推广码：场景/合伙人绑定/上下线；touch 归因；metrics 四指标+事件日志(v3.4.13)。
+
+## 8. 开城
+
+创建城市 → 绑定主账号合伙人 → 配置佣金 → 上架商品 → 仓库(可选)。
+
+## 9. 开店
+
+合伙人三步录入 → (负责人复核) → HQ 审核 → (试核销100) → OPEN → C 端可见。
+
+## 10. 订单
+
+状态机三态；支付回调幂等；同城小飞侠/跨城 HQ 填单；现场提货即完成；大单≥10箱 HQ 确认。
+
+## 11. 财务
+
+- **门店**：核销→store_payout T+1；未出账可提现→HQ 审→打款
+- **合伙人**：T+30 月账独立确认打款
+- **酒厂**：T+3 账单(v3.4.12)
+- **物流**：按承运商月结(小飞侠计价见 PRD §3.7.1)
+
+## 12. 发票
+
+用户申请 → HQ 2 工作日处理 → 回传（Wave 3 完整）
+
+## 13. 工单
+
+**售后**（用户）：仅退款/补发/退货等四类型 → HQ 审 → 仓/合伙人协同  
+**技术支持**（内部 ST）：BUG/建议 → 审批 → 开发任务 → 版本发布 → 工单 PUBLISHED(v3.4.13)
+
+## 14. 配送
+
+小飞侠推单/回调；`POST /callbacks/courier/xfx/track`；签收→订单 COMPLETED。
+
+## 15. 好客权益
+
+支付成功发放；FIFO 扣减；流水 `common_event(BENEFIT_LEDGER)`；核销后评价。
+
+## 16. 系统设置
+
+HQ 账号/角色(`hq-permissions`) · 客户端 `minClientVersion` · 运营告警走企微消息推送(DB Webhook)。
+
+## 17. 企业微信
+
+| 能力 | 入口 |
+|------|------|
+| 智能机器人 | `/wecom/bots` 长连接指令 |
+| 消息推送 | `/wecom/pushes` Webhook+eventKey |
+| 日志 | `/logs/wecom-bots` |
+
+eventKey：`alert.ops` · `support_ticket.created` · `dev_plan.task_dispatch` · 支付/核销/结算告警。
+
+---
+
+## 附录
+
+**端职责矩阵** → PRD §4.5  
+**文档索引**：PRD · 编码手册 · 现状对照 · v3.4.x 开发文档 · 埋点规范 · 城市日志架构  
+**变更**：随 v3.4.x 版本文档更新，不在此重复 ST 明细。