From 53a79d125577c66181fd6b8319224efb4bf32ad7 Mon Sep 17 00:00:00 2001 From: jacy <18049821889@163.com> Date: Thu, 6 Aug 2026 01:09:19 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8E=8B=E7=BC=A9=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- 杜康好客-V2编码手册.md | 3820 +--------------------- 杜康好客-preV1编码手册.md | 450 +-- 杜康好客-v2.1编码手册.md | 170 +- 杜康好客-v3-PRD.md | 600 +--- 杜康好客-v3-埋点规范.md | 92 +- 杜康好客-v3-城市仓库与日志架构.md | 133 +- 杜康好客-v3-现状对照.md | 387 +-- 杜康好客-v3.4.12-工单迭代开发文档.md | 50 +- 杜康好客-v3.4.13-体验优化开发文档.md | 200 +- 杜康好客-v3编码手册.md | 238 +- 杜康好客-开发计划功能开发文档-v3.4.11.md | 183 +- 杜康好客-知识库.md | 995 +----- 杜康好客-门店套餐功能开发文档-v3.4.10.md | 386 +-- 14 files changed, 469 insertions(+), 7237 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 24c262b..2121fd6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ | **V3.0 唯一需求源** | [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) | 产品需求与三波交付（**只看这个**） | | **现状对照** | [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md) | 已完成 / 冲突 / 缺口审计 | | **V3 实现验收** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 核销规则、分工、闭环 | -| ~~V2 / preV1~~ | 历史参考 | **不再作为需求依据** | +| ~~V2 / preV1~~ | 历史参考（**已压缩**；V2 全文见 git 2026-08-06 前） | **不再作为需求依据** | **禁止**：臆造 PRD 未定义规则；依赖 `doc/` 下过时文档；跨 OWNER 直写他人 Prisma 表。 diff --git a/杜康好客-V2编码手册.md b/杜康好客-V2编码手册.md index 4c1a884..95103d6 100644 --- a/杜康好客-V2编码手册.md +++ b/杜康好客-V2编码手册.md @@ -1,3802 +1,30 @@ -# 杜康好客 · V2 编码手册（完整规格 · 唯一事实源） +# 杜康好客 · V2 编码手册（已归档） -> **V3 交付提示**：当前交付验收以 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 为准。本手册中「核销单次上限 ¥500」等规则已被 V3 替代（直接核销可达总余额 / 单据 cap）。 +> **勿作需求依据**。交付与验收以 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) + [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 为准。 +> 完整 V2 原文（§一~§九、DB v3.1、API v3.1、任务卡）保留在 **git 历史**（2026-08-06 压缩前）。 -> **版本**：**V2**（完整四端 + 微信生态 + 真实第三方） -> **联调裁剪版**：见 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)（三端 H5 + Mock，同库同 API 契约） -> **用途**：V2 正式编码与 preV1 预留对齐的完整规格 -> **日期**：2026-06-27 -> **范围**：郑州开城 · 4 款清香型 SKU · 四端（C端小程序/门店H5/合伙人小程序/总部小程序） -> **技术栈**：Taro 3 + React + TS · NestJS 10 + Prisma 5 · MySQL 8 · Redis 7 · BullMQ -> **数据库**：v3.1（28 表，见 §五） -> **API**：v3.1（见 §六） -> **协作**：见根目录 `conventions.md`、`agent.md`、`skills.md` +## 仍可能引用的 V2 片段（与 V3 冲突时以 V3 为准） ---- +| 主题 | V2 口径 | V3 替代 | +|------|---------|---------| +| 核销上限 | 单次 ¥500 | 直接核销 ≤ 总余额；单据核销 ≤ 单据余额 | +| 订单 Tab | 5 Tab | 待付款 / 已付款 / 已完成 | +| 核销码 TTL | 5 分钟 | **3 分钟** | +| 总部端 | 小程序 `pages/hq/` | **`apps/admin-web` WebAdmin** | +| C 端 | 微信小程序 | `mini-user` / `h5-user` 过渡 | -## 文档索引 +## 索引（归档） -| 章节 | 内容 | -|------|------| -| §一 | 项目目标与 V1 范围 | -| §二 | 产品需求（PRD + 原型对应） | -| §三 | 原型全清单与页面流 | -| §四 | 技术架构与模块边界 | -| §五 | 数据库设计 v3.1 | -| §六 | API 列表 v3.1 | -| §七 | 开发计划与任务卡 | -| §八 | 核心业务链路 | -| §九 | 第三方集成与非功能 | - ---- - -# §一、项目目标与 V2 范围 - -杜康好客是杜康酒业 O2O 平台：用户购酒获等额「好客权益」，到合作餐饮门店核销；城市合伙人拓店与履约；总部管开城、商品、结算与客服。 - -| 端 | 载体 | 原型目录 | 后端 Guard | -|----|------|----------|------------| -| C端 | 微信小程序 | pages/user/ | UserAuth → user_user | -| 门店 | H5 | pages/shop/ | StoreAuth → store_account | -| 合伙人 | 微信小程序 | pages/partner/ | PartnerAuth → partner_account | -| 总部 | 微信小程序 | pages/hq/ | AdminAuth → hq_account | - -**V2 锁定**：郑州 · 4 款清香型 · 含退款/推广码/埋点 · 不含会员体系 · 订单 5 Tab（含待发货） · 核销单次上限 ¥500 · 门店 T+1 / 合伙人 T+30 结算。 - -**里程碑**：M0 骨架 → M1 IAM/开城/商品 → M2 交易 → M3 权益核销 → M4 拓店售后 → M5 结算 → M6 推广埋点 → 上线。 - ---- - -# §二、产品需求（PRD） - -## 1. 项目背景与目标 - -### 1.1 背景 - -杜康好客是杜康酒业的 O2O 消费平台：用户在线购买杜康酒品，同时获得等额「好客权益」用于合作餐饮门店消费；城市合伙人负责拓展本地门店网络与订单履约；总部统一管理开城、商品、结算与客服。 - -### 1.2 产品目标 - -1. 打通「购酒 → 赠权益 → 到店核销」完整闭环 -2. 支持多城市开城，同城/跨城差异化配送 -3. 为城市合伙人、门店、总部提供各自工作台 -4. 可追溯订单来源（推广码）与资金结算 - -### 1.3 产品范围（四端） - - -| 端 | 载体 | 用户 | -| ------ | --------- | ---------- | -| C端 | 微信小程序 | 终端消费者 | -| 门店端 | H5 | 合作餐饮门店 | -| 城市合伙人端 | 微信小程序 | 城市合伙人及子账号 | -| 总部管理端 | **微信小程序** | 总部运营、财务、客服 | - - -### 1.4 V1 上线范围（已锁定） - - -| 维度 | V1 范围 | 说明 | | -| -------- | ---------- | ---------------------- | ----------------- | -| 开城 | **郑州** | 唯一上线城市；其他城市原型仅作扩展参考 | | -| 商品 | **4 款清香型** | 酱香型/浓香型 Tab 展示但不可购（灰态） | | -| 会员体系 | **不实现** | 个人中心仅默认头像 + 昵称 + 平台 ID | | -| 退款 | | **纳入 V1** | 总部客服中心处理，见 §3.6.2 | -| 推广码 + 埋点 | **纳入 V1** | 见 §3.10 | | -| 跨城配送 | 纳入 V1 | 逻辑保留，V1 以郑州同城为主 | | - - ---- - -## 2. 核心概念 - -### 2.1 好客权益 - -- 用户购酒并支付成功后发放好客权益（餐券） -- **V1 默认规则**：权益金额 **= 商品售价**（等额） -- **可配置扩展**：总部商品管理可单独设置「权益金额」字段；未配置时自动取商品售价，便于后续营销活动灵活调整 -- 系统内统一称为「好客权益」，可在合作门店核销抵扣餐饮消费 -- **永久有效**，当前版本不设过期时间 -- 支持部分核销：一张券可多次使用直至余额为 0 -- **单次核销上限**：不超过当前券可用余额（系统校验） - -### 2.2 开城与订单路由 - -- 总部「开城管理」配置城市及城市合伙人 -- 用户定位/选城决定可见商品与配送方式 -- 订单归属城市 = 收货地址所在城市（用于合伙人业绩与佣金） - -### 2.3 配送模式 - - -| 模式 | 条件 | 配送方 | 时效 | 运费 | 起购量 | -| ---- | ---------- | ------ | ------ | --- | -------- | -| 同城配送 | 地址在已开城同城范围 | 小飞侠 | 24 小时内 | ¥0 | 2 瓶 | -| 跨城物流 | 超出同城范围 | 总部物流快递 | 依物流 | 到付 | 6 瓶（1 箱） | - - ---- - -## 3. C端用户小程序 - -**原型目录**：`pages/user/` -**底部导航**：首页 | 门店 | 好客权益 | 我的 - -| 原型文件 | 页面 | PRD 模块 | -|----------|------|----------| -| `pages/user/1-登录.png` | 登录 | §3.1 | -| `pages/user/2-首页.png` | 首页 | §3.2 | -| `pages/user/3-商品详情页.png` | 商品详情 | §3.2 | -| `pages/user/4-立即购买确认订单.png` | 确认订单（同城） | §3.3 | -| `pages/user/5-订单确认-跨城配送.png` | 确认订单（跨城） | §3.3 | -| `pages/user/6-地址列表.png` | 地址列表 | §3.4 | -| `pages/user/7-新增收货地址.png` | 新增地址 | §3.4 | -| `pages/user/8-微信支付页面.png` | 微信支付 | §3.3 | -| `pages/user/9-我的订单列表.png` | 订单列表（5 Tab） | §3.5 | -| `pages/user/10-我的订单-补发状态.png` | 补发订单 | §3.5 | -| `pages/user/11-我的订单详情.png` | 订单详情 | §3.5 | -| `pages/user/12-修改地址弹窗.png` | 修改地址 | §3.5 | -| `pages/user/13-联系客服弹窗.png` | 联系客服 | §3.6 | -| `pages/user/14-联系在线客服.png` | 在线客服 | §3.6 | -| `pages/user/15-门店页面-门店列表.png` | 门店列表 | §3.7 | -| `pages/user/16-门店详情页.png` | 门店详情 | §3.7 | -| `pages/user/17-好客权益页.png` | 好客权益 | §3.8 | -| `pages/user/18-好客权益明细.png` | 权益明细 | §3.8 | -| `pages/user/19-个人中心页.png` | 个人中心 | §3.9 | -| `pages/user/20-好客权益核销.png` | 核销输入 | §3.8 | -| `pages/user/21-核销码展示.png` | 核销码 | §3.8 | -| `pages/user/22-核销成功及评价.png` | 核销成功 | §3.8 | - -### 3.1 模块一：登录与城市归属 - -**原型**：`1-登录.png` - - -| 功能 | 说明 | -| ------- | ------------------- | -| 手机验证码登录 | 输入手机号 + 验证码 | -| 微信授权登录 | 需勾选用户协议与授权 | -| 定位授权 | 登录后请求定位，获取市+区（最多两级） | -| 手动选城 | 用户可手动选择城市/区域 | - - -**业务规则** - -- 城市决定后续商品、门店、配送方式 -- **V1 仅郑州开城**；非郑州用户可浏览，下单按跨城/未开通规则处理 - ---- - -### 3.2 模块二：首页与商品展示 - -**原型**：`2-首页.png`、`3-商品详情页.png` - -#### 3.2.1 首页 - - -| 元素 | 说明 | -| ------ | --------------------------------- | -| 品牌区 | 杜康好客 + 当前城市 | -| 香型 Tab | 清香型 / 酱香型 / 浓香型（**当前仅清香型上线**） | -| 商品卡片 | 大图 + 标题 + 规格 + 价格 + 好客权益标签 + 立即购买 | -| 商品数量 | **V1 固定 4 款**清香型，大图列表布局 | - - -#### 3.2.2 商品详情 - - -| 元素 | 说明 | -| -------- | ---------------------------------------- | -| 主图轮播 | 商品主图 | -| 价格/名称/规格 | 固定展示 | -| 好客权益说明 | 标准文案：「买杜康美酒·享全城好客礼遇」，展示金额取 `权益金额`（默认同售价） | -| 图文详情 | 后台商品管理维护，支持图片+文字 | -| 操作 | 返回首页 / 立即购买 | - - -**业务规则** - -- 权益展示/发放金额 = 商品配置的 `benefit_amount`；**未配置时默认 = 商品售价** -- 首页卡片「享 ¥X 好客权益」同步读取该字段 - ---- - -### 3.3 模块三：下单与微信支付 - -**原型**：`4-立即购买确认订单.png`、`5-订单确认-跨城配送.png`、`6~8` - -#### 3.3.1 确认订单 - - -| 字段 | 说明 | -| ----- | ---------------------- | -| 收货地址 | 必选；跳转地址列表 | -| 商品信息 | 图、名、规格、单价、数量 | -| 好客权益 | 本单可享权益金额 | -| 配送方式 | 同城：小飞侠（预计 24h）；跨城：物流配送 | -| 运费 | 同城 ¥0；跨城显示「到付」 | -| 合计/实付 | 商品总额 + 运费（跨城不含运费） | -| 支付 | 仅微信支付 | - - -#### 3.3.2 跨城提示 - -地址超出同城范围时： - -- 弹窗/横幅提示：总部物流发货，运费到付，需用户确认继续 -- 配送方式变为「物流配送」，运费标记「到付」 - -#### 3.3.3 起购校验 - - -| 配送类型 | 最低数量 | 不满足时 | -| ---- | ---- | ---- | -| 同城 | 2 瓶 | 拦截下单 | -| 跨城 | 6 瓶 | 拦截下单 | - - -#### 3.3.4 支付流程 - -1. 点击「微信支付」→ 锁单 -2. 跳转微信支付确认页 -3. 支付成功 → 微信回调 → 订单生成 -4. 初始状态：**待发货** -5. 支付成功同时**发放好客权益** - ---- - -### 3.4 模块四：地址管理 - -**原型**：`6-地址列表.png`、`7-新增收货地址.png` - - -| 功能 | 说明 | -| ---- | ---------------------- | -| 地址列表 | 历史地址，可选择 | -| 新增地址 | 收货人、手机号、地区选择、详细地址、是否默认 | -| 默认地址 | 下单时优先选中 | - - ---- - -### 3.5 模块五：订单管理 - -**原型**：`9-我的订单列表.png`、`10~12`、`11-我的订单详情.png` - -#### 3.5.1 订单列表 Tab - -**原型**：`9-我的订单列表.png`（**5 Tab：全部/待付款/待发货/待收货/已完成**） - - -| Tab | 包含状态 | -| ------- | ---------------- | -| 全部 | 所有（含退款中、已退款、补发单） | -| 待付款 | 待支付 | -| **待发货** | 已支付，待出库/待推配送 | -| 待收货 | 配送中 + 待签收 | -| 已完成 | 已完成 | - - -**完整状态机**：`待付款 → 待发货 → 配送中 → 待签收 → 已完成` -**异常分支**：`退款中 → 已退款`；`补发中`（关联原单，价格 ¥0） - -> **原型改稿**：`pages/user/9` 需增补「待发货」Tab，详见 `doc/原型说明.md`。 - -#### 3.5.2 列表卡片字段 - -- 订单号、状态 -- 商品图、名称、规格、数量、金额 -- 好客权益使用情况 + 「去使用」按钮（未用完时） -- 补发单：标记「补发单」，价格 ¥0，提示破损免费补发 - -#### 3.5.3 订单详情 - - -| 区块 | 内容 | -| ---- | --------------------------- | -| 进度条 | 下单成功 → 出库中 → 配送中 → 待签收 → 完成 | -| 商品信息 | 含好客权益引导入口 | -| 收货信息 | 姓名、地址、配送方式；**待发货/配送中可修改** | -| 订单信息 | 订单号、创建时间、支付方式 | -| 结算 | 商品总额、运费、实付 | -| 操作 | 联系客服、确认收货 | - - -#### 3.5.4 修改收货地址 - -**原型**：`12-修改地址弹窗.png` - -- 弹窗提示：系统将尝试拦截配送；拦截失败需联系配送员 -- 若已按原地址签收，不再二次派送 -- **拦截成功**（物流返回「商品已退回」）→ 推送新订单到城市合伙人 → 二次配送 - ---- - -### 3.6 模块六：售后与客服 - -**原型**：`13-联系客服弹窗.png`、`14-联系在线客服.png` - - -| 渠道 | 说明 | -| ------ | ------ | -| 电话客服 | 调起拨号 | -| 微信图文客服 | 在线实时沟通 | - - -**补发流程**（破损等）： - -1. 用户联系总部客服，提供订单号 -2. 总部客服发起补发 -3. 通知用户；推送城市合伙人确认 -4. 合伙人确认后进入配送；系统记录补发关联原订单 - -#### 3.6.2 退款流程（V1） - -**原型**：`pages/hq/26-补发与退款处理.png` - - -| 环节 | 说明 | -| ---- | -------------------------------------------------------- | -| 发起 | 用户通过客服（电话/在线）申请退款，提供订单号与原因 | -| 受理 | 总部客服在「客服中心」创建退款工单，关联原订单 | -| 审核 | 总部客服/财务审核；可部分退款或全额退款 | -| 执行 | 调用微信退款 API；订单状态 → `退款中` → `已退款` | -| 权益回退 | 若对应好客权益**未使用**：全额退款时作废权益；**已部分核销**：按未使用余额比例退款或人工核算（客服备注） | -| 通知 | 退款结果推送用户（小程序订阅消息/客服会话） | - - -**可退款状态** - - -| 订单状态 | 是否可退 | 说明 | -| ------- | ---- | ------------------------ | -| 待付款 | 否 | 用户直接取消/超时关单 | -| 待发货 | 是 | 全额退款优先 | -| 配送中 | 是 | 需拦截配送成功后退款 | -| 待签收/已完成 | 条件可退 | 签收 7 天内且未开瓶/未核销权益，客服人工判定 | -| 补发单 | 否 | — | - - ---- - -### 3.7 模块七：门店 - -**原型**：`15-门店页面-门店列表.png`、`16-门店详情页.png` - -#### 3.7.1 门店列表 - - -| 元素 | 说明 | -| --- | ----------------------------------- | -| 定位 | 按用户城市/区域筛选 | -| 分类 | 火锅、地方菜、高端餐饮、烧烤烤肉等 | -| 卡片 | 招牌图、名称、评分、人均、支持核销标签、营业状态 | -| 搜索 | 店名、地址 | -| 过滤 | **永久闭店、临时闭店均不在 C 端展示**；仅「营业中」门店可见可选 | - - -#### 3.7.2 门店详情 - -- 大图、名称、状态、评分、标签 -- 环境图（3 张） -- 地址、距用户距离 -- 电话、导航（调起地图） -- 图文介绍（后台维护） -- 「去核销」→ 跳转核销页 - ---- - -### 3.8 模块八：好客权益 - -**原型**：`17-好客权益页.png`、`18-好客权益明细.png`、`20~22` - -#### 3.8.1 权益首页 - -- 当前余额（汇总） -- 「去使用」→ 核销流程 -- Tab：待使用 | 已用完/已过期（当前无过期，仅已用完） -- 券卡片：金额、来源订单、永久有效、已用/未用进度、券编号、立即核销 - -#### 3.8.2 权益明细 - -- 获取记录 + 消费记录 - -#### 3.8.3 核销流程 - -1. 选择门店（或从订单/权益页直接进入） -2. **核销页**：展示可用余额，输入本次核销金额，支持「全部核销」 - - 校验：`0 < 金额 ≤ min(可用余额, ¥500)` - - 超出 ¥500 提示「单次最高可核销 ¥500.00」 -3. 点击「生成核销码」→ 展示二维码 -4. 核销码 **5 分钟有效**，一次性使用，可刷新 -5. 门店扫码确认 → **核销成功页** -6. 快速评价：服务态度、用餐环境（五星，点击即保存） - -**入口汇总** - -- 底部 Tab「好客权益」 -- 订单列表/详情「去使用」 -- 门店详情「去核销」 -- 个人中心「去使用」 - ---- - -### 3.9 模块九：个人中心 - -**原型**：`19-个人中心页.png` - - -| 区块 | 说明 | -| ---------- | -------------------------------------------- | -| 用户信息 | 全局默认头像、微信昵称、平台 ID（**V1 无会员等级**，不展示「至尊会员」等标签） | -| 我的资产 | 好客权益余额 → 明细 | -| 我的订单 | 待付款/待发货/配送中/已完成 快捷入口 | -| 地址管理 | 跳转地址列表 | -| 可用门店 | 跳转门店 Tab | -| 联系客服 | 同订单页 | -| 关于我们 / 版本号 | 展示系统版本 | -| 退出登录 | — | - - ---- - -### 3.10 模块十：推广码与埋点（V1） - -**原型**：`pages/hq/16-推广码管理.png`、`17-推广码生成.png` - -#### 3.10.1 推广码 - - -| 功能 | 说明 | -| ---- | --------------------------------------------- | -| 创建 | 总部创建推广码，绑定渠道名称（如「XX 品鉴会」） | -| 扫码归因 | 用户扫码进入小程序，**首次**写入 `channel_source` 至 session | -| 订单绑定 | 下单时将 `channel_source` 写入订单；合伙人/总部订单详情可查看 | -| 统计 | 总部数据报表按渠道汇总 GMV、订单量 | - - -#### 3.10.2 用户行为埋点（V1 事件清单） - - -| 事件名 | 触发时机 | 关键参数 | -| -------------------------- | ----------- | ------------------------------- | -| `app_launch` | 小程序启动 | city, channel_source | -| `login_success` | 登录成功 | method( sms/wechat ) | -| `location_grant` | 定位授权结果 | granted, city, district | -| `home_view` | 首页曝光 | city, aroma_tab | -| `product_click` | 点击商品卡片 | product_id, price | -| `product_detail_view` | 商品详情曝光 | product_id, benefit_amount | -| `order_confirm_view` | 确认订单页曝光 | product_id, qty, delivery_type | -| `order_submit` | 点击微信支付 | order_id, amount, delivery_type | -| `pay_success` / `pay_fail` | 支付回调 | order_id, amount, fail_reason | -| `order_tab_view` | 订单列表 Tab 切换 | tab_name | -| `store_list_view` | 门店列表曝光 | city, category | -| `store_detail_view` | 门店详情 | store_id | -| `benefit_redeem_start` | 进入核销页 | store_id, available_balance | -| `benefit_qrcode_generate` | 生成核销码 | amount, coupon_id | -| `benefit_redeem_success` | 核销成功 | amount, store_id | -| `cs_contact` | 联系客服 | type( phone/chat ) | -| `promo_scan` | 扫描推广码 | promo_code, channel_name | - - -**技术要求** - -- 统一上报 SDK，支持批量上报与失败重试 -- 埋点数据可在总部「数据报表中心」查询（V1 基础统计即可） - ---- - -## 4. 门店端 H5 - -**原型目录**：`pages/shop/` -**底部导航**：首页 | 核销记录 | 我的 - -| 原型文件 | 页面 | PRD 模块 | -|----------|------|----------| -| `pages/shop/1-登录页.png` | 登录 | §4.1 | -| `pages/shop/2-一键登录.png` | 快捷登录 | §4.1 | -| `pages/shop/3-门店管理首页-核销页.png` | 首页核销 | §4.2 | -| `pages/shop/4-核销确认.png` | 核销确认 | §4.3 | -| `pages/shop/5-核销成功.png` | 核销成功 | §4.3 | -| `pages/shop/6-核销记录.png` | 核销记录 | §4.4 | -| `pages/shop/7-门店信息.png` | 门店信息 | §4.5 | - -### 4.1 登录 - -**原型**：`1-登录页.png`、`2-一键登录.png` - -- 门店手机号 + 验证码 -- 微信授权登录 -- 记住登录态，二次进入快捷登录 -- 展示门店名称、绑定手机号 - -### 4.2 首页 · 扫码核销 - -**原型**：`3-门店管理首页-核销页.png` - - -| 元素 | 说明 | -| --------------- | ------------------------ | -| 门店名称 | 当前登录门店 | -| 今日核销笔数 / 今日到账金额 | 实时统计 | -| 扫码核销 | 主操作按钮；亦支持微信扫一扫 | -| 营业状态 | 开店 / 临时闭店切换，**实时同步 C 端** | -| 最近核销 | 时间 + 金额，倒序 | - - -**营业规则** - -- 门店端：开店 / 临时闭店 -- 临时闭店 → **C 端列表隐藏**，不可核销 -- 永久闭店：仅城市合伙人可操作，C 端不可见 - -### 4.3 核销确认 - -**原型**：`4-核销确认.png`、`5-核销成功.png` - - -| 确认页字段 | 说明 | -| ----- | -------------- | -| 当前门店 | 登录门店信息 | -| 用户手机号 | 脱敏展示 | -| 核销金额 | 用户输入的面额 | -| 券编号 | 券 ID | -| 有效期 | 永久（码本身 5 分钟有效） | - - -- 点击「确认核销」→ 服务端执行核销 -- 成功 → 用户端更新；门店端展示成功页 -- **短信通知**门店老板：到账金额 + 核销时间 -- 仅**授权且营业中**的门店可核销 - -### 4.4 核销记录 - -**原型**：`6-核销记录.png` - - -| 筛选项 | 选项 | -| --- | ------------------- | -| 时间 | 今日 / 近 7 日 / 近 30 日 | -| 状态 | 全部 / 待打款 / 已打款 | - - - -| 汇总 | 说明 | -| ------ | -------- | -| 期间核销总额 | 面额合计 | -| 期间到账总额 | 面额 × 60% | -| 结算比例 | 60%（6 折） | - - - -| 明细字段 | 说明 | -| ----------- | -------------------- | -| 核销单号、时间 | — | -| 核销面额 / 到账金额 | 60% | -| 打款状态 | 待打款 / 已打款 | -| 打款时间 | 总部打款时间 | -| **打款周期** | **T+1 工作日**（核销日次日起算） | - - -- 待打款记录展示「预计打款：T+1 工作日」 -- 账单链接亦可通过服务号/短信通知查看 - -### 4.5 我的 · 门店信息 - -**原型**：`7-门店信息.png` - -- 门店名称、地址、电话：**仅查看** -- 修改需联系城市合伙人 -- 营业状态切换 -- 退出登录 - ---- - -## 5. 城市合伙人端小程序 - -**原型目录**：`pages/partner/` -**底部导航**：首页 | 门店管理 | 合伙人中心 - -| 原型文件 | 页面 | PRD 模块 | -|----------|------|----------| -| `pages/partner/1-登录页.png` | 登录 | §5.1 | -| `pages/partner/2-快捷登录.png` | 快捷登录 | §5.1 | -| `pages/partner/3-首页.png` | 工作台 | §5.2 | -| `pages/partner/4-拦截配送.png` | 拦截配送 | §5.6 | -| `pages/partner/5-门店管理.png` | 门店列表 | §5.3 | -| `pages/partner/6~8` | 录入门店三步 | §5.3.2 | -| `pages/partner/9-补发处理.png` | 补发 | §5.5 | -| `pages/partner/10-财务对账.png` | 财务对账 | §5.7 | -| `pages/partner/11-周报.png` | 周报 | §5.8 | -| `pages/partner/12-13` | 订单列表/详情 | §5.4 | -| `pages/partner/15~16,18` | 子账号/员工 | §5.9 | -| `pages/partner/17,20-23` | 合伙人中心/结算 | §5.10 | - -### 5.1 登录与账号 - -**原型**：`1-登录页.png`、`2-快捷登录.png` - -- 账号由**总部创建**城市合伙人入驻 -- 手机验证码 / 微信授权 / 快捷登录 -- 微信授权有效期 **30 天** -- 展示：企业名称、地址、入驻城市、手机号 - -### 5.2 工作台首页 - -**原型**：`3-首页.png` - - -| 指标 | 说明 | -| ----- | ------------------- | -| 实时营业额 | 所辖城市酒品订单 GMV | -| 预计利润 | 营业额 × 35%（30% + 5%） | -| 门店总数 | 正常运营 / 异常·闭店 | -| 今日订单量 | 待发货 / 配送中 / 已完成 | -| 拓店情况 | 下级合伙人拓店统计 | -| 贡献榜 | 按拓店数排行 | - - -**快捷入口**：录入新店 | 补发处理 | 财务对账 | 数据周报 | 拦截配送 - -> 脚本明确「今日活跃度」等字段暂不使用。 - -### 5.3 门店管理 - -**原型**：`5-门店管理.png`、`6~8` - -#### 5.3.1 门店列表 - -- 状态：营业中 / 暂时闭店 / 已关闭（永久闭店） -- 搜索：名称、地址 - -#### 5.3.2 录入新门店（三步） - - -| 步骤 | 内容 | -| ------ | ----------------------------- | -| 1 基本信息 | 名称*、电话*、地图选址*、门牌号、简介(10~500字) | -| 2 照片上传 | 门头照、环境照（≥3 张）、签约合同副本 | -| 3 结算资质 | 银行卡姓名、卡号、开户支行 | - - -- 提交 → 推送**总部审核** -- 审核通过 → 门店生效，获得核销权限 -- 合伙人可编辑门店；**永久闭店**仅合伙人可操作 - -#### 5.3.3 审核记录 - -- 待审核 / 已通过 / 已驳回 -- 驳回可修改重新提交 - -### 5.4 订单管理 - -**原型**：`12-订单列表.png`、`13-订单详情.png` - -- 仅查看**所辖城市**订单 -- 时间：今天 / 近 7 天 / 近 30 天 -- 状态：全部 / 待发货 / 运输中 / 已完成 / 异常（退货补发）/ 拦截 -- 列表：订单号、商品、规格、赠券金额、收货地址 -- 详情：物流状态、佣金（下单 + 核销两笔）、推广渠道来源 - -### 5.5 补发处理 - -**原型**：`9-补发处理.png` - -- 总部下达补发工单：原订单号、状态 -- 合伙人点击「开始配送」→ 推送城市配送 -- 物流签收回调 或 合伙人手动确认送达 - -### 5.6 拦截配送 - -**原型**：`4-拦截配送.png` - -- 用户改地址触发拦截通知 -- 合伙人查看详情，发起拦截 -- **拦截成功** → 新地址二次配送（等同正常订单流转） -- 待配送状态：直接撤回原单 - -### 5.7 财务对账与结算 - -**原型**：`10-财务对账.png`、`22-确认账单.png`、`23-申请打款.png` - - -| 概念 | 规则 | -| ---- | --------------------- | -| 账期 | T+30 天 | -| 流程 | 总部发起账单 → 合伙人确认 → 总部打款 | -| 账单状态 | 待结算 / 审核中 / 已结算 | -| 佣金构成 | 酒品下单佣金 + 权益核销佣金 | -| 佣金比例 | 总部在开城/合伙人配置处设置 | - - -**确认账单页** - -- 展示账期、应结总金额 -- 拆分：订单分佣 + 核销分佣 -- 勾选确认 → 申请打款 -- 仅**主账号**（签约账号）可收账单确认通知；子账号不可 - -### 5.8 经营周报 - -**原型**：`11-周报.png` - -- 默认近 7 天，可回溯 -- GMV、活跃门店数（有核销即活跃）、购酒订单量 -- 本周新签门店、每日 GMV 趋势、门店核销排行 - -### 5.9 子账号管理 - -**原型**：`15~16`、`18` - - -| 角色 | 说明 | -| ----- | ----- | -| 城市合伙人 | 子级合伙人 | -| 内部员工 | 拓店人员 | -| 推广员 | 线下推广 | - - -- 创建：姓名、手机号（验证码校验）、角色 -- 默认**禁用**，需手动启用 -- 可编辑、禁用、删除 -- 贡献榜按拓店数排名 - -### 5.10 合伙人中心 - -**原型**：`17`、`20-21` - -- 所在城市、账户余额（待结算 / 已提现） -- 发起提现 → 总部财务审核 -- 资产明细、合同管理（PDF、编号、签约/到期日期） -- 门店审核记录、员工管理入口 - ---- - -## 6. 总部管理端（微信小程序） - -**原型目录**：`pages/hq/` -**载体**：微信小程序 -**底部导航**：管理中心 | 门店审核 | 结算中心 | 客服中心 - -| 原型文件 | 页面 | PRD 模块 | -|----------|------|----------| -| `pages/hq/1-2` | 登录 | §6 | -| `pages/hq/3-5` | 首页/预警 | §6.1, §6.10 | -| `pages/hq/6-9` | 开城管理 | §6.2 | -| `pages/hq/10-11,13,24-25` | 订单中心 | §6.4 | -| `pages/hq/12,14` | 商品管理 | §6.3 | -| `pages/hq/15` | 数据报表 | §6.9 | -| `pages/hq/16-17` | 推广码 | §6.6 | -| `pages/hq/19-20` | 门店审核 | §6.5 | -| `pages/hq/21-23` | 结算中心 | §6.7 | -| `pages/hq/26-27` | 补发退款 | §6.8 | - -### 6.1 管理中心首页 - -**原型**：`3-数据聚合与预警.png` - -**今日概况**：订单数、新增用户、核销笔数、新增门店、今日 GMV、累计 GMV、核销金额 - -**待办预警**：超时订单等异常，可跳转处理 - -**核心管理入口** - -- 开城管理 -- 订单中心 -- 商品管理 -- 推广码 -- 数据报表 - -### 6.2 开城管理 - -**原型**：`6-开城管理.png`、`7-新增城市.png`、`8`、`9-配置佣金比例.png` - - -| 功能 | 说明 | -| ---- | --------------- | -| 城市列表 | 运营中 / 暂停 / 待开城 | -| 城市卡片 | 合伙人、门店数、累计 GMV | -| 操作 | 编辑、暂停/恢复、配置 | -| 新增城市 | 基本信息 + 开户行 + 附件 | -| 佣金配置 | 下单佣金比例、核销佣金比例 | - - -### 6.3 商品管理 - -**原型**：`12-商品列表.png`、`14-商品添加.png` - -- 杜康系列酒品 CRUD -- 字段：名称、规格、价格、香型、主图、图文详情、**权益金额（可选）** -- **权益金额规则**：留空 = 默认等于售价；填写 = 按配置值发放与展示 -- V1 上架 **4 款清香型**；上下架控制 - -### 6.4 订单中心 - -**原型**：`10-11`、`13-1~4`、`24-跨城订单处理.png`、`25-发货处理.png` - -- 全链路订单监控 -- 搜索：订单号、手机号、城市；时间筛选 -- 状态筛选：待发货 / 配送中 / 已完成 / 异常 -- 跨城订单：总部物流发货处理 -- 订单详情：完整履约信息、佣金拆分、推广来源 - -### 6.5 门店审核 - -**原型**：`19-门店审核管理.png`、`20-门店详情页面.png` - - -| Tab | 说明 | -| -------------------- | --- | -| 全部 / 待审核 / 已通过 / 已驳回 | — | - - -- 审核类型：首次入驻 / 信息修改 -- 操作：查看详情、修改、通过、驳回 -- 总部也可编辑门店信息 - -### 6.6 推广码管理 - -**原型**：`16-推广码管理.png`、`17-推广码生成.png` - -- 创建推广码（品鉴会等场景） -- 关联渠道名称 -- 订单归因统计 - -### 6.7 结算中心 - -**原型**：`21-结算中心.png`、`22-23` - -**Tab**：城市合伙人结算 | 门店结算 - - -| 功能 | 说明 | -| ----- | --------------------------- | -| 待结算总额 | 汇总 | -| 待处理记录 | 发送账单 / 确认打款 | -| 门店结算 | 核销打款给门店（60%），周期 **T+1 工作日** | - - -**结算周期对比** - - -| 对象 | 周期 | 流程 | -| ----- | -------- | --------------------- | -| 门店 | **T+1** | 总部按日/批打款，门店核销记录标记已打款 | -| 城市合伙人 | **T+30** | 账期 → 发账单 → 合伙人确认 → 打款 | - - -### 6.8 客服中心 · 补发与退款 - -**原型**：`26-补发与退款处理.png`、`27-补发详情页面.png` - - -| 功能 | 说明 | -| ---- | --------------------------------- | -| 补发 | 输入订单号 → 创建补发单 → 推送合伙人 → 跟踪配送 | -| 退款 | 输入订单号 → 创建退款工单 → 审核 → 微信退款 → 权益回退 | -| 工单列表 | 待处理 / 已完成；类型：补发 / 退款 | -| 关联查询 | 原订单、补发单、退款单互相关联 | - - -### 6.9 数据报表 - -**原型**：`15-数据报表中心.png` - -- 全链路经营数据看板 - -### 6.10 预警 - -**原型**：`4-预警详情.png`、`5-超时订单详情.png` - -- 超时未处理订单预警 -- 跳转订单处理 - ---- - -## 7. 关键业务流程 - -### 7.1 购酒履约 - -```mermaid -sequenceDiagram - participant U as C端用户 - participant S as 系统 - participant W as 微信支付 - participant D as 小飞侠/物流 - participant P as 城市合伙人 - - U->>S: 选商品、地址、数量 - S->>S: 校验起购量、配送方式 - U->>W: 微信支付 - W->>S: 支付回调 - S->>S: 订单待发货 + 发放好客权益 - S->>D: 推送配送 - D->>S: 状态回调(出库/配送中/签收) - S->>U: 更新订单进度 - Note over P: 同城由合伙人辖区履约 -``` - - - -### 7.2 好客权益核销 - -```mermaid -sequenceDiagram - participant U as C端用户 - participant S as 系统 - participant M as 门店H5 - - U->>S: 选门店、输入核销金额 - S->>U: 生成二维码(5min有效) - M->>S: 扫码 - S->>M: 展示确认页(金额/用户/券) - M->>S: 确认核销 - S->>U: 核销成功 + 评价 - S->>M: 更新记录 + 短信通知老板 -``` - - - -### 7.3 门店入驻 - -```mermaid -flowchart LR - A[合伙人录入门店] --> B[总部审核] - B -->|通过| C[门店生效可核销] - B -->|驳回| D[合伙人修改重提] - C --> E[C端可见可选] -``` - - - -### 7.4 合伙人结算 - -```mermaid -flowchart LR - A[T+30 账期到期] --> B[总部发起账单] - B --> C[合伙人确认] - C --> D[总部打款] - D --> E[已结算] -``` - - - -### 7.5 门店核销打款（T+1） - -```mermaid -flowchart LR - A[门店确认核销] --> B[记录待打款] - B --> C[T+1 工作日] - C --> D[总部批量打款] - D --> E[门店记录已打款] -``` - - - -### 7.6 退款流程 - -```mermaid -sequenceDiagram - participant U as C端用户 - participant CS as 总部客服 - participant S as 系统 - participant W as 微信退款 - - U->>CS: 申请退款(订单号) - CS->>S: 创建退款工单 - CS->>S: 审核通过 - S->>W: 发起退款 - W->>S: 退款回调 - S->>S: 回退未使用权益 - S->>U: 通知退款结果 -``` - - - ---- - -## 8. 非功能需求（初稿） - - -| 类别 | 要求 | -| --- | --------------------------- | -| 安全 | 手机号脱敏；核销码一次性+短时效 | -| 性能 | 首页/列表首屏 < 2s（目标，待压测确认） | -| 兼容 | 微信小程序基础库版本 **待确认** | -| 通知 | 短信（核销到账、账单链接）；微信服务号 **待确认** | - - ---- - -## 9. V1 决策记录（已确认） - - -| # | 决策项 | 结论 | -| --- | ------ | -------------------------- | -| 1 | 好客权益金额 | 默认 = 酒价；商品管理支持单独配置 | -| 2 | 暂停营业门店 | C 端完全隐藏 | -| 3 | 订单 Tab | 增加「待发货」：全部/待付款/待发货/待收货/已完成 | -| 4 | V1 范围 | 含退款、推广码、埋点；不含会员体系 | -| 5 | 上线范围 | 郑州 + 4 款清香型 | -| 6 | 总部端载体 | 微信小程序 | -| 7 | 核销单次上限 | ¥500 | -| 8 | 门店打款 | T+1 工作日 | - - ---- - -## 10. 待技术对接事项 - - -| # | 事项 | 说明 | -| --- | ----------- | -------------------- | -| 1 | 小飞侠 API | 出库/配送中/签收状态枚举与回调格式 | -| 2 | 跨城物流 API | 发货、轨迹、签收回调 | -| 3 | 微信退款 API | 退款时效、部分退款能力 | -| 4 | 小程序基础库版本 | 四端最低兼容版本 | -| 5 | 服务费 | V1 结算不扣除服务费；后续版本预留字段 | -| 6 | 总部小程序 appId | 独立应用 or 子包方案 | - - ---- - -## 11. V1 里程碑 - - -| 阶段 | 范围 | 交付 | -| ----- | -------------------------- | --------- | -| M1 基础 | 郑州开城、4 SKU、账号、总部小程序 | 可配置商品与开城 | -| M2 交易 | C端下单支付、待发货 Tab、同城配送 | 完整购酒履约 | -| M3 权益 | 权益发放（可配置金额）、门店、核销（¥500 上限） | O2O 闭环 | -| M4 运营 | 合伙人门店录入、补发/拦截、退款工单 | 城市运营 + 售后 | -| M5 结算 | 门店 T+1 打款、合伙人 T+30 对账 | 资金闭环 | -| M6 增长 | 推广码归因、行为埋点、数据报表 | 渠道可追溯 | - - ---- - - ---- - -# §三、原型全清单与页面流 - -## C端用户 `pages/user/` - -| 文件 | 页面 | 关联模块 | -|------|------|----------| -| 1-登录.png | 登录 | 账号 | -| 2-首页.png | 首页 | 商品展示、城市定位 | -| 3-商品详情页.png | 商品详情 | 商品、好客权益说明 | -| 4-立即购买确认订单.png | 确认订单（同城） | 下单 | -| 5-订单确认-跨城配送.png | 确认订单（跨城到付） | 下单、配送规则 | -| 6-地址列表.png | 地址列表 | 地址管理 | -| 7-新增收货地址.png | 新增地址 | 地址管理 | -| 8-微信支付页面.png | 微信支付 | 支付 | -| 9-我的订单列表.png | 订单列表 | 订单 | **5 Tab（含待发货）** | -| 10-我的订单-补发状态.png | 补发订单 | 售后 | -| 11-我的订单详情.png | 订单详情 | 订单履约 | -| 12-修改地址弹窗.png | 修改地址 | 订单 | -| 13-联系客服弹窗.png | 联系客服 | 客服 | -| 14-联系在线客服.png | 在线客服 | 客服 | -| 15-门店页面-门店列表.png | 门店列表 | 门店 | -| 16-门店详情页.png | 门店详情 | 门店 | -| 17-好客权益页.png | 好客权益 | 权益 | -| 18-好客权益明细.png | 权益明细 | 权益 | -| 19-个人中心页.png | 个人中心 | 我的 | V1 移除「至尊会员」标签 | -| 20-好客权益核销.png | 核销输入 | 核销 | -| 21-核销码展示.png | 核销码 | 核销 | -| 22-核销成功及评价.png | 核销成功 | 核销、评价 | - -**底部导航**：首页 | 门店 | 好客权益 | 我的 - -## 门店端 H5 `pages/shop/` - -| 文件 | 页面 | 关联模块 | -|------|------|----------| -| 1-登录页.png | 登录 | 账号 | -| 2-一键登录.png | 快捷登录 | 账号 | -| 3-门店管理首页-核销页.png | 首页 | 核销、营业状态 | -| 4-核销确认.png | 核销确认 | 核销 | -| 5-核销成功.png | 核销成功 | 核销 | -| 6-核销记录.png | 核销记录 | 账单 | -| 7-门店信息.png | 门店信息 | 门店 | - -**底部导航**：首页 | 核销记录 | 我的 - -## 城市合伙人 `pages/partner/` - -| 文件 | 页面 | 关联模块 | -|------|------|----------| -| 1-登录页.png | 登录 | 账号 | -| 2-快捷登录.png | 快捷登录 | 账号 | -| 3-首页.png | 工作台首页 | 概览 | -| 4-拦截配送.png | 拦截配送 | 订单拦截 | -| 5-门店管理.png | 门店管理 | 门店 | -| 6-录入门店.png | 录入门店-基本信息 | 门店入驻 | -| 7-录入门店-合同.png | 录入门店-照片合同 | 门店入驻 | -| 8-录入门店银行卡号.png | 录入门店-结算信息 | 门店入驻 | -| 9-补发处理.png | 补发处理 | 售后 | -| 10-财务对账.png | 财务对账 | 结算 | -| 11-周报.png | 经营周报 | 数据 | -| 12-订单列表.png | 订单列表 | 订单 | -| 13-订单详情.png | 订单详情 | 订单 | -| 14-贡献榜.png | 合伙人贡献榜 | 拓店 | -| 15-子账号管理.png | 子账号管理 | 账号 | -| 16-添加子账号.png | 添加子账号 | 账号 | -| 17-合伙人中心.png | 合伙人中心 | 我的 | -| 18-员工管理.png | 员工管理 | 账号 | -| 19-门店核销列表.png | 门店核销列表 | 权益 | -| 20-资产列表.png | 资产明细 | 佣金 | -| 21-合同管理.png | 合同管理 | 合同 | -| 22-确认账单.png | 确认账单 | 结算 | -| 23-申请打款.png | 申请打款 | 结算 | - -**底部导航**：首页 | 门店管理 | 合伙人中心 - -## 总部管理 `pages/hq/` - -| 文件 | 页面 | 关联模块 | -|------|------|----------| -| 1-登录.png | 登录 | 账号 | -| 2-快捷登录.png | 快捷登录 | 账号 | -| 3-数据聚合与预警.png | 管理中心首页 | 概览 | -| 4-预警详情.png | 预警详情 | 预警 | -| 5-超时订单详情.png | 超时订单 | 订单 | -| 6-开城管理.png | 开城管理 | 开城 | -| 7-新增城市.png | 新增城市 | 开城 | -| 8-完善开户行与附件上传.png | 开城-银行信息 | 开城 | -| 9-配置佣金比例.png | 配置佣金比例 | 开城/佣金 | -| 10-订单中心.png | 订单中心搜索 | 订单 | -| 11-订单中心管理页.png | 订单中心列表 | 订单 | -| 12-商品列表.png | 商品列表 | 商品 | -| 13-订单详情-1~4.png | 订单详情 | 订单 | -| 14-商品添加.png | 商品添加 | 商品 | -| 15-数据报表中心.png | 数据报表 | 数据 | -| 16-推广码管理.png | 推广码管理 | 营销 | -| 17-推广码生成.png | 推广码生成 | 营销 | -| 18-佣金拆分和订单.png | 佣金拆分 | 佣金 | -| 19-门店审核管理.png | 门店审核 | 门店 | -| 20-门店详情页面.png | 门店详情 | 门店 | -| 21-结算中心.png | 结算中心 | 结算 | -| 22-账单明细.png | 账单明细 | 结算 | -| 23-门店结算明细.png | 门店结算 | 结算 | -| 24-跨城订单处理.png | 跨城订单 | 订单 | -| 25-发货处理.png | 发货处理 | 订单 | -| 26-补发与退款处理.png | 补发退款 | 售后 | -| 27-补发详情页面.png | 补发详情 | 售后 | - -**底部导航**：管理中心 | 门店审核 | 结算中心 | 客服中心 - -## 第三方集成清单 - -| 系统 | 用途 | 触发场景 | -|------|------|----------| -| 微信登录/支付 | 登录、下单支付 | C端、门店、合伙人 | -| 微信客服 | 图文客服 | C端联系客服 | -| 小飞侠 | 同城配送状态回调 | 出库、配送中、签收 | -| 物流快递 | 跨城配送状态 | 跨城订单 | -| 微信地图 | 选址、导航 | 地址、门店 | -| 短信 | 核销到账通知、账单链接 | 门店老板 | -| 微信扫一扫 | 门店核销（H5 外） | 门店端 | - - -### C 端页面流 - -` -登录(1) → 首页(2) → 商品详情(3) → 确认订单(4/5) → 支付(8) - 订单列表(9) → 订单详情(11) → 修改地址(12) - 门店列表(15) → 门店详情(16) → 核销(20) → 核销码(21) → 成功(22) - 好客权益(17) → 明细(18) → 个人中心(19) → 地址(6/7) -` - -### 原型与 PRD 差异（实现以 PRD 为准） - -| 原型 | 说明 | -|------|------| -| pages/user/9 | Tab 必须为 5 个：全部/待付款/**待发货**/待收货/已完成 | -| pages/user/19 | 移除「至尊会员」标签 | -| 各端城市示例 | 原型多为洛阳，V1 上线城市为**郑州** | - ---- - -# §四、技术架构 - - - -### 1.1 建设目标 - -在 V1 范围内（郑州开城、4 SKU、四端协同）交付可运营的生产系统，支撑： - -- 购酒交易与微信支付的可靠闭环 -- 好客权益发放、核销与门店 T+1 结算 -- 城市合伙人拓店、履约、T+30 分佣结算 -- 总部开城/商品/审核/客服/数据运营 -- 推广码归因与用户行为埋点 - -### 1.2 架构原则 - -| 原则 | 说明 | -|------|------| -| **方案三：统一后端 + 模块归属** | 一个 NestJS 进程；全栈按「端 + 后端模块」分工，禁止多端各自起服务、仅共库 | -| **单体优先、模块化拆分** | V1 单进程部署；模块间通过 **Exported Service** 协作，禁止跨模块直写表 | -| **多端复用、统一 API** | 四端共用 REST API；契约见本手册 §六 | -| **事件驱动异步** | 支付/配送回调、埋点、T+1 结算走 BullMQ，保证幂等 | -| **开城可扩展** | 城市、佣金、配送规则配置化 | -| **财务可追溯** | 订单、权益、核销、打款全链路留痕 | -| **共享类型优先** | 枚举/DTO 放 `packages/shared-types`，禁止各端复制业务常量 | - -### 1.3 推荐技术栈（总览） - -| 层次 | 推荐选型 | 备选 | -|------|----------|------| -| C端 / 合伙人 / 总部小程序 | **Taro 3 + React + TypeScript** | 原生微信小程序 ×3 | -| 门店 H5 | **Taro H5**（与小程序同 monorepo） | Vue3 + Vite 独立 H5 | -| 后端 API | **Node.js 20 LTS + NestJS 10** | Express / Koa（需自建分层） | -| ORM | **Prisma** | TypeORM | -| 主库 | **MySQL 8.0** | — | -| 缓存 / 锁 / 队列 | **Redis 7** + **BullMQ** | ioredis 直连 | -| 对象存储 | 阿里云 OSS / 腾讯云 COS | — | -| 定时任务 | **@nestjs/schedule** + BullMQ 延时队列 | node-cron | -| 埋点 | 自建 `log_user_analytics` + BullMQ 异步入库 | — | -| 部署 | Docker + PM2 或 Node 单进程 + Nginx | K8s（二期） | -| CI/CD | GitHub Actions / GitLab CI | — | - -**选型理由（NestJS + Taro 全栈 TypeScript）** - -- **与前端同语言**：Taro 与 NestJS 共用 TypeScript，DTO/枚举可抽到 `packages/shared-types`，减少联调成本 -- **NestJS 模块化**：Module/Controller/Service 分层清晰，接近 Spring 结构，适合订单/结算等复杂域 -- **微信生态**：`wechatpay-node-v3`、小程序 code2session 等 Node SDK 成熟，满足 V1 支付/退款 -- **异步友好**：支付回调、埋点、短信等 I/O 密集场景 Node 表现良好 -- V1 仍为**模块化单体**，无需微服务 - ---- - -## 2. 系统架构 - -### 2.1 逻辑架构 - -```mermaid -flowchart TB - subgraph clients [客户端] - U[C端小程序] - P[合伙人小程序] - H[总部小程序] - S[门店 H5] - end - - subgraph gateway [接入层] - NG[Nginx / HTTPS] - end - - subgraph app [dukang-api 单体服务] - direction TB - M1[iam 身份认证] - M2[catalog 商品开城] - M3[trade 交易订单] - M4[benefit 好客权益] - M5[store 门店] - M6[redeem 核销] - M7[settlement 结算] - M8[ops 总部运营] - M9[notify 通知集成] - M10[analytics 埋点报表] - end - - subgraph infra [基础设施] - DB[(MySQL)] - RD[(Redis)] - OSS[对象存储] - end - - subgraph ext [外部系统] - WX[微信登录/支付/退款/客服] - XFX[小飞侠配送] - LOG[物流快递] - SMS[短信] - end - - U & P & H & S --> NG --> app - app --> DB & RD & OSS - app --> WX & XFX & LOG & SMS -``` - -### 2.2 部署架构（V1） - -``` - ┌──────────────┐ - │ CDN/OSS │ 静态资源、图片 - └──────────────┘ -┌─────────┐ ┌──────────────┐ ┌─────────┐ -│ 微信小程序 │ ──────►│ Nginx + SSL │────────►│ MySQL │ -│ ×3 + H5 │ │ NestJS :3000 │ │ 主从可选 │ -└─────────┘ └──────┬───────┘ └─────────┘ - │ - └────────────────► Redis + BullMQ -``` - -- **环境**：dev / staging / prod 三套 -- **配置**：敏感项走环境变量（`.env` 不入库）；生产用 Docker secrets -- **日志**：Pino 结构化 JSON + 请求 traceId（nestjs-pino） -- **进程**：PM2 cluster 或 Docker 单副本；V1 单实例即可 - -### 2.3 仓库结构（Monorepo 建议） - -``` -dukang/ -├── apps/ -│ ├── mini-user/ # C端 Taro 小程序 -│ ├── mini-partner/ # 合伙人 Taro 小程序 -│ ├── mini-hq/ # 总部 Taro 小程序 -│ └── h5-shop/ # 门店 H5（Taro 或独立） -├── packages/ -│ ├── shared-ui/ # 公共组件（前端） -│ ├── shared-utils/ # 工具、常量 -│ ├── shared-types/ # API DTO、枚举、错误码（前后端共用） -│ └── domain/ # 纯函数领域规则（起购/核销上限/权益计算，无 IO） -├── server/ -│ └── dukang-api/ # 唯一后端进程（NestJS 单体） -│ ├── prisma/ # schema 按模块 OWNER 分区注释，迁移需 OWNER Review -│ └── src/ -│ ├── common/ # 全局：Guard、Filter、PrismaModule -│ ├── modules/ # 见 §2.4 模块归属 -│ ├── callbacks/ # 微信/配送回调（薄层，转调各 Module Service） -│ └── jobs/ # BullMQ 消费者、定时任务 -├── doc/ -└── deploy/ -``` - ---- - -## 2.4 多人协作架构（方案三） - -### 2.4.1 方案定义 - -| 项 | 结论 | -|----|------| -| 选定方案 | **方案三**：Monorepo + **一个** NestJS 后端 + 模块 OWNER + 全栈负责「端 + 模块」 | -| 明确不做 | 多端各自独立后端、仅数据库对齐；多个微信支付回调入口 | -| 协作单元 | **后端 Module**（领域边界）+ **前端 App**（交互边界） | -| 集成契约 | HTTP API（`doc/API列表-杜康好客.md`）+ `shared-types` + Prisma schema（OWNER Review） | - -### 2.4.2 分工模型 - -``` -全栈开发者 A ──► apps/mini-user + modules/{iam,trade,benefit} Controller -全栈开发者 B ──► apps/mini-partner + modules/{store} + 部分 partner 接口 -全栈开发者 C ──► apps/mini-hq + modules/{catalog,ops,settlement} 总部侧 -全栈开发者 D ──► apps/h5-shop + modules/{redeem} + 门店侧接口 -公共 ──► packages/* , callbacks/, jobs/ , prisma 迁移（架构师/轮值 Review） -``` - -> OWNER 为**主责**（改代码、Review PR、负责迁移），非 OWNER 提需求走 Issue + 跨模块 PR。 - -### 2.4.3 模块与端归属表 - -| 后端模块 | 职责摘要 | 主 OWNER 建议 | 关联前端 App | 关联 API 前缀 | -|----------|----------|---------------|--------------|---------------| -| **iam** | 登录、JWT、四端鉴权、用户身份 U1~U5 | 全栈 A | 四端共用 | `/auth`, `/user` | -| **catalog** | 开城、商品、推广码、佣金配置 | 全栈 C | mini-hq | `/catalog`, `/admin/cities`, `/admin/products`, `/admin/promo-codes` | -| **trade** | 订单、支付、退款、拦截、补发单 | 全栈 A | mini-user, mini-partner, mini-hq | `/trade`, `/admin/orders`, `/partner/orders` | -| **benefit** | 权益券、流水、发放/作废 | 全栈 A | mini-user | `/benefit` | -| **store** | 门店 CRUD、审核、营业状态 | 全栈 B | mini-partner, mini-user, mini-hq | `/stores`, `/partner/stores`, `/admin/store-audits` | -| **redeem** | 核销码、确认核销、评价 | 全栈 D | h5-shop, mini-user | `/redeem`, `/shop/redeem` | -| **settlement** | 门店 T+1、合伙人 T+30、提现 | 全栈 C | mini-partner, h5-shop, mini-hq | `/settlement`, `/partner/settlement`, `/admin/settlement` | -| **ops** | 总部看板、预警、报表聚合 | 全栈 C | mini-hq | `/admin/dashboard`, `/admin/reports`, `/admin/alerts` | -| **notify** | 短信、订阅消息（被各模块调用） | 轮值 / 架构 | — | 内部 Service | -| **analytics** | 埋点入库、渠道统计 | 全栈 A | mini-user + 总部报表 | `/analytics`, `/promo/touch` | -| **callbacks** | 微信/小飞侠/物流回调入口 | 架构师 + trade OWNER | — | `/callbacks/*` | -| **jobs** | 超时关单、T+1 打款、出账 | settlement + trade OWNER | — | 内部 | - -### 2.4.4 协作规则（强制） - -| # | 规则 | +| § | 内容 | |---|------| -| R1 | **禁止** Module A 直接使用 `PrismaService` 读写 Module B 拥有的表；只调用 B 导出的 `XxxService` | -| R2 | 每个 Module 通过 `xxx.module.ts` 的 `exports: [XxxService]` 暴露能力；禁止 export Repository/Prisma 裸访问 | -| R3 | 改 `schema.prisma` 中某表 → 必须对应模块 OWNER Review | -| R4 | 新增/变更 API → 同步更新 `doc/API列表-杜康好客.md` + `shared-types` | -| R5 | 跨模块写操作走 **Service 调用** 或 **Domain Event + BullMQ**；禁止分布式「各写各的」 | -| R6 | 微信支付/退款/配送回调 **仅** `callbacks/` 入口，内部转调 `TradeService` 等 | -| R7 | 集成测试必须覆盖横切链路：购酒→发券→核销→门店打款（CI 门禁） | -| R8 | 前端 App **禁止** import `server/` 代码；只通过 HTTP + `shared-types` | - -### 2.4.5 全栈闭环定义 - -「独立闭环」指 **在模块依赖规则内** 端到端交付，而非单独部署： - -| 开发者 | 闭环范围（示例） | -|--------|------------------| -| A | C端下单支付 → 发券 → 权益页（trade + benefit + mini-user） | -| B | 合伙人录店 → 总部审核 → C端可见（store + mini-partner + 配合 C 审核 API） | -| D | C端出码 → 门店扫码核销 → 短信通知（redeem + h5-shop + notify 调用） | -| C | 总部退款/结算/报表（trade 回调 + settlement + ops + mini-hq） | - ---- - -## 2.5 模块依赖：允许 / 禁止 - -### 2.5.1 分层与允许依赖（模块图） - -**规则**：只能 **向下** 或 **同层通过 exported Service** 依赖；箭头表示「允许 import / inject」。 - -```mermaid -flowchart TB - subgraph L6 [L6 接入与编排] - CB[callbacks 回调入口] - JB[jobs 定时与队列] - OP[ops 运营报表] - end - - subgraph L5 [L5 结算域] - ST[settlement 结算] - end - - subgraph L4 [L4 核销域] - RD[redeem 核销] - end - - subgraph L3 [L3 交易域] - TR[trade 订单支付] - BF[benefit 好客权益] - end - - subgraph L2 [L2 主数据] - CT[catalog 开城商品] - SO[store 门店] - end - - subgraph L1 [L1 基础域] - IM[iam 身份] - AN[analytics 埋点] - NT[notify 通知] - end - - subgraph L0 [L0 基础设施] - CM[common 公共] - PR[(prisma)] - PK[packages/domain] - end - - CB --> TR - CB --> ST - JB --> ST - JB --> TR - - OP --> TR - OP --> ST - OP --> SO - OP --> AN - - ST --> TR - ST --> RD - ST --> SO - ST --> CT - - RD --> BF - RD --> SO - RD --> ST - RD --> IM - RD --> NT - - TR --> BF - TR --> CT - TR --> IM - TR --> SO - TR --> NT - - BF --> IM - - SO --> CT - SO --> IM - - CT --> IM - - AN --> IM - - IM --> CM - TR --> CM - BF --> CM - RD --> CM - ST --> CM - SO --> CM - CT --> CM - OP --> CM - AN --> CM - NT --> CM - CB --> CM - JB --> CM - - TR -.-> PK - BF -.-> PK - RD -.-> PK - ST -.-> PK -``` - -**图例** - -- 实线箭头：允许 **NestJS Module imports + Service 注入** -- 虚线：允许引用 `packages/domain` **纯函数**（无 DB/Redis） - -### 2.5.2 允许依赖矩阵（✅ = 可调 Service） - -| 调用方 ↓ / 被调方 → | iam | catalog | store | trade | benefit | redeem | settlement | notify | analytics | domain | -|---------------------|:---:|:-------:|:-----:|:-----:|:-------:|:------:|:----------:|:------:|:---------:|:------:| -| **catalog** | ✅ | — | | | | | | | | ✅ | -| **store** | ✅ | ✅ | — | | | | | | | ✅ | -| **trade** | ✅ | ✅ | ✅ | — | ✅ | | | ✅ | | ✅ | -| **benefit** | ✅ | | | — | — | | | | | ✅ | -| **redeem** | ✅ | | ✅ | | ✅ | — | ✅ | ✅ | | ✅ | -| **settlement** | ✅ | ✅ | ✅ | ✅ | | ✅ | — | ✅ | | ✅ | -| **ops** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅ | | -| **callbacks** | | | | ✅ | ✅ | | ✅ | | | | -| **jobs** | | | | ✅ | | | ✅ | ✅ | | | -| **analytics** | ✅ | | | | | | | | — | | - -### 2.5.3 禁止依赖（❌ 违反即 PR 拒绝） - -| # | 禁止项 | 原因 | 正确做法 | -|---|--------|------|----------| -| F1 | `redeem` → 直接 `prisma.order.update` | 订单归 trade | 调 `TradeService` | -| F2 | `store` → `trade` / `benefit` | 门店域不处理交易 | 由 redeem/trade 回调 | -| F3 | `benefit` → `trade` / `redeem` | 防止循环依赖 | trade 调 `BenefitService.grant(dto)`，benefit 不反向查 trade | -| F4 | `trade` → `redeem` | 交易不感知核销细节 | 仅通过 benefit 关联 | -| F5 | `benefit` → `redeem` | 权益不依赖核销 | redeem 调 benefit 扣券 | -| F6 | `catalog` → `trade` / `settlement` | 主数据不依赖业务 | 反向调用 | -| F7 | 任意 Module → 另一 Module 的 `*.controller.ts` | Controller 不可跨模块引 | 只 inject Service | -| F8 | 任意 Module → 另一 Module 未 export 的 Provider | 破坏封装 | 在 `module.ts` 显式 exports | -| F9 | `apps/*` → `server/*` 源码 import | 前后端物理隔离 | HTTP + shared-types | -| F10 | 多个 Module 各自注册 `/callbacks/wechat/pay` | 重复回调 | 仅 `callbacks` 模块 | -| F11 | 复制粘贴起购/核销/权益规则到 Controller | 规则漂移 | 用 `packages/domain` | - -### 2.5.4 跨模块典型调用链（允许） - -**支付成功发券** - -``` -callbacks/wechat/pay → TradeService.handlePaySuccess() - → BenefitService.grantOnOrderPaid(orderId) - → NotifyService（可选） -``` - -**核销确认** - -``` -ShopRedeemController → RedeemService.confirm() - → BenefitService.deduct(couponId) - → SettlementService.createStorePayout(redeemRecordId) - → NotifyService.sendSms(storeOwner) -``` - -**退款** - -``` -AdminRefundController → TradeService.createRefund() - → BenefitService.voidUnused(orderId) - → WechatPayService.refund() -``` - -### 2.5.5 Module 文件约定 - -每个模块目录结构统一，便于 CODEOWNERS： - -``` -modules/trade/ -├── trade.module.ts # imports / exports 唯一入口 -├── trade.controller.ts # 仅本域路由 -├── trade.service.ts # 业务 + 本域表 Prisma -├── dto/ -├── events/ # 可选：BullMQ producer -└── __tests__/ -``` - -`trade.module.ts` 示例： - -```typescript -@Module({ - imports: [CatalogModule, BenefitModule, IamModule, NotifyModule], - controllers: [TradeController, PartnerOrderController, AdminOrderController], - providers: [TradeService, WechatPayService], - exports: [TradeService], // 仅导出 Service -}) -export class TradeModule {} -``` - ---- - -## 3. 后端模块设计 - -### 3.1 模块职责 - -| 模块 | 职责 | 主要实体 | -|------|------|----------| -| **iam** | 四端登录、Token、角色权限、子账号 | User, Account, Role, Session | -| **catalog** | 商品、开城、推广码、佣金配置 | Product, City, PromoCode, CommissionRule | -| **trade** | 订单、支付、退款、补发、地址改派 | Order, OrderItem, Payment, Refund, Reshipment | -| **benefit** | 权益券发放、余额、明细 | BenefitCoupon, BenefitLedger | -| **store** | 门店 CRUD、审核、营业状态 | Store, StoreAudit, StoreMedia | -| **redeem** | 核销码生成、门店扫码核销、评价 | RedeemToken, RedeemRecord, StoreRating | -| **settlement** | 门店 T+1、合伙人 T+30 账单 | StorePayout, PartnerBill, Withdrawal | -| **ops** | 总部首页统计、预警、报表 | Alert, ReportSnapshot | -| **notify** | 微信/短信/订阅消息封装 | NotificationLog | -| **analytics** | 埋点接收、渠道归因 | EventLog, ChannelAttribution | - -### 3.2 核心领域模型（简化 ER） - -```mermaid -erDiagram - USER ||--o{ ORDER : places - ORDER ||--|{ ORDER_ITEM : contains - ORDER ||--o| PAYMENT : has - ORDER ||--o{ BENEFIT_COUPON : grants - BENEFIT_COUPON ||--o{ REDEEM_RECORD : redeemed_at - STORE ||--o{ REDEEM_RECORD : receives - STORE }o--|| CITY : belongs - CITY }o--|| PARTNER : managed_by - ORDER }o--o| PROMO_CODE : attributed - REDEEM_RECORD ||--o| STORE_PAYOUT : settles - PARTNER ||--o{ PARTNER_BILL : billed -``` - -### 3.3 订单状态机（后端枚举） - -``` -PENDING_PAY 待付款 -PENDING_SHIP 待发货 -SHIPPING 配送中 -PENDING_RECEIVE 待签收 -COMPLETED 已完成 -REFUNDING 退款中 -REFUNDED 已退款 -``` - -补发单：`RESHIPMENT`，关联 `origin_order_id`，金额 0。 - -### 3.4 好客权益规则（实现要点） - -```typescript -// 发放金额 -const benefitAmount = product.benefitAmount ?? product.price; - -// 核销校验 -if (amount <= 0 || amount > coupon.balance || amount > 500) { - throw new BusinessException('INVALID_REDEEM_AMOUNT'); -} -``` - -- 核销 Token：Redis `SET redeem:token:{id} JSON EX 300` -- 核销事务：Prisma `$transaction` 内完成「扣券余额 → 写 redeem_record → 写 store_payout 待打款」 -- 并发：券表 `version` 字段乐观锁，或 `UPDATE ... WHERE balance >= amount` - -### 3.5 NestJS 模块与依赖 - -> **模块边界与允许/禁止依赖见 §2.5。** 下表为各 Module 技术要点。 - -| NestJS Module | 主要 Providers | 外部依赖 | -|---------------|----------------|----------| -| `IamModule` | AuthService, JwtStrategy | Redis（session） | -| `TradeModule` | OrderService, WechatPayService | BenefitModule, CatalogModule | -| `RedeemModule` | RedeemService | BenefitModule, SettlementModule, Redis | -| `SettlementModule` | PayoutService, BillService | BullMQ（T+1 任务） | -| `NotifyModule` | SmsService, WxSubscribeService | 短信 SDK（被各模块 inject） | - -**常用 Nest 生态** - -| 能力 | 包 | -|------|-----| -| 配置 | `@nestjs/config` | -| 校验 | `class-validator` + `class-transformer` | -| JWT | `@nestjs/jwt` + `@nestjs/passport` | -| 定时 | `@nestjs/schedule` | -| 队列 | `@nestjs/bullmq` | -| 微信支付的 | `wechatpay-node-v3` | -| API 文档 | `@nestjs/swagger` | - -### 3.6 鉴权与多租户 - -| 端 | 标识 | 数据隔离 | -|----|------|----------| -| C端 | `user_id` | 仅本人订单/权益/地址 | -| 门店 | `store_id` | 仅本店核销记录 | -| 合伙人 | `partner_id` + `city_id` | 仅辖城市订单/门店 | -| 总部 | `admin_role` | 全局；操作审计日志 | - -**Token**：JWT（access 2h）+ Redis refresh；小程序登录走 `wx.login` → code2session。 - ---- - -## 4. 接口设计规范 - -### 4.1 约定 - -- Base URL：`https://api.example.com/api/v1` -- 认证：`Authorization: Bearer ` -- 响应：`{ "code": 0, "message": "ok", "data": {} }` -- 分页：`page`, `pageSize`；列表统一 `{ list, total }` -- 幂等：支付回调、核销、退款用 **业务幂等键**（`idempotency_key` / 微信 `transaction_id`） - -### 4.2 核心 API 分组（V1） - -#### 认证 ` /auth` - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/auth/sms/send` | 发送验证码 | -| POST | `/auth/login/sms` | 手机号登录 | -| POST | `/auth/login/wechat` | 微信登录（含 appId 区分端） | -| POST | `/auth/refresh` | 刷新 Token | - -#### 商品与开城 ` /catalog` - -| GET | `/products` | 商品列表（按城市/香型） | -| GET | `/products/{id}` | 商品详情 | -| GET | `/cities/current` | 当前开城信息 | - -#### 交易 ` /trade` - -| POST | `/orders/preview` | 下单预览（配送方式、起购校验、运费） | -| POST | `/orders` | 创建订单 | -| POST | `/orders/{id}/pay` | 发起微信支付 | -| POST | `/callbacks/wechat/pay` | 支付回调（内部） | -| GET | `/orders` | 订单列表（tab 参数） | -| GET | `/orders/{id}` | 订单详情 | -| PUT | `/orders/{id}/address` | 修改地址（触发拦截工单） | -| POST | `/orders/{id}/confirm-receive` | 确认收货 | - -#### 权益与核销 ` /benefit`, `/redeem` - -| GET | `/benefit/summary` | 权益余额汇总 | -| GET | `/benefit/coupons` | 券列表 | -| POST | `/redeem/token` | 生成核销码 | -| POST | `/redeem/confirm` | 门店确认核销 | -| POST | `/redeem/rating` | 核销后评价 | - -#### 门店 ` /stores` - -| GET | `/stores` | C端门店列表（仅营业中） | -| GET | `/stores/{id}` | 门店详情 | -| PUT | `/stores/{id}/status` | 门店切换营业状态（门店端） | -| POST | `/stores` | 合伙人录入门店 | -| POST | `/stores/{id}/audit` | 总部审核 | - -#### 结算 ` /settlement` - -| GET | `/settlement/store/records` | 门店核销记录 | -| GET | `/settlement/partner/bills` | 合伙人账单 | -| POST | `/settlement/partner/bills/{id}/confirm` | 确认账单 | - -#### 总部运营 ` /admin` - -| GET | `/admin/dashboard` | 今日概况 | -| GET | `/admin/alerts` | 待办预警 | -| POST | `/admin/refunds` | 创建退款工单 | -| POST | `/admin/reshipments` | 创建补发单 | -| POST | `/admin/promo-codes` | 创建推广码 | - -#### 埋点 ` /analytics` - -| POST | `/analytics/events` | 批量上报（可异步队列） | - ---- - -## 5. 第三方集成 - -### 5.1 微信支付 - -| 场景 | 接口 | 要点 | -|------|------|------| -| 下单支付 | JSAPI 统一下单 | `wechatpay-node-v3`，按 appId 多商户配置 | -| 支付回调 | notify_url | 验签 → BullMQ 异步入队 → 幂等更新订单 → 发券 | -| 退款 | 退款 API | RefundService；失败重试队列 | - -### 5.2 小飞侠（同城配送） - -- 下单成功后推送配送单 -- 回调状态映射：`OUT_WAREHOUSE → SHIPPING → DELIVERED` -- 超时未回调 → 总部预警（`admin/alerts`） - -### 5.3 跨城物流 - -- 总部手动/半自动发货；对接物流查询 API（V1 可人工录入运单号 + 状态手动更新，API 对接并行） - -### 5.4 短信 - -- 核销成功通知门店老板 -- 账单链接（短链跳转 H5/小程序页） - -### 5.5 推广码 - -- 小程序码参数：`scene=promo_{code}` -- 启动时写入 Redis `user:{id}:channel`，下单时落库 `order.channel_source` - ---- - ---- - -# §五、数据库设计 v3.1 - -## 1. 命名规范 - -| 前缀 | 含义 | 示例 | -|------|------|------| -| `user_` | C 端用户域 | `user_order` | -| `partner_` | 城市合伙人域 | `partner_bill` | -| `store_` | 门店域 | `store_store` | -| `hq_` | 总部域 | `hq_account` | -| `common_` | 跨域公共 | `common_resource`、`common_event` | -| `log_` | 日志/审计（只追加） | `log_third_party` | - ---- - -## 2. 公共抽象设计 - -### 2.1 `common_resource`（资源表 · OSS） - -所有图片、视频、合同文件统一入库，文件实体在**阿里云 OSS**。 - -| 字段 | 说明 | -|------|------| -| `owner_type` | 归属类型：`PRODUCT` / `STORE` / `PARTNER` / `USER` / `ORDER` / `HQ` | -| `owner_id` | 归属业务 ID | -| `biz_type` | 业务用途：`COVER` / `ENV` / `CONTRACT` / `CAROUSEL` / `DETAIL` / `AVATAR` / `QRCODE` / `SIGN_PHOTO` / `VIDEO` | -| `media_type` | `IMAGE` / `VIDEO` / `FILE` | -| `oss_bucket` / `oss_key` | OSS 定位 | -| `url` | 访问 URL（CDN） | -| `sort_order` | 同 owner 下排序 | - -**替代关系** - -| 原表/字段 | v3 做法 | -|-----------|---------| -| `store_media` | `owner_type=STORE`, `biz_type=COVER/ENV/CONTRACT` | -| `partner_contracts.file_url` | `owner_type=PARTNER`, `biz_type=CONTRACT` + `partner` 表存 contract_no | -| `products.main_image_url` / `carousel_urls` | `owner_type=PRODUCT`, `biz_type=COVER/CAROUSEL` | -| `stores.cover_url` | `cover_resource_id` → `common_resource.id` | -| `promo_codes.wx_qrcode_url` | `owner_type=PROMO`, `biz_type=QRCODE` | -| 用户头像 | `owner_type=USER`, `biz_type=AVATAR` | -| 签收照片 | `owner_type=ORDER`, `biz_type=SIGN_PHOTO` | - -### 2.2 `common_event`（统一业务事件表） - -**定位**：仅记录**有业务语义、需审计/追溯**的后端事件（审核、状态流转、权益变动、总部操作、推广触达统计）。**用户行为埋点**写入 `log_user_analytics`，不写入本表。 - -查询：`ref_type + ref_id + event_type`。 - -| 字段 | 说明 | -|------|------| -| `event_type` | 事件类型（见 §5.1） | -| `ref_type` / `ref_id` | 关联业务实体 | -| `actor_type` / `actor_id` | 操作人（USER/STORE/PARTNER/HQ/SYSTEM） | -| `status` | 部分事件有状态（如审核 PENDING/APPROVED） | -| `param1` ~ `param3` | 参数值（状态码、ID、类型等） | -| `param1_desc` ~ `param3_desc` | 参数含义说明（文档化，便于 UI 展示） | -| `amount1` / `amount2` | **仅 `BENEFIT_LEDGER` 使用**（变动额、变动后余额）；其余类型为 NULL | -| `remark` | 备注/驳回原因 | -| `extra_json` | 扩展快照（原 submit_data、操作 detail 等） | - -### 2.3 `common_ticket`（通用工单表） - -原 `after_sale_tickets`、部分 `alerts` 等工单类事务统一抽象。 - -| 字段 | 说明 | -|------|------| -| `ticket_type` | `REFUND` / `RESHIPMENT` / `ALERT` | -| `ticket_no` | 对外工单号 | -| `ref_type` / `ref_id` | 关联订单/门店等 | -| `operator_type` / `operator_id` | 处理人 | -| `param1` ~ `param3` + desc | 类型相关参数（金额、关联单号等） | -| `status` | 工单状态 | - -### 2.4 `log_third_party`（第三方交互记录） - -原 `payments` 及所有外部调用统一记录。 - -| 字段 | 说明 | -|------|------| -| `provider` | `WECHAT_PAY` / `WECHAT_REFUND` / `WECHAT_AUTH` / `WECHAT_MAP` / `XFX` / `SMS` / `LOGISTICS` | -| `scene` | 业务场景：`ORDER_PAY` / `ORDER_REFUND` / `LOGIN` / `DELIVERY_CALLBACK` / `SMS_VERIFY` … | -| `ref_type` / `ref_id` | 关联订单/用户等 | -| `request_url` | 请求 URL | -| `request_body` | 发送参数 JSON | -| `response_body` | 响应 JSON | -| `external_no` | 第三方单号（微信 transaction_id 等） | -| `amount` | 涉及金额 | -| `status` | `PENDING` / `SUCCESS` / `FAILED` | - -**订单支付**：不再建 `payments` 表；`user_order` 保留 `pay_status` / `paid_at` / `pay_external_no` 冗余字段，明细查 `log_third_party`。 - -**核销码**：删除 `redeem_tokens` 表，**仅存 Redis**（5 分钟）；`user_redeem_record` 不再存 token_id。 - -### 2.5 `log_user_analytics`（用户埋点日志） - -C 端行为埋点专用表，与 `common_event` 分离（见 §4.1 探讨）。 - -| 字段 | 说明 | -|------|------| -| `user_id` | 用户 ID；未登录上报可为 NULL | -| `session_id` | 会话 ID，用于漏斗串联 | -| `event_name` | 事件名（与 PRD §3.10.2 对齐，见 §4.1） | -| `ref_type` / `ref_id` | 关联商品/门店/订单等 | -| `keyword` | 搜索类事件关键词 | -| `source_type` / `source_ref_id` | 注册类事件来源快照 | -| `extra_json` | 其余埋点参数 | - ---- - -## 3. 表清单（28 张） - -| 前缀 | 表名 | 说明 | -|------|------|------| -| common | `common_wx_app_config` | 四端微信配置 | -| common | `common_resource` | 统一资源（OSS） | -| common | `common_event` | 统一业务事件（非埋点） | -| common | `common_ticket` | 通用工单 | -| common | `common_product_item` | 商品 SKU（含 69 码） | -| common | `common_store_category` | 门店餐饮分类 | -| common | `common_city` | 开城 | -| common | `common_city_commission_rule` | 城市佣金规则 | -| common | `common_promo_code` | 推广码 | -| user | `user_user` | C 端用户（含注册来源） | -| user | `user_address` | 收货地址 | -| user | `user_city_preference` | 城市偏好 | -| user | `user_promo_attribution` | 推广首次触达（统计用） | -| user | `user_order` | 订单（含商品快照冗余，无明细子表） | -| user | `user_order_delivery` | 配送（含签收照，与订单 1:1） | -| user | `user_benefit_coupon` | 权益券 | -| user | `user_redeem_record` | 核销记录 | -| user | `user_store_rating` | 核销评价 | -| partner | `partner_partner` | 合伙人主体 | -| partner | `partner_account` | 合伙人账号 | -| partner | `partner_bill` | T+30 账单（汇总金额，无 commission 明细表） | -| store | `store_store` | 门店 | -| store | `store_account` | 门店登录账号 | -| store | `store_payout` | 门店 T+1 打款 | -| hq | `hq_account` | 总部账号 | -| log | `log_third_party` | 第三方交互日志 | -| log | `log_user_analytics` | 用户行为埋点日志 | - ---- - -## 5. 枚举与事件/工单参数映射 - -### 5.1 `common_event.event_type`（写入逻辑） - -| event_type | 中文 | 原表 | 触发逻辑 | param 约定 | amount | -|------------|------|------|----------|------------|--------| -| `STORE_AUDIT` | 门店审核 | store_audits | 门店提交入驻/资料变更；总部审核通过或驳回 | p1=audit_type(NEW/UPDATE), p2=status, p3=reviewer_id；remark=驳回原因；extra=submit_data | — | -| `ORDER_STATUS` | 订单状态变更 | order_status_logs | 状态机每次 transition（含 SYSTEM/回调） | p1=from_status, p2=to_status, p3=operator 标识 | — | -| `BENEFIT_LEDGER` | 权益流水 | benefit_ledgers | 发券/核销/退款作废/人工调整，与券余额变更同事务 | p1=ledger_type(GRANT/REDEEM/VOID/ADJUST), p2=coupon_id, p3=ref_id；ref_type=关联类型 | **amount1=变动额, amount2=balance_after** | -| `HQ_OPERATION` | 总部操作审计 | operation_logs | 总部后台写操作（非查询） | p1=action, p2=ref_type, p3=ref_id；extra=detail | — | -| `PROMO_TOUCH` | 推广触达 | — | 用户扫码/带参进入（可选，与 scan_count++ 同事务） | p1=promo_code_id, p2=触达类型(SCAN/LINK) | — | - -### 5.2 `common_ticket.ticket_type` - -| ticket_type | 中文 | 原场景 | param 约定 | -|-------------|------|--------|------------| -| `REFUND` | 退款工单 | 客服发起退款 | p1=refund_amount, p2=wx_refund_id, p3=benefit_adjust | -| `RESHIPMENT` | 补发工单 | 漏发/错发补发 | p1=origin_order_id, p2=reshipment_order_id | -| `ALERT` | 运营预警 | 超时未发货等 | p1=alert_type, p2=severity；extra=content | - -### 5.3 枚举值（含中文释义） - -#### 订单 `user_order` - -| 字段 | 枚举值 | 中文释义 | -|------|--------|----------| -| `status` | `PENDING_PAY` | 待付款 | -| | `PENDING_SHIP` | 待发货 | -| | `OUT_WAREHOUSE` | 已出库 | -| | `SHIPPING` | 配送中 | -| | `PENDING_RECEIVE` | 待签收 | -| | `COMPLETED` | 已完成 | -| | `CANCELLED` | 已取消 | -| | `REFUNDING` | 退款中 | -| | `REFUNDED` | 已退款 | -| `pay_status` | `UNPAID` | 未支付 | -| | `PAYING` | 支付中 | -| | `PAID` | 已支付 | -| | `REFUNDING` | 退款中 | -| | `REFUNDED` | 已退款 | -| `order_type` | `NORMAL` | 普通订单 | -| | `RESHIPMENT` | 补发订单 | -| `delivery_type` | `LOCAL` | 同城配送 | -| | `CROSS_CITY` | 跨城配送 | -| `freight_pay_type` | `FREE` | 包邮 | -| | `COD` | 运费到付 | - -#### 权益 `user_benefit_coupon` - -| 字段 | 枚举值 | 中文释义 | -|------|--------|----------| -| `status` | `ACTIVE` | 可用 | -| | `USED_UP` | 已用完 | -| | `VOID` | 已作废 | - -#### 门店 `store_store` - -| 字段 | 枚举值 | 中文释义 | -|------|--------|----------| -| `status` | `OPEN` | 营业中 | -| | `PAUSED` | 临时闭店 | -| | `CLOSED` | 永久关闭 | - -#### 结算 - -| 表.字段 | 枚举值 | 中文释义 | -|---------|--------|----------| -| `store_payout.status` | `PENDING` | 待打款 | -| | `PAID` | 已打款 | -| `partner_bill.status` | `DRAFT` | 草稿 | -| | `PENDING_CONFIRM` | 待合伙人确认 | -| | `CONFIRMED` | 已确认 | -| | `PAID` | 已打款 | -| | `REJECTED` | 已驳回 | - -#### 用户来源 `user_user.source_type` - -| 枚举值 | 中文释义 | -|--------|----------| -| `ORGANIC` | 自然流量（无渠道参数） | -| `PROMO_CODE` | 推广码/渠道码 | -| `SHARE_LINK` | 分享链接（好友/群分享带参） | -| `FRIEND_REFERRAL` | 好友推荐（referrer_user_id） | -| `OFFLINE_EVENT` | 线下活动 | -| `OTHER` | 其他 | - -#### 商品 `common_product_item` - -| 字段 | 枚举值 | 中文释义 | -|------|--------|----------| -| `aroma_type` | `QINGXIANG` | 清香型 | -| | `JIANGXIANG` | 酱香型 | -| | `NONGXIANG` | 浓香型 | -| `status` | `DRAFT` | 草稿 | -| | `ON_SALE` | 在售 | -| | `OFF_SALE` | 下架 | - -#### 开城 `common_city.status` - -| 枚举值 | 中文释义 | -|--------|----------| -| `PENDING` | 待开城 | -| `ACTIVE` | 已开城 | -| `PAUSED` | 暂停 | - -#### 资源 `common_resource` - -| 字段 | 枚举值 | 中文释义 | -|------|--------|----------| -| `media_type` | `IMAGE` | 图片 | -| | `VIDEO` | 视频 | -| | `FILE` | 文件 | -| `status` | `ACTIVE` | 有效 | -| | `DELETED` | 已删除 | - -#### 账号状态（`store_account` / `partner_account` / `hq_account`） - -| 枚举值 | 中文释义 | -|--------|----------| -| `ACTIVE` | 正常 | -| `DISABLED` | 禁用 | - -#### 合伙人子账号 `partner_account.staff_role` - -| 枚举值 | 中文释义 | -|--------|----------| -| `PARTNER` | 合伙人 | -| `INTERNAL` | 内部员工 | -| `PROMOTER` | 推广员 | - -#### 总部职能 `hq_account.admin_role` - -| 枚举值 | 中文释义 | -|--------|----------| -| `SUPER_ADMIN` | 超级管理员 | -| `OPS` | 运营 | -| `FINANCE` | 财务 | -| `CUSTOMER_SERVICE` | 客服 | - -#### 配送 `user_order_delivery.provider` - -| 枚举值 | 中文释义 | -|--------|----------| -| `XFX` | 小飞侠同城 | -| `LOGISTICS` | 传统物流 | -| `MANUAL` | 人工配送 | - -#### 第三方 `log_third_party` - -| 字段 | 枚举值 | 中文释义 | -|------|--------|----------| -| `provider` | `WECHAT_PAY` | 微信支付 | -| | `WECHAT_REFUND` | 微信退款 | -| | `WECHAT_AUTH` | 微信授权 | -| | `WECHAT_MAP` | 微信地图 | -| | `XFX` | 小飞侠 | -| | `SMS` | 短信 | -| | `LOGISTICS` | 物流查询 | -| `status` | `PENDING` | 处理中 | -| | `SUCCESS` | 成功 | -| | `FAILED` | 失败 | - -#### 权益流水 `BENEFIT_LEDGER` param1（ledger_type） - -| 枚举值 | 中文释义 | -|--------|----------| -| `GRANT` | 发放 | -| `REDEEM` | 核销扣减 | -| `VOID` | 退款作废 | -| `ADJUST` | 人工调整 | - -#### 工单 `common_ticket.status`（通用） - -| 枚举值 | 中文释义 | -|--------|----------| -| `PENDING` | 待处理 | -| `PROCESSING` | 处理中 | -| `COMPLETED` | 已完成 | -| `REJECTED` | 已驳回 | -| `CANCELLED` | 已取消 | - ---- - -## 6. ER 图（核心） - -```mermaid -erDiagram - user_user ||--o{ user_address : has - user_user ||--o| user_city_preference : has - user_user ||--o{ user_order : places - user_user ||--o{ user_benefit_coupon : owns - user_user ||--o{ user_redeem_record : redeems - user_user ||--o{ log_user_analytics : tracks - - common_city ||--o{ store_store : contains - common_city ||--o{ user_order : routes - partner_partner ||--o{ common_city : manages - partner_partner ||--o{ store_store : owns - partner_partner ||--o{ partner_account : has - partner_partner ||--o{ partner_bill : billed - - common_product_item ||--o{ user_order : sold_in - common_promo_code ||--o{ user_order : source - - user_order ||--o| user_order_delivery : "1:1 delivered" - user_order ||--o{ user_benefit_coupon : grants - user_order ||--o{ common_ticket : tickets - user_order ||--o{ log_third_party : third_party - - user_benefit_coupon ||--o{ user_redeem_record : redeemed - store_store ||--o{ user_redeem_record : receives - store_store ||--|| store_account : login - store_store ||--o{ store_payout : payout - - common_resource }o--|| store_store : cover - common_resource }o--|| common_product_item : images - common_resource }o--|| user_order : product_image - common_resource }o--|| user_order_delivery : sign_photo - - common_event }o--|| user_order : logs - common_event }o--|| store_store : audits - common_event }o--|| user_benefit_coupon : ledger - - common_ticket }o--|| user_order : after_sale - hq_account ||--o{ common_ticket : handles -``` - ---- - -## 7. 公共 API（common 模块） - -> 详见本手册 §六；以下为 v3 新增/调整接口。 - -### 7.1 资源 `common_resource` - -| 方法 | 路径 | 鉴权 | 说明 | -|------|------|------|------| -| POST | `/common/resources/upload-token` | * | 获取 OSS 直传凭证 `{ bizType, mediaType, fileName }` | -| POST | `/common/resources` | * | 上传确认/登记 `{ ownerType, ownerId, bizType, ossKey, url, ... }` | -| GET | `/common/resources` | * | 列表 `?ownerType=&ownerId=&bizType=` | -| GET | `/common/resources/:id` | * | 详情 | -| PUT | `/common/resources/:id` | * | 更新排序/状态 | -| DELETE | `/common/resources/:id` | * | 删除（OSS 异步删） | - -### 7.2 事件 `common_event` - -| 方法 | 路径 | 鉴权 | 说明 | -|------|------|------|------| -| POST | `/common/events` | Internal/各端 | 写入事件（业务 Service 调用） | -| GET | `/common/events` | * | 查询 `?refType=&refId=&eventType=&page=` | -| GET | `/common/events/timeline` | * | 聚合时间线（订单/门店详情页） | - -### 7.3 工单 `common_ticket` - -| 方法 | 路径 | 鉴权 | 说明 | -|------|------|------|------| -| POST | `/common/tickets` | AdminAuth 等 | 创建工单 | -| GET | `/common/tickets` | * | 列表 `?ticketType=&status=&refType=&refId=` | -| GET | `/common/tickets/:id` | * | 详情 | -| PUT | `/common/tickets/:id/status` | * | 更新状态/处理 | -| PUT | `/common/tickets/:id/assign` | AdminAuth | 指派处理人 | - -### 7.4 第三方日志 `log_third_party`（只读，内部写入） - -| 方法 | 路径 | 鉴权 | 说明 | -|------|------|------|------| -| GET | `/common/third-party-logs` | AdminAuth | 查询 `?provider=&scene=&refType=&refId=` | -| GET | `/common/third-party-logs/:id` | AdminAuth | 详情（对账/排错） | - -### 7.5 用户埋点 `log_user_analytics` - -| 方法 | 路径 | 鉴权 | 说明 | -|------|------|------|------| -| POST | `/log/analytics/batch` | UserAuth 可选 | 客户端批量上报 `{ events: [...] }` | -| GET | `/admin/analytics/events` | AdminAuth | 总部报表 `?eventName=&userId=&from=&to=` | -| GET | `/admin/analytics/funnel` | AdminAuth | 漏斗统计（V1 基础） | - ---- - -## 8. 核心业务链路（v3） - -### 8.1 购酒 → 发券 - -``` -user_user - → user_order（含 product 快照 + 价格冗余） - → log_third_party (WECHAT_PAY, scene=ORDER_PAY) → user_order.pay_status=PAID - → log_user_analytics (pay_success) - → common_event (ORDER_STATUS → PENDING_SHIP) - → user_order_delivery（预创建，待发货） - → user_benefit_coupon - → common_event (BENEFIT_LEDGER, GRANT) -``` - -### 8.2 核销 → 门店打款 - -``` -Redis redeem:token (5min，无 DB 表) - → user_redeem_record - → common_event (BENEFIT_LEDGER, REDEEM) - → store_payout (T+1) - → user_store_rating - → log_third_party (SMS, 通知门店) -``` - -### 8.3 门店入驻 - -``` -partner_partner - → store_store + common_resource (COVER/ENV/CONTRACT) - → common_event (STORE_AUDIT, PENDING) - → hq_account 审核 → common_event (APPROVED) - → store_account -``` - -### 8.4 退款 - -``` -common_ticket (REFUND) - → log_third_party (WECHAT_REFUND) - → user_benefit_coupon VOID - → common_event (BENEFIT_LEDGER, VOID) - → common_event (ORDER_STATUS, REFUNDED) -``` - ---- - -## 9. 可执行 SQL（完整建表脚本） - -> `mysql -u root -p dukang_haoke < init_v3.sql` - -```sql --- ============================================================ --- 杜康好客 V3.1 数据库初始化脚本 --- MySQL 8.0+ utf8mb4_unicode_ci InnoDB --- ============================================================ - -SET NAMES utf8mb4; -SET FOREIGN_KEY_CHECKS = 0; - -CREATE DATABASE IF NOT EXISTS dukang_haoke - DEFAULT CHARACTER SET utf8mb4 - DEFAULT COLLATE utf8mb4_unicode_ci; - -USE dukang_haoke; - --- ===================== COMMON ============================= - -DROP TABLE IF EXISTS common_wx_app_config; -CREATE TABLE common_wx_app_config ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - client_app VARCHAR(32) NOT NULL COMMENT 'USER_MINI|PARTNER_MINI|HQ_MINI|SHOP_H5', - app_id VARCHAR(64) NOT NULL, - app_secret VARCHAR(128) NOT NULL, - mch_id VARCHAR(32) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_common_wx_app_config_client (client_app) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='四端微信配置'; - -DROP TABLE IF EXISTS common_resource; -CREATE TABLE common_resource ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - owner_type VARCHAR(32) NOT NULL COMMENT 'PRODUCT|STORE|PARTNER|USER|ORDER|PROMO|HQ', - owner_id BIGINT UNSIGNED NOT NULL COMMENT '归属业务ID', - biz_type VARCHAR(32) NOT NULL COMMENT 'COVER|ENV|CONTRACT|CAROUSEL|DETAIL|AVATAR|QRCODE|SIGN_PHOTO|VIDEO', - media_type VARCHAR(16) NOT NULL DEFAULT 'IMAGE' COMMENT 'IMAGE|VIDEO|FILE', - oss_bucket VARCHAR(64) NOT NULL COMMENT 'OSS Bucket', - oss_key VARCHAR(256) NOT NULL COMMENT 'OSS Object Key', - url VARCHAR(512) NOT NULL COMMENT 'CDN访问URL', - file_name VARCHAR(128) DEFAULT NULL, - file_size BIGINT UNSIGNED DEFAULT NULL COMMENT '字节', - mime_type VARCHAR(64) DEFAULT NULL, - sort_order INT NOT NULL DEFAULT 0, - status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT 'ACTIVE|DELETED', - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_common_resource_owner (owner_type, owner_id, biz_type), - KEY idx_common_resource_status (status) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='统一资源表(OSS)'; - -DROP TABLE IF EXISTS common_event; -CREATE TABLE common_event ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - event_type VARCHAR(32) NOT NULL COMMENT 'STORE_AUDIT|ORDER_STATUS|BENEFIT_LEDGER|HQ_OPERATION|PROMO_TOUCH', - ref_type VARCHAR(32) NOT NULL COMMENT 'ORDER|STORE|BENEFIT_COUPON|USER|PRODUCT|...', - ref_id BIGINT UNSIGNED NOT NULL, - actor_type VARCHAR(16) DEFAULT NULL COMMENT 'USER|STORE|PARTNER|HQ|SYSTEM', - actor_id BIGINT UNSIGNED DEFAULT NULL, - status VARCHAR(32) DEFAULT NULL COMMENT '事件子状态(如审核PENDING/APPROVED)', - param1 VARCHAR(128) DEFAULT NULL, - param1_desc VARCHAR(64) DEFAULT NULL, - param2 VARCHAR(128) DEFAULT NULL, - param2_desc VARCHAR(64) DEFAULT NULL, - param3 VARCHAR(128) DEFAULT NULL, - param3_desc VARCHAR(64) DEFAULT NULL, - amount1 DECIMAL(10,2) DEFAULT NULL COMMENT '仅BENEFIT_LEDGER:变动额', - amount2 DECIMAL(10,2) DEFAULT NULL COMMENT '仅BENEFIT_LEDGER:变动后余额', - remark VARCHAR(512) DEFAULT NULL, - extra_json JSON DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_common_event_ref (ref_type, ref_id, event_type), - KEY idx_common_event_type_created (event_type, created_at), - KEY idx_common_event_actor (actor_type, actor_id) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='统一事件表'; - -DROP TABLE IF EXISTS common_ticket; -CREATE TABLE common_ticket ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - ticket_no VARCHAR(32) NOT NULL, - ticket_type VARCHAR(32) NOT NULL COMMENT 'REFUND|RESHIPMENT|ALERT', - status VARCHAR(32) NOT NULL DEFAULT 'PENDING', - ref_type VARCHAR(32) NOT NULL COMMENT 'ORDER|STORE|PARTNER|...', - ref_id BIGINT UNSIGNED NOT NULL, - operator_type VARCHAR(16) DEFAULT NULL COMMENT 'HQ|PARTNER|SYSTEM', - operator_id BIGINT UNSIGNED DEFAULT NULL, - param1 VARCHAR(128) DEFAULT NULL, - param1_desc VARCHAR(64) DEFAULT NULL, - param2 VARCHAR(128) DEFAULT NULL, - param2_desc VARCHAR(64) DEFAULT NULL, - param3 VARCHAR(128) DEFAULT NULL, - param3_desc VARCHAR(64) DEFAULT NULL, - remark VARCHAR(512) DEFAULT NULL, - extra_json JSON DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - completed_at DATETIME(3) DEFAULT NULL, - PRIMARY KEY (id), - UNIQUE KEY uk_common_ticket_no (ticket_no), - KEY idx_common_ticket_ref (ref_type, ref_id), - KEY idx_common_ticket_type_status (ticket_type, status) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='通用工单表'; - -DROP TABLE IF EXISTS common_product_item; -CREATE TABLE common_product_item ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - sku_code VARCHAR(32) NOT NULL COMMENT 'SKU编码', - barcode_69 VARCHAR(32) NOT NULL COMMENT '69码(商品条码)', - name VARCHAR(128) NOT NULL, - subtitle VARCHAR(256) DEFAULT NULL, - aroma_type VARCHAR(16) NOT NULL COMMENT 'QINGXIANG|JIANGXIANG|NONGXIANG', - spec VARCHAR(128) NOT NULL, - price DECIMAL(10,2) NOT NULL, - benefit_amount DECIMAL(10,2) DEFAULT NULL COMMENT 'NULL=等同售价', - status VARCHAR(16) NOT NULL DEFAULT 'DRAFT' COMMENT 'DRAFT|ON_SALE|OFF_SALE', - sort_order INT NOT NULL DEFAULT 0, - cover_resource_id BIGINT UNSIGNED DEFAULT NULL COMMENT '主图 common_resource.id', - detail_content JSON DEFAULT NULL COMMENT '图文详情(纯文本结构)', - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_common_product_item_sku (sku_code), - UNIQUE KEY uk_common_product_item_barcode (barcode_69), - KEY idx_common_product_item_status (status, aroma_type) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='商品SKU'; - -DROP TABLE IF EXISTS common_store_category; -CREATE TABLE common_store_category ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - code VARCHAR(32) NOT NULL, - name VARCHAR(64) NOT NULL, - sort INT NOT NULL DEFAULT 0, - PRIMARY KEY (id), - UNIQUE KEY uk_common_store_category_code (code) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='门店餐饮分类'; - -DROP TABLE IF EXISTS common_promo_code; -CREATE TABLE common_promo_code ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - code VARCHAR(32) NOT NULL, - name VARCHAR(128) NOT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE', - qrcode_resource_id BIGINT UNSIGNED DEFAULT NULL COMMENT '小程序码 common_resource.id', - scan_count INT NOT NULL DEFAULT 0, - order_count INT NOT NULL DEFAULT 0, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_common_promo_code_code (code) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='推广码'; - --- ===================== PARTNER（先于 city/store） ============================= - -DROP TABLE IF EXISTS partner_partner; -CREATE TABLE partner_partner ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - company_name VARCHAR(128) NOT NULL, - address VARCHAR(256) NOT NULL, - contact_phone VARCHAR(20) NOT NULL, - contract_no VARCHAR(64) DEFAULT NULL COMMENT '合同编号', - contract_signed_at DATETIME(3) DEFAULT NULL, - contract_expire_at DATETIME(3) DEFAULT NULL, - bank_account_name VARCHAR(64) DEFAULT NULL, - bank_account_no VARCHAR(32) DEFAULT NULL, - bank_branch VARCHAR(128) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_partner_partner_phone (contact_phone) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='城市合伙人主体'; - -DROP TABLE IF EXISTS common_city; -CREATE TABLE common_city ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - code VARCHAR(16) NOT NULL, - name VARCHAR(64) NOT NULL, - province VARCHAR(32) NOT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'PENDING', - partner_id BIGINT UNSIGNED DEFAULT NULL, - local_min_qty INT NOT NULL DEFAULT 2, - cross_min_qty INT NOT NULL DEFAULT 6, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_common_city_code (code), - KEY idx_common_city_partner (partner_id), - CONSTRAINT fk_common_city_partner FOREIGN KEY (partner_id) REFERENCES partner_partner(id) ON DELETE SET NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='开城配置'; - -DROP TABLE IF EXISTS common_city_commission_rule; -CREATE TABLE common_city_commission_rule ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - city_id BIGINT UNSIGNED NOT NULL, - order_commission_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0000, - redeem_commission_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0000, - partner_profit_rate DECIMAL(5,4) NOT NULL DEFAULT 0.3500, - store_settlement_rate DECIMAL(5,4) NOT NULL DEFAULT 0.6000, - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_common_city_commission_city (city_id), - CONSTRAINT fk_common_city_commission_city FOREIGN KEY (city_id) REFERENCES common_city(id) ON DELETE CASCADE -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='城市佣金规则'; - -DROP TABLE IF EXISTS partner_account; -CREATE TABLE partner_account ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - partner_id BIGINT UNSIGNED NOT NULL, - phone VARCHAR(20) NOT NULL, - name VARCHAR(64) NOT NULL, - wx_open_id VARCHAR(64) DEFAULT NULL, - wx_union_id VARCHAR(64) DEFAULT NULL, - is_primary TINYINT NOT NULL DEFAULT 0, - parent_account_id BIGINT UNSIGNED DEFAULT NULL, - staff_role VARCHAR(16) DEFAULT NULL COMMENT 'PARTNER|INTERNAL|PROMOTER', - status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE', - last_login_at DATETIME(3) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_partner_account_phone (phone), - KEY idx_partner_account_partner (partner_id), - CONSTRAINT fk_partner_account_partner FOREIGN KEY (partner_id) REFERENCES partner_partner(id) ON DELETE RESTRICT, - CONSTRAINT fk_partner_account_parent FOREIGN KEY (parent_account_id) REFERENCES partner_account(id) ON DELETE SET NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='合伙人账号'; - -DROP TABLE IF EXISTS partner_bill; -CREATE TABLE partner_bill ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - bill_no VARCHAR(32) NOT NULL, - partner_id BIGINT UNSIGNED NOT NULL, - period_start DATETIME(3) NOT NULL, - period_end DATETIME(3) NOT NULL, - order_commission DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '下单佣金汇总', - redeem_commission DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '核销佣金汇总', - total_amount DECIMAL(10,2) NOT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'DRAFT', - confirmed_at DATETIME(3) DEFAULT NULL, - paid_at DATETIME(3) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_partner_bill_no (bill_no), - KEY idx_partner_bill_partner_status (partner_id, status), - CONSTRAINT fk_partner_bill_partner FOREIGN KEY (partner_id) REFERENCES partner_partner(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='合伙人T+30账单'; - --- ===================== HQ ============================= - -DROP TABLE IF EXISTS hq_account; -CREATE TABLE hq_account ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - phone VARCHAR(20) NOT NULL, - name VARCHAR(64) NOT NULL, - admin_role VARCHAR(32) NOT NULL DEFAULT 'OPS', - wx_open_id VARCHAR(64) DEFAULT NULL, - wx_union_id VARCHAR(64) DEFAULT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE', - last_login_at DATETIME(3) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_hq_account_phone (phone) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='总部账号'; - --- ===================== USER ============================= - -DROP TABLE IF EXISTS user_user; -CREATE TABLE user_user ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - user_no VARCHAR(20) NOT NULL, - phone VARCHAR(20) NOT NULL, - wx_open_id VARCHAR(64) DEFAULT NULL, - wx_union_id VARCHAR(64) DEFAULT NULL, - nickname VARCHAR(64) DEFAULT NULL, - avatar_resource_id BIGINT UNSIGNED DEFAULT NULL COMMENT '头像 common_resource.id', - status TINYINT NOT NULL DEFAULT 1, - source_type VARCHAR(32) NOT NULL DEFAULT 'ORGANIC' COMMENT 'ORGANIC|PROMO_CODE|SHARE_LINK|FRIEND_REFERRAL|OFFLINE_EVENT|OTHER', - source_ref_id BIGINT UNSIGNED DEFAULT NULL COMMENT 'promo_code_id 或 referrer_user_id', - source_label VARCHAR(128) DEFAULT NULL COMMENT '渠道名称快照', - referrer_user_id BIGINT UNSIGNED DEFAULT NULL COMMENT '好友推荐人 user_user.id', - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_user_phone (phone), - UNIQUE KEY uk_user_user_no (user_no), - KEY idx_user_user_source (source_type, source_ref_id), - KEY idx_user_user_referrer (referrer_user_id), - KEY idx_user_user_wx_open (wx_open_id) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='C端用户'; - -DROP TABLE IF EXISTS user_address; -CREATE TABLE user_address ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - user_id BIGINT UNSIGNED NOT NULL, - receiver_name VARCHAR(32) NOT NULL, - phone VARCHAR(20) NOT NULL, - province VARCHAR(32) NOT NULL, - city VARCHAR(32) NOT NULL, - district VARCHAR(32) NOT NULL, - detail VARCHAR(256) NOT NULL, - latitude DECIMAL(10,7) DEFAULT NULL, - longitude DECIMAL(10,7) DEFAULT NULL, - is_default TINYINT NOT NULL DEFAULT 0, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_user_address_user (user_id), - CONSTRAINT fk_user_address_user FOREIGN KEY (user_id) REFERENCES user_user(id) ON DELETE CASCADE -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户收货地址'; - -DROP TABLE IF EXISTS user_city_preference; -CREATE TABLE user_city_preference ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - user_id BIGINT UNSIGNED NOT NULL, - selected_city_code VARCHAR(16) DEFAULT NULL, - selected_district VARCHAR(32) DEFAULT NULL, - locate_city_code VARCHAR(16) DEFAULT NULL, - locate_district VARCHAR(32) DEFAULT NULL, - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_city_preference_user (user_id), - CONSTRAINT fk_user_city_preference_user FOREIGN KEY (user_id) REFERENCES user_user(id) ON DELETE CASCADE -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户城市偏好'; - -DROP TABLE IF EXISTS user_promo_attribution; -CREATE TABLE user_promo_attribution ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - user_id BIGINT UNSIGNED NOT NULL, - promo_code_id BIGINT UNSIGNED NOT NULL, - channel_name VARCHAR(128) NOT NULL, - first_touch_at DATETIME(3) NOT NULL, - PRIMARY KEY (id), - UNIQUE KEY uk_user_promo_attribution_user (user_id), - KEY idx_user_promo_attribution_promo (promo_code_id), - CONSTRAINT fk_user_promo_attribution_user FOREIGN KEY (user_id) REFERENCES user_user(id) ON DELETE CASCADE, - CONSTRAINT fk_user_promo_attribution_promo FOREIGN KEY (promo_code_id) REFERENCES common_promo_code(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='推广首次触达(统计)'; - --- ===================== STORE ============================= - -DROP TABLE IF EXISTS store_store; -CREATE TABLE store_store ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - city_id BIGINT UNSIGNED NOT NULL, - partner_id BIGINT UNSIGNED NOT NULL, - category_id BIGINT UNSIGNED DEFAULT NULL, - name VARCHAR(128) NOT NULL, - phone VARCHAR(20) NOT NULL, - province VARCHAR(32) NOT NULL, - city_name VARCHAR(32) NOT NULL COMMENT '市(冗余)', - district VARCHAR(32) NOT NULL, - address VARCHAR(256) NOT NULL, - latitude DECIMAL(10,7) DEFAULT NULL, - longitude DECIMAL(10,7) DEFAULT NULL, - intro TEXT DEFAULT NULL, - cover_resource_id BIGINT UNSIGNED DEFAULT NULL COMMENT '门头图', - avg_price DECIMAL(10,2) DEFAULT NULL, - rating DECIMAL(3,2) DEFAULT NULL, - tags JSON DEFAULT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'PAUSED', - open_time VARCHAR(8) DEFAULT NULL, - close_time VARCHAR(8) DEFAULT NULL, - bank_account_name VARCHAR(64) DEFAULT NULL, - bank_account_no VARCHAR(32) DEFAULT NULL, - bank_branch VARCHAR(128) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_store_store_city_status (city_id, status), - KEY idx_store_store_partner (partner_id), - CONSTRAINT fk_store_store_city FOREIGN KEY (city_id) REFERENCES common_city(id) ON DELETE RESTRICT, - CONSTRAINT fk_store_store_partner FOREIGN KEY (partner_id) REFERENCES partner_partner(id) ON DELETE RESTRICT, - CONSTRAINT fk_store_store_category FOREIGN KEY (category_id) REFERENCES common_store_category(id) ON DELETE SET NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='餐饮门店'; - -DROP TABLE IF EXISTS store_account; -CREATE TABLE store_account ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - store_id BIGINT UNSIGNED NOT NULL, - phone VARCHAR(20) NOT NULL, - name VARCHAR(64) NOT NULL, - wx_open_id VARCHAR(64) DEFAULT NULL, - wx_union_id VARCHAR(64) DEFAULT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE', - last_login_at DATETIME(3) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_store_account_store (store_id), - UNIQUE KEY uk_store_account_phone (phone), - CONSTRAINT fk_store_account_store FOREIGN KEY (store_id) REFERENCES store_store(id) ON DELETE CASCADE -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='门店H5账号'; - --- ===================== USER ORDER ============================= - -DROP TABLE IF EXISTS user_order_item; -DROP TABLE IF EXISTS user_order_delivery; -DROP TABLE IF EXISTS user_order; -CREATE TABLE user_order ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - order_no VARCHAR(32) NOT NULL, - order_type VARCHAR(16) NOT NULL DEFAULT 'NORMAL' COMMENT 'NORMAL|RESHIPMENT', - user_id BIGINT UNSIGNED NOT NULL, - city_id BIGINT UNSIGNED NOT NULL, - status VARCHAR(32) NOT NULL DEFAULT 'PENDING_PAY', - pay_status VARCHAR(16) NOT NULL DEFAULT 'UNPAID' COMMENT 'UNPAID|PAYING|PAID|REFUNDING|REFUNDED', - delivery_type VARCHAR(16) NOT NULL COMMENT 'LOCAL|CROSS_CITY', - origin_order_id BIGINT UNSIGNED DEFAULT NULL, - promo_code_id BIGINT UNSIGNED DEFAULT NULL, - channel_source VARCHAR(128) DEFAULT NULL, - product_id BIGINT UNSIGNED NOT NULL COMMENT '商品 common_product_item.id', - barcode_69 VARCHAR(32) NOT NULL COMMENT '69码快照', - product_name VARCHAR(128) NOT NULL COMMENT '商品名称快照', - product_spec VARCHAR(128) NOT NULL COMMENT '规格快照', - image_resource_id BIGINT UNSIGNED DEFAULT NULL COMMENT '商品图快照 common_resource.id', - quantity INT NOT NULL COMMENT '购买数量', - list_unit_price DECIMAL(10,2) NOT NULL COMMENT '标价单价', - list_amount DECIMAL(10,2) NOT NULL COMMENT '标价总额', - discount_amount DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '优惠金额', - product_amount DECIMAL(10,2) NOT NULL COMMENT '商品应付', - freight_amount DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '运费', - freight_pay_type VARCHAR(8) DEFAULT NULL COMMENT 'FREE|COD', - pay_amount DECIMAL(10,2) NOT NULL COMMENT '实付总额', - benefit_amount DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '本单发放权益', - receiver_name VARCHAR(32) NOT NULL, - receiver_phone VARCHAR(20) NOT NULL, - receiver_address TEXT NOT NULL, - receiver_province VARCHAR(32) NOT NULL, - receiver_city VARCHAR(32) NOT NULL, - receiver_district VARCHAR(32) NOT NULL, - pay_external_no VARCHAR(64) DEFAULT NULL COMMENT '微信交易号(冗余)', - paid_at DATETIME(3) DEFAULT NULL COMMENT '支付时间', - shipped_at DATETIME(3) DEFAULT NULL COMMENT '发货时间(冗余=user_order_delivery.shipping_at)', - completed_at DATETIME(3) DEFAULT NULL COMMENT '完成时间', - cancelled_at DATETIME(3) DEFAULT NULL COMMENT '取消时间', - pay_expire_at DATETIME(3) DEFAULT NULL COMMENT '待付款过期时间', - remark VARCHAR(512) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_order_no (order_no), - KEY idx_user_order_user_status (user_id, status), - KEY idx_user_order_city_created (city_id, created_at), - KEY idx_user_order_product (product_id), - KEY idx_user_order_barcode (barcode_69), - KEY idx_user_order_pay_external (pay_external_no), - CONSTRAINT fk_user_order_user FOREIGN KEY (user_id) REFERENCES user_user(id) ON DELETE RESTRICT, - CONSTRAINT fk_user_order_city FOREIGN KEY (city_id) REFERENCES common_city(id) ON DELETE RESTRICT, - CONSTRAINT fk_user_order_origin FOREIGN KEY (origin_order_id) REFERENCES user_order(id) ON DELETE SET NULL, - CONSTRAINT fk_user_order_promo FOREIGN KEY (promo_code_id) REFERENCES common_promo_code(id) ON DELETE SET NULL, - CONSTRAINT fk_user_order_product FOREIGN KEY (product_id) REFERENCES common_product_item(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单(含商品快照,V1单SKU)'; - -DROP TABLE IF EXISTS user_order_delivery; -CREATE TABLE user_order_delivery ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - order_id BIGINT UNSIGNED NOT NULL, - provider VARCHAR(16) NOT NULL COMMENT 'XFX|LOGISTICS|MANUAL', - provider_order_no VARCHAR(64) DEFAULT NULL, - tracking_no VARCHAR(64) DEFAULT NULL, - out_warehouse_at DATETIME(3) DEFAULT NULL, - shipping_at DATETIME(3) DEFAULT NULL, - delivered_at DATETIME(3) DEFAULT NULL, - sign_photo_resource_id BIGINT UNSIGNED DEFAULT NULL COMMENT '签收照片 common_resource.id', - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_order_delivery_order (order_id), - CONSTRAINT fk_user_order_delivery_order FOREIGN KEY (order_id) REFERENCES user_order(id) ON DELETE CASCADE -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单配送(与user_order 1:1)'; - --- ===================== BENEFIT & REDEEM ============================= - -DROP TABLE IF EXISTS user_benefit_coupon; -CREATE TABLE user_benefit_coupon ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - coupon_no VARCHAR(32) NOT NULL, - user_id BIGINT UNSIGNED NOT NULL, - order_id BIGINT UNSIGNED NOT NULL, - total_amount DECIMAL(10,2) NOT NULL, - used_amount DECIMAL(10,2) NOT NULL DEFAULT 0.00, - balance DECIMAL(10,2) NOT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE', - source_product VARCHAR(128) NOT NULL, - version INT NOT NULL DEFAULT 0 COMMENT '乐观锁', - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_benefit_coupon_no (coupon_no), - KEY idx_user_benefit_coupon_user (user_id, status), - CONSTRAINT fk_user_benefit_coupon_user FOREIGN KEY (user_id) REFERENCES user_user(id) ON DELETE RESTRICT, - CONSTRAINT fk_user_benefit_coupon_order FOREIGN KEY (order_id) REFERENCES user_order(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='好客权益券'; - -DROP TABLE IF EXISTS user_redeem_record; -CREATE TABLE user_redeem_record ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - redeem_no VARCHAR(32) NOT NULL, - user_id BIGINT UNSIGNED NOT NULL, - coupon_id BIGINT UNSIGNED NOT NULL, - store_id BIGINT UNSIGNED NOT NULL, - amount DECIMAL(10,2) NOT NULL, - settle_amount DECIMAL(10,2) NOT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_redeem_record_no (redeem_no), - KEY idx_user_redeem_record_store (store_id, created_at), - CONSTRAINT fk_user_redeem_record_user FOREIGN KEY (user_id) REFERENCES user_user(id) ON DELETE RESTRICT, - CONSTRAINT fk_user_redeem_record_coupon FOREIGN KEY (coupon_id) REFERENCES user_benefit_coupon(id) ON DELETE RESTRICT, - CONSTRAINT fk_user_redeem_record_store FOREIGN KEY (store_id) REFERENCES store_store(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='核销记录'; - -DROP TABLE IF EXISTS user_store_rating; -CREATE TABLE user_store_rating ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - redeem_record_id BIGINT UNSIGNED NOT NULL, - store_id BIGINT UNSIGNED NOT NULL, - service_score TINYINT NOT NULL, - env_score TINYINT NOT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_user_store_rating_redeem (redeem_record_id), - CONSTRAINT fk_user_store_rating_redeem FOREIGN KEY (redeem_record_id) REFERENCES user_redeem_record(id) ON DELETE CASCADE, - CONSTRAINT fk_user_store_rating_store FOREIGN KEY (store_id) REFERENCES store_store(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='核销评价'; - -DROP TABLE IF EXISTS store_payout; -CREATE TABLE store_payout ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - redeem_record_id BIGINT UNSIGNED NOT NULL, - store_id BIGINT UNSIGNED NOT NULL, - redeem_amount DECIMAL(10,2) NOT NULL, - payout_amount DECIMAL(10,2) NOT NULL, - settlement_rate DECIMAL(5,4) NOT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'PENDING', - expected_pay_at DATETIME(3) NOT NULL, - paid_at DATETIME(3) DEFAULT NULL, - batch_no VARCHAR(32) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - UNIQUE KEY uk_store_payout_redeem (redeem_record_id), - KEY idx_store_payout_store_status (store_id, status), - CONSTRAINT fk_store_payout_redeem FOREIGN KEY (redeem_record_id) REFERENCES user_redeem_record(id) ON DELETE RESTRICT, - CONSTRAINT fk_store_payout_store FOREIGN KEY (store_id) REFERENCES store_store(id) ON DELETE RESTRICT -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='门店T+1打款'; - --- ===================== LOG ============================= - -DROP TABLE IF EXISTS log_third_party; -CREATE TABLE log_third_party ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - provider VARCHAR(32) NOT NULL COMMENT 'WECHAT_PAY|WECHAT_REFUND|WECHAT_AUTH|WECHAT_MAP|XFX|SMS|LOGISTICS', - scene VARCHAR(64) NOT NULL COMMENT '业务场景', - ref_type VARCHAR(32) DEFAULT NULL COMMENT 'ORDER|USER|STORE|...', - ref_id BIGINT UNSIGNED DEFAULT NULL, - request_url VARCHAR(512) DEFAULT NULL, - request_body JSON DEFAULT NULL COMMENT '发送参数', - response_body JSON DEFAULT NULL COMMENT '响应数据', - external_no VARCHAR(128) DEFAULT NULL COMMENT '第三方单号', - amount DECIMAL(10,2) DEFAULT NULL, - status VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT 'PENDING|SUCCESS|FAILED', - error_message VARCHAR(512) DEFAULT NULL, - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_log_third_party_ref (ref_type, ref_id), - KEY idx_log_third_party_provider_scene (provider, scene, created_at), - KEY idx_log_third_party_external (external_no) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='第三方交互记录'; - -DROP TABLE IF EXISTS log_user_analytics; -CREATE TABLE log_user_analytics ( - id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, - user_id BIGINT UNSIGNED DEFAULT NULL COMMENT '未登录可为NULL', - session_id VARCHAR(64) DEFAULT NULL COMMENT '会话ID', - event_name VARCHAR(64) NOT NULL COMMENT '见§4.1 event_name 清单', - client_app VARCHAR(32) DEFAULT NULL COMMENT 'USER_MINI|PARTNER_MINI|HQ_MINI|SHOP_H5', - page_path VARCHAR(128) DEFAULT NULL COMMENT '页面路径', - ref_type VARCHAR(32) DEFAULT NULL COMMENT 'PRODUCT|STORE|ORDER|TAB|ADDRESS|PROMO|...', - ref_id BIGINT UNSIGNED DEFAULT NULL, - keyword VARCHAR(128) DEFAULT NULL COMMENT '搜索关键词', - source_type VARCHAR(32) DEFAULT NULL COMMENT 'register事件:来源类型快照', - source_ref_id BIGINT UNSIGNED DEFAULT NULL COMMENT 'register事件:来源ID', - extra_json JSON DEFAULT NULL COMMENT 'PRD埋点参数', - created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), - PRIMARY KEY (id), - KEY idx_log_user_analytics_user_created (user_id, created_at), - KEY idx_log_user_analytics_event_created (event_name, created_at), - KEY idx_log_user_analytics_session (session_id), - KEY idx_log_user_analytics_ref (ref_type, ref_id) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户行为埋点日志'; - -SET FOREIGN_KEY_CHECKS = 1; -``` - ---- - -# §六、API 列表 v3.1 - -## 1. 通用约定 - -### 1.1 请求头 - -| Header | 说明 | -|--------|------| -| `Authorization` | `Bearer `（除公开接口与回调） | -| `X-Client-App` | `USER_MINI` / `PARTNER_MINI` / `HQ_MINI` / `SHOP_H5` | -| `X-Request-Id` | 可选，链路追踪 | - -### 1.2 响应格式 - -```json -{ - "code": 0, - "message": "ok", - "data": {} -} -``` - -### 1.3 分页参数 - -`page`（从 1）、`pageSize`（默认 20，最大 100）→ `data: { list, total, page, pageSize }` - -### 1.4 鉴权角色 - -| Guard | 适用端 | 数据表 | -|-------|--------|--------| -| `UserAuth` | C端 | `user_user` | -| `StoreAuth` | 门店 H5 | `store_account` | -| `PartnerAuth` | 合伙人（含子账号） | `partner_account` | -| `PartnerPrimaryAuth` | 仅主账号（账单确认、提现） | `partner_account`（`is_primary=1`） | -| `AdminAuth` | 总部 | `hq_account` | -| `Public` | 无需登录 | — | -| `WxCallback` | 微信/配送回调验签 | — | - -### 1.5 JWT Payload（四端统一） - -```json -{ - "sub": "12345", - "actorType": "USER", - "actorId": "12345", - "clientApp": "USER_MINI" -} -``` - -| `actorType` | 含义 | `actorId` 指向 | -|-------------|------|----------------| -| `USER` | C端消费者 | `user_user.id` | -| `STORE` | 门店登录账号 | `store_account.id` | -| `PARTNER` | 合伙人/子账号 | `partner_account.id` | -| `HQ` | 总部管理员 | `hq_account.id` | - -> 鉴权时须同时校验 `clientApp` 与 `actorType` 一致，禁止仅用数字 ID 跨表匹配。 - ---- - -## 2. 认证 Auth - -### 2.1 通用接口 - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| POST | `/auth/sms/send` | Public | 发送短信验证码 `{ phone, scene }` | §3.1 | -| POST | `/auth/refresh` | Public | 刷新 Token | — | -| POST | `/auth/logout` | * | 退出，失效 refresh | §3.9 | -| GET | `/auth/me` | * | 当前登录身份摘要（按 `actorType` 返回不同结构） | — | - -**`scene` 枚举**：`USER_LOGIN` / `STORE_LOGIN` / `PARTNER_LOGIN` / `HQ_LOGIN` / `BIND_PHONE` / `PARTNER_STAFF_ADD` - -### 2.2 C端（`clientApp: USER_MINI` → `user_user`） - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| POST | `/auth/login/sms` | Public | 手机号登录 `{ phone, code }` → 查/建 `user_user` | §3.1 | -| POST | `/auth/login/wechat` | Public | 微信登录 `{ code }` → 换 openId；**已绑定 phone 则直接登录，否则返回 `needBindPhone: true`** | §3.1 | -| POST | `/auth/wechat/bind-phone` | Public | 微信首登补绑手机 `{ wxSessionKey, phone, code }` → 写 `user_user.phone` + `wx_open_id` | U4 | - -**`POST /auth/login/sms` 响应要点** - -```json -{ - "accessToken": "", - "refreshToken": "", - "actorType": "USER", - "actorId": "10001", - "user": { - "id": "10001", - "userNo": "DK88293401", - "phone": "138****8888", - "nickname": "", - "hasWechat": true - } -} -``` - -### 2.3 门店端（`clientApp: SHOP_H5` → `store_account`） - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| POST | `/shop/auth/login/sms` | Public | `{ phone, code }` → 查 `store_account` | §4.1 | -| POST | `/shop/auth/login/wechat` | Public | `{ code }` → 写辅助 openId 后仍须匹配 `store_accounts.phone` | §4.1 | - -**响应 `actorType`**：`STORE`；附带 `storeId`、`storeName`。 - -### 2.4 合伙人端（`clientApp: PARTNER_MINI` → `partner_account`） - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| POST | `/partner/auth/login/sms` | Public | `{ phone, code }` → 查 `partner_account` | §5.1 | -| POST | `/partner/auth/login/wechat` | Public | 微信登录（30 天免登） | §5.1 | - -**响应 `actorType`**：`PARTNER`；附带 `partnerId`、`isPrimary`、`staffRole`。 - -### 2.5 总部端（`clientApp: HQ_MINI` → `hq_account`） - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| POST | `/admin/auth/login/sms` | Public | `{ phone, code }` → 查 `hq_account` | §6 | -| POST | `/admin/auth/login/wechat` | Public | 微信登录 | §6 | - -**响应 `actorType`**：`HQ`；附带 `adminRole`（`SUPER_ADMIN` / `OPS` / `FINANCE` / `CUSTOMER_SERVICE`）。 - -### 2.6 身份校验错误码 - -| code | 说明 | -|------|------| -| `PHONE_REQUIRED` | C 端微信首登未绑定手机 | -| `PHONE_ALREADY_USED` | 手机号已被同端其他账号占用 | -| `ACCOUNT_DISABLED` | B 端账号 `status=DISABLED` | -| `ACTOR_TYPE_MISMATCH` | Token `actorType` 与接口 Guard 不匹配 | -| `NOT_PRIMARY_ACCOUNT` | 非合伙人主账号调用 `PartnerPrimaryAuth` 接口 | - ---- - -## 3. C端用户 API（UserAuth） - -### 3.1 用户与城市 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/user/profile` | 个人中心信息 | §3.9 | -| PUT | `/user/profile` | 更新昵称/头像 | §3.9 | -| GET | `/user/city` | 获取选城/定位偏好 | §3.1 | -| PUT | `/user/city` | 更新选城 `{ cityCode, district }` | §3.1 | -| POST | `/user/location` | 上报定位 `{ lat, lng, city, district }` | §3.1 | - -### 3.2 地址 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/user/addresses` | 地址列表 | §3.4 | -| POST | `/user/addresses` | 新增地址 | §3.4 | -| PUT | `/user/addresses/:id` | 编辑地址 | §3.4 | -| DELETE | `/user/addresses/:id` | 删除地址 | §3.4 | -| PUT | `/user/addresses/:id/default` | 设为默认 | §3.4 | - -### 3.3 商品与开城（Public / 部分需登录） - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| GET | `/catalog/cities/open` | Public | 已开城列表（V1 郑州） | §1.4 | -| GET | `/catalog/products` | Public | 商品列表 `?aromaType=&cityCode=` | §3.2 | -| GET | `/catalog/products/:id` | Public | 商品详情（含 benefitAmount） | §3.2 | - -### 3.4 订单交易 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| POST | `/trade/orders/preview` | 下单预览：配送方式、起购、运费、权益 | §3.3 | -| POST | `/trade/orders` | 创建订单（锁单） | §3.3 | -| POST | `/trade/orders/:id/pay` | 发起微信支付，返回 prepay 参数 | §3.3.4 | -| GET | `/trade/orders` | 订单列表 `?tab=all\|pending_pay\|pending_ship\|pending_receive\|completed` | §3.5.1 | -| GET | `/trade/orders/:id` | 订单详情（进度、权益入口） | §3.5.3 | -| PUT | `/trade/orders/:id/address` | 修改收货地址（触发拦截） | §3.5.4 | -| POST | `/trade/orders/:id/cancel` | 取消待付款订单 | §3.5 | -| POST | `/trade/orders/:id/confirm-receive` | 确认收货 | §3.5.3 | -| GET | `/trade/orders/counts` | 各 Tab 数量（个人中心角标） | §3.9 | - -**`POST /trade/orders/preview` 请求** - -```json -{ - "productId": "", - "quantity": 2, - "addressId": "" -} -``` - -**响应要点**：`deliveryType`, `freightAmount`, `freightPayType`, `benefitAmount`, `minQty`, `crossCityWarning` - -### 3.5 好客权益 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/benefit/summary` | 权益余额汇总 | §3.8.1 | -| GET | `/benefit/coupons` | 券列表 `?status=active\|used` | §3.8.1 | -| GET | `/benefit/coupons/:id` | 券详情 | §3.8 | -| GET | `/benefit/ledgers` | 权益明细（获取+消费） | §3.8.2 | - -### 3.6 核销 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| POST | `/redeem/token` | 生成核销码 `{ couponId, storeId, amount }` | §3.8.3 | -| POST | `/redeem/token/:token/refresh` | 刷新核销码（作废旧码） | §3.8.3 | -| GET | `/redeem/token/:token` | 轮询码状态（可选） | §3.8.3 | -| POST | `/redeem/rating` | 核销评价 `{ redeemRecordId, serviceScore, envScore }` | §3.8.3 | - -### 3.7 门店（C端浏览） - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| GET | `/stores` | Public | 门店列表（**仅 OPEN**）`?cityCode=&category=&keyword=&lat=&lng=` | §3.7 | -| GET | `/stores/:id` | Public | 门店详情 | §3.7.2 | -| GET | `/stores/categories` | Public | 分类列表 | §3.7 | - -### 3.8 推广与埋点 - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| POST | `/promo/touch` | UserAuth | 扫码归因 `{ promoCode }`（首次写入） | §3.10.1 | -| POST | `/log/analytics/batch` | UserAuth / Public | 批量埋点 `{ events:[] }` | §3.10.2 | - ---- - -## 4. 门店端 API（StoreAuth） - -> 登录见 §2.3。Token 中 `actorType=STORE`，`actorId` 为 `store_account.id`。 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/shop/dashboard` | 首页：今日笔数/金额、营业状态 | §4.2 | -| GET | `/shop/store` | 门店信息（只读） | §4.5 | -| PUT | `/shop/store/status` | 切换营业 `{ status: OPEN\|PAUSED }` | §4.2 | -| POST | `/shop/redeem/scan` | 扫码解析 `{ token }` → 确认页数据 | §4.3 | -| POST | `/shop/redeem/confirm` | 确认核销 `{ token }` | §4.3 | -| GET | `/shop/redeem/records` | 核销记录 `?range=today\|7d\|30d&status=` | §4.4 | -| GET | `/shop/redeem/records/summary` | 期间汇总（核销额/到账额/60%） | §4.4 | -| GET | `/shop/redeem/records/:id` | 单笔详情 | §4.4 | - -**`POST /shop/redeem/scan` 响应（确认页）** - -```json -{ - "storeName": "", - "userPhoneMasked": "138****9021", - "amount": 100.00, - "couponNo": "DK202310248892", - "couponValidity": "永久", - "tokenExpireAt": "" -} -``` - ---- - -## 5. 城市合伙人 API（PartnerAuth） - -> 登录见 §2.4。Token 中 `actorType=PARTNER`，`actorId` 为 `partner_account.id`。 - -### 5.1 工作台 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/partner/dashboard` | 营业额、利润、门店数、今日订单 | §5.2 | -| GET | `/partner/dashboard/leaderboard` | 贡献榜 | §5.2, §5.9 | -| GET | `/partner/reports/weekly` | 经营周报 `?startDate=` | §5.8 | - -### 5.2 门店管理 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/partner/stores` | 门店列表 `?status=&keyword=` | §5.3 | -| GET | `/partner/stores/:id` | 门店详情 | §5.3 | -| POST | `/partner/stores` | 录入门店（步骤1 基本信息） | §5.3.2 | -| PUT | `/partner/stores/:id/basic` | 更新基本信息 | §5.3 | -| POST | `/partner/stores/:id/media` | 上传照片/合同（步骤2） | §5.3.2 | -| PUT | `/partner/stores/:id/settlement` | 结算银行卡（步骤3） | §5.3.2 | -| POST | `/partner/stores/:id/submit-audit` | 提交审核 | §5.3.2 | -| PUT | `/partner/stores/:id/status` | 变更状态 `{ status: PAUSED\|CLOSED\|OPEN }` | §5.3 | -| GET | `/partner/store-audits` | 审核记录 | §5.3.3 | - -### 5.3 订单 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/partner/orders` | 订单列表 `?range=&status=&keyword=` | §5.4 | -| GET | `/partner/orders/:id` | 订单详情（佣金、渠道） | §5.4 | -| GET | `/partner/benefit/overview` | 权益发放/待核销统计 | §5.4 | -| GET | `/partner/benefit/records` | 已核销权益明细 | §5.4 | - -### 5.4 补发与拦截 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/partner/after-sales/reshipments` | 补发待处理列表 | §5.5 | -| POST | `/partner/after-sales/reshipments/:id/confirm-ship` | 开始配送 | §5.5 | -| POST | `/partner/after-sales/reshipments/:id/confirm-delivered` | 手动确认送达 | §5.5 | -| GET | `/partner/intercepts` | 拦截列表 | §5.6 | -| GET | `/partner/intercepts/:id` | 拦截详情 | §5.6 | -| POST | `/partner/intercepts/:id/start` | 发起拦截 | §5.6 | -| POST | `/partner/intercepts/:id/confirm-success` | 确认拦截成功 | §5.6 | - -### 5.5 财务 - -| 方法 | 路径 | 鉴权 | 说明 | PRD | -|------|------|------|------|-----| -| GET | `/partner/settlement/summary` | 待结算/已结算/本月预估 | §5.7 | -| GET | `/partner/settlement/bills` | 账单列表 | §5.7 | -| GET | `/partner/settlement/bills/:id` | 账单详情（拆分佣金） | §5.7 | -| POST | `/partner/settlement/bills/:id/confirm` | 确认账单 | §5.7 | -| PartnerPrimary | | | | -| GET | `/partner/assets` | 资产明细 | §5.10 | -| POST | `/partner/withdrawals` | 申请提现 | §5.10 | -| GET | `/partner/contracts` | 合同列表 | §5.10 | - -### 5.6 子账号（`partner_account` 表） - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/partner/staff` | 员工/子账号列表（`parent_account_id` 指向主账号） | §5.9 | -| POST | `/partner/staff` | 添加子账号 `{ phone, name, staffRole, code }` | §5.9 | -| PUT | `/partner/staff/:id` | 编辑/启用/禁用 | §5.9 | -| DELETE | `/partner/staff/:id` | 删除子账号 | §5.9 | - -> `:id` 为 `partner_account.id`。主账号 `is_primary=1`，子账号须设 `staffRole`（`PARTNER` / `INTERNAL` / `PROMOTER`）。 - ---- - -## 6. 总部管理 API（AdminAuth） - -> 登录见 §2.5。Token 中 `actorType=HQ`，`actorId` 为 `hq_account.id`。 -> 门店审核、退款审核、售后工单、操作审计均关联 `hq_account.id`。 - -### 6.0 总部账号（`hq_account` 表，`SUPER_ADMIN` 可管） - -| 方法 | 路径 | 鉴权 | 说明 | -|------|------|------|------| -| GET | `/admin/hq-accounts` | AdminAuth | 总部账号列表 | -| POST | `/admin/hq-accounts` | SUPER_ADMIN | 创建账号 `{ phone, name, adminRole }` | -| PUT | `/admin/hq-accounts/:id` | SUPER_ADMIN | 编辑/启用/禁用 | -| GET | `/admin/hq-accounts/me` | AdminAuth | 当前总部账号信息 | - -### 6.1 首页与预警 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/dashboard` | 今日概况 | §6.1 | -| GET | `/admin/alerts` | 预警列表 | §6.1, §6.10 | -| GET | `/admin/alerts/:id` | 预警详情 | §6.10 | -| PUT | `/admin/alerts/:id/resolve` | 标记已处理 | §6.10 | - -### 6.2 开城 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/cities` | 开城列表 | §6.2 | -| POST | `/admin/cities` | 新增城市 | §6.2 | -| GET | `/admin/cities/:id` | 城市详情 | §6.2 | -| PUT | `/admin/cities/:id` | 编辑城市 | §6.2 | -| PUT | `/admin/cities/:id/status` | 暂停/恢复 | §6.2 | -| PUT | `/admin/cities/:id/commission` | 配置佣金比例 | §6.2 | -| POST | `/admin/partners` | 创建合伙人主体 | §6.2 | - -### 6.3 商品 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/products` | 商品列表 | §6.3 | -| POST | `/admin/products` | 新增商品 | §6.3 | -| GET | `/admin/products/:id` | 商品详情 | §6.3 | -| PUT | `/admin/products/:id` | 编辑（含 benefitAmount） | §6.3 | -| PUT | `/admin/products/:id/status` | 上下架 | §6.3 | - -### 6.4 订单中心 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/orders` | 订单列表/搜索 | §6.4 | -| GET | `/admin/orders/search-suggest` | 搜索建议 | §6.4 | -| GET | `/admin/orders/:id` | 订单详情 | §6.4 | -| PUT | `/admin/orders/:id/status` | 手动改状态（异常处理） | §6.4 | -| POST | `/admin/orders/:id/ship` | 跨城发货/录入运单 | §6.4 | -| GET | `/admin/orders/:id/commissions` | 佣金拆分 | §6.4 | - -### 6.5 门店审核 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/store-audits` | 审核列表 `?status=` | §6.5 | -| GET | `/admin/store-audits/:id` | 审核详情 | §6.5 | -| PUT | `/admin/store-audits/:id/approve` | 通过 | §6.5 | -| PUT | `/admin/store-audits/:id/reject` | 驳回 `{ reason }` | §6.5 | -| PUT | `/admin/stores/:id` | 总部编辑门店 | §6.5 | - -### 6.6 推广码 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/promo-codes` | 推广码列表 | §6.6 | -| POST | `/admin/promo-codes` | 创建（生成小程序码） | §6.6 | -| PUT | `/admin/promo-codes/:id/status` | 启用/禁用 | §6.6 | -| GET | `/admin/promo-codes/:id/stats` | 扫码/转化统计 | §6.6 | - -### 6.7 结算中心 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/settlement/summary` | 待结算总额等 | §6.7 | -| GET | `/admin/settlement/partner-bills` | 合伙人待处理账单 | §6.7 | -| POST | `/admin/settlement/partner-bills` | 发起账期账单 | §6.7 | -| POST | `/admin/settlement/partner-bills/:id/send` | 发送账单通知 | §6.7 | -| POST | `/admin/settlement/partner-bills/:id/confirm-paid` | 确认打款 | §6.7 | -| GET | `/admin/settlement/store-payouts` | 门店待打款列表 | §6.7 | -| POST | `/admin/settlement/store-payouts/batch-pay` | T+1 批量打款 | §6.7 | -| GET | `/admin/settlement/withdrawals` | 提现审核列表 | §5.10 | -| PUT | `/admin/settlement/withdrawals/:id/approve` | 提现审核 | §5.10 | - -### 6.8 客服 · 售后 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/after-sales` | 工单列表 `?type=refund\|reshipment&status=` | §6.8 | -| GET | `/admin/after-sales/:id` | 工单详情 | §6.8 | -| POST | `/admin/after-sales/refunds` | 创建退款 `{ orderId, amount, reason }` | §3.6.2 | -| PUT | `/admin/after-sales/refunds/:id/approve` | 审核通过并发起微信退款 | §3.6.2 | -| PUT | `/admin/after-sales/refunds/:id/reject` | 驳回 | §3.6.2 | -| POST | `/admin/after-sales/reshipments` | 创建补发 `{ orderId, reason }` | §3.6 | -| GET | `/admin/after-sales/reshipments/:id` | 补发详情/进度 | §6.8 | - -### 6.9 数据报表 - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| GET | `/admin/reports/overview` | 报表中心概览 | §6.9 | -| GET | `/admin/reports/gmv` | GMV 趋势 | §6.9 | -| GET | `/admin/reports/channels` | 推广渠道转化 | §3.10 | -| GET | `/admin/reports/events` | 埋点统计 | §3.10.2 | - -### 6.10 通用 - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/admin/upload` | 图片/文件上传 OSS | -| GET | `/admin/operation-logs` | 操作审计（`common_event(HQ_OPERATION)`） | - ---- - -## 7. 回调接口（验签，无 JWT） - -| 方法 | 路径 | 说明 | PRD | -|------|------|------|-----| -| POST | `/callbacks/wechat/pay` | 支付结果通知 | §3.3.4 | -| POST | `/callbacks/wechat/refund` | 退款结果通知 | §3.6.2 | -| POST | `/callbacks/xfx/delivery` | 小飞侠配送状态 | §7.1 | -| POST | `/callbacks/logistics/tracking` | 跨城物流状态 | §2.3 | - ---- - -## 8. API 统计 - -| 端 | 接口数（约） | -|----|-------------| -| 认证（四端分拆） | 11 | -| C端 | 28 | -| 门店 | 8 | -| 合伙人 | 32 | -| 总部 | 49 | -| 回调 | 4 | -| **合计** | **~132** | - ---- - -## 9. 业务场景 → API 快速索引 - -| 场景 | 关键 API | -|------|----------| -| C端手机登录（phone 唯一） | `POST /auth/login/sms` → `user_user` | -| C端微信首登绑手机 | `POST /auth/login/wechat` → `POST /auth/wechat/bind-phone` | -| 门店 H5 登录 | `POST /shop/auth/login/sms` → `store_account` | -| 合伙人/子账号登录 | `POST /partner/auth/login/sms` → `partner_account` | -| 总部登录 | `POST /admin/auth/login/sms` → `hq_account` | -| JWT 四端隔离 | `actorType` + `actorId`，见 §1.5 | -| 同城2瓶/跨城6瓶 | `POST /trade/orders/preview` | -| 跨城到付 | preview 返回 `crossCityWarning` + create | -| 支付发券 | 回调 → 内部服务；`GET /benefit/coupons` | -| 订单5 Tab | `GET /trade/orders?tab=pending_ship` 等 | -| 改址拦截 | `PUT /trade/orders/:id/address` → `common_ticket+改址流程` | -| 核销¥500上限 | `POST /redeem/token` 校验 | -| 门店隐藏暂停 | `GET /stores` 过滤 | -| 门店T+1 | `GET /shop/redeem/records` + 总部 batch-pay | -| 合伙人T+30 | `/partner/settlement/bills/*` | -| 退款 | `/admin/after-sales/refunds/*` | -| 补发 | `/admin/after-sales/reshipments` + partner confirm | -| 推广归因 | `POST /promo/touch` + 下单写 channel | -| 埋点17事件 | `POST /analytics/events` | - ---- - - - ---- - -# §七、开发计划与任务卡 - -# 杜康好客 · V1 开发计划（可执行版） - -> **版本**：v2.0 -> **日期**：2026-06-27 -> **状态**：Agent / 人工编码事实源 -> **目标上线**：郑州开城、4 SKU、四端闭环（日历 10~12 周，按团队调整） - ---- - -## 0. 文档权威与 Agent 使用说明 - -### 0.1 阅读优先级（冲突时） - -| 优先级 | 文档 | 用途 | -|--------|------|------| -| 1 | `本手册 §二` | **做什么**（业务规则、状态、边界） | -| 2 | `conventions.md` | **怎么协作**（模块边界、提交、契约） | -| 3 | `本手册 §四` | **怎么架构**（NestJS 模块、依赖规则） | -| 4 | `本手册 §五` | **表结构**（Prisma / SQL 事实源 v2.1） | -| 5 | `本手册 §六` | **接口契约**（v1.1，含四端 JWT） | -| 6 | `pages/{user,shop,partner,hq}/` | **UI 参照**（字段、布局、跳转） | -| 7 | `doc/原型说明.md` | 原型与 PRD 差异（如 user/9 待发货 Tab） | - -### 0.2 Cursor Agent 编码流程 - -1. **绑定 Skill**：实现代码时启用 `.cursor/skills/dukang-coding`（或用户 @dukang-coding） -2. **领取任务**：从本文 **附录 A** 取任务卡 ID（如 `M2-FE-U-003`），一次只做一个任务卡 -3. **读文档**：按任务卡上的 PRD §、API 路径、DB 表、原型路径逐项对照 -4. **写代码**：遵守 `conventions.md` §2 模块边界；DTO/枚举进 `packages/shared-types` -5. **自验**：完成任务卡「验收标准」；跨模块改动同步 API 文档 -6. **提交**：Conventional Commits，scope = 端或模块（`feat(trade)`） - -### 0.3 技术栈（锁定） - -| 层 | 选型 | -|----|------| -| 前端 | Taro 3 + React + TypeScript，Monorepo 四 App | -| 后端 | Node 20 + NestJS 10 + Prisma 5 + MySQL 8 + Redis 7 + BullMQ | -| 协作 | **方案三**：一个 `dukang-api`，模块 OWNER，禁止跨模块直写表 | - -### 0.4 仓库目标结构（M0 必须落地） - -``` -dukang/ -├── apps/ -│ ├── mini-user/ # C端 -│ ├── mini-partner/ # 合伙人 -│ ├── mini-hq/ # 总部 -│ └── h5-shop/ # 门店 H5 -├── packages/ -│ ├── shared-types/ # DTO、枚举、错误码、JWT Payload -│ ├── shared-utils/ -│ ├── shared-ui/ -│ └── domain/ # 纯函数：起购、权益额、核销上限 -├── server/ -│ └── dukang-api/ -│ ├── prisma/schema.prisma # 已 v2.1 -│ └── src/ -│ ├── common/ -│ ├── modules/{iam,catalog,trade,benefit,store,redeem,settlement,ops,notify,analytics} -│ ├── callbacks/ -│ └── jobs/ -├── pages/ # 原型图（只读参照） -├── doc/ -└── conventions.md -``` - ---- - -## 1. 团队与 OWNER 分工 - -| OWNER | 前端 App | 后端 Module | 主责里程碑 | -|-------|----------|-------------|------------| -| A | `mini-user` | iam, trade, benefit, analytics | M1~M2, M6 | -| B | `mini-partner` | store | M1, M4 | -| C | `mini-hq` | catalog, settlement, ops | M1, M4~M6 | -| D | `h5-shop` | redeem | M3 | -| Lead | `packages/*` | callbacks, jobs, common | M0, 横切 CI | - -跨模块 PR：相关双 OWNER Review（技术方案 §2.4.4 R1~R3）。 - ---- - -## 2. 里程碑总览 - -| 里程碑 | 周次 | 核心交付 | 出口标准 | -|--------|------|----------|----------| -| **M0** | 第 0~1 周 | Monorepo + 骨架 + 环境 | `pnpm dev` 四端可启，API `/health` 通 | -| **M1** | 第 1~2 周 | IAM 四端、开城、商品 | 总部配郑州+4 SKU；四端可登录 | -| **M2** | 第 3~4 周 | C端购酒支付履约 | 同城2瓶/跨城6瓶；支付发券；5 Tab 订单 | -| **M3** | 第 5~6 周 | 权益+核销+门店 H5 | 端到端核销；门店短信 | -| **M4** | 第 7~8 周 | 拓店审核、补发退款拦截 | 合伙人录店→总部审→C端可见 | -| **M5** | 第 9 周 | T+1 门店 / T+30 合伙人 | 结算状态正确 | -| **M6** | 第 10 周 | 推广码、埋点、报表 | 渠道可归因 | -| **上线** | 第 11~12 周 | UAT、提审、试运行 | 郑州试运行 | - -```mermaid -gantt - title 杜康好客 V1（示意） - dateFormat YYYY-MM-DD - section 基础 - M0 仓库骨架 :m0, 2026-07-01, 7d - M1 IAM开城商品 :m1, after m0, 10d - section 核心 - M2 交易 :m2, after m1, 14d - M3 权益核销 :m3, after m2, 14d - section 运营 - M4 拓店售后 :m4, after m3, 14d - M5 结算 :m5, after m4, 10d - M6 增长 :m6, after m5, 7d - section 上线 - UAT上线 :launch, after m6, 14d -``` - ---- - -## 3. M0 仓库初始化（第 0~1 周） - -> **阻塞一切后续任务**。任务卡见附录 A `M0-*`。 - -| 类别 | 交付 | -|------|------| -| 根目录 | `pnpm-workspace.yaml`、`package.json`、ESLint/Prettier、`.env.example` | -| packages | `shared-types`（ActorType、OrderStatus、错误码）、`domain`（起购/权益/核销纯函数） | -| server | NestJS 启动、`PrismaModule`、`GlobalExceptionFilter`、统一 `{code,message,data}` | -| apps | 四端 Taro 脚手架、`request.ts`（带 `X-Client-App`）、登录态存储 | -| deploy | `docker-compose.yml`（MySQL + Redis）、`prisma migrate` 或执行 `数据库设计2` §5 SQL | -| CI | lint + `prisma validate` + `domain` 单元测试 | - -**M0 出口**：`GET /api/v1/health` 200；`npx prisma validate` 通过；四端空白页 + 登录页壳可编译。 - ---- - -## 4. 分里程碑交付说明 - -### M1 基础（IAM + 开城 + 商品） - -**PRD**：§3.1 登录、§6.2 开城、§6.3 商品 -**DB**：`users`、`store_accounts`、`partner_accounts`、`hq_accounts`、`cities`、`products`、`wx_app_configs` -**API**：§2 四端认证、`/catalog/*`、`/admin/cities`、`/admin/products`、`/admin/hq-accounts` - -| 端 | 页面（原型） | 关键能力 | -|----|--------------|----------| -| mini-hq | hq/1~2, 6~9, 12~14 | 总部登录、开城、商品 CRUD | -| mini-user | user/1, 2 | C端登录、首页骨架 | -| mini-partner | partner/1~2 | 合伙人登录壳 | -| h5-shop | shop/1~2 | 门店登录壳 | - -### M2 交易（C端主链路） - -**PRD**：§3.2~§3.6 -**DB**：`orders`、`order_items`、`payments`、`user_addresses`、`benefit_coupons`、`benefit_ledgers` -**API**：`/trade/orders/*`、`/user/addresses`、`callbacks/wechat/pay` - -| 端 | 页面 | 关键能力 | -|----|------|----------| -| mini-user | user/3~12, **9 含待发货 Tab** | 详情、下单、支付、5 Tab 订单、改址 | - -**业务验收**：同城 1 瓶拒单、2 瓶成功；跨城 5 瓶拒单、6 瓶成功；支付成功发券。 - -### M3 权益与核销 - -**PRD**：§3.7~§3.8、§4 -**DB**：`redeem_tokens`、`redeem_records`、`store_ratings`、`store_payouts`（创建待打款） -**API**：`/benefit/*`、`/redeem/*`、`/stores`、`/shop/redeem/*` - -| 端 | 页面 | 关键能力 | -|----|------|----------| -| mini-user | user/15~22, 17~18 | 门店列表、权益、核销码、评价 | -| h5-shop | shop/3~7 | 扫码、确认核销、记录 | - -**业务验收**：核销 ¥501 拒单；码 5 分钟失效；暂停门店 C 端不可见。 - -### M4 运营（拓店 + 售后） - -**PRD**：§5.3~§5.6、§6.5、§6.8 -**DB**：`stores`、`store_media`、`store_audits`、`after_sale_tickets`、`refunds`、`delivery_intercepts` -**API**：`/partner/stores/*`、`/admin/store-audits/*`、`/admin/after-sales/*`、`/partner/intercepts/*` - -### M5 结算 - -**PRD**：§4.4、§5.7、§6.7 -**DB**：`store_payouts`、`partner_bills`、`order_commissions`、`partner_withdrawals` -**API**：`/admin/settlement/*`、`/partner/settlement/*`、`/shop/redeem/records` - -### M6 增长 - -**PRD**：§3.10 -**DB**：`promo_codes`、`user_promo_attributions`、`event_logs` -**API**：`/promo/touch`、`/analytics/events`、`/admin/promo-codes`、`/admin/reports/*` - ---- - -## 5. 编码规范速链 - -- 模块禁止跨表：见 `conventions.md` §2、`技术方案` §2.5 -- JWT：`actorType` + `actorId`，见 `API列表` §1.5 -- C 端用户：`users.phone` 唯一必填；B 端三表分离 -- 金额：`Decimal(10,2)`；权益发放 `benefitAmount ?? price` -- 核销：Redis Token 5min + `benefit_coupons.version` 乐观锁 -- 订单 Tab：`all|pending_pay|pending_ship|pending_receive|completed` - ---- - -## 6. 测试策略 - -| 类型 | 范围 | -|------|------| -| 单元 | `packages/domain`：起购、权益额、核销上限 ¥500 | -| 集成 | 支付回调、核销事务、退款权益 VOID | -| E2E | 购酒→发券→核销→门店 payout PENDING | -| 里程碑末 | 全量冒烟 + 附录 A 任务卡验收勾选 | - -**必测 8 条**（与 v1.2 相同）：起购、跨城到付、发券金额、核销上限、闭店隐藏、待发货 Tab、退款作废、T+1 状态。 - ---- - -## 7. 前置依赖 - -| 项 | 最迟 | -|----|------| -| 微信商户号、三小程序 AppId | M1 | -| `pages/user/9` 改稿（待发货 Tab） | M2 | -| 郑州 4 SKU 素材 | M1 | -| 小飞侠 API（可 Mock） | M2 | -| 短信模板 | M3 | - ---- - -## 8. 人天估算（不变） - -约 **176 人天**，8 人团队 **10~12 周**（见 v1.2 §4）。 - ---- - -## 附录 A · 编码任务卡 - -> Agent：**一次只领取一张卡**；完成后在 PR 描述写 `Closes Mx-XX-XXX`。 - -### M0 基础设施 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M0-INFRA-001 | Lead | pnpm workspace + 根脚本 | `/package.json`, `pnpm-workspace.yaml` | — | — | `pnpm -r list` 四 apps + server | -| M0-INFRA-002 | Lead | `packages/shared-types` 枚举与 JWT | `packages/shared-types/src/` | — | API §1.5 | 导出 ActorType、OrderStatus、ApiResponse | -| M0-INFRA-003 | Lead | `packages/domain` 纯函数 + 测试 | `packages/domain/` | PRD §2.1, §2.3 | — | 起购/权益/¥500 单测通过 | -| M0-BE-001 | Lead | NestJS 骨架 + health | `server/dukang-api/src/main.ts` | 技术方案 §2.3 | — | `GET /health` | -| M0-BE-002 | Lead | PrismaModule + migrate | `server/dukang-api/prisma/` | 数据库设计2 §5 | 全表 | `prisma validate` | -| M0-BE-003 | Lead | 统一响应/异常 Filter | `server/dukang-api/src/common/` | API §1.2 | — | `{code,message,data}` | -| M0-FE-001 | A~D | 四端 Taro init | `apps/*/` | — | — | 各端 `dev` 编译通过 | -| M0-FE-002 | A | `mini-user` request + auth 存储 | `apps/mini-user/src/services/` | API §1.1 | — | 可带 X-Client-App | -| M0-DEV-001 | Lead | docker-compose MySQL+Redis | `deploy/docker-compose.yml` | — | — | 本地 DB 可连 | - -### M1 IAM + 开城 + 商品 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M1-BE-IAM-001 | A | 短信发送 | `modules/iam/` | §3.1 | `POST /auth/sms/send`, `sms_logs` | scene 分端 | -| M1-BE-IAM-002 | A | C端 sms/wechat 登录 | `modules/iam/` | §3.1, U1~U4 | `/auth/login/*`, `users` | phone 唯一 | -| M1-BE-IAM-003 | D | 门店登录 | `modules/iam/` | §4.1 | `/shop/auth/*`, `store_accounts` | actorType=STORE | -| M1-BE-IAM-004 | B | 合伙人登录 | `modules/iam/` | §5.1 | `/partner/auth/*`, `partner_accounts` | actorType=PARTNER | -| M1-BE-IAM-005 | C | 总部登录 + hq 账号 CRUD | `modules/iam/`, `modules/catalog/` | §6 | `/admin/auth/*`, `hq_accounts` | actorType=HQ | -| M1-BE-IAM-006 | A | JWT Guard 四端 | `common/guards/` | API §1.4 | — | actor 校验 | -| M1-BE-CAT-001 | C | 开城 CRUD + 佣金 | `modules/catalog/` | §6.2 | `/admin/cities/*`, `cities`, `city_commission_rules` | 郑州 ACTIVE | -| M1-BE-CAT-002 | C | 商品 CRUD | `modules/catalog/` | §6.3 | `/admin/products/*`, `products` | benefit_amount 可空 | -| M1-BE-CAT-003 | C | C端商品列表 Public | `modules/catalog/` | §3.2 | `GET /catalog/products` | 仅 ON_SALE | -| M1-FE-HQ-001 | C | 总部登录+开城+商品页 | `apps/mini-hq/` | hq/1,6~9,12,14 | §6 admin | 可配 4 SKU | -| M1-FE-U-001 | A | C端登录+首页 | `apps/mini-user/` | user/1,2 | §3.1~3.2 | 清香型 4 款 | -| M1-FE-P-001 | B | 合伙人登录壳 | `apps/mini-partner/` | partner/1~2 | §5.1 | 可登录 | -| M1-FE-S-001 | D | 门店登录壳 | `apps/h5-shop/` | shop/1~2 | §4.1 | 可登录 | - -### M2 交易 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M2-BE-TRD-001 | A | 地址 CRUD | `modules/trade/` | §3.4 | `/user/addresses`, `user_addresses` | 默认地址 | -| M2-BE-TRD-002 | A | 下单 preview（起购/运费） | `modules/trade/` + `domain` | §2.3, §3.3 | `POST /trade/orders/preview` | 2/6 瓶规则 | -| M2-BE-TRD-003 | A | 创建订单 + 推广归因 | `modules/trade/` | §3.10 | `POST /trade/orders`, `orders.promo_code_id` | 带 channel_source | -| M2-BE-TRD-004 | A | 微信支付 + 回调 | `modules/trade/`, `callbacks/` | §3.3.4 | `/trade/orders/:id/pay`, `payments` | 幂等 SUCCESS | -| M2-BE-BEN-001 | A | 支付成功发券 | `modules/benefit/` | §2.1 | `benefit_coupons`, `benefit_ledgers` | GRANT 流水 | -| M2-BE-TRD-005 | A | 订单列表 5 Tab | `modules/trade/` | §3.5.1 | `GET /trade/orders?tab=` | **含 pending_ship** | -| M2-BE-TRD-006 | A | 改址 + 拦截工单 | `modules/trade/` | §3.5.4 | `delivery_intercepts` | 创建拦截 | -| M2-FE-U-002 | A | 商品详情+确认订单 | `apps/mini-user/` | user/3~5 | preview API | 跨城弹窗 | -| M2-FE-U-003 | A | 地址+支付+订单列表 | `apps/mini-user/` | user/6~12,**9** | trade API | 5 Tab | -| M2-INT-001 | A | 小飞侠 Mock/对接 | `callbacks/xfx` | §7.1 | 配送状态 | 待发货→配送中 | - -### M3 权益与核销 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M3-BE-BEN-002 | A | 权益汇总/券/明细 | `modules/benefit/` | §3.8 | `/benefit/*` | 余额正确 | -| M3-BE-RDM-001 | D | 核销 Token Redis | `modules/redeem/` | §3.8.3 | `POST /redeem/token`, `redeem_tokens` | 5min/¥500 | -| M3-BE-RDM-002 | D | 门店扫码确认核销 | `modules/redeem/` | §4.3 | `/shop/redeem/*`, `redeem_records` | 事务+乐观锁 | -| M3-BE-RDM-003 | D | 核销评价 | `modules/redeem/` | §3.8.3 | `store_ratings` | 1~5 分 | -| M3-BE-STR-001 | B | C端门店列表/详情 | `modules/store/` | §3.7 | `GET /stores` | 仅 OPEN | -| M3-BE-NOT-001 | Lead | 核销短信 | `modules/notify/` | §4.3 | `sms_logs` | 门店收到短信 | -| M3-FE-U-004 | A | 权益+核销全流程 | `apps/mini-user/` | user/15~22 | benefit+redeem | 出码成功 | -| M3-FE-S-002 | D | 门店核销全流程 | `apps/h5-shop/` | shop/3~7 | shop/redeem | 扫码确认 | - -### M4 运营 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M4-BE-STR-002 | B | 门店三步录入+审核 | `modules/store/` | §5.3 | `/partner/stores/*`, `store_audits` | 提交 PENDING | -| M4-BE-STR-003 | C | 总部审核门店 | `modules/store/` | §6.5 | `/admin/store-audits/*` | reviewer=hq_accounts | -| M4-BE-IAM-007 | B | 合伙人子账号 | `modules/iam/` | §5.9 | `/partner/staff`, `partner_accounts` | 主/子账号 | -| M4-BE-TRD-007 | A | 补发单 | `modules/trade/` | §3.6 | `orders` RESHIPMENT | 金额 0 | -| M4-BE-TRD-008 | A | 退款+权益 VOID | `modules/trade/` | §3.6.2 | `refunds`, `after_sale_tickets` | 微信退款 | -| M4-FE-P-002 | B | 合伙人门店+补发+拦截 | `apps/mini-partner/` | partner/4~9,12~13 | partner API | 闭环 | -| M4-FE-HQ-002 | C | 总部审核+客服 | `apps/mini-hq/` | hq/19~20,26~27 | admin after-sales | 退款可操作 | - -### M5 结算 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M5-BE-STL-001 | C | 核销→store_payouts | `modules/settlement/` | §4.4 | 60%, T+1 | PENDING | -| M5-BE-STL-002 | C | T+1 打款任务 | `jobs/` | §6.7 | batch-pay | PAID | -| M5-BE-STL-003 | C | 合伙人 T+30 账单 | `modules/settlement/` | §5.7 | `partner_bills` | 确认流程 | -| M5-FE-* | B,C,D | 三端结算页 | 各 app | partner/10,22; shop/6; hq/21~23 | settlement API | 状态展示 | - -### M6 增长 - -| ID | OWNER | 任务 | 主要路径 | PRD | API/DB | 验收 | -|----|-------|------|----------|-----|--------|------| -| M6-BE-ANA-001 | A | promo touch 归因 | `modules/analytics/` | §3.10.1 | `user_promo_attributions` | 首次触达 | -| M6-BE-ANA-002 | A | 埋点批量入库 | `modules/analytics/` | §3.10.2 | `event_logs` | 17 事件 | -| M6-BE-CAT-004 | C | 推广码+统计 | `modules/catalog/` | §6.6 | `/admin/promo-codes` | scan/order_count | -| M6-FE-HQ-003 | C | 报表+预警 | `apps/mini-hq/` | hq/3~5,15~17 | `/admin/reports` | GMV/渠道 | - ---- - -## 附录 B · 原型 → API → 模块 速查 - -| 端 | 原型目录 | 主要 API 前缀 | NestJS Module | -|----|----------|---------------|---------------| -| C端 | `pages/user/` | `/auth`, `/user`, `/catalog`, `/trade`, `/benefit`, `/redeem`, `/stores`, `/promo` | iam, catalog, trade, benefit, redeem, store, analytics | -| 门店 | `pages/shop/` | `/shop/auth`, `/shop/redeem`, `/shop/store` | iam, redeem, store | -| 合伙人 | `pages/partner/` | `/partner/*` | iam, store, trade, settlement | -| 总部 | `pages/hq/` | `/admin/*` | iam, catalog, store, trade, settlement, ops, analytics | - ---- - -## 附录 C · Skills 绑定说明 - -| Skill | 路径 | 何时启用 | -|-------|------|----------| -| **dukang-coding** | `.cursor/skills/dukang-coding/` | **写代码、实现任务卡、修 Bug** | -| dukang-project | `.cursor/skills/dukang-project/` | 写 PRD、评审需求、对照原型 | - -在 Cursor 项目设置或对话中 @dukang-coding，并指明任务卡 ID，例如： - -> 实现 M2-BE-TRD-002，按开发计划与 PRD 完成下单 preview。 - ---- - -*计划随迭代每周更新；任务卡新增请保持 ID 格式 `Mx-LAYER-NNN`。* - - ---- - -# §八、核心业务链路 - -### 购酒 → 发券 → 配送 - -``` -user_user → user_order(含商品快照) → log_third_party(WECHAT_PAY) -→ user_order_delivery(1:1) → user_benefit_coupon → common_event(BENEFIT_LEDGER,GRANT) -``` - -### 核销 → 门店 T+1 - -``` -Redis redeem:token(5min) → user_redeem_record → common_event(BENEFIT_LEDGER,REDEEM) -→ store_payout(T+1) → user_store_rating → log_third_party(SMS) -``` - -### 门店入驻 - -``` -partner_partner → store_store + common_resource → common_event(STORE_AUDIT) -→ hq_account 审核 → store_account -``` - -### 退款 - -``` -common_ticket(REFUND) → log_third_party(WECHAT_REFUND) → user_benefit_coupon VOID -→ common_event(BENEFIT_LEDGER,VOID) → common_event(ORDER_STATUS,REFUNDED) -``` - -### 改址拦截 - -用户改址 API 更新 user_order 收货字段 → common_event(ORDER_STATUS) + 可选 common_ticket(ALERT) → 合伙人 `pages/partner/4-拦截配送.png` 处理 → user_order_delivery 与第三方回调同步状态。 - ---- - -# §九、第三方集成与非功能 - -| 系统 | 用途 | 落库 | -|------|------|------| -| 微信支付/退款 | 下单、退款 | log_third_party + user_order.pay_* | -| 小飞侠 | 同城配送 | log_third_party(XFX) + user_order_delivery | -| 物流 | 跨城 | user_order_delivery + 总部发货 | -| 短信 | 验证码、核销通知 | log_third_party(SMS) | -| OSS | 图片/合同 | common_resource | - -**非功能**：JWT 四端隔离；支付/核销幂等；列表 P95 < 500ms；核销 Redis 5min + 券 version 乐观锁；手机号脱敏。 - ---- - -*编码配合根目录 agent.md、skills.md、conventions.md。* +| §一 | 四端目标、郑州 4 SKU | +| §二 | PRD + 原型 | +| §三 | 页面流 | +| §四 | Nest 模块边界、OWNER | +| §五 | MySQL 28 表 v3.1 | +| §六 | `/api/v1` 路由清单 | +| §七 | M0~M6 任务卡 | +| §八 | 购酒/核销/结算链路 | +| §九 | 微信/小飞侠/短信集成 | + +**联调裁剪**：[`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md) diff --git a/杜康好客-preV1编码手册.md b/杜康好客-preV1编码手册.md index fff81dd..455e693 100644 --- a/杜康好客-preV1编码手册.md +++ b/杜康好客-preV1编码手册.md @@ -1,435 +1,41 @@ -# 杜康好客 · preV1 编码手册（Mock 联调版） +# 杜康好客 · preV1 编码手册（Mock 联调） -> **V3 交付提示**：preV1 不再作为交付验收标准。核销规则以 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) §3 为准（无 ¥500 上限）。 +> **非 V3 验收标准**。核销等规则以 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 为准。 +> 原则：**同 V2 库表与 API 路径**，用 Mock/Flag/Seed 跳过外部依赖。 -> **版本**：preV1（在 V2 完整规格之上的**裁剪实现阶段**） -> **完整规格（V2）**：[`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) — PRD、DB v3.1、API、任务卡均以 V2 为准 -> **原则**：**不删表、不删 V2 API 路径、不改 V2 字段语义**；preV1 用 Mock / Feature Flag / Seed 跳过外部依赖，开关关闭即切回 V2 真实流程。 +## 六条裁剪 ---- +| # | 裁剪 | 替代 | +|---|------|------| +| 1 | 无 HQ 前端 | `/admin/*` 脚本或后续 admin-web | +| 2 | 三端均 H5 | `h5-user` / `h5-shop` / `h5-partner` | +| 3 | 登录 | 手机号 + 固定码 `999888` | +| 4 | 支付 | Mock 即时成功 | +| 5 | 配送 | Mock 状态推进 | +| 6 | 短信 | Mock | -## 文档索引 +## Feature Flag（`.env`） -| 章节 | 内容 | +| Flag | 作用 | |------|------| -| §0 | 版本关系（preV1 vs V2） | -| §1 | preV1 范围：六条裁剪规则 | -| §2 | 三端 H5 与仓库结构 | -| §3 | 认证 Mock（无微信） | -| §4 | 支付 Mock | -| §5 | 配送与订单状态 Mock | -| §6 | 无总部端：能力替代 | -| §7 | preV1 功能清单 | -| §8 | Feature Flag 与 V2 切换 | -| §9 | preV1 里程碑与任务卡 | -| §10 | API / 数据行为差异速查 | +| `MOCK_SMS` | 验证码 999888 | +| `MOCK_PAY` | 支付同步成功 | +| `MOCK_DELIVERY` | 配送 Mock 推进 | ---- - -# §0、版本关系 - -| 维度 | preV1（本文） | V2（完整版） | -|------|---------------|--------------| -| 定位 | 三端 H5 联调，跑通购酒→发券→核销主链路 | 四端小程序/H5 + 真实微信/物流/支付 | -| 客户端 | **用户 / 门店 / 合伙人 均为 H5** | C端+合伙人+总部小程序，门店 H5 | -| 总部 HQ | **无独立端** | `pages/hq/` + AdminAuth | -| 登录 | **仅手机号 + 固定验证码** | 短信 + 微信授权/绑定 | -| 支付 | **Mock 即时成功** | 微信 JSAPI + 回调 | -| 配送 | **Mock 状态推进** | 小飞侠/物流回调 | -| 数据库 | **同 V2 v3.1（28 表）** | 同左 | -| API 路径 | **同 V2 §六**（行为可 Mock） | 完整实现 | - -**升级路径**：preV1 完成后，按 §8 逐项打开 Flag、补小程序端与 HQ 端，**无需重构表结构**。 - ---- - -# §1、preV1 范围：六条裁剪规则 - -### 1.1 删掉 HQ 端 - -- **不做**：`apps/mini-hq`、`pages/hq/` 任何页面、AdminAuth 前端。 -- **保留**：`hq_account` 表、§六 全部 `/admin/*` 路由（preV1 可不实现 Controller，或仅内部/脚本调用）。 -- **替代**：见 §6。 - -### 1.2 用户 / 门店 / 合伙人 均改为 H5 - -| V2 端 | preV1 App | `X-Client-App` | 原型参照 | -|-------|-----------|----------------|----------| -| C端小程序 | `apps/h5-user` | `USER_H5` | `pages/user/` | -| 门店 H5 | `apps/h5-shop` | `SHOP_H5` | `pages/shop/` | -| 合伙人小程序 | `apps/h5-partner` | `PARTNER_H5` | `pages/partner/` | - -- JWT `actorType` 不变：`USER` / `STORE` / `PARTNER`。 -- V2 的 `USER_MINI` / `PARTNER_MINI` / `HQ_MINI` 枚举**保留**，preV1 不用即可。 - -### 1.3 微信登录与授权暂不走 - -- **不调用**：微信 `code2session`、获取手机号组件、微信 OAuth。 -- **不写入**：`wx_open_id` / `wx_union_id`（保持 NULL）。 -- **仅实现**：`POST /auth/sms/send` + `POST /auth/login/sms`（及三端等价路径 `/shop/auth/*`、`/partner/auth/*`）。 -- V2 的 `POST /auth/login/wechat`、`/auth/wechat/bind-phone`：**保留路由**，preV1 返回 `501 FEATURE_DISABLED` 或 Flag 关闭时不注册。 - -### 1.4 手机号验证固定 Mock - -| 项 | preV1 约定 | -|----|------------| -| 验证码 | 固定 **`123456`**（全端、全 scene 通用） | -| 开关 | `MOCK_SMS=true` 时：不调用短信网关，不写入 `log_third_party(SMS)` 真实外呼 | -| 校验 | `AuthService.verifyCode(phone, code)` 内：`if (MOCK_SMS && code === '123456') return ok` | -| 限流 | preV1 可放宽；V2 打开真实短信后启用频率限制 | - -**测试账号（Seed，见 §6.1）** - -| 角色 | 手机号 | 表 | -|------|--------|-----| -| C端用户 | `13800000001` | `user_user` | -| 门店 | `13900000001` | `store_account` | -| 合伙人主账号 | `13700000001` | `partner_account` | - -### 1.5 配送与订单状态 Mock（跳过第三方） - -- **不调用**：小飞侠 API、物流查询 API；`log_third_party` 的 `XFX` / `LOGISTICS` 在 preV1 可不写入（或写 MOCK 占位）。 -- **仍创建**：支付成功后 `user_order_delivery` 空壳（与 V2 一致 1:1）。 -- **状态推进**（任选其一，推荐 A+B）： - - **A. 自动任务**：`MOCK_DELIVERY_AUTO=true` 时，支付成功 30s 后 BullMQ 任务：`PENDING_SHIP → OUT_WAREHOUSE → SHIPPING → PENDING_RECEIVE → COMPLETED`，并写 `common_event(ORDER_STATUS)`。 - - **B. 合伙人手动**：`POST /partner/orders/:id/mock-advance-delivery`（preV1 专用，V2 可保留为内部测试接口或 Flag 保护）。 -- **user_order** 冗余时间字段 `shipped_at` / `completed_at` 与 `user_order_delivery.shipping_at` / `delivered_at` **双写**（同 V2）。 - -### 1.6 跳过支付 - -- **不调用**：微信统一下单、支付回调验签。 -- **用户侧**：确认订单页按钮文案可为「提交订单（Mock 支付）」；仍调用 **`POST /trade/orders/:id/pay`**（路径与 V2 相同）。 -- **服务端**：`MOCK_PAY=true` 时 `PayService` 同步： - 1. `user_order.pay_status=PAID`，`paid_at=NOW()`，`pay_external_no='MOCK-{orderNo}'` - 2. 可选写 `log_third_party(WECHAT_PAY, scene=ORDER_PAY, status=SUCCESS, external_no=MOCK-...)` - 3. 订单 `status=PENDING_SHIP` + `common_event(ORDER_STATUS)` - 4. 调用 `BenefitService.grantOnOrderPaid(orderId)`（**真实发券逻辑，非 Mock**） - 5. 预创建 `user_order_delivery` -- V2 切换：`MOCK_PAY=false` 时走 `wechatpay-node-v3` + `/callbacks/wechat/pay`。 - ---- - -# §2、三端 H5 与仓库结构 - -preV1 Monorepo（在 V2 目标结构上演进，**暂不建 mini-* / mini-hq**）： - -``` -dukang/ -├── apps/ -│ ├── h5-user/ # C端 H5（Taro H5 或 Vite+React，与 V2 技术栈一致即可） -│ ├── h5-shop/ # 门店 H5 -│ └── h5-partner/ # 合伙人 H5 -├── packages/ -│ ├── shared-types/ # 含 USER_H5 / PARTNER_H5 / SHOP_H5 -│ └── domain/ -├── server/dukang-api/ # 同 V2 单体 NestJS -├── pages/{user,shop,partner}/ # UI 参照（hq 仅 V2 用） -├── 杜康好客-V2编码手册.md -└── 杜康好客-preV1编码手册.md # 本文 -``` - -**请求头**：各 H5 固定 `X-Client-App: USER_H5 | SHOP_H5 | PARTNER_H5`。 - -**页面实现**：字段、Tab、跳转以 V2 手册 §二、§三 原型为准；C 端订单 **5 Tab（含待发货）** 不变。 - ---- - -# §3、认证 Mock（无微信） - -### 3.1 实现的登录路径 - -| 端 | 发送验证码 | 登录 | -|----|------------|------| -| C端 | `POST /auth/sms/send` scene=`USER_LOGIN` | `POST /auth/login/sms` | -| 门店 | `POST /auth/sms/send` scene=`STORE_LOGIN` | `POST /shop/auth/login/sms` | -| 合伙人 | `POST /auth/sms/send` scene=`PARTNER_LOGIN` | `POST /partner/auth/login/sms` | - -### 3.2 preV1 不实现的登录路径 - -| 路径 | preV1 行为 | -|------|------------| -| `POST /auth/login/wechat` | 501 或 Flag 关闭 | -| `POST /auth/wechat/bind-phone` | 501 | -| `POST /shop/auth/login/wechat` | 501 | -| `POST /partner/auth/login/wechat` | 501 | -| `POST /admin/auth/*` | 不暴露给前端（无 HQ 端） | - -### 3.3 实现要点（便于 V2 切换） - -```typescript -// packages/shared-types 或 server config -export const AppConfig = { - mockSms: process.env.MOCK_SMS === 'true', - mockSmsCode: process.env.MOCK_SMS_CODE ?? '123456', - mockPay: process.env.MOCK_PAY === 'true', - mockDeliveryAuto: process.env.MOCK_DELIVERY_AUTO === 'true', -}; - -// AuthService — 单一验证码入口，V2 只改内部实现 -async verifySmsCode(phone: string, code: string, scene: string) { - if (AppConfig.mockSms && code === AppConfig.mockSmsCode) return; - // V2: 查 Redis / log_third_party / 真实短信平台 -} -``` - ---- - -# §4、支付 Mock - -### 4.1 用户流程（与 V2 UI 一致，跳过收银台） - -``` -确认订单 → POST /trade/orders（锁单 PENDING_PAY） - → POST /trade/orders/:id/pay - [MOCK_PAY=true] 同步成功，无跳转微信 - → 订单列表可见「待发货」 - → 权益页可见新券 -``` - -### 4.2 字段与表（与 V2 相同） - -| 写入 | 说明 | -|------|------| -| `user_order.pay_status` | `PAID` | -| `user_order.paid_at` | 当前时间 | -| `user_order.pay_external_no` | `MOCK-{orderNo}` | -| `user_order.status` | `PENDING_SHIP` | -| `log_third_party` | 可选 MOCK 记录，便于 V2 对账逻辑联调 | -| `user_benefit_coupon` + `common_event(BENEFIT_LEDGER,GRANT)` | **真实业务**，非 Mock | - -### 4.3 preV1 不做的支付相关能力 - -- 微信 prepay 参数、支付回调、`/callbacks/wechat/pay` 验签（路由保留，Mock 模式不触发）。 -- 退款微信 API：preV1 **整模块可跳过**（§7）；表与 `common_ticket(REFUND)` 仍保留。 - ---- - -# §5、配送与订单状态 Mock - -### 5.1 自动推进状态机（推荐默认开启） - -`MOCK_DELIVERY_AUTO=true` 时，支付成功后注册延时任务： - -| 延时 | from → to | 配送表 | -|------|-----------|--------| -| T+0 | `PENDING_SHIP` → `OUT_WAREHOUSE` | `out_warehouse_at` | -| T+10s | → `SHIPPING` | `shipping_at`，`user_order.shipped_at` | -| T+30s | → `PENDING_RECEIVE` | — | -| T+60s | → `COMPLETED` | `delivered_at`，`user_order.completed_at` | - -每次 transition 写 `common_event(ORDER_STATUS)`；`provider` 填 `MANUAL` 或 `MOCK`。 - -### 5.2 合伙人端手动推进（可选） - -`POST /partner/orders/:id/mock-advance-delivery` - -- Guard：`PartnerAuth` + 订单 `city_id` 属合伙人辖区。 -- Body：`{ targetStatus: 'SHIPPING' | 'COMPLETED' | ... }` -- preV1 专用；V2 生产环境 `MOCK_DELIVERY=false` 时返回 403。 - -### 5.3 改址拦截（preV1 简化） - -- V2 PRD：用户改址 → 合伙人拦截配送。 -- preV1：`PUT /trade/orders/:id/address` **仅更新** `user_order` 收货字段 + `common_event`；**不**调第三方、不建复杂 intercept 表（V2 仍用 `common_ticket(ALERT)`，preV1 可省略工单）。 - ---- - -# §6、无总部端：能力替代 - -HQ 能力在 preV1 通过 **Seed + 合伙人 H5 子集 + 可选内部 API** 覆盖，**表结构不删**。 - -### 6.1 启动 Seed（`prisma/seed-prev1.ts` 或 SQL） - -| 数据 | 内容 | -|------|------| -| `common_city` | 郑州 `ACTIVE`，`local_min_qty=2`，`cross_min_qty=6` | -| `common_city_commission_rule` | 默认佣金比例 | -| `common_product_item` | 4 款清香型 `ON_SALE`，含 `barcode_69` | -| `common_store_category` | 火锅/地方菜等 | -| `partner_partner` + `partner_account` | 郑州合伙人 + 主账号 `13700000001` | -| `store_store` + `store_account` | 至少 2 家 `OPEN` 门店 | -| `user_user` | 测试用户 `13800000001` | -| `hq_account` | 可 Seed 1 条供未来 V2，preV1 无 UI | - -商品图/门头图：preV1 可用 **占位 URL** 或 `common_resource` 写死 CDN；V2 换 OSS 上传流程即可。 - -### 6.2 原 HQ 功能 → preV1 替代 - -| V2 HQ 功能 | preV1 替代 | -|------------|------------| -| 开城 / 商品 CRUD | **Seed 固定**；变更改 Seed 或直连 DB（开发环境） | -| 门店审核 | 合伙人提交后 **`AUTO_APPROVE_STORE=true` 自动通过**，写 `common_event(STORE_AUDIT,APPROVED)` | -| 订单中心 / 发货 | 合伙人 H5 看辖区订单；跨城发货 preV1 跳过或 Mock 运单号 | -| 推广码 | **跳过 UI**；`channel_source` 可手填或 Seed 一条 `common_promo_code` | -| 退款 / 客服工单 | **跳过**（或合伙人 H5 仅查看，不发起微信退款） | -| 结算中心 T+1/T+30 | **Mock 状态**：核销后 `store_payout.status=PENDING`；合伙人 `partner_bill` 可 Seed 一条 `CONFIRMED` 演示 | -| 数据报表 / 埋点 | 埋点 **可写 `log_user_analytics`**；总部报表 **不做** | - -### 6.3 合伙人 H5 在 preV1 的扩展（承接部分 HQ） - -在 V2 合伙人 API 基础上，preV1 **额外开放**（Flag 保护）： - -| 能力 | 说明 | -|------|------| -| 门店审核自动通过 | 配置项，非新表 | -| Mock 推进配送 | §5.2 | -| 查看辖区订单 | V2 已有 `GET /partner/orders` | - ---- - -# §7、preV1 功能清单 - -### 7.1 必做（跑通主链路） - -| 模块 | 功能 | V2 预留 | -|------|------|---------| -| IAM | 三端短信 Mock 登录 | 微信登录路由保留 | -| Catalog | 读商品/开城（Seed） | `/admin/products` 未实现 | -| Trade | 预览、下单、Mock 支付、5 Tab 订单、改址 | 真实微信支付 | -| Benefit | 发券、券列表、明细 | 同 V2 | -| Redeem | Redis 核销码、门店扫码确认、评价 | 同 V2 | -| Store | C 端门店列表/详情；合伙人录店；**自动审核** | HQ 人工审核 | -| Settlement | 核销后 `store_payout` PENDING | T+1 打款任务可 Mock 为手动改 PAID | -| Analytics | 可选：批量写 `log_user_analytics` | 同 V2 | - -### 7.2 preV1 明确跳过（V2 补） - -| 模块 | 跳过内容 | -|------|----------| -| HQ 端 | 全部页面与 AdminAuth 前端 | -| 微信 | 登录、支付、退款、订阅消息 | -| 第三方 | 小飞侠、物流、真实短信 | -| 运营 | 退款工单、推广码管理 UI、总部报表 | -| 合伙人 | 拦截配送完整流程、T+30 真实打款、提现 | -| 小程序 | 全部（preV1 仅 H5） | - -### 7.3 业务规则（与 V2 相同，Mock 不减免） - -- 同城起购 **2 瓶** / 跨城 **6 瓶**（`packages/domain`） -- 权益金额 `benefit_amount ?? price` -- 核销上限 **¥500**，Redis 码 **5 分钟** -- C 端门店仅 **`OPEN`** -- 订单 **5 Tab**（含 `pending_ship`） - ---- - -# §8、Feature Flag 与 V2 切换 - -### 8.1 环境变量（`.env.example`） +## 启动验证 ```bash -# preV1 Mock 开关（true = Mock 模式） -MOCK_SMS=true -MOCK_SMS_CODE=123456 -MOCK_PAY=true -MOCK_DELIVERY_AUTO=true -AUTO_APPROVE_STORE=true - -# V2 就绪后逐项 false，并配置真实密钥 -WECHAT_PAY_ENABLED=false -WECHAT_AUTH_ENABLED=false -XFX_ENABLED=false -SMS_PROVIDER=mock +pnpm dev:api && pnpm dev:user && pnpm dev:shop && pnpm dev:partner +node scripts/smoke-prev1.mjs ``` -### 8.2 切换检查表（preV1 → V2） +## 与 V2 差异速查 -| 步骤 | 动作 | -|------|------| -| 1 | `MOCK_PAY=false`，配置商户号，启用 `/callbacks/wechat/pay` | -| 2 | `MOCK_SMS=false`，接入短信，`log_third_party(SMS)` | -| 3 | `MOCK_DELIVERY_AUTO=false`，对接小飞侠/物流回调 | -| 4 | `AUTO_APPROVE_STORE=false`，上线 `apps/mini-hq` + 门店审核 | -| 5 | 新增 `apps/mini-user`、`apps/mini-partner`，`X-Client-App` 改 MINI | -| 6 | `WECHAT_AUTH_ENABLED=true`，实现 wechat 登录/bind-phone | -| 7 | 启用退款、结算 Job、推广码 HQ 页面 | +| 项 | preV1 | V2/V3 | +|----|-------|-------| +| 客户端 | 三 H5 | 小程序 + H5 | +| 总部 | 无 UI | admin-web | +| 微信 | 无 | JSAPI/OAuth | +| 表结构 | v3.1 同左 | 同左 | -### 8.3 代码组织（避免 Mock 散落） - -``` -server/dukang-api/src/ -├── integrations/ -│ ├── sms/ -│ │ ├── sms.interface.ts # ISmsProvider -│ │ ├── sms.mock.provider.ts # preV1 -│ │ └── sms.aliyun.provider.ts # V2 -│ ├── pay/ -│ │ ├── pay.interface.ts -│ │ ├── pay.mock.provider.ts -│ │ └── pay.wechat.provider.ts -│ └── delivery/ -│ ├── delivery.interface.ts -│ ├── delivery.mock.provider.ts -│ └── delivery.xfx.provider.ts -``` - -`TradeModule` / `AuthModule` 只依赖 **interface**，由 `ConfigModule` 注入 Mock 或 Real 实现。 - ---- - -# §9、preV1 里程碑与任务卡 - -> 详细 API/表结构见 V2 手册 §五、§六；任务 ID 前缀 **`P1-`**，与 V2 `M0~M6` 并行命名空间。 - -| 里程碑 | 交付 | 出口标准 | -|--------|------|----------| -| **P1-M0** | Monorepo 三 H5 + API 骨架 + Seed | 三端登录页、`GET /health`、Seed 郑州+4 SKU | -| **P1-M1** | IAM Mock + 商品/门店读 | 三端 Mock 登录；C 端首页 4 款酒 | -| **P1-M2** | 下单 + Mock 支付 + 5 Tab 订单 | 2 瓶起购；支付后待发货+发券 | -| **P1-M3** | 权益 + 核销 + 门店 H5 | 端到端核销；`store_payout` PENDING | -| **P1-M4** | 合伙人录店 + 自动审核 | C 端可见新门店 | -| **P1-M5** | Mock 配送自动推进 | 订单可到已完成 | -| **P1-M6** | 埋点可选 + 联调修复 | 主链路冒烟通过 | - -### 任务卡（精简） - -| ID | 任务 | 验收 | -|----|------|------| -| P1-M0-001 | pnpm workspace + `h5-user/shop/partner` | 三端 `dev` 可编译 | -| P1-M0-002 | `shared-types` + Mock Flags | 导出 `AppConfig` | -| P1-M0-003 | NestJS + Prisma + `init_v3.sql` | `prisma validate` | -| P1-M0-004 | `seed-prev1.ts` | 郑州/4SKU/测试账号 | -| P1-M1-001 | `SmsMockProvider` + 三端 login/sms | 123456 登录 | -| P1-M1-002 | C 端首页/详情 Public catalog | 对照 `pages/user/2,3` | -| P1-M2-001 | preview + create order | 起购校验 | -| P1-M2-002 | `PayMockProvider` + grant benefit | Mock 支付发券 | -| P1-M2-003 | 订单 5 Tab | `pending_ship` 有数据 | -| P1-M3-001 | 权益页 + redeem token | ¥500 上限 | -| P1-M3-002 | 门店扫码核销 | `pages/shop/3~5` | -| P1-M4-001 | 合伙人录店 + AUTO_APPROVE | C 端门店可见 | -| P1-M5-001 | `DeliveryMockProvider` 自动推进 | 订单 COMPLETED | - ---- - -# §10、API / 数据行为差异速查 - -| API / 行为 | V2 | preV1 | -|------------|-----|-------| -| `X-Client-App` | USER_MINI / … | USER_H5 / SHOP_H5 / PARTNER_H5 | -| `/admin/*` | AdminAuth 小程序 | 无前端；Seed/脚本 | -| `/auth/login/wechat` | 实现 | 501 或 Flag 关 | -| `/auth/sms/send` | 真实短信 | 固定码，不外呼 | -| `/trade/orders/:id/pay` | 微信 prepay | 同步 Mock 成功 | -| `/callbacks/wechat/pay` | 验签回调 | 不触发 | -| `/callbacks/xfx/delivery` | 配送回调 | 不触发 | -| `log_third_party` | 真实流水 | 可选 MOCK 行或跳过 | -| 门店审核 | HQ 审 | `AUTO_APPROVE_STORE` | -| 退款 | HQ 工单+微信退款 | **跳过** | -| 推广码 UI | HQ | **跳过** | -| 核销 / 权益 / 订单表 | 真实 | **真实（同 V2）** | - ---- - -## 原型参照（preV1 仍用 V2 映射） - -| H5 App | 原型目录 | -|--------|----------| -| h5-user | `pages/user/` | -| h5-shop | `pages/shop/` | -| h5-partner | `pages/partner/` | - -C 端订单列表：**5 Tab（含待发货）**；个人中心无会员标签；城市示例以 **郑州** 为准。 - ---- - -*preV1 为 V2 的 Mock 联调阶段；完整 PRD、DB DDL、全量 API 见 [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md)。* +升级：逐项关 Mock → 接真实集成 → 补 admin-web / mini-user。 diff --git a/杜康好客-v2.1编码手册.md b/杜康好客-v2.1编码手册.md index 8c1f5a2..6405eb9 100644 --- a/杜康好客-v2.1编码手册.md +++ b/杜康好客-v2.1编码手册.md @@ -1,169 +1,3 @@ -# 杜康好客 · V3 编码手册（交付业务版） +# 杜康好客 · v2.1 编码手册 -> **版本定位**：V3 是基于当前数据库 v3.1 的完整交付版本，目标不是 Mock 联调，而是把「购酒 → 发券 → 到店核销 → 门店打款 → 合伙人结算 → 总部运营」全流程跑通。 -> **对照文件**：V2 手册定义完整产品蓝图；preV1 手册定义 Mock 联调裁剪；本文件定义 V3 的交付口径、核销新规则、两人分工与业务闭环任务口径。 -> **数据库事实**：当前 Prisma schema 已是 v3.1，V3 不默认新增大表，优先补齐业务闭环、第三方集成、任务调度、验收测试与运营后台。 - ---- - -## 1. V3 交付目标 - -V3 必须达到可业务验收状态： - -1. C 端用户能登录、选城、浏览商品、下单、支付、查看订单、获得权益、到店核销。 -2. 门店端能登录、扫码/输码核销、查看核销记录、管理营业状态，并形成待打款记录。 -3. 合伙人端能登录、录入门店、管理门店、查看辖区订单、处理配送/补发、查看账单与经营数据。 -4. WebAdmin 能完成开城、商品、门店审核、订单、权益、核销、配送、退款/补发、结算、资源和账号管理。 -5. 后端能完成真实支付回调、配送状态推进、退款/补发工单、门店 T+1、合伙人 T+30、日志与审计。 -6. 测试能覆盖主链路、关键边界和生产开关，不再只依赖一条 happy path 冒烟。 - ---- - -## 2. V3 端与负责人 - -| 负责人 | 主责端 | 主责后端/公共范围 | 说明 | -|---|---|---|---| -| `jacy-dukang` | `apps/h5-user`、`apps/admin-web` | `packages/*`、`iam`、`catalog`、`trade`、`benefit`、`settlement`、`ops`、`callbacks`、`jobs`、`integrations`、Prisma | Tech lead，负责架构、主交易链路、支付退款、后台运营、交付验收 | -| `刘景尧` | `apps/h5-shop`、`apps/h5-partner` | `store`、`redeem`，并配合 `settlement`、配送/核销联调 | 负责门店、合伙人、录店、核销、门店体验与辖区履约 | - -协作规则： - -- `apps/*` 只走 HTTP API 与 `packages/shared-types`，禁止 import `server/*` 或其他 app。 -- 后端跨模块只调用 exported Service，禁止为了赶进度直接写他人领域表。 -- 涉及 API、枚举、DTO、业务规则变更，必须同步 `packages/shared-types`、`packages/domain` 与本手册。 -- Prisma 迁移由 `jacy-dukang` 主导；涉及 `store` / `redeem` 表或核销流程时 `刘景尧` 必须 Review。 - ---- - -## 3. V3 核销规则（已替代 V2 的 ¥500 上限） - -### 3.1 两种核销入口 - -| 入口 | 前端表现 | API 入参 | 限制规则 | 券扣减方式 | -|---|---|---|---|---| -| 直接点核销 | 用户在权益首页点击「去使用」 | `{ amount }`，不带 `couponId` | `0 < amount <= 用户全部 ACTIVE 权益总余额` | 按券创建时间 FIFO 扣减，可跨多张权益 | -| 指向单据核销 | 用户在某张权益/核销单点击「立即核销」 | `{ couponId, amount }` | `0 < amount <= 该单据当前可用金额` | 只扣减该单据 | - -### 3.2 后端不变量 - -- 核销码只存在 Redis，TTL = 5 分钟。 -- 生成核销码前必须校验金额，门店确认核销时必须二次校验。 -- 门店确认时使用券 `version` 乐观锁，避免并发重复扣减。 -- 核销成功后写入： - - `user_redeem_record` - - `common_event(BENEFIT_LEDGER, REDEEM)` - - `store_payout(PENDING)` -- 若核销码绑定门店，确认核销时只能由该门店使用；若未绑定门店，任意 `OPEN` 门店可确认。 -- 已关闭或暂停门店不可核销。 - -### 3.3 前端提示 - -- 直接核销：显示「最高可核销 = 当前好客权益总余额」。 -- 单据核销：显示「最高可核销 = 当前单据可用金额」。 -- 不再展示「单次最高可核销 ¥500.00」。 - ---- - -## 4. V3 完整业务闭环 - -### 4.1 C 端购酒与权益 - -1. 用户打开 H5，完成手机号/微信登录。 -2. 选择城市，首页展示已开城商品。 -3. 进入商品详情，选择数量与收货地址。 -4. 订单预览校验同城 2 瓶、跨城 6 瓶。 -5. 创建订单，状态 `PENDING_PAY`。 -6. 发起支付，Mock 环境同步成功，生产环境走微信 JSAPI。 -7. 支付成功回调幂等更新订单为 `PENDING_SHIP`。 -8. 根据商品 `benefitAmount ?? price` 发放好客权益。 -9. 用户在权益页直接核销或指定单据核销。 -10. 门店确认核销后，用户可评价，权益余额与流水更新。 - -### 4.2 门店核销与打款 - -1. 门店账号登录。 -2. 首页扫码或输入核销码。 -3. 后端校验核销码、门店状态、权益余额、单据金额。 -4. 核销成功生成记录。 -5. 系统创建 `store_payout(PENDING)`，预计 T+1 打款。 -6. 系统按门店绑定关系计算并记录对应合伙人的核销收益，用于合伙人账单与经营统计。 -7. WebAdmin 财务确认或 Job 自动推进打款状态。 -8. 门店端可查看核销记录与打款状态。 -9. 绑定合伙人端可查看辖区门店对应的核销订单、核销金额、门店打款状态与合伙人收益。 - -### 4.3 合伙人拓店与履约 - -1. 合伙人登录工作台。 -2. 录入门店资料、门头/环境图、合同资料、银行卡信息。 -3. V3 由 WebAdmin 审核门店，审核通过后门店才可对 C 端可见并参与核销。 -4. 合伙人查看辖区订单。 -5. 配送 Mock 或真实配送推进订单。 -6. 异常时发起/处理补发、改址拦截、配送异常。 -7. 合伙人查看月度账单、佣金、经营周报。 - -### 4.4 WebAdmin 运营 - -1. 管理员登录。 -2. 配置开城、商品、合伙人、门店分类。 -3. 审核门店。 -4. 查看订单与配送。 -5. 处理退款、补发、客服工单。 -6. 管理权益、核销、资源、账号。 -7. 财务确认门店 T+1 和合伙人 T+30 结算。 -8. 查看运营报表、异常预警、第三方日志。 - ---- - -## 5. V3 验收用例清单 - -### 必过主链路 - -1. C 端手机号登录成功。 -2. 首页展示郑州 4 个上架商品。 -3. 同城 1 瓶下单失败，2 瓶成功。 -4. 跨城 5 瓶下单失败，6 瓶成功。 -5. 支付成功后订单进入待发货，并发放权益。 -6. 直接核销不带 `couponId`，金额可达到总余额。 -7. 单据核销带 `couponId`，金额不能超过该单据余额。 -8. 门店扫码确认核销成功。 -9. 核销后生成 `store_payout(PENDING)`。 -10. 门店关闭后不可核销，C 端不可见关闭门店。 -11. 合伙人录店后进入审核流，审核通过后 C 端可见。 -12. 配送自动或真实回调推进到完成。 -13. 退款工单通过后订单/权益/第三方日志一致。 -14. 门店 T+1 打款状态可确认。 -15. 合伙人 T+30 账单可生成并确认。 - -### 必过后台链路 - -1. WebAdmin 登录成功。 -2. 创建/编辑/上下架商品。 -3. 审核门店。 -4. 查询订单与配送单。 -5. 查询权益券、核销记录、打款记录。 -6. 处理退款/补发/异常工单。 -7. 查看第三方日志与运营报表。 -8. 导出或核对财务数据。 - ---- - -## 6. 当前已知技术债 - -| 优先级 | 技术债 | 处理要求 | -|---|---|---| -| P0 | 旧文档与规则仍有 ¥500 上限描述 | V3 以后以本手册为准；后续批量清理 V2/preV1 中过时描述 | -| P0 | `lint` 多数为 `echo ok` | 交付验收前必须接入有效检查 | -| P0 | smoke 覆盖不足 | 按 4.x 业务闭环补齐主流程冒烟 | -| P1 | shared-types DTO 不全 | 按接口稳定度分批上提 | -| P1 | 跨模块直写 Prisma 表 | 逐步改为 exported Service | -| P1 | 真实短信、配送、退款未闭环 | 按 4.1、4.3、4.4 对应业务闭环完成 | -| P2 | `admin-web` 与 V2 HQ 小程序形态不一致 | V3 先以 WebAdmin 交付，是否迁小程序另立版本 | - ---- - -## 7. 版本冻结规则 - -- V3 业务规则以本文件为准。 -- V2 手册仍作为完整蓝图参考，但与 V3 冲突时，V3 优先。 -- preV1 手册只作为 Mock 联调历史参考，不再作为交付验收标准。 -- 未写入本文件的新增需求，不进入 V3 交付范围；如必须加入，先更新本手册与任务表负责人。 +> **已合并**。内容与 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 重复，请以 **v3 编码手册** 为准。本文件保留作历史链接占位。 diff --git a/杜康好客-v3-PRD.md b/杜康好客-v3-PRD.md index 0f22e37..4fcd3c1 100644 --- a/杜康好客-v3-PRD.md +++ b/杜康好客-v3-PRD.md @@ -1,571 +1,147 @@ -# 杜康好客 · V3.0 产品需求文档（PRD） +# 杜康好客 · V3.0 PRD -> **版本**：v3.0（源自产品 PRD v1.3，2026-07-10） -> **作者**：吕丹（产品）· 工程对齐：jacy-dukang -> **状态**：本期交付事实源（与 V2 蓝图冲突时 **V3.0 优先**） -> **关联**：[`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md)（实现与验收口径）· [`AGENTS.md`](./AGENTS.md)（AI 入口） +> **v3.0**（2026-07-10）· 产品事实源 · 冲突时 **V3 > V2** +> 实现：[`v3编码手册`](./杜康好客-v3编码手册.md) · 审计：[`v3-现状对照`](./杜康好客-v3-现状对照.md) ---- +## 0. 说明 -## 0. 文档说明 +| 项 | 内容 | +|----|------| +| 四端 | C 小程序 · 门店/合伙人 H5 · 总部 **WebAdmin**（工程口径，非 H5） | +| 试点 | 郑州 · 同城小飞侠 · 跨城总部物流到付 | +| 工程差异 | C 端现 `mini-user`/h5-user；核销 TTL **3min**；订单 Tab **三态** | -| 字段 | 内容 | -|------|------| -| 项目名称 | 杜康好客 — 四端系统 | -| 覆盖端 | 用户端（**微信小程序**）、门店端（H5）、城市合伙人端（H5）、总部端（H5） | -| 试点城市 | 郑州 | -| 配送 | 同城小飞侠；跨城总部物流到付 | -| 主销场景 | 品鉴会 + 小程序 | +### 版本变更索引 -### 0.1 与仓库现状的差异（实现迁移注记） - -| PRD v3.0 目标 | 当前 preV1/V3 代码现状 | 处理 | -|---------------|------------------------|------| -| C 端微信小程序 | `apps/h5-user`（H5） | V3.0 以小程序为交付形态；H5 可作联调过渡 | -| 总部 H5 | `apps/admin-web`（WebAdmin） | V3.0 功能对齐总部 H5 职责；形态可暂用 admin-web | -| 核销码 TTL 3 分钟 | 编码手册写 5 分钟 | **以本 PRD 3 分钟为准** | -| 订单 Tab 三态 | preV1 五 Tab | **以本 PRD 待付款/已付款/已完成为准** | - -### 0.2 变更：3.4.10 门店套餐 - -| 版本 | 日期 | 说明 | -|------|------|------| -| **3.4.10** | 2026-08-03 | 新增 §3.9 门店套餐；REQ-P-027 / REQ-S-021 / REQ-H-025 / REQ-U-027；开发设计见 [`杜康好客-门店套餐功能开发文档-v3.4.10.md`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) | - -### 0.3 变更：3.4.11 开发计划 - -| 版本 | 日期 | 说明 | -|------|------|------| -| **3.4.11** | 2026-08-04 | 新增 §3.10 开发计划、§3.11 企微机器人角色与权限重构；REQ-H-026 ~ REQ-H-028；开发设计见 [`杜康好客-开发计划功能开发文档-v3.4.11.md`](./杜康好客-开发计划功能开发文档-v3.4.11.md) | - -### 0.4 变更：3.4.12 工单迭代 - -| 版本 | 日期 | 说明 | -|------|------|------| -| **3.4.12** | 2026-08-04 | 售后退款回滚、mini-user 门店详情、酒厂 T+3、门店多笔提现、开发计划批量编辑/审批企微派发、技术支持编辑/附件/批量改状态、套餐 imageUrl；开发设计见 [`杜康好客-v3.4.12-工单迭代开发文档.md`](./杜康好客-v3.4.12-工单迭代开发文档.md) | - -### 0.5 变更：3.4.13 体验优化 - -| 版本 | 日期 | 说明 | -|------|------|------| -| **3.4.13** | 2026-08-05 | 推广码归因统计 + **指标事件日志/高峰趋势**、核销用户信息 + **权益券详情加宽/核销详情增强**、技术支持工单优先级、mini-user **我的页版本号/低于 min 强制退出**、门店/商品/提货/**物流增强（签收照/拨号/ETA/路由回调签收→已完成）**、H5 登录校验、合伙人微信暂停禁登、**OSS 图片超 10MB 客户端压缩**；开发设计见 [`杜康好客-v3.4.13-体验优化开发文档.md`](./杜康好客-v3.4.13-体验优化开发文档.md) | +| 版 | 日期 | 要点 | 开发文档 | +|----|------|------|----------| +| 3.4.10 | 08-03 | 门店套餐 | [`门店套餐`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) | +| 3.4.11 | 08-04 | 开发计划 + 企微机器人/消息推送 | [`开发计划`](./杜康好客-开发计划功能开发文档-v3.4.11.md) | +| 3.4.12 | 08-04 | 退款回滚/财务/批量任务·工单/套餐 imageUrl | [`v3.4.12`](./杜康好客-v3.4.12-工单迭代开发文档.md) | +| 3.4.13 | 08-05 | metrics/核销详情/版本联动 PUBLISHED/mini 体验/H5 OAuth | [`v3.4.13`](./杜康好客-v3.4.13-体验优化开发文档.md) | --- ## 1. 背景与目标 -### 1.1 商业模型 +**模型**：总部供酒 → 合伙人拓店 → 门店核销 1:1 好客权益（酒+餐）。 -总部供酒 → 城市合伙人分销拓店 → 门店核销好客权益 → C 端买酒送 **1:1 等价好客权益**，覆盖「酒 + 餐」。 +| 锚点 | 值 | +|------|-----| +| 酒水成本 | ~售价 3 折 | +| 门店结算 | 核销额 × **60%** | +| 合伙人佣金池 | 订单+核销 ≤ 订单额 **5%**（默认 **0%+3%**） | +| 权益 | 实付 **1:1**，永久；口径 `benefit_amount ?? price` | -**成本与分润锚点**： +**G1~G5**：四端闭环 · 购酒履约 · 权益核销结算 · 合伙人拓店对账 · 售后/发票/代下单/推广/评价。 -- 酒水成本约售价 **3 折** -- 门店结算 = 核销金额 × **60%** -- 单合伙人佣金池：订单佣金比例 + 核销佣金比例 ≤ 订单金额 **5%**（默认 **0% + 3%**） -- 权益：支付成功赠送订单实付金额 **1:1**，永久有效 - -### 1.2 本期目标 G1–G5 - -| ID | 目标 | -|----|------| -| G1 | 四端上线并可独立闭环运营 | -| G2 | 购酒履约（同城/跨城/现场提货）跑通 | -| G3 | 好客权益发放 → 门店核销 → 门店 6 折结算 + 手动提现跑通 | -| G4 | 合伙人拓店审核、多合伙人管辖、佣金配置、独立对账打款 | -| G5 | 售后工单、发票、代下单、问卷、门店评价、推广码归因本期交付 | - -### 1.3 成功标准 - -**核心（门禁）** - -| ID | 标准 | 波次 | -|----|------|------| -| S1 | 用户可下单（含支付与权益发放） | Wave 1（7.10） | -| S2 | 门店可核销 | Wave 1（7.10） | -| S3 | 城市合伙人可添加门店 | Wave 1（7.10） | -| S4 | 门店佣金（结算款）可手动提现 | Wave 2（7.15） | - -**链路验收** - -| ID | 标准 | -|----|------| -| S5 | 郑州用户：浏览→下单支付→履约/提货→权益到账→门店核销 | -| S6 | 跨城推总部物流；现场提货提交即完成 | -| S7 | 门店 T+1 按核销额 6 折出账；各合伙人按配置比例独立对账 | -| S8 | 工单四类型总部可审；发票可申请可回传 | -| S9 | 推广码归因合伙人；订单佣金按履约规则解析（跨城归总部） | +**门禁 S1~S4**：下单+权益(W1) · 核销(W1) · 拓店(W1) · 门店提现(W2)。 --- ## 2. 角色与场景 -### 2.1 角色 +| 角色 | 端 | 诉求 | +|------|-----|------| +| C 用户 | 小程序 | 买酒、权益、核销、售后 | +| 门店/店员 | H5 | 核销、营业、提现(W2) | +| 合伙人 | H5 | 拓店、订单、账单 | +| 总部 | WebAdmin | 审核、结算、运营 | -| 角色 | 端 | 核心诉求 | -|------|-----|----------| -| C 端用户 | 小程序 | 买酒、收权益、门店核销、售后/发票 | -| 门店主账号 | H5 | 核销、子账号管理、营业状态、结算提现 | -| 门店店员子账号 | H5 | 仅核销 + 本店记录（Wave 2） | -| 合伙人管理员 | H5 | 子账号、管辖范围经营数据、代下单等 | -| 合伙人推广员 | H5 | 仅门店入驻 + 看自己提交的店 | -| 总部运营/客服/财务 | H5 | 商品、审核、工单、发票、结算打款、报表 | +**SC-01~09**：同城购酒 · 现场提货 · 跨城 · 核销 · 拓店 · 售后 · 代下单 · 问卷评价 · 推广归因（见 PRD 原文路径摘要）。 -### 2.2 主场景 SC-01 ~ SC-09 - -| ID | 场景 | 路径摘要 | -|----|------|----------| -| SC-01 | 同城购酒 | 浏览→≥2瓶→微信支付→小飞侠→确认/24h自动→权益→核销 | -| SC-02 | 现场提货 | 隐藏入口→支付→直接已完成→权益 | -| SC-03 | 跨城购酒 | 未开通城市→≥1箱→总部物流到付→权益；订单佣金归总部 | -| SC-04 | 门店核销 | 出码/报手机号→核销→权益扣减→门店账本×60% | -| SC-05 | 拓店入驻 | 合伙人录入→负责人复核→总部审核→试核销100元→营业 | -| SC-06 | 售后工单 | 用户四类型→总部审→仓/合伙人协同→补发/退款 | -| SC-07 | 代下单 | 总部/合伙人手机号建用户下单；在线支付（商家收款码 / 合伙人微信代付）后发权益；配送进入待发货由总部履约，现场提货走自提闭环；订单记代下单人 | -| SC-08 | 问卷+评价 | 成交后问卷；核销后门店评价 | -| SC-09 | 推广归因 | 推广码进小程序→绑定合伙人→统计成交/佣金 | - -### 2.3 权限摘要 - -- 合伙人数据**平级隔离**（全城/区域不可互查） -- 推广员：仅门店入驻 + 看自己提交的店（须在管辖范围内） -- 门店主账号：子账号、核销、提现、营业状态；店员：仅核销+本店记录 -- 总部：审核、管辖与佣金配置、打款、全数据 -- 手机号脱敏：门店/合伙人中间 4 位加密；总部仅管理员看全号 +**权限**：合伙人平级隔离；推广员仅拓店+看自己店；手机号脱敏（门店/合伙人中间4位）。 --- -## 3. 业务闭环与核心规则 +## 3. 核心规则 -### 3.1 五条主闭环 +### 3.1 五条闭环 -| 闭环 | 触发 | 关键节点 | 终点 | -|------|------|----------|------| -| 购酒履约 | 用户下单 | 同城小飞侠/跨城总部物流/现场提货 | 已完成 + 权益 1:1 | -| 权益核销 | 用户出码/报号 | 门店确认 | 权益扣减 + 门店账本×60% + 核销佣金释放 | -| 拓店入驻 | 合伙人录入 | 总部审核 + 试核销 | 营业中 C 端可见 | -| 售后工单 | 用户发起 | 总部审 + 协同 | 补发/退款或驳回 | -| 结算提现 | 核销入账 | T+1 出账 + 未出账可提 | 总部审后打款 | +购酒履约 · 权益核销(60%+核销佣金) · 拓店入驻 · 售后工单 · 结算提现(T+1 出账+未出账可提)。 -### 3.2 订单状态机 +### 3.2 订单 -``` -待付款 ──支付成功──► 已付款 ──履约完成/确认收货/24h自动──► 已完成 - └─ 30 分钟未付取消 -``` - -- **同城**：仓配履约——有仓且绑 API 承运商则自动推单（首期小飞侠）；有仓选自管则管仓方手工填单；**无仓**则总部传统快递填单 -- **大单拦截**：同城订单 **≥10 箱（箱规 6 瓶，即 ≥60 瓶）** 不自动推小飞侠；订单打标「大单待确认」，由总部确认后推小飞侠或自配送（填快递单） -- **跨城**：总部传统快递到付填单；订单佣金归总部 -- **现场提货**：支付后直接已完成；有现场推广码则订单佣金归码所属合伙人，无码归总部 +`待付款 → 已付款 → 已完成`；30min 未付取消。同城自动推小飞侠（有仓+API）；**≥10箱(60瓶)** 大单待 HQ 确认。跨城总部物流到付。现场提货支付即完成。 ### 3.3 佣金与结算 -| 类型 | 比例 | 归属 | 释放时机 | -|------|------|------|----------| -| 订单佣金 | 按合伙人配置（默认 0%） | §3.3.1 解析 | 支付成功落快照 | -| 核销佣金 | 按合伙人配置（默认 3%） | 核销门店归属合伙人 | 按核销金额占比释放 | -| 门店结算 | 核销额×60% | 该门店 | T+1 出账；未出账可提现 | - -**约束**：单合伙人订单+核销佣金 ≤ 5%；比例变更仅对新单/新核销生效；账单展示快照。 - -#### 3.3.1 多合伙人管辖（v1.2） - -| 类型 | 管辖范围 | 限制 | -|------|----------|------| -| 全城合伙人 | 该城未被区域占用的区县 | 每城最多 1 名 | -| 区域合伙人 | 总部勾选的区县 | 每城多名；同一区县不可重复 | - -**同城订单佣金解析**：收货区县→区域合伙人；未命中→全城合伙人；再无→总部。 - -**核销佣金**：归核销门店归属合伙人（拓店绑定，总部可调整；变更后仅影响新核销）。 - -**推广码**：归因统计；除现场提货「有码归码」外，不决定同城/跨城订单佣金。 - -#### 3.3.2 门店结算与提现 - -| 规则 | 结论 | -|------|------| -| 结算金额 | 核销金额 × 60% | -| T+1 出账 | 自然日统计，次日形成账期；法定节假日顺延 | -| 手动提现 | 未出账金额可提现（不必等出账日） | -| 打款 | 提现申请→总部审核→打款至入驻收款账户 | -| 结算异议 | 核销后 3 个工作日内（附凭证） | - -**试点护栏 FIN-001~003**： - -| ID | 规则 | -|----|------| -| FIN-001 | 未出账提现仅总部白名单门店 | -| FIN-002 | 单店单日上限默认 ¥5,000（可配置） | -| FIN-003 | 工作日提现 T+0 审完；超时看板预警 | - -各合伙人独立 **T+30** 月账单、独立确认、独立打款（无上下级二次分账）。 - -### 3.4 门店账号模型（Wave 2） - -- **一号多店**：同一手机号可作多家店主账号 -- **主账号唯一**：每店入驻第三步负责人手机号，每店仅一个主账号 -- **店员子账号**：主账号创建，仅归属单店 -- **多店登录**：多店时选店列表；7 天免登记住上次所选 - -### 3.5 门店入驻 SOP - -对齐《门店签约 SOP v3.0》S1–S12。 - -**三步录入**： - -1. 基础信息（门头展示名/执照全称、筛选：面积≥200㎡、客单价≥60、包房≥5 等） -2. 证照/合同/照片 + **附件一结构化规则** -3. 结算信息（法人收款或授权书+银行卡短信校验） - -**流程**：`暂存 → 待负责人复核 → 待总部审核 → 通过(待试核销) → 试核销100元 → 正式入驻 + 短信` - -合伙人创建门店时，手机号已关联其他店 → 提示确认后可继续。 - -### 3.6 工单四类型（§4.4） - -| 类型 | 总部决策 | 通过后 | -|------|----------|--------| -| 仅退款 | 同意/驳回 | 原路退款 | -| 破损补发 | 同意/驳回 | 负责仓配送+取回；通知管仓合伙人 | -| 破损退货 | 同意/驳回 | 负责仓取回→退款 | -| 退货退款 | 同意/驳回 | 通知归属合伙人+负责仓取回→退款 | - -### 3.7 城市多仓与仓配（Wave 3） - -- 一城多仓；每仓最多关联 1 名管仓合伙人 -- **仓配管理**（总部）：注册第三方履约接口（小飞侠、京东、顺丰等）；启用后仓库方可选择；**承运商需配置银行账户、结算方式（充值/挂账月结）、计价标准** -- **仓库设置**：履约方式 = API 自动推单（选已注册承运商）或 **自管**（手工填运单号 + 查询链接模板） -- 同城有仓订单支付后自动按仓配置推单；自管仓由管仓合伙人/总部代填单；**≥10 箱大单除外**（见 §3.2） -- 同城无仓 / 跨城：总部传统快递填单 -- 佣金与仓无关（订单佣金仍按 §3.3.1）；仓用于履约与工单协同 -- 未关联合伙人的仓 → 总部直派 - -#### 3.7.1 物流对账（总部财务） - -| 规则 | 结论 | -|------|------| -| 汇总维度 | 按快递/仓配承运商（`FulfillmentProvider`）独立月账单 | -| 计费口径 | 账期内已发货订单瓶数 × 承运商计价标准（账单落快照） | -| 小飞侠默认价 | **2 瓶 6 元**；每加 1 瓶 **+2 元**；**6 瓶一箱 14 元**（整箱按箱费，余瓶按起送阶梯） | -| 结算方式 | **前期充值扣款**（`PREPAID`）：总部向承运商账户充值，月账单自动/确认扣余额；**后期挂账月结**（`MONTHLY_CREDIT`）：生成应付账单后总部确认打款 | -| 银行账户 | 每承运商配置收款户名/开户行/支行/账号，打款对照 | -| 出账节奏 | 自然月；每月 1 日汇总上月；可手工按承运商/月生成 | -### 3.8 弱网核销兜底（Wave 3 · OPT-006） - -- Wave 1~2：网络异常明确提示+重试；总部预警+人工补核销 -- Wave 3：连续**网络类**失败 5 次→拍照兜底→上传→总部 T+0 补核销 -- 业务错误（码过期、余额不足等）不计入 5 次；幂等防重复扣款 - -### 3.9 门店套餐（引入于 **3.4.10**） - -> 实现设计见 [`杜康好客-门店套餐功能开发文档-v3.4.10.md`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) - -门店可向 C 端展示餐饮套餐信息（与酒水 SKU 无关），用于核销前用户了解可核销内容；**套餐变更审核与整店入驻审核独立**。 - -#### 3.9.1 套餐数据结构 - -| 字段 | 说明 | 示例 | +| 类型 | 默认 | 释放 | |------|------|------| -| 套餐名称 | 必填（单条内） | 套餐A | -| 价格 | 元 | 198 | -| 菜品 | 文本 | 红烧肉、红烧鱼、油焖茄子 | -| 使用时间 | 文本 | 节假日除外 | -| 其他说明 | 文本 | 不可叠加 | +| 订单佣金 | 配置(0%) | 支付快照 | +| 核销佣金 | 配置(3%) | 核销时按门店归属合伙人 | +| 门店结算 | 60% | T+1；未出账可提现 | -- 可不填；可多条；**同一门店最多 10 条** -- C 端仅展示**已审核通过（生效中）**的套餐，自上而下标题+内容形式 +**多合伙人**：全城/区域管辖；同城订单佣金按收货区县解析；核销佣金归拓店合伙人。 +**FIN-001~003**：白名单未出账提现 · 单店日限 ¥5000 · T+0 审完预警。 +合伙人 **T+30** 独立月账/打款。 -#### 3.9.2 维护与审核 +### 3.4~3.8 Wave 能力 -| 端 | 能力 | 审核 | -|----|------|------| -| 合伙人拓店 | 新建流程增加「套餐」页（可跳过） | 随门店或独立提审（见开发文档） | -| 合伙人门店详情 | 套餐列表 → 编辑 → **提交审核** | 是 | -| 门店端 | 套餐列表 → 编辑 → **提交审核** | 是 | -| 总部 | 门店详情新增「套餐」Tab | **直接保存生效，无需审核** | +- **3.4** 门店一号多店、主账号、店员子账号(W2) +- **3.5** 拓店三步 + SOP + 试核销100 +- **3.6** 工单四类型：仅退款/破损补发/破损退货/退货退款 +- **3.7** 多仓、承运商、物流月结对账（小飞侠：2瓶6元 +2/瓶，6瓶箱14元） +- **3.8** 弱网5次拍照兜底(W3) -- 合伙/门店提交后 → 总部收到套餐变更审核 → **通过/驳回** -- **通过**：自动替换该店生效套餐；**驳回**：保留上一版生效套餐 -- 提审中：C 端仍展示上一版已通过套餐（从未通过则不展示） +### 3.9~3.11 增量（详开发文档） -#### 3.9.3 客服异议 +| § | 主题 | 文档 | +|---|------|------| +| 3.9 | 门店套餐 ≤10 条、独立审核 | v3.4.10 | +| 3.10 | 开发计划/任务/版本/技术支持联动 | v3.4.11 | +| 3.11 | 企微智能机器人 + 消息推送 Webhook | v3.4.11 | -- 用户对核销过程中套餐内容有异议 → 可提交客服申诉 -- 工单/客服类型新增：**套餐异议**（`PACKAGE_DISPUTE`） +--- -### 3.10 开发计划（引入于 **3.4.11**） +## 4. REQ 索引 -> 实现设计见 [`杜康好客-开发计划功能开发文档-v3.4.11.md`](./杜康好客-开发计划功能开发文档-v3.4.11.md) +> 完整 REQ：`.cursor/skills/dukang-v3/reference-req-index.md` -总部 admin-web 新增一级菜单 **开发计划**，含版本列表、任务列表、开发设置；与 **技术支持** 工单审批联动（通过后创建开发任务）。 +| 端 | ID 范围 | 模块要点 | +|----|---------|----------| +| 用户 | U-001~027 | 四Tab/支付/权益3min/门店/套餐/工单/发票/推广/评价 | +| 门店 | S-001~021 | 核销双通道/记录×60%/提现/子账号/套餐提审 | +| 合伙人 | P-001~027 | 子账号/拓店+套餐/订单账单/代下单(W3) | +| 总部 | H-001~028 | 开城/审核/结算/推广/套餐/开发计划 | -| 子模块 | 要点 | -|--------|------| -| 版本 | CRUD；多选关联任务；状态流转自动写时间戳/用时 | -| 任务 | 全局任务池 CRUD；勾选 → **评审派发** → 任务派发助手 Webhook（@ 开发者 userid） | -| 设置 | 任务派发助手（单例）；本地审核 AI 助手 | -| 技术支持 | 单一「审批」入口；通过须 ≥1 开发任务；批量 AI 预审 → 人工确认 | +**SKU 锚价**：128/168/298/498（瓶）· 768/1008/1788/2988（箱6瓶）。 -企微接入：开发计划任务派发、运营告警、技术支持工单通知均走 HQ「企微机器人 → 消息推送」（Webhook 多实例 + 条件勾选）；对话能力由「智能机器人」WebSocket SDK 承担。 +--- -### 3.11 企微机器人（引入于 **3.4.11**） +## 5. 非功能 NFR-001~010 -> HQ 菜单：**企微机器人** → 智能机器人 `/wecom/bots`、消息推送 `/wecom/pushes`、智能机器人日志 `/logs/wecom-bots` +7天免登 · 微信单支付 · 验证码3min · 脱敏鉴权 · 幂等 · 弱网/兜底 · 兼容 · 审计 · 24h履约 · 推广归因落库。 -#### 3.11.1 智能机器人（长连接） +--- -| 角色 | 默认能力 | -|------|----------| -| **客服助手** | 订单/配送/门店/核销/售后工单只读 + 创建售后工单 + 短信验证查用户 | -| **财务助手** | 门店/合伙人/酒厂/物流账单、打款、提现 **只读** | -| **运营助手** | 订单/门店/用户/核销/配送 **只读** | -| **技术支持** | 技术支持工单只读/创建；**审批**（通过/驳回）；开发计划只读 | -| **自定义** | HQ 手工勾选模块化权限 | +## 6. 数据与集成 -**权限模型**：按模块划分（如 `order.read`、`finance.store_bill.read`、`support_ticket.review`）；废弃 `api.read.all`、`db.read`。聊天回复仅 Markdown 业务摘要，禁止 JSON/tool 泄露。 +**实体**：用户/商品/订单(佣金快照)/权益/门店/套餐/核销/工单/结算/合伙人/推广/仓(W3)/待处理核销(W3)。 -**审批**：仅机器人配置的 **SuperAdmin 企微 userid 白名单** 可执行 `support_ticket.review`；「通过」须自动从工单标题创建 **1 条** 开发任务（类型映射同 HQ 审批）。 - -**审计**：每条查询/审批写入 `log_wecom_bot`，Admin 可筛选 bot、userid、action、时间。 - -#### 3.11.2 消息推送（Webhook 多实例，v3.4.11） - -| 字段 | 说明 | +| TECH | 系统 | |------|------| -| 名称 / 头像 | HQ 列表展示 | -| Webhook URL | 企微群机器人 Webhook（**运行时仅读 DB，不读 .env**） | -| 启用 | 列表开关 | -| @ userid | 可选，markdown `<@userid>` | -| 推送条件 | 多选 eventKey，可同时匹配多条推送 | +| 011~012 | 微信支付/短信 | +| 013 | 小飞侠 | +| 014~016 | 微信能力/分享/腾讯位置 | -**推送条件（eventKey）**： - -| key | 触发场景 | -|-----|----------| -| `alert.ops` | 售后工单、客户端错误等运营告警 | -| `support_ticket.created` | 新建技术支持工单（独立 Markdown，可与 alert.ops 并行） | -| `alert.pay` / `alert.redeem` | 支付/核销异常 | -| `alert.system` | 5xx、监控、回调 | -| `alert.settlement` | 结算 scheduler | -| `dev_plan.task_dispatch` | 开发任务评审派发 | - -**迁移**：首次空表时从 `.env` `WECOM_ALERT_WEBHOOK_URL` seed「运营告警」；原 `dev_plan_settings.task_dispatch_*` seed「开发任务派发」。废弃系统设置 `WECOM_ALERT_ENABLED` 与开发设置任务派发 Webhook UI。 +**金额**：权益=实付1:1 · 门店结算=核销×60% · 试核销=**100元** · 码TTL=**3min**。 --- -## 4. 功能需求（REQ 索引） +## 7~8. UI 与 ACC -> 完整 REQ 结论见 [`.cursor/skills/dukang-v3/reference-req-index.md`](./.cursor/skills/dukang-v3/reference-req-index.md) - -### 4.1 用户端（小程序）— REQ-U-001 ~ 027 - -| 模块 | 要点 | -|------|------| -| 导航账号 | 四 Tab；无感登录；确认下单提示绑定手机号（可选、不强制）；仅微信支付；7 天免登 | -| 商品下单 | 4 款酒祖杜康 SKU；同城≥2瓶免运费；跨城≥1箱；现场提货隐藏；锁单30分钟 | -| 权益核销 | 1:1 发放；出码 3 分钟；核销前规则弹窗（OPT-011）；附件一规则详情 | -| 门店 | 列表/详情/搜索/省市区筛选；仅营业中展示；立即核销 | -| **门店套餐（3.4.10）** | 门店详情展示生效套餐（标题+内容）；套餐异议申诉入口（REQ-U-027） | -| 增长售后 | 四类型工单 + **套餐异议**；发票四组合；成交问卷（无激励）；推广码；微信商品分享 | -| 评价 | 核销后门店评价 | - -**SKU 价格锚点** - -| 商品 | 瓶价 | 箱价(6瓶) | -|------|------|-----------| -| 酒祖杜康（国标特级10）53° | ¥128 | ¥768 | -| 酒祖杜康（国标特级15）53° | ¥168 | ¥1008 | -| 酒祖杜康（国标特级20）53° | ¥298 | ¥1788 | -| 酒祖杜康（国标特级30）53° | ¥498 | ¥2988 | - -### 4.2 门店端（H5）— REQ-S-001 ~ 021 - -| 模块 | 要点 | -|------|------| -| 登录 | 主账号/店员；多店选店（Wave 2）；7 天免登 | -| 核销 | 扫码大按钮 + 手机号通道；手机号、金额、验证码与确认核销同页完成，先按手机号和金额发送验证码，验证成功后直接核销；今日汇总；弱网处理 | -| 记录结算 | 筛今日/7日/1月/全部；到账金额×60%；T+1 出账 | -| 提现 | 未出账可提（FIN 护栏）；提现记录；结算异议 3 工作日 | -| 账号 | 主账号管理店员（Wave 2）；待处理核销单（Wave 3） | -| **门店套餐（3.4.10）** | 套餐列表/编辑；提交审核（REQ-S-021） | - -### 4.3 合伙人端（H5）— REQ-P-001 ~ 027 - -| 模块 | 要点 | -|------|------| -| 权限 | 管理员 vs 推广员菜单裁剪 | -| 拓店 | 三步录入 + **套餐页（3.4.10，可跳过）**；一号多店确认；负责人复核；试核销100元；附件一 | -| 经营 | 首页三卡；排行；订单/权益/工单；佣金快照下钻 | -| 财务 | 本合伙人月账对账（Wave 2/3） | -| 扩展 | 代下单（Wave 3）；管仓只读（Wave 3） | -| **门店套餐（3.4.10）** | 拓店套餐页；门店详情套餐列表/编辑/提审（REQ-P-027） | - -### 4.4 总部端（H5）— REQ-H-001 ~ 028 - -| 模块 | 要点 | -|------|------| -| 基础 | 商品管理；营销规则 1:1 权益；签约主体：山西领势酒业有限责任公司 | -| 城市合伙人 | 开通城市；创建合伙人（全城/区域+佣金）；仓库管理（Wave 3） | -| 审核交易 | 门店审核；**套餐变更审核（3.4.10）**；全量订单/权益/工单；发票 2 工作日；补核销 | -| 结算 | 门店+合伙人双 Tab；提现审；白名单配置；**物流对账**（按承运商月结） | -| 增长 | 推广码；问卷；评价；腾讯位置热力图 | -| **门店套餐（3.4.10）** | 门店详情「套餐」Tab 直存；套餐变更审核通过/驳回（REQ-H-025） | -| **开发计划（3.4.11）** | 版本/任务/设置；企微 Agent；任务评审派发；技术支持审批联动（REQ-H-026~028） | - -### 4.5 端职责矩阵 - -| 能力 | 用户端 | 门店端 | 合伙人端 | 总部端 | -|------|:------:|:------:|:--------:|:------:| -| 下单/支付/权益 | ● | | 代下单 | 代下单 | -| 核销 | 出码 | ● | 看记录 | 看全量 | -| 拓店 | 看门店 | 改营业 | ●录入 | ●审核 | -| 工单 | ●发起 | 查看 | 查看 | ●决策 | -| 结算提现 | | ● | 对账确认 | ●审打款 | -| 推广码/问卷/评价 | ● | 被评价 | 看数据 | 配置/看板 | -| **门店套餐（3.4.10）** | 看生效套餐 | 编辑提审 | 编辑提审 | ●直存/●审核 | +主色杜康红 `#8B1E1E` · 权益金 `#C4A35A` · 空态人话+下一步。 +ACC 全量：`.cursor/skills/dukang-v3/reference-acc.md` --- -## 5. 非功能需求 +## 9. 三波交付 -| ID | 类别 | 结论 | -|----|------|------| -| NFR-001 | 登录态 | 四端 7 天免登 | -| NFR-002 | 支付 | 仅微信支付；待付款锁单 30 分钟 | -| NFR-003 | 短信 | 登录/核销验证码 3 分钟；核销成功必发短信 | -| NFR-004 | 安全 | 按端/角色脱敏与鉴权 | -| NFR-005 | 幂等 | 支付回调、核销、提现、补核销 | -| NFR-006 | 可用性 | Wave 1~2 弱网重试；Wave 3 拍照兜底 | -| NFR-007 | 兼容 | 小程序两主版本；H5 微信内置浏览器 | -| NFR-008 | 审计 | 工单、审核、打款、分账配置留痕 | -| NFR-009 | 履约 | 同城目标 24h；送达未确认 24h 自动完成 | -| NFR-010 | 归因 | 推广码与佣金归属下单时落库 | +| 波 | 日期 | 门禁 | 含 | 不含 | +|----|------|------|-----|------| +| W1 | 7.10 | S1~S4 | 登录商品支付核销拓店子账号 | 提现推广现场跨城工单发票 | +| W2 | 7.15 | S1~S5 | 提现FIN推广现场门店子账号多合伙 | 代下单弱网多仓跨城发票问卷 | +| W3 | 7.22 | 全量 | 代下单弱网多仓跨城工单发票看板 | — | ---- - -## 6. 数据实体与外部依赖 - -### 6.1 核心实体（TECH-001 ~ 019） - -用户、商品、订单（含佣金快照）、好客权益账本、门店（主账号/店员）、**门店套餐（3.4.10）**、核销单、工单、结算/提现、合伙人（管辖+佣金）、推广码、仓库（W3）、待处理核销单（W3）、门店账号（W2）。 - -### 6.2 外部对接 - -| ID | 系统 | 用途 | -|----|------|------| -| TECH-011 | 微信支付 | 下单、原路退 | -| TECH-012 | 短信网关 | 登录/核销验证码、成功通知 | -| TECH-013 | 小飞侠 | 同城推单、状态、取送拍照 | -| TECH-014 | 微信能力 | 手机号、定位、客服、分享 | -| TECH-015 | 微信商品分享 | 分享归因 | -| TECH-016 | 腾讯位置服务 | 总部热力图 | - -### 6.3 金额落库口径 - -- 权益入账 = 订单实付 × 1:1 -- 订单佣金 = 订单金额 × 归属合伙人 order_commission_rate（支付成功快照） -- 核销佣金 = 按核销金额占比从 verify_commission_rate 池释放（核销时快照） -- 门店结算 = 核销金额 × 60% -- 物流费 = 按承运商计价标准对单票瓶数计价（小飞侠默认见 §3.7.1） -- 核销码 TTL = **3 分钟**；试核销固定 **100 元** - ---- - -## 7. UI 规范（§8 摘要） - -- **主色** 杜康红 `#8B1E1E`~`#A12828`；**权益金** `#C4A35A`；**价格** `#C62828` -- C 端：品牌优先、商品大图；B 端：核销效率 / 经营看板 / 中控后台 -- 四端统一「好客权益」图标与权益数字样式 -- 空态：一句人话 + 可执行下一步 - ---- - -## 8. 验收标准（ACC 索引） - -> 完整 ACC 见 [`.cursor/skills/dukang-v3/reference-acc.md`](./.cursor/skills/dukang-v3/reference-acc.md) - -| 类别 | 代表 ACC | -|------|----------| -| 交易 | ACC-001~004 下单/同城/现场/跨城 | -| 核销 | ACC-005、ACC-017 两通道+弱网 | -| 组织 | ACC-006~007 一号多店/拓店 | -| 资金 | ACC-008~009 提现/佣金 | -| 售后增长 | ACC-010~014 工单/发票/代下单/问卷/推广码 | -| 多合伙人 | ACC-P21~P28 管辖/快照/隔离 | -| 多仓弱网 | ACC-W01~W03、ACC-017a | - ---- - -## 9. 三波交付计划 - -| 波次 | 日期 | 门禁 | 包含 | 不含 | -|------|------|------|------|------| -| **Wave 1** | 7.10 | W1-S1~S4 | 登录、商品、同城支付、小飞侠、核销、拓店、试核销、合伙人子账号 | 提现、推广码、现场提货、跨城、工单、发票、门店子账号、多合伙人 | -| **Wave 2** | 7.15 | W2-S1~S5 | 未出账提现+FIN、打款、推广码、现场提货、门店子账号、多合伙人 | 代下单、弱网拍照、多仓、跨城、工单、发票、问卷、热力图 | -| **Wave 3** | 7.22 | 全量 | 代下单、弱网5次拍照、多仓、跨城、工单、发票、月账、问卷/评价/热力图 | — | - -### 9.1 阶段映射（DLV） - -| ID | 波次 | 内容 | -|----|------|------| -| DLV-W1-M1 | W1 | 四端登录、权限、UI Token、商品 | -| DLV-W1-M2 | W1 | 支付、锁单、同城小飞侠、权益 1:1 | -| DLV-W1-M3 | W1 | 出码/扫码/手机号核销、规则弹窗 | -| DLV-W1-M4 | W1 | 合伙人子账号、门店三步、审核、试核销 | -| DLV-W2-M1 | W2 | T+1、未出账提现、总部审打款 | -| DLV-W2-M2 | W2 | 现场提货、推广码 | -| DLV-W2-M3 | W2 | 多合伙人管辖/佣金 | -| DLV-W2-M4 | W2 | 门店子账号、多店选店 | -| DLV-W3-M1 | W3 | 代下单 | -| DLV-W3-M2 | W3 | 弱网拍照兜底 | -| DLV-W3-M3 | W3 | 多仓、跨城、工单、发票 | -| DLV-W3-M4 | W3 | 月账、问卷/评价/热力图 | -| DLV-W3-M5 | W3 | ACC 全量回归 | - -### 9.2 OPT 波次口径 - -| OPT | 波次 | 说明 | -|-----|------|------| -| OPT-002 代下单 | W3 | 合伙人主账号：选品/履约（配送须勾选自动收货或现场提货）→创建待支付订单→收款码或微信代付（合伙人 openId）→支付成功发权益；配送单 PENDING_SHIP 由总部发货，合伙人可看物流；现场提货支付后自提闭环；新用户 sourceType=PARTNER_PROXY；总部代下单同为在线收款码支付 | -| OPT-006 弱网 | W3 | W1~2 重试+人工补核销 | -| OPT-010 未出账提现 | W2 | 含 FIN-001~003 | -| OPT-005 现场提货 | W2 | — | -| OPT-001 发票 | W3 | — | -| OPT-004 问卷 | W3 | 无权益激励 | -| OPT-012 话术 | W3 | 上线后 3 日内对齐 | - ---- - -## 10. 风险（R1~R8） - -| ID | 风险 | 处置 | -|----|------|------| -| R1 | 小飞侠对接延期 | 并行联调；备选手动改状态 | -| R2 | 弱网重复扣款 | 幂等键 + OPT-006 | -| R3 | 三波排期 | 严格 W1→W2→W3；人工补核销/代下单 SOP | -| R4 | 发票 SLA | 看板预警 | -| R5 | 话术不同步 | OPT-012 3 日内更新 | -| R6 | 腾讯位置服务 | P2 不阻塞 L1 | -| R7 | 未出账提现资金 | FIN 护栏 | -| R8 | 多合伙人管辖冲突 | 区县互斥 + 快照 + 全覆盖校验 | - ---- - -## 11. 变更记录 - -| 版本 | 日期 | 说明 | -|------|------|------| -| **3.4.10** | 2026-08-03 | 新增 §3.9 门店套餐；REQ-P-027 / REQ-S-021 / REQ-H-025 / REQ-U-027；套餐异议工单类型 | -| v3.0.2 | 2026-08-02 | OPT-002/SC-07：代下单改为在线支付（收款码/合伙人微信代付）；去掉线下已收款直完成；配送单总部履约、合伙人可看物流 | -| v3.0.1 | 2026-07-27 | ACC-012/OPT-002/SC-07：明确合伙人代下单双短信、线下完成、来源 PARTNER_PROXY、C 端展示代下单人 | -| v3.0 | 2026-07-11 | 由产品 PRD v1.3 整理为工程 V3.0 事实源；配套 `@dukang-v3` skill 与 `v3-delivery-lead` agent | - ---- - -## 附录 A · 需求变更流程 - -1. 业务规则变更 → **先改本文件** → 同步 `杜康好客-v3编码手册.md` + `shared-types`/`domain` -2. 编码 Agent **不得**边写代码边改业务规则 -3. 跨模块改动 → 相关双 Owner Review；Prisma 迁移 jacy-dukang 主 Review（store/redeem 需刘景尧） +DLV 任务卡：`.cursor/skills/dukang-task-card/` diff --git a/杜康好客-v3-埋点规范.md b/杜康好客-v3-埋点规范.md index 7929a50..54ebd25 100644 --- a/杜康好客-v3-埋点规范.md +++ b/杜康好客-v3-埋点规范.md @@ -1,86 +1,38 @@ # 杜康好客 · V3 埋点规范 -> **版本**：2026-08-03 -> **存储**：C 端 → `log_user_analytics`；门店 → `log_store_analytics`；合伙人 → `log_partner_analytics` -> **契约**：[`packages/shared-types/src/*-log.ts`](../packages/shared-types/src/) -> **查询**：admin-web `/logs/users` · `/logs/stores` · `/logs/partners` +> 存储：C→`log_user_analytics` · 门店→`log_store_analytics` · 合伙人→`log_partner_analytics` +> 契约：`packages/shared-types/src/*-log.ts` · HQ：`/logs/users|stores|partners` ## 原则 -1. 端侧 **page_view / 点击** 走客户端 `track()`；业务结果（支付成功、核销确认）走后端 `AnalyticsService.track*Safe` -2. 所有客户端事件携带 `sessionId`（localStorage `dukang_session_id`），支持匿名漏斗 -3. `extraJson` 不含密码/令牌；手机号脱敏 -4. eventName 必须先登记在 shared-types taxonomy，再 emit +1. 端侧 page_view/点击 → `track()`；支付/核销结果 → 后端 `AnalyticsService.track*Safe` +2. 携带 `sessionId`（`dukang_session_id`） +3. `extraJson` 无密码/令牌；手机号脱敏 +4. eventName 先登记 taxonomy 再 emit ## API | 端 | 路由 | 鉴权 | |----|------|------| -| C 端 | `POST /api/v1/analytics/events` | OptionalJwt | -| 门店 | `POST /api/v1/analytics/store-events` | Jwt + STORE | -| 合伙人 | `POST /api/v1/analytics/partner-events` | Jwt + PARTNER | -| 推广 | `POST /api/v1/promo/touch` | OptionalJwt（双写 `promo_touch` 埋点） | +| C | `POST /analytics/events` | OptionalJwt | +| 门店 | `POST /analytics/store-events` | Jwt+STORE | +| 合伙人 | `POST /analytics/partner-events` | Jwt+PARTNER | +| 推广 | `POST /promo/touch` | OptionalJwt（双写 touch） | -## 完整 eventName 清单 +## eventName -见 shared-types： +完整清单 → `user-log.ts` / `store-log.ts` / `partner-log.ts` -- [`user-log.ts`](../packages/shared-types/src/user-log.ts) — C 端 13 个 category -- [`store-log.ts`](../packages/shared-types/src/store-log.ts) — 门店 8 个 category -- [`partner-log.ts`](../packages/shared-types/src/partner-log.ts) — 合伙人 9 个 category +## extraJson 要点 -## extraJson 字段约定 +| 端 | 常用字段 | +|----|----------| +| C | sessionId, cityCode, productId, storeId, orderId, amount, pagePath, failReason | +| 门店 | redeemChannel, amount, durationMs, failReason | +| 合伙人 | storeId, orderId, billId, cityCode | -### C 端（UserAnalyticsExtra） +## 漏斗（摘要） -| 字段 | 说明 | -|------|------| -| sessionId | 会话 ID，漏斗串联 | -| cityCode | 开城/地域 | -| productId / skuId | 商品偏好 | -| storeId | 门店偏好 | -| orderId | 订单归因 | -| amount / quantity | 客单价 | -| sourceType / sourceRefId | 获客渠道 | -| failReason | 失败原因 | -| pagePath | 页面路径 | - -### 门店（StoreAnalyticsExtra） - -| 字段 | 说明 | -|------|------| -| redeemChannel | scan / phone / pending | -| amount | 核销金额 | -| durationMs | 耗时 | -| failReason | 失败原因 | - -### 合伙人（PartnerAnalyticsExtra） - -| 字段 | 说明 | -|------|------| -| storeId / orderId / billId | 业务关联 | -| cityCode | 城市维度 | - -## 转化漏斗（C 端） - -``` -session_start → home_view → product_detail_view → order_confirm_view - → order_submit → pay_page_view → pay_success - → benefit_redeem_start → redeem_code_view → benefit_redeem_success -``` - -## 核销漏斗（门店） - -``` -store_home_view → store_redeem_scan_start → store_redeem_preview - → store_redeem_confirm | store_redeem_confirm_fail -``` - -## 合伙人经营漏斗 - -``` -partner_home_view → partner_store_create_view → partner_store_create - → partner_store_audit_approved -partner_order_list_view → partner_order_ship -partner_bills_view → partner_bill_detail_view → partner_bill_confirm -``` +- **C**：session→home→detail→confirm→submit→pay→redeem +- **门店**：home→scan→preview→confirm +- **合伙人**：home→store_create→audit / orders→ship / bills→confirm diff --git a/杜康好客-v3-城市仓库与日志架构.md b/杜康好客-v3-城市仓库与日志架构.md index 21e26d4..64b1b28 100644 --- a/杜康好客-v3-城市仓库与日志架构.md +++ b/杜康好客-v3-城市仓库与日志架构.md @@ -1,124 +1,37 @@ -# 杜康好客 · V3 城市 / 仓库 / 日志架构 +# 杜康好客 · 城市 / 仓库 / 日志架构 -> **版本**：2026-07-12 -> **状态**：P1 城市多合伙 + P2 仓库 **已实现**（2026-07-12）；合伙人端管仓日志仍待 Wave 3 -> **分工**：刘景尧任务暂由 `jacy-dukang` 代管（见 `AGENTS.md`） +> **2026-07-12** P1 多合伙 + P2 仓库 ✅ · 合伙人管仓日志 ⏳ Wave 3 ---- - -## 1. 目标数据模型（城市顶层） +## 数据模型（摘要） ``` -CommonCity (开城) - ├── PartnerAccount[] 1:N 主账号（isPrimary=1，含城市绑定 + 购酒/核销佣金） - ├── CityWarehouse[] 1:N 城市仓库（HQ 管 / 合伙人管） - └── CatalogProduct[] 按城市上架 - -PartnerAccount (主账号 = 城市合伙人主体) - ├── cityId / scopeType / districtCodes / bindingStatus - ├── orderCommissionRate / redeemCommissionRate - ├── companyName / 银行 / 合同等主体信息 - ├── managedWarehouseId? 可选管仓 - └── PartnerAccount[] 子账号（parentAccountId，permissions JSON） - -CityWarehouse - ├── cityId - ├── managerType: HQ | PARTNER - └── partnerAccountId? 合伙人管仓时绑定主账号 - -Store - ├── partnerAccountId FK → 主账号 - └── settlementRate 门店核销结算比例（默认 0.60） +CommonCity → PartnerAccount(主) → Store(partnerAccountId, settlementRate) + → CityWarehouse(HQ|PARTNER 管仓) + → CatalogProduct +PartnerAccount → 子账号(parentAccountId, permissions JSON) ``` -**迁移要点（2026-07）**：删除 `partner_partner`、`common_city_partner`、`common_city_commission_rule`；城市绑定与购酒分佣合并至 `partner_account` 主账号；门店结算比例下沉至 `store_store.settlementRate`；订单快照字段为 `partnerAccountIdAtPay` + `orderCommissionRateAtPay`。 +迁移：城市绑定/购酒分佣合并至 `partner_account`；订单快照 `partnerAccountIdAtPay` + `orderCommissionRateAtPay`。 ---- +## 日志职责 -## 2. 日志表与职责划分 +| 主体 | 表 | 入口 | +|------|-----|------| +| HQ 写操作 | `common_event` HQ_OPERATION | `@HqOperation` → `/logs/hq` | +| 合伙人 | `log_partner_analytics` | `/logs/partners` | +| 门店 | `log_store_analytics` | `/logs/stores` | +| C 端 | `log_user_analytics` | `/logs/users` | +| 权益/订单 | `common_event` BENEFIT_LEDGER / ORDER_STATUS | 领域查询 | -| 操作主体 | 日志表 | eventType / eventName | 查询入口 | -|----------|--------|----------------------|----------| -| **HQ WebAdmin** 写操作 | `common_event` | `HQ_OPERATION` + `param1=action` | admin-web `/logs/hq` | -| **合伙人端** 行为 | `log_partner_analytics` | `partner_*` eventName | admin-web `/logs/partner` | -| **门店端** 行为 | `log_store_analytics` | `store_*` | admin-web `/logs/store` | -| **C 端** 行为 | `log_user_analytics` | 埋点 eventName | admin-web `/logs/user` | -| 权益/订单状态机 | `common_event` | `BENEFIT_LEDGER` / `ORDER_STATUS` | 领域查询 | +## HQ action（新业务） -**原则**：HQ 侧 **CRUD / 审核 / 结算确认** 一律 `@HqOperation` → `common_event`；端侧 **登录 / 业务操作** 走对应 `log_*_analytics`。 +`CITY_*` · `WAREHOUSE_*` · `PARTNER_*` · `PARTNER_ACCOUNT_*` · `HQ_ACCOUNT_*` · `HQ_PERMISSION_*` +常量：`hq-operation.constants.ts` · 筛选项：`apps/admin-web/src/lib/hq-log.ts` ---- +## 合伙人子账号 eventName -## 3. CRUD → 日志映射（新业务） +`partner_staff_create|update|permission_update|delete` ✅ · `partner_warehouse_*` ⏳ -### 3.1 HQ 侧（`common_event.HQ_OPERATION`） +## DoD -| 实体 | refType | action 常量 | 装饰器状态 | -|------|---------|-------------|------------| -| 开城城市 | `CITY` | `CITY_CREATE` / `CITY_UPDATE` | ✅ 已接入 | -| 开城城市 | `CITY` | `CITY_DELETE` | ⏳ 待 API | -| 城市仓库 | `WAREHOUSE` | `WAREHOUSE_CREATE` / `UPDATE` / `DELETE` | ✅ 已接入 | -| 城市合伙人（主账号） | `PARTNER` | `PARTNER_CREATE` / `PARTNER_UPDATE` | ✅ 已接入 | -| 合伙人账号（HQ） | `PARTNER_ACCOUNT` | `PARTNER_ACCOUNT_CREATE` / `UPDATE` / `DELETE` | ✅ 已接入 | -| HQ 管理员 | `HQ_ACCOUNT` | `HQ_ACCOUNT_CREATE` / `UPDATE` | ✅ 已接入 | -| HQ 权限 | `HQ_PERMISSION` | `HQ_PERMISSION_UPDATE` | ✅ 已接入 | - -实现约定： - -- Controller 方法加 `@HqOperation({ action, refType, refIdField|refIdParam, includeBody })` -- `extraJson` 自动写入 `requestBody`（脱敏 password）+ `response` 摘要 -- 常量定义：`server/.../hq-operation.constants.ts`；admin 筛选项：`apps/admin-web/src/lib/hq-log.ts` - -### 3.2 合伙人端子账号（`log_partner_analytics`） - -| 操作 | eventName | refType | 状态 | -|------|-----------|---------|------| -| 主账号新增子账号 | `partner_staff_create` | `PARTNER_ACCOUNT` | ✅ `PartnerStaffService` | -| 编辑子账号 | `partner_staff_update` | `PARTNER_ACCOUNT` | ✅ | -| 仅改角色/权限 | `partner_staff_permission_update` | `PARTNER_ACCOUNT` | ✅ | -| 删除子账号 | `partner_staff_delete` | `PARTNER_ACCOUNT` | ✅ | -| 仓库查看/维护（合伙人管仓） | `partner_warehouse_view` / `partner_warehouse_update` | `WAREHOUSE` | ⏳ Wave 3 | - -分类：`packages/shared-types/src/partner-log.ts` → `account_ops` / `warehouse_ops`。 - -### 3.3 门店子账号 - -| 操作 | 日志表 | action / eventName | 状态 | -|------|--------|-------------------|------| -| HQ 创建/编辑门店账号 | `common_event` | `STORE_ACCOUNT_CREATE` / `UPDATE` | ✅ | -| 门店端自助（若有） | `log_store_analytics` | 待定义 `store_staff_*` | ⏳ | - ---- - -## 4. 实现检查清单（DoD） - -每条 CRUD 合并前确认： - -- [ ] HQ 写接口有 `@HqOperation`，且 `HqOperationAction` + `hq-log.ts` 标签已同步 -- [ ] 合伙人端写接口调用 `AnalyticsService.trackPartnerOneSafe`，eventName 已登记在 `partner-log.ts` -- [ ] `extraJson` 不含明文密码/令牌；手机号脱敏 -- [ ] admin-web 日志页可按 action / category 筛选到新事件 -- [ ] 跨模块不直写他人日志表（经 Analytics / HqOperationLogService） - ---- - -## 5. 分阶段交付 - -| 阶段 | 内容 | 依赖 | -|------|------|------| -| **P0 日志补全** | 子账号 CRUD 落 `log_partner_analytics`；扩展 HQ action 常量 | 无 | -| **P1 城市架构** | `city_partner` 表、迁移 `partner_id`、HQ CRUD + `@HqOperation` | ✅ 2026-07-12 | -| **P2 仓库** | `city_warehouse` 表、HQ CRUD + 合伙人管仓校验 | ✅ 2026-07-12 | -| **P3 权限 JSON** | `PartnerAccount.permissions` 替代纯 `staffRole`；权限变更双写 HQ/合伙人日志 | P1 | - ---- - -## 6. 相关文件 - -| 路径 | 说明 | -|------|------| -| `server/dukang-api/src/common/hq-operation/` | HQ 审计装饰器 + 拦截器 | -| `server/dukang-api/src/modules/iam/partner-staff.service.ts` | 合伙人子账号 + 日志 | -| `packages/shared-types/src/partner-log.ts` | 合伙人日志分类 | -| `apps/admin-web/src/pages/HqLogsPage.tsx` | HQ 操作日志 | -| `apps/admin-web/src/pages/PartnerLogsPage.tsx` | 合伙人日志 | +HQ 写接口有 `@HqOperation`；合伙人写走 `trackPartnerOneSafe`；extraJson 脱敏；不跨模块直写他人日志表。 diff --git a/杜康好客-v3-现状对照.md b/杜康好客-v3-现状对照.md index 64029c7..fe61800 100644 --- a/杜康好客-v3-现状对照.md +++ b/杜康好客-v3-现状对照.md @@ -1,359 +1,66 @@ -# 杜康好客 · V3.0 现状对照表 +# 杜康好客 · V3.0 现状对照 -> **对照基准**：仅 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)（V3.0 产品事实源） -> **审计日期**：2026-07-11 -> **说明**：V2 / preV1 手册**不再作为需求依据**；本表只回答「相对 V3.0 PRD，当前代码处于什么状态」。 -> **工程口径**：总部端 **保持 `apps/admin-web`（WebAdmin）**，不改为 H5；PRD 中「总部 H5」按 **REQ-H 功能在 admin-web 实现** 验收。 -> **图例**：✅ 已完成 · 🔶 部分完成 · ⚠️ 与 V3.0 冲突（需改造） · ❌ 未实现 +> 基准：仅 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · 总部 = **`admin-web`**（非 H5） +> 图例：✅ 完成 · 🔶 部分 · ❌ 未做 · ⚠️ 曾冲突已修 ---- - -## 0. 总览 +## 0. 总览（2026-08-06） | 维度 | 结论 | |------|------| -| **整体完成度（粗估）** | Wave 1 约 **45%**；Wave 2 约 **10%**；Wave 3 约 **5%** | -| **可跑通的主链路** | 登录 → 浏览商品 → 同城下单 Mock/微信支付 → 权益 1:1 → **扫码核销** → T+1 门店 payout 记录 → 总部确认打款 | -| **最大阻塞** | C 端小程序迁移（暂缓）、Wave 1 缺口（手机号核销/规则弹窗/试核销/自动推小飞侠） | -| **P0 冲突** | C2~C7、C14 **已修复**（2026-07-12） | -| **冒烟覆盖** | `scripts/smoke-v3.mjs` 仅覆盖窄 W1 切片，**不等于** V3.0 ACC 全量 | +| 主链路 | 登录→下单支付→权益→扫码核销→payout→HQ 打款 **可跑通** | +| C 端 | `mini-user` 小程序 + h5-user；v3.4.13 版本门控/门店/物流已上 | +| 近期版本 | v3.4.10 套餐 · v3.4.11 开发计划/企微 · v3.4.12 工单迭代 · v3.4.13 体验优化 **已发生产** | +| 冒烟 | `scripts/smoke-v3.mjs` 窄路径 ≠ 全量 ACC | +| REQ 明细 | PRD §4 + `.cursor/skills/dukang-v3/reference-req-index.md` | -### Wave 门禁状态 +## 1. P0 冲突（2026-07-12 ✅） -| 门禁 | 状态 | 一句话 | -|------|------|--------| -| **W1-S1** 下单+支付+权益 | 🔶 | TTL/Tab/SKU/佣金已对齐；仍缺小程序形态 | -| **W1-S2** 门店核销双通道 | 🔶 | 扫码 ✅；手机号核销 ❌ | -| **W1-S3** 合伙人子账号 | ✅ | CRUD + 推广员菜单裁剪已有 | -| **W1-S4** 拓店→审核→C 端可见 | 🔶 | 三步录入有；试核销100/负责人复核/SOP 缺失 | -| **W2-S1~S5** | ❌ | 提现/FIN/现场提货/多合伙人/门店子账号 基本未做 | -| **W3-S1~S4** | ❌ | 代下单/弱网拍照/多仓/跨城履约/四类型工单/发票/问卷/热力图 基本未做 | +| # | 项 | 状态 | +|---|-----|------| +| C2~C3 | 核销/短信 TTL **3min** | ✅ | +| C4~C5 | 订单 Tab/列表 **三态** | ✅ | +| C6~C7 | 4 SKU + 佣金 **0%+3%** | ✅ | +| C13 | 多合伙人主账号模型 | ✅ | +| C14 | 文档旧口径清理 | ✅ | +| C1 | C 端小程序 | 🔶 mini-user 进行中 | +| C8~C12 | 一号多店/自动推单/提现/四类型工单/现场提货 | 🔶~❌ 见 PRD Wave | ---- +## 2. 按域快照 -## 0.1 已确认的工程口径（非冲突） +| 域 | ✅ 已有 | 🔶/❌ 主要缺口 | +|----|---------|----------------| +| **mini-user** | 购酒/权益/核销/门店/物流/版本门控 | 规则弹窗、发票、四类型工单、问卷 | +| **h5-shop** | 扫码核销、记录、营业、iOS 扫码 OAuth | 手机号核销、提现、子账号、弱网兜底 | +| **h5-partner** | 子账号、拓店、订单/账单、套餐 | 试核销100、负责人复核、代下单 | +| **admin-web** | 商品/开城/门店/订单/权益/核销/结算/推广码 metrics/开发计划/技术支持 | 完整 SOP 审核 UI、发票、热力图 | +| **后端** | 主模块、支付、权益、核销、payout、Courier 适配 | 30min 取消 job、部分 Wave3 | -| 项 | PRD 原文 | V3 工程决策 | -|----|----------|-------------| -| 总部端形态 | 总部 H5 | **`apps/admin-web`（WebAdmin）为唯一交付端，不改为 H5** | -| 验收方式 | REQ-H-* | 功能在 admin-web 实现即可；不要求微信内 H5 或小程序总部端 | -| `mini-hq` | — | 非主交付；与 admin-web 重叠能力以 **admin-web 补齐** 为准 | +## 3. 场景 SC-01~09 ---- - -## 1. ⚠️ 冲突项与改造计划 - -> 代码已存在但与 V3.0 PRD 直接矛盾。**P0 已于 2026-07-12 执行**；P1/P2 排后续迭代。 - -### 1.1 改造计划总览 - -| 阶段 | 冲突项 | 内容 | 状态 | -|------|--------|------|------| -| **P0** | C2~C7、C14 | TTL、订单三 Tab、SKU seed、佣金默认、文档规则 | ✅ **已执行** | -| **P1** | C1 | C 端 H5 过渡；目标微信小程序另立项 | 📋 已决策暂缓 | -| **P1** | C9 | 支付后自动推小飞侠 | 📋 待做（Wave 1） | -| **P2** | C8 | 一号多店（schema + 拓店确认） | 📋 待做（Wave 2） | -| **P2** | C10 | 门店主动提现 + FIN 护栏 | 📋 待做（Wave 2） | -| **P2** | C12 | 现场提货 `ON_SITE_PICKUP` | 📋 待做（Wave 2） | -| **P3** | C11 | 工单四类型 | 📋 待做（Wave 3） | -| **P3** | C13 | 多合伙人管辖/佣金快照 | 📋 待做（Wave 2~3） | - -### 1.2 冲突明细 - -| # | V3.0 要求 | 改造前 | 状态 | 改造记录（2026-07-12） | -|---|-----------|--------|------|------------------------| -| C1 | C 端微信小程序 | `h5-user` H5 | 📋 暂缓 | 工程决策：H5 过渡，小程序另立项 | -| C2 | 核销码 TTL **3 分钟** | 300s | ✅ 已修复 | `REDEEM_TOKEN_TTL_SECONDS=180`；C 端文案 | -| C3 | 短信验证码 **3 分钟** | 300s | ✅ 已修复 | `SMS_CODE_TTL_SECONDS=180` | -| C4 | 订单 Tab 三态 | 5 Tab | ✅ 已修复 | `pending_pay` / `paid` / `completed` | -| C5 | 列表展示三态 | 9 态直出 | ✅ 已修复 | 内部状态保留；Tab/列表映射三态 | -| C6 | 4 款酒祖杜康 + 锚点价 | preV1 SKU | ✅ 已修复 | `seed-v31.ts` 四 SKU ¥128~498 | -| C7 | 佣金 0%+3% | seed 5% 订单 | ✅ 已修复 | seed + `admin-cities` + settlement 默认 | -| C8 | 一号多店 | phone @unique | 📋 P2 | 待 schema + `partnerCheckStorePhone` | -| C9 | 支付后推小飞侠 | MANUAL delivery | 📋 P1 | 待 `trade.service` 支付回调 | -| C10 | 门店主动提现 | 自动 StorePayout | 📋 P2 | 待提现申请流 | -| C11 | 工单四类型 | 3 enum | 📋 P3 | 待扩展 `TicketType` | -| C12 | 现场提货 | 无 DeliveryType | 📋 P2 | 待 `ON_SITE_PICKUP` | -| C13 | 多合伙人 | 单 partnerId | ✅ 已修复 | 主账号 `partner_account` 合并城市绑定；`partner_partner`/`city_partner` 已删 | -| C14 | 文档残留旧口径 | 5min/5 Tab | ✅ 已修复 | `apps/AGENTS.md`、rules、agents、skills | - -### 1.3 P0 已改文件清单 - -| 模块 | 文件 | +| 场景 | 状态 | |------|------| -| 契约 | `packages/shared-types/src/enums.ts` | -| 规则 | `packages/domain/src/index.ts`、`index.test.ts` | -| 短信 | `server/.../sms/sms-code.store.ts` | -| 佣金 | `seed-v31.ts`、`admin-cities.service.ts`、`settlement.service.ts` | -| C 端 | `OrderListPage.tsx`、`MinePage.tsx`、`PayPage.tsx`、`RedeemPage.tsx`、`RedeemCodePage.tsx` | -| 文档 | `apps/AGENTS.md`、`.cursor/rules/*`、`.cursor/agents/owner-d-shop-redeem.md` | +| SC-01 同城 | 🔶 支付权益✅；自动推单/24h 完成 部分 | +| SC-02 现场提货 | 🔶 | +| SC-03 跨城 | 🔶 | +| SC-04 核销 | 🔶 扫码✅；手机号通道❌ | +| SC-05 拓店 | 🔶 三步✅；试核销/SOP 部分 | +| SC-06 售后 | 🔶 REFUND 有；四类型 部分 | +| SC-07~09 | 代下单❌ · 问卷🔶 · 推广🔶 | -> **重跑 seed**：本地需 `cd server/dukang-api && pnpm prisma:seed` 后商品/佣金数据才与 C6/C7 一致。 +## 4. 版本交付索引 ---- - -## 2. ✅ 已完成（与 V3.0 对齐或基本对齐） - -### 2.1 用户端 `apps/h5-user` - -| REQ | 功能 | 证据 | 备注 | -|-----|------|------|------| -| REQ-U-001 | 四 Tab 导航 | `src/layouts/TabLayout.tsx` | 形态为 H5 非小程序 | -| REQ-U-002 | 登录 + 下单提示手机号（可选） | `OrderConfirmPage` / `order-confirm`、微信登录签发会话 | ✅ | -| REQ-U-003 | 微信支付 | `pay-wechat.ts` + 后端 callback | Mock/真实均有 | -| REQ-U-004 | 定位/开城 | `HomePage.tsx`、`wechat-location.ts` | 🔶 H5 定位 API | -| REQ-U-005~006 | 商品列表/详情 | `HomePage.tsx`、`ProductDetailPage.tsx` | ✅ seed 已对齐酒祖杜康 | -| REQ-U-007 | 同城 ≥2 瓶 | `packages/domain` + `trade.service.ts` | ✅ | -| REQ-U-010 | 锁单写入 30min | `trade.service.ts` `payExpireAt` | 🔶 无自动取消 job | -| REQ-U-011 | 权益 1:1 | `benefit.service.ts` | ✅ | -| REQ-U-012 | 客服入口 | `CustomerServicePage.tsx` | 🔶 Mock 对话 | -| REQ-U-013~014 | 门店列表/详情 | `StoreListPage.tsx` 等 | ✅ 仅 OPEN | -| REQ-U-015 | 出码核销 | `RedeemPage.tsx` | ✅ TTL 3 分钟 | -| REQ-U-017 | 核销后评价 | `RedeemSuccessPage.tsx` | ✅ | -| REQ-U-018 | 权益页 Tab | `BenefitPage.tsx` | ✅ | -| REQ-U-019 | 个人中心 | `MinePage.tsx` | ✅ | -| REQ-U-024~025 | 推广码/分享（部分） | `lib/promo.ts`、`WechatShareBootstrap.tsx` | 🔶 Wave 2 完整归因 | - -### 2.2 门店端 `apps/h5-shop` - -| REQ | 功能 | 证据 | -|-----|------|------| -| REQ-S-001 | 三/四 Tab 导航 | `App.tsx` | -| REQ-S-002 | 登录 + 7 天 session | `lib/api.ts` | -| REQ-S-004 | 扫码核销 | `HomePage.tsx` + JSSDK | -| REQ-S-007 | 今日汇总 | `HomePage.tsx` dashboard | -| REQ-S-009 | 核销记录 + ×60% | `RecordsPage.tsx` | -| REQ-S-010~011 | 营业状态/门店信息 | `StatusPage.tsx`、`MinePage.tsx` | - -### 2.3 合伙人端 `apps/h5-partner` - -| REQ | 功能 | 证据 | -|-----|------|------| -| REQ-P-001 | 导航 | `PartnerAppRoutes.tsx` | -| REQ-P-002 | 7 天免登 | `auth.service.ts` refresh 7d | -| REQ-P-003 | 推广员菜单裁剪 | `partnerAccess.ts`、`SubAccountLayout` | -| REQ-P-005 | 合伙人子账号 | `StaffListPage.tsx`、`partner-staff.service.ts` | -| REQ-P-009 | 拓店三步（简化版） | `StoreCreatePage.tsx`、`storeDraft.ts` | -| REQ-P-013~017 | 首页/排行/订单 | `HomePage.tsx`、`OrderListPage.tsx` 等 | -| REQ-P-020 | 合伙人账单列表 | `SettlementPage.tsx` + settlement API | - -### 2.4 总部端 `apps/admin-web`（WebAdmin） - -> **交付口径**：总部 = WebAdmin，**不改为 H5**。REQ-H 功能在本端验收；`mini-hq` 仅作参考或非阻塞补充。 - -| REQ | 功能 | 证据 | 备注 | -|-----|------|------|------| -| REQ-H-001 | 登录 | `admin-web/LoginPage.tsx` | ✅ | -| REQ-H-002 | 商品 CRUD | `ProductsPage.tsx` | ✅ | -| REQ-H-004 | 开城 | `CitiesPage.tsx` | ✅ | -| REQ-H-005~006 | 门店管理/状态 | `StoresPage.tsx` | 🔶 非完整 SOP 审核 UI | -| REQ-H-008 | 全量订单 | `OrdersPage.tsx` | ✅ | -| REQ-H-009 | 权益 | `BenefitCouponsPage.tsx` | ✅ | -| REQ-H-010 | 工单（部分） | `TicketsPage.tsx` | 🔶 仅 REFUND/RESHIPMENT | -| REQ-H-013~014 | 门店结算打款 | `StoreBillsPage.tsx` | 🔶 非 PRD 提现流 | -| REQ-H-015 | 合伙人账单 | `PartnerBillsPage.tsx` | ✅ | -| REQ-H-017 | 推广码 | `mini-hq/pages/promo/`（参考） | ❌ **admin-web 缺页**，需在 WebAdmin 补齐 | - -### 2.5 后端与集成 - -| 项 | 证据 | 备注 | -|----|------|------| -| 模块骨架 iam/trade/benefit/catalog/store/redeem/settlement/ops/analytics | `server/dukang-api/src/modules/` | ✅ | -| 核销 → 自动创建 StorePayout（×60%） | `redeem.service.ts`、`settlement.service.ts` | ⚠️ 模式见 C11 | -| Prisma v3.1 schema（28+ 模型） | `prisma/schema.prisma` | ⚠️ 缺多合伙人/仓库/提现等 | -| domain 起购/权益规则 | `packages/domain/src/index.ts` | ✅ | -| 微信支付 mock + 真实 | `integrations/pay/`、`callbacks/wechat-pay` | ✅ | -| 短信 mock + 阿里云 | `integrations/sms/` | ⚠️ TTL 见 C4 | -| 小飞侠集成层 | `integrations/courier/xiaofeixia/` | 🔶 未支付后自动推单 | -| 腾讯逆地理 | `integrations/map/tencent-lbs` | 🔶 无热力图 | -| JWT 7 天 | `iam.module.ts` | ✅ | - ---- - -## 3. ❌ 未实现 / 重大缺口 - -### 3.1 Wave 1 缺口（7.10 门禁相关） - -| REQ / 能力 | 说明 | -|------------|------| -| **REQ-S-005 OPT-007** 手机号核销通道 | 门店端仅扫码；无「查余额→用户收验证码→门店输入」全流程 | -| **REQ-U-016 OPT-011** 核销规则弹窗 | 出码前无附件一/规则弹窗 | -| **REQ-P-011 OPT-009** 试核销 100 元 | 无「待试核销」状态与固定 100 元试核逻辑 | -| **REQ-P-024** 负责人复核 | 创建后直接 `PENDING` 或 auto-approve，无「待负责人复核」 | -| **REQ-P-023 / REQ-U-026** 附件一结构化 | 无菜品/酒水/服务费等可核销勾选 | -| **REQ-P-012 OPT-008** 入驻成功短信 | 未见正式入驻短信模板发送 | -| **支付后自动推小飞侠** | 见冲突 C10 | -| **待付款 30min 自动取消** | 仅写 `payExpireAt`，无 cancel job | -| **核销成功短信 NFR-003** | `redeem.service` 无 SMS 通知 | -| **NFR-009 送达 24h 自动完成** | Mock delivery 快速推进，非 24h 逻辑 | - -### 3.2 Wave 2 缺口（7.15） - -| REQ / 能力 | 说明 | -|------------|------| -| **REQ-U-008 OPT-005** 现场提货 | 无隐藏入口、无支付即完成 | -| **REQ-S-012~016 OPT-010** 未出账提现 + FIN-001~003 | 无提现申请、白名单、单日上限 | -| **REQ-H-014a** 提现白名单配置 | 无 | -| **REQ-S-017~019** 门店子账号 + 多店选店 | 无店员角色、无选店列表 | -| **REQ-P-008** 一号多店确认弹窗 | 当前直接拒绝（见 C9） | -| **REQ-H-004a / REQ-H-007** 多合伙人管辖与佣金 | 主账号 `partner_account` + HQ 合伙人页；支付写 `partnerAccountIdAtPay` 快照 | 🔶 基础已做；ACC-P21~P28 全套验收待补 | -| **ACC-P21~P28** 多合伙人全套 | 主账号模型 + HQ UI + 域规则单测 | 🔶 部分完成 | -| **推广码完整归因（W2 门禁）** | 后端有部分 API；**admin-web 缺推广码管理页** | -| **合伙人 T+30 独立确认打款** | 有 bill generate；合伙人确认/打款流不完整 | - -### 3.3 Wave 3 缺口（7.22） - -| REQ / 能力 | 说明 | -|------------|------| -| **REQ-P-021 / REQ-H-012** 代下单 | 无 | -| **REQ-S-008a / REQ-S-020 / REQ-H-020a** 弱网 5 次拍照兜底 | 无待处理核销单模型与 UI | -| **REQ-H-004b / REQ-P-026** 一城多仓 + 管仓合伙人 | `city_warehouse` + admin 仓库 Tab 已做；工单协同待 Wave 3 | -| **REQ-U-009 + SC-03** 跨城完整履约 | 后端有 `CROSS_CITY` 检测；总部物流 UX/佣金归总部未闭环 | -| **REQ-U-021 OPT-001** 发票 | 无模块 | -| **REQ-U-022** 四类型工单用户端 | 仅 refund-request | -| **REQ-U-023 OPT-004** 成交问卷 | 无 | -| **REQ-H-016 / REQ-H-023** 热力图 | 无看板 | -| **REQ-H-018~019** 问卷/评价总部看板 | 评价有 DB；总部看板无 | -| **REQ-H-021 OPT-012** 话术对齐 | 无运营文档交付机制 | - -### 3.4 门店套餐（目标版本 **3.4.10**，未实现） - -> 需求：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) §3.9 · 开发设计：[`杜康好客-门店套餐功能开发文档-v3.4.10.md`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) - -| REQ / 能力 | 说明 | -|------------|------| -| **REQ-P-027** 合伙人拓店套餐页 + 门店套餐编辑提审 | 拓店仍三步；无套餐页；无 `StorePackage` 实体 | -| **REQ-S-021** 门店端套餐列表/编辑/提审 | 门店端仅营业状态；无资料编辑 API | -| **REQ-H-025** 总部套餐 Tab 直存 + 套餐变更审核 | 门店 Drawer 无套餐 Tab；无独立套餐审核流 | -| **REQ-U-027** C 端展示生效套餐 + 套餐异议 | 门店详情无套餐区块；工单无 `PACKAGE_DISPUTE` | -| **数据模型** | 无 `store_package` / `store_package_change_request` 表 | - ---- - -## 4. 按端汇总矩阵 - -| 端 | ✅ 已完成 | ⚠️ 冲突 | ❌ 未实现 | 粗估完成率 | -|----|----------|---------|----------|------------| -| **用户端** | 登录、商品、下单、权益、扫码、门店、评价 | 端形态、Tab、TTL、SKU | 现场提货、规则弹窗、发票、四类型工单、问卷 | ~50% | -| **门店端** | 扫码核销、记录、营业状态 | 结算模式 | 手机号核销、提现、子账号、多店、弱网兜底 | ~35% | -| **合伙人端** | 子账号、拓店三步、订单/账单 | 一号多店、佣金模型 | 试核销、负责人复核、附件一、代下单、管仓 | ~40% | -| **总部端（WebAdmin）** | 商品、开城、订单、部分工单/结算 | 佣金默认 | 多合伙人、提现审、发票、热力图、推广码页、补核销审 | ~35% | -| **后端** | 主模块、支付、权益、扫码核销、payout | TTL、状态机、佣金、账号模型 | 自动取消、自动推单、提现、多仓、快照 | ~40% | -| **集成** | 微信/短信/xiaofeixia 骨架 | 验证码 TTL | 支付后自动推单、热力图、核销短信 | ~35% | - ---- - -## 5. 场景闭环 SC-01 ~ SC-09 - -| 场景 | 状态 | 说明 | +| 版本 | 文档 | 状态 | |------|------|------| -| SC-01 同城购酒 | 🔶 | 下单支付权益 ✅；小飞侠自动推单 ❌；24h 自动完成 ❌ | -| SC-02 现场提货 | ❌ | 全链路未做 | -| SC-03 跨城购酒 | 🔶 | 起购校验有；总部物流到付履约 ❌ | -| SC-04 门店核销 | 🔶 | 扫码 ✅；手机号 ❌；短信通知 ❌ | -| SC-05 拓店入驻 | 🔶 | 三步录入 ✅；复核/试核销100/SOP ❌ | -| SC-06 售后工单 | 🔶 | 总部处理 REFUND 有；四类型 ❌ | -| SC-07 代下单 | ❌ | Wave 3 | -| SC-08 问卷+评价 | 🔶 | 评价 ✅；问卷 ❌ | -| SC-09 推广归因 | 🔶 | touch API 有；现场提货归码 ❌ | +| 3.4.10 | [`门店套餐`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) | ✅ | +| 3.4.11 | [`开发计划`](./杜康好客-开发计划功能开发文档-v3.4.11.md) | ✅ | +| 3.4.12 | [`工单迭代`](./杜康好客-v3.4.12-工单迭代开发文档.md) | ✅ | +| 3.4.13 | [`体验优化`](./杜康好客-v3.4.13-体验优化开发文档.md) | ✅ 生产 `0181af0` | ---- - -## 6. 建议改造顺序（仅 V3.0 视角） - -### P0 — 消除冲突 ✅ 已完成（2026-07-12） - -C2~C7、C14 见 §1.3。 - -### P1 — 补齐 Wave 1 门禁（3~5 天） - -1. REQ-S-005 手机号核销全链路 -2. REQ-U-016 核销规则弹窗 -3. REQ-P-011 试核销 100 + REQ-P-024 负责人复核 -4. C9 支付后自动推小飞侠 -5. 待付款 30min 自动取消 job -6. 核销成功短信 - -### P2 — Wave 2（按 PRD 7.15） - -提现+FIN、现场提货、推广码闭环、多合伙人 schema、门店子账号/多店 - -### P3 — Wave 3（按 PRD 7.22） - -代下单、弱网拍照、多仓、跨城履约、四类型工单、发票、问卷、热力图 - -### 平台决策（需产品确认） - -- **C1**：`h5-user` 过渡 vs 立即建 `mini-user` -- **总部端**：已确认保持 **WebAdmin**，不改为 H5 - ---- - -## 7. 审计方法 - -- 需求源：仅 `杜康好客-v3-PRD.md` + `@dukang-v3` reference -- 代码：`apps/*`、`server/dukang-api/src/modules/*`、`packages/*`、`prisma/schema.prisma`、`seed-v31.ts` -- 验证脚本：`scripts/smoke-v3.mjs`（窄路径） -- **未使用** V2 / preV1 手册作为需求对照 - ---- - -## 8. v3.4.11 开发计划（2026-08-04） - -| 项 | 状态 | 说明 | -|----|------|------| -| Prisma 六表 + shared-types | ✅ | `dev_plan_*` | -| DevPlanModule API | ✅ | `/admin/dev-plan/*` | -| 技术支持 review + 批量 AI | ✅ | `SupportTicketReviewAiService` | -| admin-web 三页面 + 菜单 | ✅ | `/dev-plan/versions|tasks|settings` | -| 企微机器人角色/权限重构 | ✅ | 四类角色、模块化权限、`log_wecom_bot`、Capability 门面 | -| 企微菜单重组 | ✅ | 智能机器人 `/wecom/bots`、消息推送 `/wecom/pushes`、日志 | -| 消息推送多实例 | ✅ | `wecom_message_push`、eventKey 分发、迁移 env/旧派发配置 | -| 文档 | ✅ | PRD §3.10 + §3.11 + 开发文档 v3.4.11 | - ---- - -## 9. v3.4.12 工单迭代（2026-08-04） - -| 项 | 状态 | 说明 | -|----|------|------| -| P0 售后退款回滚 | ✅ | `initiateRefund` 微信失败恢复 PAID | -| mini-user 门店详情 | ✅ | 门头轮播 preview + 环境图双列 | -| 酒厂 T+3 | ✅ | `WINERY_SETTLEMENT_LAG_DAYS=3` | -| 门店多笔提现 | ✅ | 移除单 pending 限制 | -| 审批企微派发 | ✅ | review `dispatchToWecom` | -| 开发任务批量编辑 | ✅ | `POST /admin/dev-plan/tasks/batch-update` | -| 技术支持编辑/附件 | ✅ | `PATCH /admin/support-tickets/:id` + `attachmentUrls` | -| 技术支持批量改状态 | ✅ | domain 状态机 + batch API | -| 套餐 imageUrl | ✅ | 四端 + Prisma | -| 文档 | ✅ | PRD §0.4 + v3.4.12 开发文档 | - ---- - -## 10. v3.4.13 体验优化（2026-08-05） - -| 项 | 状态 | 说明 | -|----|------|------| -| 推广码 attributionCount | ✅ | HQ 详情统计卡 + **log_promo_event 事件日志 + metrics/timeline ECharts** | -| 核销用户信息 | ✅ | RedeemRecordsPage 列表+详情 | -| 技术支持优先级 | ✅ | Prisma + shared-types + HQ UI | -| 合伙人微信暂停禁登 | ✅ | loginPartnerWechat | -| H5 登录前端校验 | ✅ | partner/shop LoginPage | -| mini-user 门店体验 | ✅ | 电话脱敏/埋点、**列表两段营业时间**、门头 aspectFill 铺满、**套餐页签切换** | -| mini-user 商品/提货 | ✅ | 去分享、首图 preview、提货确认弹框 | -| mini-user 版本/物流 | ✅ | 摘要 + 签收照 + 拨号 + 时间线 + ETA；回调签收→**COMPLETED** | -| OSS 大图压缩 | ✅ | shared-ui compressImage；四端 upload + mini 头像 | -| 文档 | ✅ | PRD §0.5 + v3.4.13 开发文档 | - ---- - -## 11. 变更记录 +## 5. 变更记录 | 日期 | 说明 | |------|------| -| 2026-08-05 | v3.4.13 体验优化（20 条 ST） | -| 2026-08-04 | v3.4.12 工单迭代（退款/财务/C端/开发计划/技术支持/套餐） | -| 2026-08-04 | v3.4.11 开发计划 + 企微智能机器人/消息推送 + 角色权限重构 | -| 2026-07-12 | **P0 已执行**：C2~C7、C14 代码与文档对齐；§1 改为计划+状态表 | -| 2026-07-12 | 明确总部端保持 WebAdmin，不改为 H5 | -| 2026-07-11 | 首版：V3.0 PRD 全量对照当前 monorepo | +| 2026-08-06 | 文档压缩；现状对照更新 | +| 2026-08-05 | v3.4.13 | +| 2026-08-04 | v3.4.11 / v3.4.12 | +| 2026-07-11 | 首版对照表 | diff --git a/杜康好客-v3.4.12-工单迭代开发文档.md b/杜康好客-v3.4.12-工单迭代开发文档.md index 8bc1d35..69e9268 100644 --- a/杜康好客-v3.4.12-工单迭代开发文档.md +++ b/杜康好客-v3.4.12-工单迭代开发文档.md @@ -1,44 +1,20 @@ -# 杜康好客 · v3.4.12 工单迭代开发文档 +# 杜康好客 · v3.4.12 工单迭代 -> 版本：**v3.4.12** · 日期：2026-08-04 -> 需求源：ST 工单 + 开发计划/技术支持批量能力补充 +> **2026-08-04** · 已上线 · PRD §0.4 -## 1. 范围 - -| 模块 | 内容 | -|------|------| +| 域 | 交付 | +|----|------| | P0 售后 | `initiateRefund` 微信失败回滚订单状态 | -| mini-user | 门店详情门头 preview、环境图双列 | -| 财务 | 酒厂账单 T+3；门店可多笔 pending 提现 | -| 开发计划 | 审批创建任务可选企微派发；任务批量改状态/关联版本 | -| 技术支持 | 单条编辑/附件；批量改状态（状态机） | -| 套餐 | `StorePackage.imageUrl` 四端；HQ 删除至 0 条 UX | +| mini-user | 门头 preview、环境图双列 | +| 财务 | 酒厂 T+3；门店可多笔 pending 提现 | +| 开发计划 | 审批可选企微派发；`POST .../tasks/batch-update` | +| 技术支持 | PATCH 编辑/附件；`batch-update-status` | +| 套餐 | `StorePackage.imageUrl` 四端 | -**不在本版**：ST1785812832352437（门店列表，已完成） +## API -## 2. 后端 API +`POST /admin/dev-plan/tasks/batch-update` · `PATCH /admin/support-tickets/:id` · `POST .../batch-update-status` · review 扩展 `dispatchToWecom` -| 方法 | 路径 | 说明 | -|------|------|------| -| — | `trade.initiateRefund` | 失败时 `REFUNDING→原状态` + 事件 | -| — | `settlement.generateWineryBillForDay` | `wineryDayWindow(lag=3)` | -| — | `validateStoreWithdraw` | 移除 `hasPendingRequest` | -| POST | `/admin/dev-plan/tasks/batch-update` | `{ taskIds, status?, versionId? }` | -| POST | `/admin/support-tickets/:id/review` | 扩展 `dispatchToWecom`, `dispatchSupplement` | -| PATCH | `/admin/support-tickets/:id` | 待评审可编辑 | -| POST | `/admin/support-tickets/batch-update-status` | 批量改状态 | +## ACC -## 3. 数据表 - -- `common_support_ticket.attachment_urls` JSON -- `store_package.image_url` VARCHAR(512) - -## 4. 验收 - -- [ ] 售后 REFUND 审批后 Mock 退款成功 -- [ ] mini-user 门头点击大图、环境图双列 -- [ ] 酒厂账单滞后 3 天；门店第二笔提现可提交 -- [ ] 审批勾选企微后开发群收到任务 -- [ ] 任务多选批量改状态/关联版本 -- [ ] 技术支持待评审可编辑附件；批量 TESTING→PASSED -- [ ] 套餐 imageUrl 四端展示；HQ 可删至 0 条 +退款 Mock 成功 · 门头大图 · T+3/多笔提现 · 企微派发 · 批量改任务/工单状态 · 套餐 imageUrl diff --git a/杜康好客-v3.4.13-体验优化开发文档.md b/杜康好客-v3.4.13-体验优化开发文档.md index 6282e70..2d92edd 100644 --- a/杜康好客-v3.4.13-体验优化开发文档.md +++ b/杜康好客-v3.4.13-体验优化开发文档.md @@ -1,162 +1,58 @@ -# 杜康好客 · v3.4.13 体验优化开发文档 +# 杜康好客 · v3.4.13 体验优化 -> 版本：**v3.4.13** · 日期：2026-08-05 -> 需求源：20 条 ST 工单（体验优化 / Bug / 客户端验证） +> **2026-08-05** · 20 ST · 已发生产 `0181af0` · PRD §0.5 · 现状对照 §10 -## 1. 范围 +## ST 交付一览 -| 模块 | 内容 | +| ST | 交付要点 | +|----|----------| +| ST1785925037781309 | 推广码 attributionCount + `log_promo_event` + metrics/timeline/events + HQ ECharts | +| ST1785924286682833 | 门店电话 maskPhone + `store_phone_call` 埋点 | +| ST1785921693982470 | 工单 `priority` + HQ 筛选/编辑 | +| ST1785921585900725 | 门店 H5：OAuth 单例回调 + iOS JSSDK 预热/重试 + 授权后续扫 | +| ST1785907536648201 | 我的页 `v3.4.x`；`minClientVersion` 过低 → UpdateManager 或 `exitMiniProgram` | +| ST1785906800359657 | 合伙人暂停：发码前 `phone/check`，微信/SMS 均拒 | +| ST1785906592340255 / ST1785901711627824 | partner/shop LoginPage 空字段前端拦截 | +| ST1785906390321653 | 现场提货提交 `showModal` 确认 | +| ST1785905773501871 | 核销列表 userNo/nickname/phone；详情含门店/券分摊/结算/评价 | +| ST1785904849234806 | 工单中心（已有） | +| ST1785904076632841 | 门店列表「开城合伙人」= `partnerOptionLabel`（company/name/phone） | +| ST1785902173093977 / ST1785902141731113 | 商品去分享；首图 preview | +| ST1785901870913349 | 门店列表展示两段营业时间 | +| ST1785901838948572 | SHOP 未绑定门店（已有） | +| ST1785901775231811 | 门店套餐页签横滑切换 | +| ST1785901314893145 | 门头 aspectFill 铺满 + preview | +| ST1785939375449985 | 物流：签收照/拨号/时间线/ETA；小飞侠回调签收→`COMPLETED` | +| — | 图片 >10MB：`@dukang/shared-ui/compressImage`（各端 upload + mini 头像） | +| — | 权益券详情抽屉 980px；核销详情对齐权益券内抽屉 | +| — | 版本 `RELEASED` → 关联任务 `RELEASED`；关联工单 `PUBLISHED` + `releasedVersionNo` | + +## 契约摘要 + +**API** + +| 路径 | 说明 | |------|------| -| admin-web | 推广码 attributionCount + **指标事件日志/ECharts 趋势**；**权益券详情加宽**；**核销记录详情增强（对齐权益券内核销详情）**；技术支持工单优先级；**版本发布联动任务/工单已发布**；**大图上传前压缩** | -| mini-user | 门店电话脱敏+拨打埋点；**门店列表展示两段营业时间**；**门店详情门头 aspectFill 铺满无留白**；**门店套餐页签切换**；商品去分享+首图 preview；提货确认弹框；**我的页版本号 v3.4.x**；**低于 minClientVersion 强制更新/点我知道了退出**；**物流增强（签收照/拨号/时间线/ETA）**；**头像超 10MB 压缩** | -| h5-partner / h5-shop / h5-user | 登录 phone/code 前端校验；**门店端 iOS 首次扫码 OAuth 单例 + JSSDK 预热重试**；**OSS 图片超 10MB 自动 canvas 压缩后上传** | -| 后端 | 工单 priority；**工单 PUBLISHED + releasedVersionNo**；**版本 RELEASED 联动任务/工单**；client-config minClientVersion；合伙人微信暂停禁登；**Courier 适配器**；**log_promo_event 推广码指标日志** | +| `GET /common/client-config` | `minClientVersion` ← `MINI_USER_MIN_VERSION` | +| `GET /trade/orders/:id/track` | nodes、signPhotoUrls、estimatedArrival（Courier 100102/108/301） | +| `POST /callbacks/courier/xfx/track` | 小飞侠路由回调；生产 `api.dukanghaoke.com`，测试 `api-test.dukanghaoke.com` | +| `GET /admin/promo-codes/:id/metrics/{timeline,events}` | 推广码四指标时序 + 事件分页 | -## 2. ST 映射 +**表/枚举** -| ST | 标题 | 状态 | -|----|------|------| -| ST1785925037781309 | 总部端-推广码数据跟踪优化 | ✅ attributionCount + **事件日志 + ECharts 趋势** | -| ST1785924286682833 | 用户端-门店电话加密+拨打埋点 | ✅ maskPhone + store_phone_call | -| ST1785921693982470 | 技术支持-工单优先级 | ✅ priority 枚举 + HQ UI | -| ST1785921585900725 | 门店端扫一扫授权异常 | ✅ **OAuth 单例回调 + iOS JSSDK 预热/重试 + 授权后续扫** | -| ST1785907536648201 | 版本不对提示更新 | ✅ 我的页 v3.4.x + UpdateManager + **低于 min 强制更新/退出** | -| ST1785906800359657 | 合伙人暂停后禁登 | ✅ **发码前 phone/check + 微信/SMS 登录均拒 DISABLED** | -| ST1785906592340255 | PARTNER_H5 login 校验 | ✅ 前端空字段拦截 | -| ST1785906390321653 | 现场提货提交确认弹框 | ✅ showModal | -| ST1785905773501871 | 核销记录用户信息 | ✅ 列表+详情；**详情含门店/合伙人/券分摊/结算/评价** | -| ST1785904849234806 | 工单中心 | ✅ 已有 | -| ST1785904076632841 | 门店列表开城合伙人 | ✅ **列表展示 companyName/name/phone（同 partnerOptionLabel）** | -| ST1785902173093977 | 去掉商品详情分享按钮 | ✅ 移除 ShareNavButton | -| ST1785902141731113 | 商品首图大图 | ✅ previewable | -| ST1785901870913349 | 门店列表营业时间 | ✅ **列表展示两段营业时间** | -| ST1785901838948572 | SHOP 未绑定门店 | ✅ 已有 | -| ST1785901775231811 | 门店套餐遮挡 | ✅ **页签切换（可横滑）+ 紧凑内容区** | -| ST1785901711627824 | SHOP login 校验 | ✅ 前端空字段拦截 | -| ST1785901314893145 | 门头照裁剪 | ✅ aspectFill 铺满无留白 + preview | -| ST1785939375449985 | 订单物流追踪页 | ✅ 签收照 + 拨号 + 时间线 + ETA + 路由回调 | -| — | 上传图片超 10MB 先压缩 | ✅ `@dukang/shared-ui/compressImage` + 各端 upload | +- `log_promo_event`：SCAN / ATTRIBUTION / REGISTER / ORDER（含 IP/地点；仅统计上线后事件） +- `common_support_ticket`：`priority`；`status` 增 `PUBLISHED`；`released_version_no`、`published_at` +- 小飞侠回调：status **5** 或 statusName 含「签收」→ 订单 **COMPLETED**（幂等）；7 取消仅日志 -## 3. 后端 API / 配置 +**HQ 开发计划** -| 方法 | 路径 / 配置 | 说明 | -|------|-------------|------| -| GET | `/common/client-config` | `minClientVersion`（`MINI_USER_MIN_VERSION`）；客户端 semver 比对，低于则强制更新或退出 | -| — | `CommonSupportTicket.priority` | `LOW \| NORMAL \| HIGH \| URGENT`，默认 NORMAL | -| — | `CommonSupportTicket.status` | 新增 `PUBLISHED`（已发布）；`releasedVersionNo` + `publishedAt` | -| — | `DevPlanVersion` → `RELEASED` | 关联任务 → `RELEASED`；关联工单 → `PUBLISHED` 并写入版本号 | -| — | `loginPartnerWechat` | 非 ACTIVE 账号抛出「合伙人账号已停用」 | -| GET | `/trade/orders/:id/track` | 聚合：`nodes`（旧→新）、`signPhotoUrls`、`estimatedArrival`；经 `CourierService` 适配小飞侠 cmd 100102/100108/100301 | -| POST | `/callbacks/courier/xfx/track` | 小飞侠路由变化回调（适配器入口） | -| POST | `/callbacks/courier/logistics/track` | 跨城物流回调占位（记录日志，后续接入） | -| POST | `/callbacks/delivery/track` | 兼容旧路径，等同 `xfx` | -| GET | `/admin/promo-codes/:id/metrics/timeline` | 推广码四指标时间序列（按日/按时 + peak） | -| GET | `/admin/promo-codes/:id/metrics/events` | 推广码指标事件分页日志（时间/ID/IP/地点） | +创建版本 `v3.4.13` 并关联 ST 任务；标记 **已发布** 时自动联动任务/工单（见上表最后一行）。 -### 3.1 推广码指标日志（ST1785925037781309） +## 验收抽样 -**表** `log_promo_event` - -| event_type | 统计卡 | 写入时机 | ID | -|------------|--------|----------|-----| -| `SCAN` | 扫码进入数 | `POST /promo/touch` 且 `countScan !== false` | userId / sessionId | -| `ATTRIBUTION` | 归因用户数 | 首次写入 `user_promo_attribution` | userId | -| `REGISTER` | 扫码注册用户数 | `applyPromoSourceToUser` 成功 | userId | -| `ORDER` | 订单数 | 带推广码下单 `orderCount++` | orderId + userId | - -每条日志含 `created_at`、可选 ID、`client_ip`、`ip_province`/`ip_city`。仅统计**上线后**新事件；累计 Statistic 卡逻辑不变。 - -**HQ UI**：推广码详情页 → 数据趋势 Card（DatePicker + 按日/按时 + ECharts 四曲线 + 事件 Table） - -### 3.2 mini-user 版本门控（ST1785907536648201） - -| 项 | 行为 | -|----|------| -| 我的页 | 左下角展示 `杜康好客 v3.4.x`（与 `APP_VERSION` / package.json 同步） | -| 启动校验 | `GET /common/client-config` → `minClientVersion`；`APP_VERSION` 低于最低版本时拦截 | -| 微信有新包 | `UpdateManager` 弹「立即更新」→ `applyUpdate()` | -| 无新包 / 仍过低 | 弹「版本过低」→ 点「我知道了」→ `Taro.exitMiniProgram()` 退出小程序 | - -### 4. mini-user 物流（ST1785939375449985） - -| 页面 | 行为 | -|------|------| -| 订单详情 | **配送中**展示最新路由摘要 + 「物流详情」；物流未到时展示 **预估送达**（100301） | -| 物流详情 | 物流信息；**签收照片**（有则展示，`previewImage` 放大）；**物流动态**旧→新、节点全红点亮、最新在底部 | -| 电话拨号 | 物流文案中手机号可点击 `makePhoneCall` | -| 接口 | `GET /trade/orders/:id/track`（`OrderTrackDto`）；C 端禁止直连小飞侠 | -| 公共模块 | `order-logistics.ts` + `LogisticsRichText` 组件 | - -#### 4.1 对外回调 URL（提供给小飞侠） - -**生产** - -``` -POST https://api.dukanghaoke.com/api/v1/callbacks/courier/xfx/track -Content-Type: application/json -``` - -**测试** - -``` -POST https://api-test.dukanghaoke.com/api/v1/callbacks/courier/xfx/track -``` - -请求体： - -| 字段 | 说明 | -|------|------| -| outNumber | 商户单号 | -| number | 运单号 | -| status | 1下单 2取件 3中转 4派件 5签收 7取消 | -| statusName | 中文状态 | -| trackInfo | 路由描述 | -| createTime | 路由时间 | - -成功响应：`{"code":"100000","message":"success"}` - -#### 4.2 Courier 适配器（`integrations/courier`） - -| cmd | 能力 | Provider 方法 | -|-----|------|---------------| -| 100102 | 路由查询 | `getTrack` | -| 100108 | 签收照片 | `getSignPhotos` → OSS → `signPhotoUrls` | -| 100301 | 预估送达 | `checkDeliveryCoverage` → `estimatedArrival` | -| 回调 | 路由推送 | `parseTrackCallback` + `mapTrackStatus`（**status=5 / statusName 含「签收」→ 订单 `COMPLETED`**） | - -**路由回调状态映射（小飞侠）** - -| 小飞侠 status / statusName | 系统订单状态 | -|---------------------------|--------------| -| 1 下单 | `OUT_WAREHOUSE` | -| 2 取件 / 3 中转 | `SHIPPING` | -| 4 派件 | `SHIPPING` | -| **5 签收** / statusName **已签收** | **`COMPLETED`（已完成）** | -| 7 取消 | 仅记录日志，不改订单 | - -## 5. 数据表 - -- `common_support_ticket.priority` ENUM，默认 `NORMAL` -- `common_support_ticket.status` 新增 `PUBLISHED`；`released_version_no`、`published_at` -- `log_promo_event`：推广码指标事件（`promo_code_id`, `event_type`, `user_id`, `order_id`, `session_id`, `client_ip`, 地点, `created_at`） - -## 6. HQ 开发计划 - -在 admin-web **开发计划 → 版本列表** 创建 `v3.4.13`（状态 `IN_PROGRESS`），审批 ST 后关联 `dev_plan_task`。**版本标记为「已发布」后**，该版本下任务自动 `RELEASED`，关联技术支持工单自动 `PUBLISHED` 并写入 `releasedVersionNo`。 - -## 7. 验收 ACC - -- [ ] 推广码详情展示 attributionCount；**四指标事件日志 + ECharts 按日/按时趋势 + 高峰标注** -- [ ] 推广码 SCAN/ATTRIBUTION/REGISTER/ORDER 事件含 time + IP；幂等（重复 touch 不计 SCAN） -- [ ] 核销记录含 userNo/nickname/phone；**详情抽屉展示门店/地址/合伙人/权益券号/关联订单/券分摊/结算单/评价** -- [ ] **权益券详情抽屉加宽（980px），内嵌核销列表无横向滚动条** -- [ ] 技术支持可创建/筛选/编辑优先级；**版本 RELEASED 后关联工单为「已发布」并带版本号** -- [ ] **门店列表「开城合伙人」列展示 companyName / name / phone（与下拉选项一致）** -- [ ] 合伙人/门店登录空字段前端提示；**暂停合伙人发码前即拦截，短信/微信登录均禁止** -- [ ] mini-user：我的页左下角显示 `杜康好客 v3.4.x`；低于 `minClientVersion` 时强制更新，无新包则点「我知道了」退出小程序 -- [ ] mini-user：电话脱敏、拨打埋点、提货确认、无分享按钮、首图 preview、**门店列表两段营业时间**、**门店详情门头铺满无留白**、**门店套餐页签切换** -- [ ] mini-user：配送中物流摘要 + 签收照预览 + 电话拨号 + 时间线旧→新全点亮 + 预估送达 -- [ ] 小飞侠路由回调 `POST /callbacks/courier/xfx/track`：status=5 或 statusName 已签收 → 订单 **COMPLETED**；重复回调幂等 -- [ ] 各端上传 >10MB 图片自动压缩后可上传；仍超限有明确报错 -- [ ] **门店 H5（iPhone 微信）**：首次扫码 OAuth 后自动续扫；offline verifying 时提示再点一次扫码 -- [ ] `pnpm lint` 无新增错误 +- [ ] 推广码四指标趋势 + 事件日志；重复 touch 不计 SCAN +- [ ] 核销/权益券详情抽屉字段完整、980px 无横滚 +- [ ] 版本 RELEASED 后工单「已发布」带版本号；门店列表合伙人列非空 +- [ ] mini-user：版本门控、门店/商品/物流/压缩项 +- [ ] 门店 H5 iPhone 微信：OAuth 后续扫可用 +- [ ] 小飞侠回调 status=5 → 订单 COMPLETED diff --git a/杜康好客-v3编码手册.md b/杜康好客-v3编码手册.md index 27b9898..d744691 100644 --- a/杜康好客-v3编码手册.md +++ b/杜康好客-v3编码手册.md @@ -1,205 +1,57 @@ # 杜康好客 · V3 编码手册（交付业务版） -> **版本定位**：V3 实现与验收补充；**产品事实源**见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。 -> **现状审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)（已完成/冲突/缺口） -> **对照文件**：V2 / preV1 手册**不再作为需求依据**，仅作历史参考。 -> **数据库事实**：当前 Prisma schema 已是 v3.1，优先按 V3.0 PRD 补齐业务闭环。 +> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md) +> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。 ---- +## 1. 交付目标（六条） -## 1. V3 交付目标 +C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAdmin 运营 · 后端支付/配送/结算/审计 · 主链路冒烟+边界测试。 -V3 必须达到可业务验收状态： +## 2. 分工 -1. C 端用户能登录、选城、浏览商品、下单、支付、查看订单、获得权益、到店核销。 -2. 门店端能登录、扫码/输码核销、查看核销记录、管理营业状态，并形成待打款记录。 -3. 合伙人端能登录、录入门店、管理门店、查看辖区订单、处理配送/补发、查看账单与经营数据。 -4. WebAdmin 能完成开城、商品、门店审核、订单、权益、核销、配送、退款/补发、结算、资源和账号管理。 -5. 后端能完成真实支付回调、配送状态推进、退款/补发工单、门店 T+1、合伙人 T+30、日志与审计。 -6. 测试能覆盖主链路、关键边界和生产开关，不再只依赖一条 happy path 冒烟。 +| 负责人 | 范围 | +|--------|------| +| jacy-dukang | 全部 apps、packages、server 模块、Prisma（2026-07 起代管 B+D） | +| ~~刘景尧~~ | ~~h5-shop/partner、store/redeem~~（暂停） | ---- +**四端**：C=`mini-user`/h5-user · 门店=h5-shop · 合伙人=h5-partner · 总部=**admin-web**（`/admin/*`，`HQ_WEB`）。 -## 2. V3 端与负责人 +**边界**：apps 只 HTTP+shared-types；跨模块只 inject exported Service；枚举/DTO→shared-types；纯规则→domain。 -| 负责人 | 主责端 | 主责后端/公共范围 | 说明 | -|---|---|---|---| -| `jacy-dukang` | **全部四端**（含 `h5-shop`、`h5-partner`） | **全部模块** + `packages/*`、Prisma | Tech lead；**2026-07 起暂代刘景尧 B+D 职责** | -| `刘景尧` | ~~`apps/h5-shop`、`apps/h5-partner`~~ | ~~`store`、`redeem`~~ | **暂停分工**，恢复前由 jacy 代管 | +**日志**：见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md) -### 2.1 四端交付形态（工程口径） +## 3. 核销规则（V3） -产品 PRD 中总部端写作「H5」；**V3 工程交付以 `apps/admin-web`（WebAdmin）为准，不改为 H5，也不以迁移 H5 为验收项。** - -| 角色端 | V3 交付 App | 形态 | 说明 | -|--------|-------------|------|------| -| C 端用户 | `apps/h5-user`（过渡）→ 目标微信小程序 | H5 / 小程序 | 按 v3-PRD 逐步迁小程序 | -| 门店 | `apps/h5-shop` | H5（微信内） | 与 PRD 一致 | -| 城市合伙人 | `apps/h5-partner` | H5（微信内） | 与 PRD 一致 | -| **总部** | **`apps/admin-web`** | **WebAdmin（Ant Design）** | **保持 WebAdmin；REQ-H 能力在本端实现** | - -- 总部 API 前缀仍为 `/admin/*`，`X-Client-App: HQ_WEB`。 -- `apps/mini-hq` 若有能力重叠，**不作为 V3 主交付端**；缺的功能补在 `admin-web`（如推广码管理页）。 -- UI 参照 `pages/hq/` 原型时，按 **信息架构与字段对齐**，不要求 1:1 复刻 H5/小程序交互。 - -协作规则： - -- `apps/*` 只走 HTTP API 与 `packages/shared-types`，禁止 import `server/*` 或其他 app。 -- 后端跨模块只调用 exported Service，禁止为了赶进度直接写他人领域表。 -- 涉及 API、枚举、DTO、业务规则变更，必须同步 `packages/shared-types`、`packages/domain` 与本手册。 -- Prisma 迁移由 `jacy-dukang` 主导；涉及 `store` / `redeem` 表或核销流程时 `刘景尧` 必须 Review（**恢复分工前由 jacy 全权**）。 - -### 2.2 日志与审计（新业务） - -城市 / 仓库 / 账号 / 子账号 CRUD 须落入对应日志表，规范见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)： - -- **HQ 写操作** → `common_event(HQ_OPERATION)`，经 `@HqOperation` 装饰器 -- **合伙人端子账号** → `log_partner_analytics`（`partner_staff_*`） -- **城市多合伙、仓库表** → schema 待建；action 常量已预留 - - -## 3. V3 核销规则（已替代 V2 的 ¥500 上限） - -### 3.1 两种核销入口 - -| 入口 | 前端表现 | API 入参 | 限制规则 | 券扣减方式 | -|---|---|---|---|---| -| 直接点核销 | 用户在权益首页点击「去使用」 | `{ amount }`，不带 `couponId` | `0 < amount <= 用户全部 ACTIVE 权益总余额` | 按券创建时间 FIFO 扣减，可跨多张权益 | -| 指向单据核销 | 用户在某张权益/核销单点击「立即核销」 | `{ couponId, amount }` | `0 < amount <= 该单据当前可用金额` | 只扣减该单据 | - -### 3.2 后端不变量 - -核销码只存在 Redis，TTL = **3 分钟**（与 v3-PRD 一致）。 -- 生成核销码前必须校验金额，门店确认核销时必须二次校验。 -- 门店确认时使用券 `version` 乐观锁，避免并发重复扣减。 -- 核销成功后写入： - - `user_redeem_record` - - `common_event(BENEFIT_LEDGER, REDEEM)` - - `store_payout(PENDING)` -- 若核销码绑定门店，确认核销时只能由该门店使用；若未绑定门店，任意 `OPEN` 门店可确认。 -- 已关闭或暂停门店不可核销。 - -### 3.3 前端提示 - -- 直接核销：显示「最高可核销 = 当前好客权益总余额」。 -- 单据核销：显示「最高可核销 = 当前单据可用金额」。 -- 不再展示「单次最高可核销 ¥500.00」。 - ---- - -## 4. V3 完整业务闭环 - -### 4.1 C 端购酒与权益 - -1. 用户打开 H5，完成手机号/微信登录。 -2. 选择城市，首页展示已开城商品。 -3. 进入商品详情，选择数量与收货地址。 -4. 订单预览校验同城 2 瓶、跨城 6 瓶。 -5. 创建订单，状态 `PENDING_PAY`。 -6. 发起支付，Mock 环境同步成功，生产环境走微信 JSAPI。 -7. 支付成功回调幂等更新订单为 `PENDING_SHIP`。 -8. 根据商品 `benefitAmount ?? price` 发放好客权益。 -9. 用户在权益页直接核销或指定单据核销。 -10. 门店确认核销后，用户可评价，权益余额与流水更新。 - -### 4.2 门店核销与打款 - -1. 门店账号登录。 -2. 首页扫码或输入核销码。 -3. 后端校验核销码、门店状态、权益余额、单据金额。 -4. 核销成功生成记录。 -5. 系统创建 `store_payout(PENDING)`，预计 T+1 打款。 -6. 系统按门店绑定关系计算并记录对应合伙人的核销收益，用于合伙人账单与经营统计。 -7. WebAdmin 财务确认或 Job 自动推进打款状态。 -8. 门店端可查看核销记录与打款状态。 -9. 绑定合伙人端可查看辖区门店对应的核销订单、核销金额、门店打款状态与合伙人收益。 - -### 4.3 合伙人拓店与履约 - -1. 合伙人登录工作台。 -2. 录入门店资料、门头/环境图、合同资料、银行卡信息。 -3. V3 由 WebAdmin 审核门店，审核通过后门店才可对 C 端可见并参与核销。 -4. 合伙人查看辖区订单。 -5. 配送 Mock 或真实配送推进订单。 -6. 异常时发起/处理补发、改址拦截、配送异常。 -7. 合伙人查看月度账单、佣金、经营周报。 - -### 4.4 WebAdmin 运营（总部端） - -> 交付载体：`apps/admin-web`。本节即总部端验收口径，**不要求改为 H5**。 - -1. 管理员登录。 -2. 配置开城、商品、合伙人、门店分类。 -3. 审核门店。 -4. 查看订单与配送。 -5. 处理退款、补发、客服工单。 -6. 管理权益、核销、资源、账号。 -7. 财务确认门店 T+1 和合伙人 T+30 结算。 -8. 查看运营报表、异常预警、第三方日志。 - ---- - -## 5. V3 验收用例清单 - -### 必过主链路 - -1. C 端手机号登录成功。 -2. 首页展示郑州 4 个上架商品。 -3. 同城 1 瓶下单失败，2 瓶成功。 -4. 跨城 5 瓶下单失败，6 瓶成功。 -5. 支付成功后订单进入待发货，并发放权益。 -6. 直接核销不带 `couponId`，金额可达到总余额。 -7. 单据核销带 `couponId`，金额不能超过该单据余额。 -8. 门店扫码确认核销成功。 -9. 核销后生成 `store_payout(PENDING)`。 -10. 门店关闭后不可核销，C 端不可见关闭门店。 -11. 合伙人录店后进入审核流，审核通过后 C 端可见。 -12. 配送自动或真实回调推进到完成。 -13. 退款工单通过后订单/权益/第三方日志一致。 -14. 门店 T+1 打款状态可确认。 -15. 合伙人 T+30 账单可生成并确认。 - -### 必过后台链路 - -1. WebAdmin 登录成功。 -2. 创建/编辑/上下架商品。 -3. 审核门店。 -4. 查询订单与配送单。 -5. 查询权益券、核销记录、打款记录。 -6. 处理退款/补发/异常工单。 -7. 查看第三方日志与运营报表。 -8. 导出或核对财务数据。 - ---- - -## 6. 当前已知技术债 - -| 优先级 | 技术债 | 处理要求 | -|---|---|---| -| P0 | 旧文档与规则仍有 ¥500 上限描述 | V3 以后以本手册为准；后续批量清理 V2/preV1 中过时描述 | -| P0 | `lint` 多数为 `echo ok` | 交付验收前必须接入有效检查 | -| P0 | smoke 覆盖不足 | 按 4.x 业务闭环补齐主流程冒烟 | -| P1 | shared-types DTO 不全 | 按接口稳定度分批上提 | -| P1 | 跨模块直写 Prisma 表 | 逐步改为 exported Service | -| P1 | 真实短信、配送、退款未闭环 | 按 4.1、4.3、4.4 对应业务闭环完成 | -| P2 | `mini-hq` 与 `admin-web` 能力重叠 | V3 以 **admin-web** 为总部唯一交付端；`mini-hq` 不阻塞验收，缺项补 admin-web | - ---- - -## 7. 版本冻结规则 - -- **V3.0 业务规则**以 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) 为准；本编码手册为实现与验收补充。 -- **总部端**：交付载体固定为 **`apps/admin-web`（WebAdmin）**；PRD「总部 H5」按 REQ-H 功能对齐，**不要求改为 H5**。 -- V2 手册仍作为完整蓝图参考，但与 V3.0 冲突时，**V3 PRD 优先**。 -- preV1 手册只作为 Mock 联调历史参考，不再作为交付验收标准。 -- 未写入 v3-PRD 的新增需求，不进入 V3 交付范围；如必须加入，先更新 v3-PRD 与本手册。 - -## 8. V3.0 三波交付（摘要） - -详见 v3-PRD §9 与 `@dukang-v3` skill。 - -| 波次 | 日期 | 门禁 | +| 入口 | 入参 | 上限 | |------|------|------| -| Wave 1 | 7.10 | 下单+核销+拓店+合伙人子账号 | -| Wave 2 | 7.15 | 提现+推广码+现场提货+门店子账号+多合伙人 | -| Wave 3 | 7.22 | 代下单+弱网+多仓+跨城+工单+发票+全量 ACC | +| 直接核销 | `{ amount }` | ≤ 全部 ACTIVE 权益总余额（FIFO） | +| 单据核销 | `{ couponId, amount }` | ≤ 该单据可用金额 | + +- Redis 码 TTL **3 分钟**；确认时二次校验 + 券 version 乐观锁 +- 成功写：`user_redeem_record` · `common_event(BENEFIT_LEDGER)` · `store_payout(PENDING)` +- 绑定门店则仅该店可确认；`OPEN` 门店；暂停/关闭不可核销 +- UI 无「单次 ¥500」文案 + +## 4. 业务闭环（摘要） + +| 链路 | 关键节点 | +|------|----------| +| C 购酒 | 登录→开城商品→起购(同城2/跨城6)→支付→权益1:1→出码/核销→评价 | +| 门店 | 登录→扫码确认→记录→store_payout T+1 | +| 合伙人 | 拓店三步→HQ审核→辖区订单/账单 | +| HQ | 开城/商品/审核/订单/权益/核销/结算/工单 | + +## 5. 验收用例（必过） + +**主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30… +**后台 8 项**：商品/门店/订单/权益/核销/工单/日志/财务。 + +## 6. 技术债（摘要） + +P0：旧文档¥500 · lint 占位 · smoke 窄覆盖 +P1：DTO 不全 · 跨模块 prisma · 真实短信/配送 +P2：mini-hq vs admin-web 重叠 + +## 7. 版本与波次 + +规则变更先改 **v3-PRD**。Wave 1/2/3 见 PRD §9。 diff --git a/杜康好客-开发计划功能开发文档-v3.4.11.md b/杜康好客-开发计划功能开发文档-v3.4.11.md index 5644cb7..96004b4 100644 --- a/杜康好客-开发计划功能开发文档-v3.4.11.md +++ b/杜康好客-开发计划功能开发文档-v3.4.11.md @@ -1,177 +1,40 @@ -# 杜康好客 · 开发计划功能开发文档 v3.4.11 +# 杜康好客 · 开发计划 v3.4.11 +> PRD §3.10~3.11 · REQ-H-026~028 · 模块 `server/.../dev-plan/` +## 表 -> 对应 PRD §3.10 · REQ-H-026 ~ REQ-H-028 - -> 后端模块：`server/dukang-api/src/modules/dev-plan/` - -> 前端：`apps/admin-web` 开发计划三页面 + 技术支持改造 - - - ---- - - - -## 1. 数据模型 - - - -| 表 | 说明 | - -|----|------| - -| `dev_plan_task` | 任务池；可选 `support_ticket_id` | - -| `dev_plan_version` | 版本；状态与时间戳 | - -| `dev_plan_version_task` | 版本-任务多对多 | - -| `dev_plan_settings` | 单例：审核助手配置（LLM/知识库/提示词） | -| `dev_plan_task_dispatch` | 派发审计 | -| `wecom_message_push` | 企微群 Webhook 多实例；推送条件 JSON 数组 | - - - -枚举与 DTO：`packages/shared-types/src/dev-plan.ts`、`wecom-message-push.ts` - - - -**任务派发**：不再存于 `dev_plan_settings`；改由 HQ「消息推送」勾选 `dev_plan.task_dispatch`。 - - - ---- - - - -## 2. Admin API +`dev_plan_task` · `dev_plan_version` · `dev_plan_version_task` · `dev_plan_settings`（审核助手） · `dev_plan_task_dispatch` · `wecom_message_push` +枚举/DTO：`packages/shared-types` `dev-plan.ts` · `wecom-message-push.ts` +## Admin API（摘要） | 路由 | 说明 | - |------|------| +| `/admin/dev-plan/tasks` | CRUD · dispatch · batch-update（v3.4.12+） | +| `/admin/dev-plan/versions` | CRUD · 关联任务 · **RELEASED 联动任务/工单（v3.4.13）** | +| `/admin/dev-plan/settings` | 审核助手 LLM/知识库 | +| `/admin/wecom-message-pushes` | Webhook 多实例 + eventKey | +| `/admin/support-tickets/*` | review · batch-review · batch-update-status | -| `GET/POST /admin/dev-plan/tasks` | 任务列表 / 创建 | +任务派发：HQ「消息推送」勾选 `dev_plan.task_dispatch`（非 settings 字段）。 -| `GET/PUT/DELETE /admin/dev-plan/tasks/:id` | 任务 CRUD | +## 技术支持联动 -| `POST /admin/dev-plan/tasks/dispatch` | 评审派发（无需 devBotId） | +审批 `APPROVE` + `tasks[]`≥1 → 工单 DEVELOPING + 创建 `dev_plan_task`。批量 AI 预审 → confirm。 -| `GET/POST /admin/dev-plan/versions` | 版本列表 / 创建 | +## 企微机器人（摘要） -| `GET/PUT/DELETE /admin/dev-plan/versions/:id` | 版本 CRUD | +四类角色（客服/财务/运营/技术支持）+ 模块化权限；`support_ticket.review` 白名单；审计 `log_wecom_bot`。 +消息推送 eventKey：`alert.ops` · `support_ticket.created` · `dev_plan.task_dispatch` 等。 -| `PUT /admin/dev-plan/versions/:id/tasks` | 替换关联任务 | +## ACC 抽样 -| `GET/PUT /admin/dev-plan/settings` | 开发设置（审核助手） | - -| `GET/POST/PUT/DELETE /admin/wecom-message-pushes` | 消息推送 CRUD | - -| `POST /admin/wecom-message-pushes/:id/test` | 测试消息推送 | - - - -权限：`dev_plan`（`packages/shared-types/src/hq-permissions.ts`） - - - ---- - - - -## 3. 技术支持联动 - - - -| 路由 | 说明 | - -|------|------| - -| `POST /admin/support-tickets/:id/review` | 统一审批（SuperAdmin） | - -| `POST /admin/support-tickets/batch-review/preview` | 批量 AI 预审 | - -| `POST /admin/support-tickets/batch-review/confirm` | 批量确认落库 | - - - -审批通过：`decision=APPROVE` + `tasks[]`（≥1）→ 工单 `DEVELOPING` + 创建 `dev_plan_task`。 - - - ---- - - - -## 4. 企微与开发计划分工 - - - -| 能力 | 入口 | 说明 | -|------|------|------| -| **消息推送** | Admin `/wecom/pushes` | Webhook 多实例 + 条件勾选；运营告警 / 工单 / 任务派发 | -| **智能机器人** | Admin `/wecom/bots` | 四类角色 + 模块化权限；审计 `/logs/wecom-bots` | -| **任务评审派发** | 任务列表 · 评审 | 匹配 `dev_plan.task_dispatch` 的推送实例（可多条） | - -DevPlan Agent（HTTP 回调对话）已移除，避免与「企微机器人」重复。 - ---- - -## 附录 A · 企微机器人能力矩阵（v3.4.11 重构） - -| 模块 | 权限 | 指令示例 | -|------|------|----------| -| 订单 | `order.read` | `查订单 DK123` | -| 配送 | `delivery.read` | `快递 DK123` | -| 门店 | `store.read` | `查门店 杜康` | -| 核销 | `redeem.read` | `核销 门店名` | -| 售后工单 | `ticket.read` / `ticket.create` | `售后工单 TK…` / `工单 订单号 仅退款` | -| 用户 | `user.read` / `user.read_sms` | `用户号 U…` / `查用户 手机号` | -| 财务 | `finance.*.read` | `门店账单` / `合伙人账单` / `门店打款` | -| 技术支持 | `support_ticket.*` | `提单 BUG …` / `通过 ST…` / `驳回 ST… 理由` | -| 开发计划 | `dev_plan.task.read` / `dev_plan.version.read` | `开发任务` / `版本 v3.4.11` | - -**审批**：`support_ticket.review` + 机器人级 `reviewSuperAdminWecomUserIds` 白名单；通过自动建 1 条 dev_plan_task。 - -**废弃**：`api.read.all`、`db.read`、`TEAM_ASSISTANT`（迁移为 `OPERATIONS`）。 - - - ---- - - - -## 5. 验收（ACC） - - - -- [ ] 侧边栏「开发计划」三子页；无 `dev_plan` 权限不可见 -- [ ] 侧边栏「企微机器人」：智能机器人 / 消息推送 / 日志 -- [ ] 消息推送 CRUD + 测试；条件勾选生效 -- [ ] 任务/版本 CRUD；版本多选关联任务 -- [ ] 版本状态流转写时间戳；用时正确 -- [ ] 新建技术支持工单 → `support_ticket.created` 推送；`alert.ops` 可并行 -- [ ] 技术支持：单一审批、通过创建任务、批量 AI 审核 -- [ ] 任务勾选评审派发（走消息推送 @ userid） -- [ ] 系统设置无企微告警开关；运行时不再读 `WECOM_ALERT_WEBHOOK_URL` -- [ ] mutation 有 HQ 操作审计 - - - ---- - - - -## 6. 发版 - - - -1. `pnpm db:generate` + `prisma db push`（`wecom_message_push` 表；删除 `dev_plan_settings.task_dispatch_*`） -2. `pnpm prisma:migrate-wecom-push`（发版前，在 drop `task_dispatch_*` 之前）或 API 启动 `ensureDefaults` -3. staging 验证消息推送 + 任务派发 + 工单通知 -4. tag **`v3.4.11`** +- [ ] 开发计划三页 + 企微三菜单 +- [ ] 工单审批建任务；任务评审派发 Webhook +- [ ] v3.4.13：版本 RELEASED → 任务 RELEASED + 工单 PUBLISHED +## 发版 +`prisma db push`（`wecom_message_push`）· 迁移旧 env Webhook · tag `v3.4.11` diff --git a/杜康好客-知识库.md b/杜康好客-知识库.md index 484a3e8..5e1e2b8 100644 --- a/杜康好客-知识库.md +++ b/杜康好客-知识库.md @@ -1,960 +1,123 @@ # 杜康好客 · 业务知识库 -> **版本**：基于 V3.0 PRD 与当前四端实现整理 -> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) -> **实现验收**：[`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) -> **用途**：新人上手、运营培训、客服/财务/开发协作说明（非需求变更文档） +> **非需求文档**（不改规则请改 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） -1. [整体概述](#1-整体概述) -2. [用户小程序端](#2-用户小程序端) -3. [门店端](#3-门店端) -4. [合伙人端](#4-合伙人端) -5. [HQ 总部后台](#5-hq-总部后台) -6. [商品上传与详情模板](#6-商品上传与详情模板) -7. [活动的创建](#7-活动的创建) -8. [开城流程](#8-开城流程) -9. [开店流程](#9-开店流程) -10. [订单处理](#10-订单处理) -11. [财务模块](#11-财务模块) -12. [发票模块](#12-发票模块) -13. [工单模块](#13-工单模块) -14. [配送单](#14-配送单) -15. [好客权益](#15-好客权益) -16. [系统设置](#16-系统设置) -17. [企业微信对接](#17-企业微信对接)（含 [§17.6 运营告警 Webhook](#176-运营告警-webhook群机器人)） +- 四 Tab：首页/权益/门店/我的；微信登录+7天会话 +- 下单：选城→商品→地址→起购校验→微信支付→权益1:1 +- 权益：直接核销(≤总余额) / 单据核销(≤单据)；出码3分钟 +- 门店：仅 OPEN；详情含套餐/电话(脱敏可拨打)/两段营业时间 +- 订单 Tab：待付款/已付款/已完成；物流详情(签收照/拨号/ETA) +- 售后：客服入口；发票/四类型工单按 PRD Wave 进度 +- 版本：`minClientVersion` 过低强制更新或退出 ---- +## 3. 门店端（h5-shop） -## 1. 整体概述 +- 登录绑定门店；首页扫码核销(微信 JSSDK) +- 核销记录；今日汇总；到账金额×60%展示 +- 营业状态开关；Mine 门店信息 +- 套餐：列表编辑→提交 HQ 审核（v3.4.10） +- iOS 微信：OAuth 后自动续扫（v3.4.13） -### 1.1 产品定位 +## 4. 合伙人端（h5-partner） -**杜康好客**是杜康酒业 O2O 平台，核心链路为： +- 管理员 vs 推广员菜单裁剪；子账号 CRUD +- 拓店：基本信息→照片→结算资质→(套餐)；一号多店确认 +- 门店列表/详情/套餐提审；辖区订单；账单 T+30 +- 暂停账号：发码前即拦截登录（v3.4.13） -**购酒 → 发放等额好客权益 → 合作餐饮门店核销（酒 + 餐）** +## 5. HQ（admin-web） -商业模型： - -| 环节 | 说明 | -|------|------| -| 总部 | 供酒、开城、商品、审核、结算打款、售后 | -| 城市合伙人 | 分销拓店、辖区经营、佣金对账 | -| 门店 | 核销好客权益，按核销额 60% 结算 | -| C 端用户 | 买酒得 1:1 权益，到店核销消费 | - -**成本与分润锚点（不可偏离）**： - -- 酒水成本约售价 **3 折** -- 门店结算 = 核销金额 × **60%** -- 单合伙人「订单佣金 + 核销佣金」≤ 订单金额 **5%**（默认订单 0% + 核销 3%） -- 权益：支付成功赠送订单实付 **1:1**，永久有效 -- 权益额口径：`benefit_amount ?? price` -- 核销码 Redis TTL：**3 分钟** - -### 1.2 四端职责一览 - -| 端 | 形态 | 主要职责 | -|----|------|----------| -| **用户端** | 微信小程序（联调可用 H5 `h5-user`） | 浏览购酒、支付、履约/提货、权益出码、找店核销、售后/发票、客服 | -| **门店端** | H5（`h5-shop`） | 扫码/手机号核销、核销记录、营业状态、子账号、结算提现 | -| **合伙人端** | H5（`h5-partner`） | 拓店三步录入、辖区订单/数据、负责人复核、月账对账、代下单 | -| **总部 HQ** | WebAdmin（`admin-web`） | 开城/商品/门店审核、订单履约、财务打款、发票/工单、权益、系统配置 | - -签约主体：**山西领势酒业有限责任公司**。 - -试点城市：**郑州**。配送：同城小飞侠；跨城总部物流到付。 - -### 1.3 五条业务主闭环 - -``` -购酒履约 ──► 已完成 + 权益 1:1 -权益核销 ──► 扣减权益 + 门店账本×60% + 核销佣金 -拓店入驻 ──► 审核 + 试核销 ──► 营业中 C 端可见 -售后工单 ──► 总部审 + 仓/合伙人协同 ──► 补发/退款 -结算提现 ──► T+1 出账 / 未出账可提 ──► 总部审后打款 -``` - -### 1.4 技术骨架（便于协作） - -- API：`/api/v1`，响应 `{ code, message, data }` -- 单体 NestJS：`server/dukang-api` -- 共享契约：`packages/shared-types`；纯规则：`packages/domain` -- 统一 UI 主色：杜康红 `#8B1E1E`～`#A12828`；权益金 `#C4A35A` - ---- - -## 2. 用户小程序端 - -> PRD 交付形态为 **微信小程序**；仓库中 `apps/mini-user` 为小程序端，`apps/h5-user` 为 H5 联调过渡。 - -### 2.1 导航与账号 - -- 四 Tab：首页 / 订单（或权益相关入口）/ 门店 / 我的（以实际小程序 Tab 为准） -- 无感登录 + 7 天免登；确认下单可提示绑定手机号（可选、不强制） -- **仅微信支付**；待付款锁单 **30 分钟**未付自动取消 - -### 2.2 购酒与履约 - -| 场景 | 规则摘要 | -|------|----------| -| **同城** | 已开城城市；起购 **≥2 瓶**；免运费；小飞侠/仓配履约；送达后确认或 24h 自动完成 | -| **跨城** | 未开通城市；起购 **≥1 箱（6 瓶）**；总部物流 **到付**；订单佣金归总部 | -| **现场提货** | 隐藏入口（推广码场景）；起购 **≥2 瓶**（同同城起购）；支付后直接 **已完成** 并发权益 | - -订单列表 Tab（V3）：**待付款 | 已付款 | 已完成**。 - -### 2.3 好客权益与核销 - -- 支付成功发放实付金额 **1:1** 权益，永久有效 -- 「我的 / 好客权益」查看余额与明细 -- 出码核销：码有效期 **3 分钟**；核销前展示规则弹窗（附件一） -- 也可到店报手机号由门店发起核销 - -### 2.4 门店发现 - -- 门店列表 / 详情 / 搜索 / 省市区筛选 -- C 端仅展示 **营业中（OPEN）** 门店 -- 营业时间支持 **1 段或 2 段**（如 `09:00-22:00` 或 `09:00-14:00，17:00-21:00`） -- 入驻可选填 **人均费用**，用户端门店列表/详情展示 -- 支持「立即核销」跳转出码 - -门店状态（三态）： - -| 状态 | 含义 | C 端 | 门店端 | -|------|------|------|--------| -| OPEN | 营业中 | 可见可核销 | 可切为临时闭店 | -| PAUSED | 临时闭店 | 不可见 | 可恢复营业 | -| CLOSED | 永久关闭 | 不可见 | **不可**自行开启；需总部/合伙人处理 | - -### 2.5 售后、发票与增长 - -| 能力 | 说明 | -|------|------| -| 售后工单 | 四类型：仅退款 / 破损补发 / 破损退货 / 退货退款 | -| 发票 | 个人/企业 × 普票/专票 组合申请 | -| 客服 | 电话客服 + 企业微信在线客服（见 §17） | -| 推广码 | 扫码进小程序归因合伙人/渠道 | -| 问卷与评价 | 成交后问卷（无权益激励）；核销后门店评价 | - -### 2.6 SKU 价格锚点（酒祖杜康） - -| 商品 | 瓶价 | 箱价(6瓶) | -|------|------|-----------| -| 国标特级 10 · 53° | ¥128 | ¥768 | -| 国标特级 15 · 53° | ¥168 | ¥1008 | -| 国标特级 20 · 53° | ¥298 | ¥1788 | -| 国标特级 30 · 53° | ¥498 | ¥2988 | - ---- - -## 3. 门店端 - -> App：`apps/h5-shop`，微信内置浏览器 H5。 - -### 3.1 账号模型 - -| 角色 | 权限 | -|------|------| -| **主账号** | 核销、子账号管理、营业状态、提现、本店全量记录 | -| **店员子账号** | 仅核销 + 本店核销记录 | -| **一号多店** | 同一手机号可作多家店主账号；登录时选店；7 天免登记住上次门店 | - -主账号来源：入驻第三步「负责人手机号」，每店仅一个主账号。 - -### 3.2 核销操作 - -1. 首页大按钮进入核销页 -2. **扫码通道**：扫描用户核销码 -3. **手机号通道**：输入用户手机号 + 核销金额 → 发短信验证码 → 验证成功后直接核销（同页完成） -4. 核销成功：权益扣减、门店账本记入 **核销额 × 60%**、短信通知用户 -5. 今日汇总可在首页查看 - -**弱网兜底**：网络类失败重试；连续失败可拍照提交总部人工补核销（业务错误如码过期、余额不足不计入失败次数）。 - -### 3.3 记录、结算与提现 - -- 核销记录筛选：今日 / 7 日 / 1 月 / 全部 -- 到账金额展示按 ×60% -- T+1 自然日出账（法定节假日顺延） -- **未出账金额可申请提现**（受 FIN 护栏：白名单、单日上限等） -- 结算异议：核销后 **3 个工作日**内附凭证提出 - -### 3.4 营业状态 - -门店三态：**营业中 / 临时闭店 / 永久关闭**。门店端仅可在营业中 ↔ 临时闭店之间切换；总部设为永久关闭后，门店端不可自行开启。仅营业中门店对 C 端可见。 - ---- - -## 4. 合伙人端 - -> App：`apps/h5-partner`。 - -### 4.1 角色与权限 - -| 角色 | 菜单与能力 | -|------|------------| -| **管理员** | 拓店、经营看板、订单/权益/工单、财务对账、子账号、代下单等 | -| **推广员** | 仅门店入驻 + 查看自己提交的店（须在管辖范围内） | - -数据 **平级隔离**：全城/区域合伙人不可互查对方数据。手机号中间 4 位脱敏。 - -### 4.2 管辖类型 - -| 类型 | 范围 | 限制 | -|------|------|------| -| 全城合伙人 | 该城未被区域占用的区县 | 每城最多 1 名 | -| 区域合伙人 | 总部勾选的区县 | 每城可多名；同一区县不可重复 | - -### 4.3 拓店 - -三步录入 → 负责人复核 → 总部审核 → 试核销 100 元 → 正式入驻（详见 [§9 开店流程](#9-开店流程)）。 - -### 4.4 经营与财务 - -- 首页三卡、排行、订单/权益/工单列表 -- 佣金快照可下钻（支付时落库，比例变更仅影响新单/新核销） -- 本合伙人 **T+30 月账单**：独立确认、独立打款（无上下级二次分账） -- Wave 3：代下单、管仓只读协同 - -### 4.5 佣金归属（摘要） - -- **同城订单佣金**：收货区县 → 区域合伙人 → 否则全城合伙人 → 再无归总部 -- **跨城订单佣金**：归总部 -- **核销佣金**：归核销门店所属合伙人 -- **推广码**：主要用于归因统计；现场提货「有码归码」例外 - ---- - -## 5. HQ 总部后台 - -> App：`apps/admin-web`。登录：账号密码或短信验证码。菜单按 **角色权限** 裁剪。 - -### 5.1 角色总览 - -系统内置角色（`HQ_ADMIN_ROLES`）： - -| 角色 | 代码 | 定位 | -|------|------|------| -| **超级管理员** | `SUPER_ADMIN` | 全权限；权限分配；技术支持工单评审 | -| **运营** | `OPS` | 商品/开城/门店/订单/配送/推广/权益日常运营 | -| **财务** | `FINANCE` | 账单打款、发票、酒厂账户、订单与结算核对 | -| **客服** | `CUSTOMER_SERVICE` | 用户/订单查询、售后工单、发票协助 | - -> 说明：系统 **无独立「开发」角色码**。开发相关工作通过 **技术支持工单** 状态机完成：各角色可提单 → 超管评审 → 进入开发/测试/通过。下文「开发」指该协作职能。 - -权限可按角色默认值配置，也可按账号叠加个性化权限（`权限分配` 页，仅超管）。 - -### 5.2 运营（OPS） - -**默认可见模块（摘要）**：概览、用户、微信绑定、商品（含详情模板）、订单、推广码、门店、开城（城市/合伙人/仓库/仓配）、好客权益、配送单、工单中心、技术支持、发票、OSS、日志、小程序展示配置等。 - -**日常工作**： - -| 事项 | 菜单入口 | 要点 | -|------|----------|------| -| 开城与仓配 | 开城 → 城市 / 合伙人 / 仓库 / 仓配管理 | 见 §8 | -| 商品上架 | 商品 → 商品列表 / 详情模板 | 见 §6 | -| 门店审核 | 门店 → 门店列表 | 通过/驳回；试核销协同 | -| 订单履约 | 订单 | 同城推单、跨城/无仓填单、现场提货单查看 | -| 推广与活动 | 推广码 | 见 §7 | -| 权益运维 | 好客权益 | 券/流水/核销记录/待处理核销 | -| 配送跟踪 | 配送单 | 运单号维护、小飞侠联调 | -| 内容资源 | OSS 资源库 | 图片等素材 | - -### 5.3 财务（FINANCE） - -**默认可见模块（摘要）**：概览、订单、门店、开城、**财务三账单**、好客权益、技术支持、发票、日志、酒厂银行账户设置。 - -**日常工作**： - -| 事项 | 菜单入口 | 要点 | -|------|----------|------| -| 门店结算打款 | 财务 → 门店账单 | T+1 账期；确认打款 / 批量打款；导出 | -| 合伙人佣金 | 财务 → 合伙人账单 | 月账确认与打款 | -| 酒厂往来 | 财务 → 酒厂账单 | 与酒厂账户对照 | -| 物流对账 | 财务 → 物流对账 | 按承运商月结；充值/挂账 | -| 发票开具 | 发票管理 | 2 个工作日 SLA；回传 PDF/图片 | -| 收款账户 | 系统设置 → 酒厂银行账户 | 户名/开户行/账号 | - -### 5.4 客服（CUSTOMER_SERVICE） - -**默认可见模块（摘要）**：概览、用户、订单、工单中心、技术支持、发票、日志。 - -**日常工作**： - -| 事项 | 说明 | -|------|------| -| 查用户/订单 | 协助定位支付、履约、权益问题 | -| 售后工单 | 受理用户四类型工单；同意/驳回；协同仓与合伙人 | -| 发票协助 | 代查申请状态、催办开票 | -| 弱网补核销 | 处理门店提交的待处理核销单（与运营/权益模块协同） | -| 技术支持提单 | 将系统缺陷/建议提给超管评审 | - -### 5.5 开发（技术支持工单协作） - -入口：**工单 → 技术支持**（权限键 `tech_support`）。 - -| 步骤 | 操作人 | 状态 | -|------|--------|------| -| 创建 | 运营/财务/客服/超管等有权限账号 | `待评审` | -| 评审通过 / 驳回 | **超级管理员** | 通过 → `开发`；驳回 → `已驳回`（需填写原因） | -| 开发完成 | 有权限账号（通常超管/指定开发协作者） | `开发` → `测试` | -| 测试通过 | 有权限账号 | `测试` → `通过` | - -工单类型：`BUG` / `建议` / `其他`。 -用途：产品缺陷、体验建议、技术支持请求的闭环留痕，与 **售后工单中心**（用户订单售后）相互独立。 - -### 5.6 超级管理员 - -- 全部业务菜单 -- **权限分配**：按角色 / 按账号配置权限目录 -- **HQ 账户**：创建与维护总部账号 -- **技术支持工单评审** -- **系统设置** 全部分组（功能开关、短信、微信、OSS、部署等） -- **企微机器人**（与系统设置并列；总开关仍在功能开关） - -### 5.7 HQ 菜单地图（速查） - -| 分组 | 页面 | -|------|------| -| 概览 | Dashboard | -| 用户 / 微信绑定 | 用户列表；OpenID/UnionID 多端身份 | -| 商品 | 商品列表；详情模板 | -| 订单 / 推广码 | 全量订单；推广码与归因用户 | -| 门店 | 列表、分类、账户、资源 | -| 开城 | 城市、城市合伙人、仓库、仓配管理 | -| 财务 | 门店账单、合伙人账单、酒厂账单、物流对账 | -| 好客权益 | 权益券、流水、核销记录、待处理核销、核销调试 | -| 配送单 | 列表；小飞侠联调 | -| 工单 | 工单中心；技术支持 | -| 发票 | 发票管理 | -| 资源 / 日志 | OSS；用户/商户/合伙人/HQ/第三方日志 | -| 企微机器人 | 多实例 Bot 配置（长连接指令助手，可绑语言模型与知识库，见 §17） | -| 语言模型 | DeepSeek / OpenAI / 通义 / 自定义 API；非超管仅见自己的配置且只能改是否生效 | -| 知识库 | 上传/粘贴文档，供企微机器人 AI 检索 | -| 管理 | 权限分配；系统设置；HQ 账户 | - ---- - -## 6. 商品上传与详情模板 - -### 6.1 商品列表（运营） - -路径：**商品 → 商品列表**。 - -创建/编辑字段要点： - -| 字段 | 说明 | -|------|------| -| SKU / 69 码 | 商品编码与条码 | -| 名称 / 副标题 / 香型 / 规格 | 展示信息 | -| 售价 `price` | 用户支付价 | -| 权益额 `benefitAmount` | 默认可与售价一致；规则为 `benefit_amount ?? price` | -| 主图 / 轮播图 / 详情长图 | OSS 上传 | -| 故事标题与正文、卖点特色 | 详情页文案结构 | -| 是否允许现场提货 | `allowOnSitePickup` | -| 状态 / 排序 | 上架与列表顺序 | - -营销规则：支付成功按实付 **1:1** 发放好客权益（总部「营销规则」口径，与商品权益额配合）。 - -### 6.2 详情模板 - -路径：**商品 → 详情模板**。 - -用途：把「故事 + 卖点 + 详情长图」沉淀为可复用模板，新建/编辑商品时 **套用模板**，再按 SKU 微调图片与文案。 - -模板字段： - -- 模板编码 `code`（唯一）、名称、描述、香型 -- 详情长图列表、建议张数 -- 故事标题/正文 -- 卖点列表（图标名、标题、描述） -- 排序、状态（启用/停用） - -**推荐操作流**： - -1. 先在「详情模板」建好品牌统一长图与话术 -2. 商品表单中选择模板一键填充 -3. 替换该 SKU 专属主图/轮播后上架 - ---- - -## 7. 活动的创建 - -本期「活动」主要落在 **推广码** 与 **现场提货/品鉴** 场景，而非独立营销中台。 - -### 7.1 推广码创建 - -路径：**推广码**。 - -| 场景 `scene` | 用途 | -|--------------|------| -| 线上链接 | H5/小程序落地链接归因 | -| 现场提货 | 线下提货隐藏入口；有码则订单佣金归码所属方 | -| 合伙人渠道 | 合伙人拓客统计 | -| **活动品鉴** | 品鉴会等活动场次 | -| 其他 | 自定义 | - -创建时填写：名称、场景、备注、归属用户（可选）等；系统生成码值、落地 URL、二维码。可查看扫码次数、订单数、转化率、归因用户列表。 - -### 7.2 活动执行要点 - -1. HQ 创建「活动品鉴」或「现场提货」推广码并下载二维码 -2. 现场物料投放；用户扫码进入小程序完成绑定归因 -3. 现场提货订单支付后直接完成并发权益 -4. 后台在推广码详情核对扫码/成交数据 - -权益发放规则活动期仍遵循 **1:1 实付**，不额外叠加激励问卷权益。 - ---- - -## 8. 开城流程 - -路径：**开城** 菜单。 - -### 8.1 步骤总览 - -``` -① 新增城市（省市区划 + 启用） - ↓ -② 配置城市合伙人（全城 / 区域 + 佣金比例） - ↓ -③ 配置仓库（可选，一城多仓） - ↓ -④ 仓配管理注册承运商（小飞侠等）并绑定仓库履约方式 - ↓ -⑤ 该城 C 端按「同城」规则下单；未开城走「跨城」 -``` - -### 8.2 城市 - -- 选择省份/城市区划，填写城市名称与编码 -- 状态启用后，用户定位命中该城即走同城履约与起购规则 -- 城市详情可查看门店数、订单数、合伙人绑定、仓库列表 - -### 8.3 城市合伙人 - -- 在城市下创建或绑定合伙人账号 -- 配置管辖：全城 or 勾选区县（区县互斥） -- 配置订单佣金比例、核销佣金比例（合计 ≤ 5%） -- 可管理合伙人子账号（管理员/推广员） - -### 8.4 仓库与仓配 - -| 配置 | 说明 | -|------|------| -| 仓库 | 名称、地址、联系人；管仓方 = 总部直派 或 关联合伙人（每仓最多 1 名） | -| 履约方式 | **API 自动推单**（选已注册承运商，首期小飞侠）或 **自管**（手工填运单号 + 查询链接模板） | -| 仓配管理 | 注册第三方履约接口；启用后仓库才可选；配置银行账户/结算/计价 | -| 大单拦截 | 同城 ≥10 箱不自动推小飞侠，订单标「大单待确认」，总部确认推单或自配送 | - -规则摘要： - -- 同城 **有仓**：按仓配置自动推单或自管填单 -- 同城 **无仓** / **跨城**：总部传统快递填单 -- 佣金归属与仓无关；仓用于履约与工单协同 - ---- - -## 9. 开店流程 - -对齐《门店签约 SOP》与 PRD 拓店闭环。 - -### 9.1 录入主体 - -- **合伙人端**：三步向导录入（主路径） -- **HQ 门店列表**：总部也可代建/补录（需选择开城合伙人与匹配开城城市） - -### 9.2 三步录入 - -| 步骤 | 内容 | -|------|------| -| 1. 基础信息 | 门头展示名、执照全称；筛选条件参考（面积≥200㎡、客单价≥60、包房≥5 等） | -| 2. 证照与照片 | 证照/合同/门店照片；**附件一**结构化规则 | -| 3. 结算信息 | 法人收款或授权书 + 银行卡；短信校验 | - -一号多店：手机号已关联其他店时需确认后继续。 - -### 9.3 状态流转 - -``` -暂存 - → 待负责人复核 - → 待总部审核 - → 审核通过（待试核销） - → 试核销固定 100 元成功 - → 正式入驻 + 短信通知 - → 营业中（C 端可见） -``` - -- HQ 可在门店详情 **通过 / 驳回**（驳回需原因） -- 系统开关 `AUTO_APPROVE_STORE` 开启时，合伙人录店可自动审核通过（联调/试点用） -- 营业状态由门店主账号或 HQ 调整 - -### 9.4 HQ 门店相关页 - -- 门店列表：审核、营业状态、详情 -- 门店分类 / 门店账户 / 门店资源：分类标签、账号与媒体资源维护 - ---- - -## 10. 订单处理 - -路径：**订单**（HQ）；用户端「我的订单」；合伙人端「订单中心」。 - -### 10.1 状态机 - -``` -待付款 ──支付成功──► 已付款 ──履约完成 / 确认收货 / 24h 自动──► 已完成 - └─ 30 分钟未付 → 取消 -``` - -支付成功即发放权益；履约完成不重复发券。 - -### 10.2 同城订单 - -1. 用户定位/收货在已开城城市，数量满足 ≥2 瓶 -2. 支付成功 → 订单「已付款」 -3. 有仓且 API 承运商：系统自动推小飞侠等配送单 -4. 有仓自管：管仓方/总部手工填运单号 -5. 无仓：总部在订单详情走传统快递填单 -6. 送达后用户确认，或超时 24h 自动完成 - -HQ 订单详情可查看收货地址、仓信息、配送单、权益券与核销分摊、佣金快照等。 - -### 10.3 跨城订单 - -1. 收货城市未开城；数量 ≥1 箱 -2. 确认页提示物流到付 -3. 支付成功后由 **总部** 传统快递填单发货 -4. 订单佣金归总部 - -### 10.4 线下（现场）提货 - -1. 用户通过「现场提货」推广码等隐藏入口下单 -2. 支付成功 → 订单直接 **已完成** + 权益到账 -3. HQ / 合伙人可在订单列表按配送类型或推广码筛选核对 -4. 有现场推广码：订单佣金归码所属；无码归总部 - -### 10.5 订单详情查阅清单 - -| 查阅项 | 用途 | +| 菜单域 | 要点 | |--------|------| -| 订单号 / 状态 / 金额 / 运费 | 对账与客服 | -| 收货人、省市区、详细地址 | 履约改址（规则允许时） | -| 定位/IP 辅助信息 | 风控与同城判断留痕 | -| 商品行、权益额 | 发券核对 | -| 配送类型与运单 | 同城/跨城/现场 | -| 关联权益券与核销记录 | 售后与财务 | -| 佣金归属快照 | 合伙人结算 | +| 开城 | 城市、合伙人(全城/区域+佣金)、仓库 | +| 商品 | SKU、上下架、详情模板 | +| 门店 | 审核、套餐 Tab 直存/审核、合伙人列 | +| 交易 | 订单、权益券、核销记录、推广码+metrics | +| 财务 | 门店/合伙人/酒厂/物流账单；打款确认 | +| 工单 | 售后四类型 + 技术支持(ST) + 开发计划 | +| 系统 | 账号权限、客户端配置、企微机器人/消息推送 | +| 日志 | HQ/用户/门店/合伙人/企微 | ---- +## 6. 商品与模板 -## 11. 财务模块 +HQ 创建商品：名称/价格/权益额/箱规/香型/城市上架；详情模板(JSON 块)；资源 OSS。 -路径：**财务**。 +## 7. 活动 / 推广码 -### 11.1 门店账单 +HQ 推广码：场景/合伙人绑定/上下线；touch 归因；metrics 四指标+事件日志(v3.4.13)。 -- 来源：门店核销 → 结算额 = 核销额 × **60%** → T+1 出账形成账期 -- 列表字段：账单号、账期日、核销笔数/金额、结算比例、应打款、状态（未打款/已打款） -- 操作：查看明细、**确认打款**、批量打款、导出 Excel -- 提现申请：门店发起 → 总部审核 → 打至入驻收款账户 -- 试点护栏：未出账提现白名单、单店单日上限（默认 ¥5,000）、工作日 T+0 审完预警 +## 8. 开城 -### 11.2 合伙人账单 +创建城市 → 绑定主账号合伙人 → 配置佣金 → 上架商品 → 仓库(可选)。 -- 订单佣金（支付成功快照）+ 核销佣金（核销时按占比释放） -- 独立月账、独立确认、独立打款 -- 比例变更只影响新业务，历史账单展示快照 +## 9. 开店 -### 11.3 酒厂账单 +合伙人三步录入 → (负责人复核) → HQ 审核 → (试核销100) → OPEN → C 端可见。 -- 总部与酒厂供货/回款往来核对 -- 打款对照 **系统设置 → 酒厂银行账户** 中的户名、开户行、账号 +## 10. 订单 -### 11.4 物流对账 +状态机三态；支付回调幂等；同城小飞侠/跨城 HQ 填单；现场提货即完成；大单≥10箱 HQ 确认。 -- 按快递/仓配承运商（小飞侠等）汇总月度物流费 -- 承运商在 **开城 → 仓配管理** 配置：银行账户、结算方式（充值扣款 / 挂账月结）、计价标准 -- 小飞侠默认：2 瓶 6 元，加一瓶 +2 元，6 瓶一箱 14 元 -- 前期充值：在「物流对账」汇总页充值；生成月账单时余额充足则自动扣款 -- 后期挂账：月账单确认后打款至承运商银行账户 +## 11. 财务 -### 11.5 财务日常 SOP（建议） +- **门店**：核销→store_payout T+1；未出账可提现→HQ 审→打款 +- **合伙人**：T+30 月账独立确认打款 +- **酒厂**：T+3 账单(v3.4.12) +- **物流**：按承运商月结(小飞侠计价见 PRD §3.7.1) -1. 每日核对门店「未打款」账单与核销记录 -2. 处理门店提现申请并在账期内标记打款 -3. 月结合伙人账单并完成打款确认 -4. 月结物流承运商账单（充值余额或挂账打款） -5. 同步发票开具与退款工单对资金影响 -6. 异常走技术支持或售后工单留痕 +## 12. 发票 ---- +用户申请 → HQ 2 工作日处理 → 回传（Wave 3 完整） -## 12. 发票模块 +## 13. 工单 -路径：**发票管理**。用户端亦可发起申请。 +**售后**（用户）：仅退款/补发/退货等四类型 → HQ 审 → 仓/合伙人协同 +**技术支持**（内部 ST）：BUG/建议 → 审批 → 开发任务 → 版本发布 → 工单 PUBLISHED(v3.4.13) -### 12.1 类型组合 +## 14. 配送 -| 抬头 | 票种 | -|------|------| -| 个人 `PERSONAL` | 增值税普通发票 | -| 企业 `ENTERPRISE` | 增值税普通发票 / 增值税专用发票 | - -企业专票通常需税号、地址电话、开户行及账号等。 - -### 12.2 状态 - -| 状态 | 说明 | -|------|------| -| `PENDING` 待开票 | 用户或 HQ 已提交 | -| `ISSUED` 已开票 | HQ 上传发票文件回传 | -| `REJECTED` 已驳回 | 信息有误等 | - -SLA：**2 个工作日**内处理；超时可在列表以逾期标识预警。 - -### 12.3 HQ 处理步骤 - -1. 按状态筛选待开票 -2. 打开详情核对订单号、金额、抬头、邮箱/手机 -3. 开具后上传 PDF/图片至 OSS，执行「开票回传」 -4. 或驳回并备注原因 -5. 亦可由客服/财务代用户创建申请（需订单号） - ---- - -## 13. 工单模块 - -工单分两类，勿混淆。 - -### 13.1 售后工单中心（用户订单） - -路径：**工单 → 工单中心**。 - -| 类型 | 总部决策 | 通过后动作 | -|------|----------|------------| -| 仅退款 | 同意/驳回 | 原路退款 | -| 破损补发 | 同意/驳回 | 负责仓配送+取回；通知管仓合伙人 | -| 破损退货 | 同意/驳回 | 负责仓取回 → 退款 | -| 退货退款 | 同意/驳回 | 通知归属合伙人 + 负责仓取回 → 退款 | - -另有系统 `ALERT` 异常类工单。 -用户从已付款及之后订单发起；客服也可在 HQ 代建。处理全程留痕，协同阶段需仓/合伙人确认。 - -### 13.2 技术支持工单 - -路径：**工单 → 技术支持**。见 [§5.5](#55-开发技术支持工单协作)。 - -与售后工单权限分离：`tickets` vs `tech_support`。 - ---- - -## 14. 配送单 - -路径：**配送单 → 配送单列表**（及「小飞侠联调」）。 - -### 14.1 列表与查询 - -可按订单号、承运商 `provider`、运单号筛选。字段含：订单号、provider、运单号、第三方单号、订单状态、收货人、更新时间。 - -### 14.2 处理动作 - -- 查看关联订单与收货信息 -- **编辑** 承运商、运单号、第三方单号（自管仓/传统快递补录） -- API 自动推单失败时，人工改状态或重填运单作为兜底 -- 小飞侠联调页：对接调试推单、状态回调、取送拍照等 - -### 14.3 与订单的关系 - -配送单从属于订单履约；同城目标 24h；用户确认收货或超时自动完成后订单进入「已完成」。跨城到付同样在配送单/订单详情维护运单信息。 - ---- +小飞侠推单/回调；`POST /callbacks/courier/xfx/track`；签收→订单 COMPLETED。 ## 15. 好客权益 -路径：**好客权益**。 +支付成功发放；FIFO 扣减；流水 `common_event(BENEFIT_LEDGER)`；核销后评价。 -### 15.1 核心规则 +## 16. 系统设置 -| 规则 | 值 | -|------|-----| -| 发放 | 支付成功，实付 × 1:1 | -| 有效期 | 永久 | -| 直接核销 | `0 < amount ≤ 全部 ACTIVE 权益总余额` | -| 带单据核销 | `0 < amount ≤ 该单据可用金额` | -| 出码 TTL | 3 分钟 | -| 试核销 | 固定 100 元（拓店） | +HQ 账号/角色(`hq-permissions`) · 客户端 `minClientVersion` · 运营告警走企微消息推送(DB Webhook)。 -### 15.2 HQ 子模块 +## 17. 企业微信 -| 页面 | 用途 | +| 能力 | 入口 | |------|------| -| **权益券** | 按券号/用户/状态查询；查看余额、来源订单商品；详情含核销汇总与记录；支持人工发放（运营补偿） | -| **流水** | 发放/扣减等账本流水审计 | -| **核销记录** | 全门店核销明细；结算额核对 | -| **待处理核销** | 弱网拍照等人工业务单；T+0 补核销 | -| **核销调试** | 联调/排障工具 | +| 智能机器人 | `/wecom/bots` 长连接指令 | +| 消息推送 | `/wecom/pushes` Webhook+eventKey | +| 日志 | `/logs/wecom-bots` | -### 15.3 处理原则 - -- 补发券、作废、补核销必须留备注与操作日志 -- 退款类售后需同步评估是否回收未使用权益（按工单审批结果执行） -- 门店结算与核销记录交叉核对，避免重复入账 +eventKey：`alert.ops` · `support_ticket.created` · `dev_plan.task_dispatch` · 支付/核销/结算告警。 --- -## 16. 系统设置模块 +## 附录 -路径：**系统设置**。按分组授权（非超管可能只见部分 Tab）。 -敏感基础设施（数据库、JWT、端口等）**仅存服务器 `.env`**，不在本页维护。 - -### 16.1 功能开关 - -| 配置项 | 作用 | -|--------|------| -| Mock 短信 | 不发真实短信；验证码入库可查 | -| Mock 支付 | 关闭且商户参数齐全时走真实 JSAPI | -| Mock 微信授权 | 关闭且 AppID/Secret 齐全时走真实微信 | -| Mock 配送自动完成 | 联调自动推进配送状态 | -| 门店自动审核通过 | 录店免人工审（试点） | -| 启用企微机器人长连接 | 总开关；开启后连接 HQ「企微机器人」中已启用实例（见 §17） | - -标注「即时」的项保存后写入运行配置即可生效；「需重启」项改完需重启 API。 -企微 Bot 的 BotID/Secret **不在系统设置里配置**，改在独立菜单 **企微机器人**。 - -### 16.2 短信 - -- 签名、默认模板、核销确认模板、代下单模板 -- 阿里云 AccessKey（密钥类需重启） -- Mock 开启时可在页内查看最近验证码列表 - -### 16.3 微信 - -- 服务号 AppID/Secret -- 小程序 AppID/Secret -- 商户号、证书序列号、商户私钥、APIv3 密钥、平台证书 -- 支付回调 URL - -用于登录授权、JSAPI/小程序支付、回调验签。 - -### 16.4 微信小程序展示 - -- 首页轮播图（建议 15:8，最多 8 张） -- 首页底部图（建议 15:4） -上传后需点击 **保存**。 - -### 16.5 对象存储 OSS - -AccessKey、Bucket、Region、Endpoint、CDN 域名、上传前缀、凭证有效期、单文件大小上限等。商品图、发票文件、门店证照均依赖此配置。 - -### 16.6 应用链接 - -- C 端 H5 落地页（推广码二维码链接前缀） -- 腾讯位置服务 Key（逆地理/热力图等） - -### 16.7 发布部署 - -Webhook URL / Secret，供发版流水线回调（与 `@dukang-release` 发布流程配合）。 - -### 16.8 酒厂银行账户 - -户名、开户银行、支行、账号——财务打款对照。 - -### 16.9 相关管理页 - -| 页面 | 说明 | -|------|------| -| 权限分配 | 角色默认权限 + 账号额外权限 | -| HQ 账户 | 创建总部登录账号并指定角色 | -| 日志 | 用户/商户/合伙人/HQ 操作日志、第三方调用日志 | - ---- - -## 17. 企业微信对接 - -本节区分两套能力，勿混用： - -1. **C 端在线客服链接**（用户进人工会话） -2. **HQ 企微智能机器人**（内部同事用指令操作业务；命令式，**不依赖大语言模型**） - -### 17.1 在线客服（微信客服 / 企微客服） - -C 端「联系客服 → 在线客服」跳转企业微信 **微信客服** 链接，在微信内打开后进入原生客服会话。 - -| 项 | 说明 | -|----|------| -| 默认链接 | 配置于 `packages/shared-types` 的 `CUSTOMER_SERVICE_WECOM_URL` | -| 前端覆盖 | H5 可用环境变量 `VITE_CS_WECOM_URL` | -| 电话兜底 | `CUSTOMER_SERVICE_PHONE`（如 400 热线） | -| 使用限制 | 须在 **微信内** 打开；需用户点击手势触发 | - -小程序端优先使用小程序客服能力；非微信环境提示拨打电话。 - -### 17.2 HQ 企微机器人（智能机器人长连接） - -入口：**HQ → 企微机器人**（权限键 `wecom_bots`）。 -技术通道：企业微信「智能机器人」长连接 SDK；产品名带「智能」，本系统实现为 **关键词/指令路由**，**不必接入 AI 语言模型即可生效**。 - -#### 配置字段 - -| 字段 | 说明 | -|------|------| -| 名称 | 会话内展示用名称 | -| 角色 | 客服 / 技术支持 / 团队助手 / 自定义（决定默认权限） | -| BotID / Secret | 企微管理后台创建智能机器人后下发；每实例一对 | -| 头像 | OSS 上传（可选） | -| 欢迎语 | 进入会话时推送（可选） | -| 权限 | 可勾选能力；创建时按角色带出默认值，可改 | -| 启用 AI 问答 | 未匹配指令时调用绑定的语言模型 | -| 语言模型 | 选自 HQ「语言模型」中已生效配置（非超管仅能选自己创建的） | -| 知识库 | 选自 HQ「知识库」；检索片段注入模型上下文 | -| 启用 | 关闭则不建立长连接 | - -保存后可用页内 **重载连接**，或依赖总开关变更后的自动重载。每个已启用 Bot 同时仅保持 **1 条** 长连接。 - -#### 语言模型与知识库（与企微同级菜单） - -| 模块 | 权限键 | 规则摘要 | -|------|--------|----------| -| 语言模型 | `llm_configs` | 可选 DeepSeek / OpenAI / 通义千问 / 自定义 OpenAI 兼容 API。**超级管理员**可看改删全部；**其他 HQ** 只能看到自己创建的配置，创建后仅能改「是否生效」，不能改 Key/模型等，也不能删除 | -| 知识库 | `knowledge_bases` | 粘贴正文或上传 `.txt/.md` 等文本；非超管仅管理自己创建的库 | - -企微侧流程：先建语言模型（并测试）→ 建知识库并上传文档 → 机器人表单开启 AI 并绑定。指令仍优先；仅未匹配时走模型。 - -#### 总开关 - -**系统设置 → 功能开关 → 启用企微机器人长连接**（`WECOM_AIBOT_ENABLED`）。 -总开关关闭时，即使 HQ 里已配置 Bot，也不连企微。 - -#### 预置角色与默认权限 - -| 角色 | 默认权限 | 典型用途 | -|------|----------|----------| -| 客服机器人 | 创建售后工单；查用户（短信验证）；查快递 | 客服在企微会话内快速建单、核身份、跟物流 | -| 技术支持机器人 | 创建技术支持工单；查看开发进度 | 内部提单 BUG/建议、查工单状态 | -| 团队助手 | 查询使用手册 | 按关键词答运营/协作常识（摘自知识库摘要） | -| 自定义 | 无（自行勾选） | 组合权限 | - -权限目录：`ticket.create` · `user.view_sms` · `delivery.view` · `support_ticket.create` · `support_ticket.progress` · `handbook.query`。 - -#### 常用指令（会话内发文本） - -通用：`帮助` · `状态` - -| 权限 | 指令示例 | -|------|----------| -| 售后工单 | `工单 <订单号> <类型> [备注]`（类型：仅退款 / 破损补发 / 破损退货 / 退货退款） | -| 查用户 | `查用户 <手机号>` → `验证 <验证码>`（验证通过后返回用户摘要） | -| 查快递 | `快递 <订单号\|运单号>` | -| 技术支持提单 | `提单 <标题> [| 详情]` | -| 开发进度 | `进度`（最近）· `进度 <工单号>` | -| 使用手册 | `手册`（目录）· `手册 <关键词>`（如：开城、核销、订单） | - -未匹配指令时：若已启用 AI 并绑定模型，则走语言模型（可带知识库）；否则回复「帮助」文案。暂仅支持 **文本**。 - -> 接语言模型是**可选增强**，不是长连接生效的前提；纯指令机器人仍可独立使用。 - -#### 启用步骤（运营/研发） - -1. 企业微信管理后台创建「智能机器人」，取得 BotID、Secret -2. HQ「企微机器人」创建实例，填名称/角色/凭证/权限并启用 -3. 系统设置打开 **启用企微机器人长连接** -4. 在企微中把机器人加到会话，发送 `帮助` 验证 -5. 改配置或凭证后点 **重载连接**（或重启 API） - -> **说明**：不接大模型也能完成指令表能力。开启 AI + 知识库后，可用自然语言问答；写操作（建单等）仍建议走固定指令。 - -### 17.3 与总部客服 / 技术支持的协作 - -**人工客服链路（C 端用户）** - -1. 用户通过在线客服链接进入企微/微信客服会话，说明问题并提供订单号 -2. HQ **客服** 在用户/订单/工单中心处理，或经 **客服机器人** 用指令建售后工单 -3. 需研发介入时，在 HQ 或经 **技术支持机器人** 创建技术支持工单，超管评审 -4. 退款/补发结果回传用户（短信或会话） - -**内部同事**：优先用对应角色机器人发指令，减少反复进后台翻页；敏感查用户仍须短信验证码。 - -### 17.4 微信生态相关（易混淆对照） - -| 能力 | 是否企微 | 配置位置 | -|------|----------|----------| -| C 端微信客服链接 | 是（客服入口） | 代码常量 / `VITE_CS_WECOM_URL` | -| HQ 企微智能机器人 | 是（长连接指令助手） | HQ「企微机器人」+ 功能开关总开关 | -| 服务号 OAuth / 支付 | 否（微信开放平台/商户） | 系统设置 → 微信 | -| 小程序登录支付与首页素材 | 否 | 系统设置 → 微信 / 微信小程序 | -| 微信绑定查询 | 否 | HQ「微信绑定」页（OpenID/UnionID 多端身份） | - -### 17.5 运营注意 - -- 更换 C 端客服链接时同步改 shared-types 默认值或各端环境变量并重新发布前端 -- 企微侧客服账号、机器人可见范围、会话分配在 **企业微信管理后台** 维护；本系统不托管企微通讯录 -- Bot Secret 仅 HQ 创建/编辑时写入，列表不回明文；泄露后应在企微后台重置并更新 HQ 配置后重载 -- 工作时间话术与 PRD OPT-012 对齐（上线后 3 日内更新） - -### 17.6 运营告警 Webhook（群机器人） - -与 §17.2 **智能机器人长连接**（会话内指令）不同：本能力用企业微信 **群机器人 Webhook** 单向推送异常，不依赖 BotID/Secret。 - -| 配置项 | 说明 | -|--------|------| -| `WECOM_ALERT_ENABLED` | 总开关（HQ 功能开关可改；亦可写 `.env`） | -| `WECOM_ALERT_WEBHOOK_URL` | 群机器人 Webhook 完整 URL，**仅服务器 `.env`**，勿提交仓库 | -| `WECOM_ALERT_ENV_LABEL` | 消息前缀环境名（local / staging / production） | - -启用步骤：企微群 → 添加群机器人 → 复制 Webhook → 写入服务器环境变量 → 打开 `WECOM_ALERT_ENABLED`。 - -| 类别 | 典型触发 | -|------|----------| -| API | 未捕获异常 / HTTP ≥500 / Prisma 已知错误 | -| 支付 | 金额 `<1` 或 `>5000` 元；1 分钟尝试 `>3`；1 分钟失败 `>5`；回调失败；金额不一致 | -| 核销 | 金额 `<1` 或 `>1000` 元；1 分钟尝试 `>3`；1 分钟失败 `>5`；弱网达阈值；新建补核销待办 | -| 订单 | 超时未关待付款；待发货 >24h；配送中 >48h（每 5 分钟扫描） | -| 运维 | MySQL/Redis 探活失败；结算 Cron 失败；新建售后/技术支持工单 | -| 客户端 | `POST /api/v1/common/client-errors`：`fatal`→P0、`error`→P1；`warn` 只记日志/落库不推群 | - -#### 客户端报错上报 - -| 项 | 说明 | -|----|------| -| 接口 | `POST /api/v1/common/client-errors`（可匿名；带 JWT 时附带用户身份） | -| Body | `level`（fatal/error/warn）、`category`（js_error / unhandled_rejection / api_error / network / render / bridge / other）、`message`、可选 `stack` / `pagePath` / `clientApp` / `extra` | -| 日志 | Nest `Logger` 打 `[client_error]`；并写入 `log_user_analytics`（`event_name=client_error`） | -| 企微 | 仅 `fatal`/`error`；同指纹 10 分钟去重 | -| 前端 | mini-user、`h5-shop`、`h5-partner` 启动时 `installClientErrorReporting()`：全局 `error` / `unhandledrejection`（mini-user 另挂 Taro 钩子） | - -告警经 Redis 去重（同指纹默认 10 分钟内不重复推）；**只通知、不拦截**交易与核销。Webhook key 泄露时在企微后台重置机器人并更新 `.env`。 - ---- - -## 附录 A · 端职责矩阵 - -| 能力 | 用户端 | 门店端 | 合伙人端 | 总部端 | -|------|:------:|:------:|:--------:|:------:| -| 下单/支付/权益 | ● | | 代下单 | 代下单 | -| 核销 | 出码 | ● | 看记录 | 看全量 | -| 拓店 | 看门店 | 改营业 | ●录入 | ●审核 | -| 工单 | ●发起 | 查看 | 查看 | ●决策 | -| 结算提现 | | ● | 对账确认 | ●审打款 | -| 推广码/问卷/评价 | ● | 被评价 | 看数据 | 配置/看板 | - -## 附录 B · 相关文档 - -| 文档 | 用途 | -|------|------| -| `杜康好客-v3-PRD.md` | 唯一需求事实源 | -| `杜康好客-v3-现状对照.md` | 已完成 / 缺口审计 | -| `杜康好客-v3编码手册.md` | 实现与验收 | -| `杜康好客-v3-城市仓库与日志架构.md` | 开城/仓/日志技术说明 | -| `AGENTS.md` / `conventions.md` | 工程协作与模块边界 | -| `pages/ROUTE_MAP.md` | 原型屏与路由对照 | - -## 附录 C · 变更说明 - -本知识库用于培训与协作，**不替代 PRD**。若业务规则变更，须先改 `杜康好客-v3-PRD.md`，再同步本文件与编码手册。 +**端职责矩阵** → PRD §4.5 +**文档索引**：PRD · 编码手册 · 现状对照 · v3.4.x 开发文档 · 埋点规范 · 城市日志架构 +**变更**：随 v3.4.x 版本文档更新，不在此重复 ST 明细。 diff --git a/杜康好客-门店套餐功能开发文档-v3.4.10.md b/杜康好客-门店套餐功能开发文档-v3.4.10.md index 62eefc6..39d604f 100644 --- a/杜康好客-门店套餐功能开发文档-v3.4.10.md +++ b/杜康好客-门店套餐功能开发文档-v3.4.10.md @@ -1,372 +1,38 @@ -# 杜康好客 · 门店套餐功能开发文档 +# 杜康好客 · 门店套餐 v3.4.10 -> **版本**：3.4.10 -> **日期**：2026-08-03 -> **状态**：需求已定 / 待实现 -> **关联**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) §3.9 · REQ-P-027 / REQ-S-021 / REQ-H-025 / REQ-U-027 +> PRD §3.9 · REQ-P/S/H/U-027 · **已实现**（含 v3.4.12 `imageUrl`） -## 变更记录 +## 要点 -| 版本 | 日期 | 说明 | -|------|------|------| -| **3.4.10** | 2026-08-03 | 新增门店套餐需求与开发设计 | +- 与酒水 SKU 独立；每店 ≤10 条；字段：名称/价格/菜品/使用时间/说明 +- C 端仅展示**已审核生效**套餐；异议类型 `PACKAGE_DISPUTE` +- 合伙/门店：编辑 → **提交审核**；HQ：门店详情 Tab **直存生效** +- 审核通过：事务替换 `store_package`；驳回保留上一版；同店仅 1 条 `PENDING` ---- +## 表 -## 目录 - -1. [背景与目标](#1-背景与目标) -2. [数据模型](#2-数据模型) -3. [API 草案](#3-api-草案) -4. [四端 UI](#4-四端-ui) -5. [审核与展示状态机](#5-审核与展示状态机) -6. [客服「套餐异议」](#6-客服套餐异议) -7. [验收清单（ACC）](#7-验收清单acc) -8. [实现分期建议](#8-实现分期建议) - -### 流程概览 - -```mermaid -flowchart LR - partnerEdit[PartnerOrShopEdit] - draft[PackageChangeRequest] - hqReview[HqApproveOrReject] - live[LiveStorePackages] - mini[MiniStoreDetail] - dispute[PackageDisputeTicket] - partnerEdit --> draft - draft --> hqReview - hqReview -->|APPROVED| live - live --> mini - mini --> dispute - hqDirect[HqDirectSave] --> live -``` - ---- - -## 1. 背景与目标 - -门店可向 C 端用户展示餐饮套餐信息，帮助用户在核销前了解可核销内容。套餐与酒水 SKU 无关，需独立数据模型与审核流。 - -### 1.1 需求原文（10 条） - -1. **合伙人新建门店**：在现有拓店流程（基本信息 / 照片 / 结算资质）后增加「套餐」页；可不填、可跳过。 -2. **套餐字段**：套餐名称、价格（元）、菜品、使用时间、其他说明。 -3. **C 端门店详情**：在「门店详情」区块附近，以纵向列表展示套餐；每条为「标题 + 内容」形式。 -4. **数量约束**：可不填；可多条；**同一门店最多 10 条**。 -5. **门店端**：新增套餐列表页，可编辑并**提交审核**。 -6. **合伙人端**：选择门店 → 套餐列表 → 编辑 → **提交审核**。 -7. **总部端**：门店详情新增「套餐」Tab，**直接保存生效、无需审核**。 -8. **审核流**：合伙/门店提交 → 总部通过/驳回；**通过后自动替换生效套餐**。 -9. **C 端展示**：仅展示**已审核通过（生效中）**的套餐。 -10. **客服异议**：用户对核销中套餐有异议 → 客服申诉类型新增 **套餐异议**。 - -### 1.2 现状对齐 - -| 现状 | 影响 | -|------|------| -| 无门店套餐实体；`Store.tags` Json 未承载套餐 | 需新建表，不复用酒水 SKU | -| 合伙人拓店三步：基本信息 / 照片 / 结算资质 | 新增「套餐」页（第 4 步或独立页） | -| 门店端仅改营业状态，**无资料编辑 API** | 需新增门店端套餐 CRUD + 提审 API | -| 门店审核仅 `NEW`/`RESUBMIT` 整店审，**无「套餐变更」独立审核** | 需独立「套餐变更审核」模型 | -| 售后工单四类型无「套餐异议」 | 扩展工单/客服类型 | -| C 端详情已有 intro / 权益规则 / 环境图 | 在「门店详情」区块附近增加套餐纵向列表 | - -### 1.3 明确不做（本文档阶段） - -- 不改 Prisma / 不写 API / 不改四端业务代码（本文档仅设计） -- 不把套餐挂到商品目录 `CommonProductItem` -- 不合并进整店 `Store.auditStatus`（套餐变更独立提审） - ---- - -## 2. 数据模型 - -### 2.1 生效数据 `StorePackage`（表名 `store_package`） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | String (cuid) | 主键 | -| `storeId` | String | 门店 ID，FK → `Store` | -| `name` | String | 套餐名称，如「套餐A」 | -| `price` | Decimal | 价格（元） | -| `dishes` | Text | 菜品文案；前端按顿号/换行展示；或 Json 字符串数组 | -| `usableTime` | String? | 使用时间，如「节假日除外」 | -| `otherNotes` | String? | 其他说明，如「不可叠加」 | -| `sortOrder` | Int | 展示序 0~9 | -| `createdAt` | DateTime | | -| `updatedAt` | DateTime | | - -**约束** - -- 同一 `storeId` 下生效套餐 **≤ 10** 条 -- 删除/替换由审核通过或总部直存事务完成 - -### 2.2 变更提审 `StorePackageChangeRequest`（表名 `store_package_change_request`） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | String (cuid) | 主键 | -| `storeId` | String | 门店 ID | -| `status` | Enum | `PENDING` / `APPROVED` / `REJECTED` | -| `packagesJson` | Json | 提审快照（完整套餐数组，最多 10 条） | -| `submitterType` | Enum | `PARTNER` / `SHOP` | -| `submitterId` | String | 提交人 ID | -| `rejectReason` | String? | 驳回原因 | -| `reviewedAt` | DateTime? | | -| `reviewerId` | String? | 总部审核人 | -| `createdAt` | DateTime | | - -**规则** - -- 同门店同时仅允许 **一条 `PENDING`** -- 审核 **通过**：事务内删除该店全部 `StorePackage`，按 `packagesJson` 重建 -- 审核 **驳回**：不改动生效表；提审方可修改后再提 - -### 2.3 提审快照 JSON 结构（`packagesJson` 数组元素） - -```json -{ - "name": "套餐A", - "price": "198.00", - "dishes": "红烧肉、红烧鱼、油焖茄子", - "usableTime": "节假日除外", - "otherNotes": "不可叠加", - "sortOrder": 0 -} -``` - -### 2.4 总部直存 - -- 写 `StorePackage`，**不写** `StorePackageChangeRequest` -- 可选记 `CommonEvent`（如 `STORE_PACKAGE_UPDATE`）留痕 - -### 2.5 枚举（建议写入 `packages/shared-types`） - -```typescript -enum StorePackageChangeStatus { - PENDING = 'PENDING', - APPROVED = 'APPROVED', - REJECTED = 'REJECTED', -} - -enum StorePackageSubmitterType { - PARTNER = 'PARTNER', - SHOP = 'SHOP', -} - -// 扩展工单类型 -enum TicketType { - // ...existing - PACKAGE_DISPUTE = 'PACKAGE_DISPUTE', -} -``` - ---- - -## 3. API 草案 - -> 路径前缀均为 `/api/v1`；响应 `{ code, message, data }`。 - -### 3.1 合伙人端 - -| 方法 | 路径 | 说明 | 权限 | -|------|------|------|------| -| GET | `/partner/stores/:storeId/packages` | 读草稿/生效套餐（见实现约定） | 管辖门店 | -| PUT | `/partner/stores/:storeId/packages` | 提交套餐变更审核（body=套餐数组） | 管辖门店 | -| GET | `/partner/stores/:storeId/package-change-requests` | 历史提审记录 | 管辖门店 | - -**拓店草稿**：新建流程中套餐可先写入 `storeDraft.packages`，门店创建成功后随首次提审或总部审核入库。 - -### 3.2 门店端（新增能力） - -| 方法 | 路径 | 说明 | 权限 | -|------|------|------|------| -| GET | `/shop/store/packages` | 当前门店套餐（草稿+生效） | 门店主账号/店员 | -| PUT | `/shop/store/packages` | 提交套餐变更审核 | 门店主账号 | - -> 现状：门店端无资料编辑 API，本模块为 **新增** Shop Store API。 - -### 3.3 总部端 - -| 方法 | 路径 | 说明 | 权限 | -|------|------|------|------| -| GET | `/admin/stores/:storeId/packages` | 读生效套餐 | HQ | -| PUT | `/admin/stores/:storeId/packages` | **直存**生效（无需审核） | HQ | -| GET | `/admin/store-package-audits` | 待审/历史列表 | HQ | -| PUT | `/admin/store-package-audits/:requestId/audit` | 通过/驳回 | HQ | - -**审核 body 示例** - -```json -{ - "action": "APPROVE" -} -``` - -```json -{ - "action": "REJECT", - "rejectReason": "价格描述不清晰" -} -``` - -### 3.4 C 端（公开） - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET | `/stores/:storeId` | 门店详情 **嵌入** `packages[]`（仅生效） | -| GET | `/stores/:storeId/packages` | 可选独立接口，仅返回生效套餐 | - -**响应字段（单条）** - -```json -{ - "name": "套餐A", - "price": "198.00", - "dishes": "红烧肉、红烧鱼、油焖茄子", - "usableTime": "节假日除外", - "otherNotes": "不可叠加", - "sortOrder": 0 -} -``` - -### 3.5 客服异议 - -扩展创建售后/客服工单： - -| 字段 | 说明 | -|------|------| -| `ticketType` | `PACKAGE_DISPUTE` | -| `storeId` | 必填 | -| `redeemRecordId` | 可选，关联核销单 | - ---- - -## 4. 四端 UI - -### 4.1 合伙人端（H5） - -| 页面 | 路径建议 | 说明 | -|------|----------|------| -| 拓店·套餐 | `/stores/create/packages` | 第 4 步；可跳过；数据进 `storeDraft` | -| 门店详情·套餐入口 | 门店详情页 | 跳转套餐列表 | -| 套餐列表 | `/stores/:id/packages` | 展示当前生效 + 待审状态 | -| 套餐编辑 | `/stores/:id/packages/edit` | 表单：名称/价格/菜品/时间/说明；最多 10 条 | -| 提交审核 | 编辑页底部 | PUT 提审；同店有 PENDING 时禁用 | - -参考：`apps/h5-partner/src/pages/StoreCreatePage.tsx` - -### 4.2 门店端（H5） - -| 页面 | 路径建议 | 说明 | -|------|----------|------| -| 套餐列表 | `/packages` | 新入口（门店信息 Tab 或独立菜单） | -| 套餐编辑 | `/packages/edit` | 同合伙人表单 | -| 提交审核 | 编辑页底部 | PUT `/shop/store/packages` | - -### 4.3 总部端（admin-web） - -| 页面 | 说明 | -|------|------| -| 门店详情 Drawer · Tab「套餐」 | 在 `StoresPage.tsx` Drawer 增加 Tab；表单直存 | -| 套餐变更审核列表 | 独立页或门店内待审提示；通过/驳回 | - -参考：`apps/admin-web/src/pages/StoresPage.tsx` - -### 4.4 用户端（mini-user） - -| 位置 | 说明 | -|------|------| -| 门店详情 · 「门店详情」区块上方或下方 | 纵向卡片列表 | -| 单条样式 | 标题 = 套餐名；内容 = 价格 / 菜品 / 使用时间 / 其他说明 | -| 空态 | 无生效套餐时不展示该区块 | - -参考：`apps/mini-user/src/pages/store-detail/index.tsx` - -### 4.5 C 端展示示例 - -``` -套餐A -198 元 · 红烧肉、红烧鱼、油焖茄子 -使用时间：节假日除外 -说明：不可叠加 -``` - ---- - -## 5. 审核与展示状态机 - -```mermaid -stateDiagram-v2 - [*] --> NoLive: 从未通过 - NoLive --> Live: 首次审核通过 / 总部直存 - Live --> Pending: 合伙/门店提审 - Pending --> Live: 审核通过（覆盖） - Pending --> Live: 审核驳回（保留旧 Live） - Live --> Live: 总部直存（覆盖） -``` - -| 状态 | C 端展示 | 编辑方可见 | -|------|----------|------------| -| 无生效套餐 | 不展示套餐区块 | 可编辑、可提审 | -| 有生效 + 无待审 | 展示生效版 | 可编辑、可提审 | -| 有生效 + 待审中 | **仍展示上一版生效** | 显示「审核中」；不可重复提审 | -| 审核通过 | 展示新版 | 可再次编辑提审 | -| 审核驳回 | 仍展示旧版 | 可修改后再提；展示驳回原因 | - ---- - -## 6. 客服「套餐异议」 - -| 项 | 说明 | +| 表 | 用途 | |----|------| -| 类型文案 | 套餐异议 | -| 枚举 | `PACKAGE_DISPUTE` | -| 入口 | C 端核销相关页 / 门店详情 / 客服页可选该类型 | -| 关联 | `storeId` 必填；可选 `redeemRecordId` | -| 总部 | 客服工单列表可按类型筛选处理 | +| `store_package` | 生效套餐（含 `image_url`） | +| `store_package_change_request` | 提审快照 `packagesJson` | -与现有四类型工单并列，不替换原有类型。 +## API（前缀 `/api/v1`） ---- +| 端 | 路径 | +|----|------| +| partner | `GET/PUT /partner/stores/:id/packages` · 变更历史 | +| shop | `GET/PUT /shop/store/packages` | +| admin | `GET/PUT /admin/stores/:id/packages` · `/admin/store-package-audits` 审 | -## 7. 验收清单（ACC） +## 流程 -| ID | 对应需求 | 验收项 | -|----|----------|--------| -| ACC-PKG-01 | #1 | 合伙人拓店流程有「套餐」页，可跳过；跳过后门店可无套餐 | -| ACC-PKG-02 | #2 | 单条套餐含名称、价格、菜品、使用时间、其他说明五字段 | -| ACC-PKG-03 | #3 | C 端门店详情以纵向标题+内容展示套餐 | -| ACC-PKG-04 | #4 | 同一门店生效套餐 ≤10；第 11 条保存/提审被拒绝 | -| ACC-PKG-05 | #5 | 门店端可列表、编辑、提交审核 | -| ACC-PKG-06 | #6 | 合伙人可选门店、编辑套餐、提交审核 | -| ACC-PKG-07 | #7 | 总部门店详情「套餐」Tab 直存后 C 端立即可见（无需审核） | -| ACC-PKG-08 | #8 | 合伙/门店提审 → 总部通过后生效表被完整替换；驳回后生效表不变 | -| ACC-PKG-09 | #9 | C 端 never 展示未通过/待审套餐；提审中仍展示旧版 | -| ACC-PKG-10 | #10 | 用户可创建「套餐异议」工单；总部可按类型筛选 | -| ACC-PKG-11 | — | 同门店仅一条 PENDING；重复提审返回业务错误 | -| ACC-PKG-12 | — | 空套餐数组提审合法；通过后 C 端不展示套餐区块 | -| ACC-PKG-13 | — | 总部直存记事件或审计日志（若启用 CommonEvent） | +``` +partner/shop 编辑 → PENDING → HQ 通过/驳回 → 生效 → mini-user 展示 +HQ 直存 ──────────────────────────────→ 生效 +``` ---- +## ACC -## 8. 实现分期建议 - -| 阶段 | 范围 | 交付 | -|------|------|------| -| **M1** | 表结构 + 总部直存 + C 端展示 | Prisma 迁移、`StorePackage` CRUD（admin）、mini-user 展示 | -| **M2** | 合伙人新建/编辑提审 + 总部审核 | `StorePackageChangeRequest`、partner 页面、admin 审核 | -| **M3** | 门店端提审 | Shop API + h5-shop 页面 | -| **M4** | 套餐异议工单类型 | `PACKAGE_DISPUTE` 枚举、C 端入口、admin 筛选 | - ---- - -## 附录：REQ 映射 - -| REQ | 端 | 内容 | -|-----|----|------| -| REQ-P-027 | 合伙人 | 拓店套餐页 + 门店套餐列表/编辑/提审 | -| REQ-S-021 | 门店 | 套餐列表/编辑/提审 | -| REQ-H-025 | 总部 | 门店详情套餐 Tab 直存；套餐变更审核通过/驳回 | -| REQ-U-027 | 用户 | 门店详情展示生效套餐；套餐异议申诉入口 | +- [ ] 四端展示 imageUrl；HQ 可删至 0 条 +- [ ] 提审中 C 端仍见上一版；通过后替换 +- [ ] 套餐异议工单可创建