6.9 KiB
杜康好客 · 业务知识库
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 再进就正常。
根因（不是系统相机权限）：
- iOS 微信 WebView 对 JSSDK 验签用的是本次 document 加载的入场 URL（含 query），不是 SPA
pushState之后的location.href。 - 登录 / OAuth 回跳常落在
/login?code=…，再navigate('/')进首页 → 签名 URL 与微信内部入场 URL 不一致 →permission value is offline verifying/ invalid signature。 - 文案「等 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 明细。