jacy
b626db5d84
Unify product/store visibility on HQ whitelist, mark isTest snapshots, and fix SUPER_ADMIN access for the new module.
162 lines
6.9 KiB
Markdown
162 lines
6.9 KiB
Markdown
# 杜康好客 · 业务知识库
|
||
|
||
> **非需求文档**（不改规则请改 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 明细。
|