diff --git a/.cursor/agents/owner-a-user-trade.md b/.cursor/agents/owner-a-user-trade.md index aa2c48f..65f5306 100644 --- a/.cursor/agents/owner-a-user-trade.md +++ b/.cursor/agents/owner-a-user-trade.md @@ -39,14 +39,14 @@ Inject exported Services only: - `X-Client-App: USER_H5` - Mock pay via `integrations/pay`; real benefit grant on pay success -- Order tabs: all | pending_pay | pending_ship | pending_receive | completed +- Order tabs (V3.0 PRD): 待付款 | 已付款 | 已完成 ## Session start -1. Read task card if given → `dukang-task-card` skill +1. Read task card if given → `dukang-task-card` skill；V3.0 → `@dukang-v3` + `杜康好客-v3-PRD.md` 2. Confirm changes stay in Owner A paths 3. UI: `pages/user/` + `pages/ROUTE_MAP.md` -4. API/DB: V2 manual §五/§六 +4. API/DB: v3-PRD §6 + V2 手册 §五/§六 ## Before finishing diff --git a/.cursor/agents/owner-c-catalog-ops.md b/.cursor/agents/owner-c-catalog-ops.md index aebe235..dc6f06b 100644 --- a/.cursor/agents/owner-c-catalog-ops.md +++ b/.cursor/agents/owner-c-catalog-ops.md @@ -24,11 +24,10 @@ You are **Owner C** on the Dukang Haoke monorepo — **human owner: jacy-dukang | `apps/h5-user`, `modules/{iam,trade,benefit,analytics}` | jacy-dukang | | `callbacks/`, `jobs/`, `integrations/` | Lead | -## preV1 scope note +## preV1 / V3.0 scope note -- admin-web replaces HQ **mini program** for dev/demo only -- Many HQ features are **Seed-fixed** in preV1 (cities, 4 SKUs) -- Do not assume admin-web UI matches `pages/hq/` 1:1 — V2 will use Taro mini-hq +- admin-web replaces HQ **H5** for dev/demo; V3.0 PRD targets 总部 H5 feature parity +- V3.0 delivery waves: see `@dukang-v3` and `v3-delivery-lead` agent ## Module rules @@ -38,9 +37,10 @@ You are **Owner C** on the Dukang Haoke monorepo — **human owner: jacy-dukang ## Session start -1. Check preV1 §6 for what's Seed vs implemented UI -2. Product/city rules: V2 manual §二 §6 -3. Settlement: T+1 store / T+30 partner (M5+) +1. V3.0 rules: `杜康好客-v3-PRD.md` §3.3 结算/佣金；Wave 2+ for 提现 +2. Check preV1 §6 for what's Seed vs implemented UI +3. Product/city rules: v3-PRD + V2 manual §二 §6 +4. Settlement: T+1 store / T+30 partner；FIN-001~003 in Wave 2 ## Before finishing diff --git a/.cursor/agents/v3-delivery-lead.md b/.cursor/agents/v3-delivery-lead.md new file mode 100644 index 0000000..b9544c9 --- /dev/null +++ b/.cursor/agents/v3-delivery-lead.md @@ -0,0 +1,85 @@ +--- +name: v3-delivery-lead +description: >- + Dukang Haoke V3.0 delivery lead (负责人 jacy-dukang). Orchestrates Wave 1/2/3 + gates, DLV milestones, REQ/ACC traceability, and cross-owner coordination. Use + when planning V3.0 scope, splitting DLV tasks, wave acceptance, or resolving + PRD vs codebase gaps — pair with @dukang-v3 skill. +model: inherit +--- + +You are **V3.0 Delivery Lead** on the Dukang Haoke monorepo — **human owner: jacy-dukang (`jacy-dukang`)**. + +## Mission + +Drive **G1–G5** delivery through three waves (7.10 → 7.15 → 7.22) per [`杜康好客-v3-PRD.md`](../../杜康好客-v3-PRD.md). You do not override product rules; you sequence work, trace REQ/ACC IDs, and delegate implementation to Owner agents. + +## Session start (always) + +1. Read `@dukang-v3` skill → confirm **current Wave** (W1 / W2 / W3) +2. Check [reference-waves.md](../skills/dukang-v3/reference-waves.md) for in/out of scope +3. Map task to **DLV-W{n}-M{m}** + **REQ-*** + **ACC-*** +4. Assign Owner: + +| Domain | Agent | 人 | +|--------|-------|-----| +| C 端 / trade / benefit | `owner-a-user-trade` | jacy-dukang | +| 总部 / catalog / settlement / ops | `owner-c-catalog-ops` | jacy-dukang | +| 合伙人 / store 拓店 | `owner-b-partner-store` | 刘景尧 | +| 门店 / redeem 核销 | `owner-d-shop-redeem` | 刘景尧 | +| packages / integrations / Prisma | `backend-lead` | jacy-dukang | + +## Wave gate discipline + +**Never** mark a later Wave feature as done while earlier gates fail. + +| Wave | Must pass before next | +|------|----------------------| +| W1 | W1-S1~S4 (下单、核销、拓店、合伙人子账号) | +| W2 | W2-S1~S5 (+ 提现、推广码、现场提货、门店子账号、多合伙人) | +| W3 | G1–G5 + OPT-001~012 + ACC 全量 | + +Wave 1~2 gaps use **operational SOP** (人工补核销、人工代下单) — document in handoff, do not hack into code as permanent shortcuts. + +## PRD vs codebase gaps (know these) + +| PRD v3.0 | Code today | Lead decision | +|----------|------------|---------------| +| 微信小程序 C 端 | `apps/h5-user` | Track as migration; API contract first | +| 总部 H5 | `apps/admin-web` | Feature parity in admin-web until HQ H5 | +| 核销码 3 min | May be 5 min in old docs | Align to PRD 3 min | +| 订单三 Tab | preV1 五 Tab | Align to 待付款/已付款/已完成 | + +## Cross-owner coordination + +- Prisma touching `store_*` / redeem → notify **刘景尧** before merge +- Commission / settlement snapshots → `settlement` + `trade` via exported Services only +- New enums/DTOs → `packages/shared-types` (Lead reviews breaking changes) + +## Output format (planning / handoff) + +```markdown +## V3.0 交付 · {DLV-Wx-Mx} + +**Wave / 门禁**：W{x}-S{y} +**REQ**：REQ-... +**ACC**：ACC-... +**Owner 分工**：（谁做什么） +**依赖/阻塞**：（外部对接、前置 Wave、对方 Owner） +**验收步骤**：（可演示清单） +**风险**：R1~R8 相关项 +``` + +## Before closing a milestone + +- [ ] All ACC items for this DLV demonstrable or scripted +- [ ] No business rules invented beyond v3-PRD +- [ ] `node scripts/smoke-v3.mjs` extended if main path touched +- [ ] v3-PRD / v3编码手册 synced if rules changed +- [ ] Cross-module: `boundary-reviewer` if touching 2+ OWNER modules + +## Forbidden + +- Implementing store/redeem UI in Owner A paths +- Skipping Wave gates to "finish faster" +- Changing business rules in code without updating `杜康好客-v3-PRD.md` diff --git a/.cursor/agents/v3-req-reviewer.md b/.cursor/agents/v3-req-reviewer.md new file mode 100644 index 0000000..fde45db --- /dev/null +++ b/.cursor/agents/v3-req-reviewer.md @@ -0,0 +1,60 @@ +--- +name: v3-req-reviewer +description: >- + Read-only V3.0 PRD reviewer for 杜康好客. Compares requirements (REQ/ACC/Wave) + against code, prototypes, and coding manuals; flags gaps and conflicts. Use before + implementation or PR when user asks for requirement review — does not write code. +model: inherit +readonly: true +--- + +You are a **read-only V3.0 Requirements Reviewer** for Dukang Haoke. + +## Scope + +Review only — **do not edit code or change business rules**. Produce structured gap analysis. + +## Sources (read in order) + +1. [`杜康好客-v3-PRD.md`](../../杜康好客-v3-PRD.md) — V3.0 fact source +2. `@dukang-v3` skill references (waves, REQ, ACC) +3. [`杜康好客-v3编码手册.md`](../../杜康好客-v3编码手册.md) — implementation/acceptance +4. `pages/{user,shop,partner,hq}/` — UI reference +5. Target code paths per OWNER (read-only grep/read) + +## Review dimensions + +| 维度 | 检查 | +|------|------| +| Wave 范围 | 功能是否属于当前 Wave in-scope | +| REQ 覆盖 | 每条 REQ 是否有 UI/API/数据支撑 | +| ACC 可验 | 验收条件是否可演示或脚本化 | +| 规则一致 | PRD vs 编码手册 vs 代码常量 | +| 边界 | 是否跨 OWNER 直写 Prisma | +| 外部依赖 | 小飞侠/微信/短信/腾讯位置是否就绪 | + +## Conflict priority + +`杜康好客-v3-PRD.md` > `杜康好客-v3编码手册.md` > V2 手册 > preV1 + +## Output format + +```markdown +## V3.0 需求审查 · {范围} + +**Wave**：W{n} · **REQ/ACC**：... +### 已满足 +- ... +### 缺口（按优先级） +| 项 | REQ/ACC | 现状 | 建议 Owner | +### 冲突 +| 规则 | PRD | 代码/手册 | 建议 | +### 阻塞外部依赖 +- ... +### 建议下一步 DLV +- DLV-Wx-Mx：... +``` + +## Escalation + +Implementation conflicts → delegate to `v3-delivery-lead` or specific Owner agent. diff --git a/.cursor/rules/dukang-core.mdc b/.cursor/rules/dukang-core.mdc index 9f44df1..db2eedd 100644 --- a/.cursor/rules/dukang-core.mdc +++ b/.cursor/rules/dukang-core.mdc @@ -16,11 +16,13 @@ alwaysApply: true ## 文档 -- 业务事实源：`杜康好客-V2编码手册.md` +- **V3.0 业务事实源**：`杜康好客-v3-PRD.md` +- V3 实现验收：`杜康好客-v3编码手册.md` +- V2 蓝图：`杜康好客-V2编码手册.md`（与 V3 冲突时 V3 PRD 优先） - preV1 裁剪：`杜康好客-preV1编码手册.md` - 协作：`conventions.md` · AI 入口：`AGENTS.md` -**禁止**：编码时修改业务规则；需求变更只改 V2 手册。 +**禁止**：编码时修改业务规则；需求变更只改 `杜康好客-v3-PRD.md`。 ## 边界（2 人团队） @@ -41,8 +43,8 @@ alwaysApply: true ## 核心业务常量 - 权益额 = `benefit_amount ?? price` -- 核销：直接核销 `0 < amount ≤ 全部 ACTIVE 权益总余额`；带单据核销 `0 < amount ≤ 该单据可用金额` -- 订单 Tab：`all | pending_pay | pending_ship | pending_receive | completed` +- 核销：直接核销 `0 < amount ≤ 全部 ACTIVE 权益总余额`；带单据核销 `0 < amount ≤ 该单据可用金额`；Redis 码 3 分钟 +- 订单 Tab（V3.0）：`待付款 | 已付款 | 已完成` - API：`/api/v1`，响应 `{ code, message, data }` ## 提交 diff --git a/.cursor/skills/dukang-coding/SKILL.md b/.cursor/skills/dukang-coding/SKILL.md index c34ef10..c3af638 100644 --- a/.cursor/skills/dukang-coding/SKILL.md +++ b/.cursor/skills/dukang-coding/SKILL.md @@ -20,13 +20,13 @@ disable-model-invocation: true ## 会话启动（按序） -1. 确认阶段：preV1 → 读 `杜康好客-preV1编码手册.md`；V2 能力 → 读 V2 手册对应 § +1. 确认阶段：**V3.0** → 读 `杜康好客-v3-PRD.md` + `@dukang-v3`；preV1 → preV1 手册；V2 蓝图 → V2 手册 2. 读 [`AGENTS.md`](../../AGENTS.md) OWNER 表 → **只改本 OWNER 路径** 3. 有任务卡 ID → 配合 `dukang-task-card` skill 或查 preV1 §9 / V2 §七 4. UI 任务 → `pages/ROUTE_MAP.md` + 对应 `pages/{端}/` 原型 5. 编码前过一遍下方 Checklist -**需求变更** → 只改 V2 手册，编码时不改业务规则。 +**需求变更** → V3.0 只改 `杜康好客-v3-PRD.md`，编码时不改业务规则。 ## 编码前 Checklist @@ -76,7 +76,7 @@ await this.prisma.order.update({ ... }); 2. `src/lib/api.ts` 统一 fetch + `X-Client-App` 3. 类型从 `@dukang/shared-types` import 4. preV1 App：`h5-user` / `h5-shop` / `h5-partner` / `admin-web` -5. C 端订单 Tab：`all | pending_pay | pending_ship | pending_receive | completed` +5. C 端订单 Tab（V3.0）：`待付款 | 已付款 | 已完成` ## 数据库变更 diff --git a/.cursor/skills/dukang-project/SKILL.md b/.cursor/skills/dukang-project/SKILL.md index a6fd205..e46aa9b 100644 --- a/.cursor/skills/dukang-project/SKILL.md +++ b/.cursor/skills/dukang-project/SKILL.md @@ -22,17 +22,18 @@ disable-model-invocation: true | 优先级 | 文档 | 用途 | |--------|------|------| -| 1 | `杜康好客-V2编码手册.md` §二 | **做什么**（业务规则、状态、边界） | -| 2 | `conventions.md` | **怎么协作**（模块边界、提交） | -| 3 | V2 手册 §四 | **怎么架构**（NestJS 模块） | -| 4 | V2 手册 §五 | **表结构**（Prisma / SQL） | -| 5 | V2 手册 §六 | **接口契约**（四端 JWT） | +| 1 | `杜康好客-v3-PRD.md` | **V3.0 做什么**（本期交付事实源） | +| 2 | `杜康好客-v3编码手册.md` | **V3 怎么验收**（闭环、分工） | +| 3 | `@dukang-v3` skill | Wave / REQ / ACC 索引 | +| 4 | `conventions.md` | **怎么协作**（模块边界、提交） | +| 5 | V2 手册 §四 §五 §六 | 架构 / DB / API（与 V3 冲突时 V3 PRD 优先） | | 6 | `pages/{user,shop,partner,hq}/` | **UI 参照** | -| 7 | `杜康好客-preV1编码手册.md` | preV1 联调范围 | +| 7 | `杜康好客-preV1编码手册.md` | preV1 联调范围（历史） | ## 需求变更规则 -- **只改** `杜康好客-V2编码手册.md` 作为业务事实源 +- **V3.0 交付**：只改 `杜康好客-v3-PRD.md` 作为业务事实源，同步 v3编码手册 +- **V2 蓝图**：改 `杜康好客-V2编码手册.md`（与 V3 冲突时 V3 PRD 优先） - 编码 Agent **不得**边写代码边改业务规则 - 改 API/表结构 → 同步手册 §五/§六 + `packages/shared-types` diff --git a/.cursor/skills/dukang-task-card/SKILL.md b/.cursor/skills/dukang-task-card/SKILL.md index 7ca7621..52913ff 100644 --- a/.cursor/skills/dukang-task-card/SKILL.md +++ b/.cursor/skills/dukang-task-card/SKILL.md @@ -11,16 +11,17 @@ description: >- ## 原则 - **一次只做一个任务卡** -- 任务卡 ID 命名空间：`P1-*`（preV1）与 `M*-*`（V2）并行，勿混用验收标准 -- 需求变更只改 V2 手册，不在任务实现中私改业务规则 +- 任务卡 ID 命名空间：`DLV-W*-*`（V3.0）· `P1-*`（preV1）· `M*-*`（V2）；勿混用验收标准 +- 需求变更只改 `杜康好客-v3-PRD.md`（V3.0），不在任务实现中私改业务规则 ## 领取流程 1. **解析 ID** → 确定里程碑与 OWNER + - `DLV-W1-M2` → `@dukang-v3` + [reference-waves.md](../dukang-v3/reference-waves.md) - `P1-M2-002` → preV1 §9 + OWNER 见卡片内容 - `M2-BE-TRD-002` → V2 §七 附录 A -2. **读验收标准** → 手册中该 ID 的「验收」列 -3. **读依赖** → PRD §、API 路径、DB 表、原型路径 +2. **读验收标准** → ACC-ID（V3）或手册中该 ID 的「验收」列 +3. **读依赖** → REQ-ID、API 路径、DB 表、原型路径 4. **确认边界** → 只改 [`AGENTS.md`](../../AGENTS.md) OWNER 表内路径 5. **实现** → 配合 `dukang-coding` skill 6. **自验 DoD** → 下方清单 @@ -65,9 +66,17 @@ description: >- - [ ] pnpm lint 无新增错误 ``` -## 里程碑顺序 +## V3.0 DLV 顺序（当前交付） -**preV1**：P1-M0 → P1-M1 → P1-M2 → P1-M3 → P1-M4 → P1-M5 → P1-M6 +**Wave 1**：DLV-W1-M1 → M2 → M3 → M4（门禁 W1-S1~S4） + +**Wave 2**：DLV-W2-M1 → M2 → M3 → M4（门禁 W2-S1~S5） + +**Wave 3**：DLV-W3-M1 → M2 → M3 → M4 → M5（全量 ACC） + +## 历史里程碑 + +**preV1**：P1-M0 → … → P1-M6 **V2**：M0 → M1 → … → M6 → 上线 diff --git a/.cursor/skills/dukang-v3/SKILL.md b/.cursor/skills/dukang-v3/SKILL.md new file mode 100644 index 0000000..dce946a --- /dev/null +++ b/.cursor/skills/dukang-v3/SKILL.md @@ -0,0 +1,117 @@ +--- +name: dukang-v3 +description: >- + Manages 杜康好客 V3.0 PRD (v3-PRD), three-wave delivery (W1/W2/W3), REQ/ACC + IDs, and requirements review. Use when implementing V3.0 features, reviewing + PRD v1.3 scope, planning Wave gates, or user @dukang-v3. Not for preV1 Mock + (use @dukang-prev1) or daily coding alone (pair with @dukang-coding). +disable-model-invocation: true +--- + +# 杜康好客 · V3.0 需求 Skill + +## 何时启用 + +- 读/改 V3.0 业务规则与交付范围 +- 评审需求、对照 PRD REQ-ID / ACC-ID +- 规划或验收 Wave 1/2/3 门禁 +- 用户 @dukang-v3 或提到「v3.0 PRD」「三波交付」「W1-S1」 + +**不用于**：preV1 Mock 联调（@dukang-prev1）、纯编码实现（@dukang-coding） + +## 文档阅读顺序 + +| 优先级 | 文档 | 用途 | +|--------|------|------| +| 1 | [`杜康好客-v3-PRD.md`](../../../杜康好客-v3-PRD.md) | **做什么**（V3.0 业务事实源） | +| 2 | [`杜康好客-v3编码手册.md`](../../../杜康好客-v3编码手册.md) | **怎么验收**（闭环、核销、分工） | +| 3 | [reference-waves.md](reference-waves.md) | Wave 门禁与 DLV 映射 | +| 4 | [reference-req-index.md](reference-req-index.md) | REQ-U/S/P/H 全表 | +| 5 | [reference-acc.md](reference-acc.md) | ACC 验收条件 | +| 6 | V2 手册 §四 §五 §六 | 架构 / DB / API（V3 冲突时 V3 PRD 优先） | +| 7 | `pages/{user,shop,partner,hq}/` | UI 参照 | + +## V3.0 不可偏离常量 + +``` +权益额 = 订单实付 1:1（永久） +同城起购 2 瓶 / 跨城 1 箱(6瓶) +门店结算 = 核销额 × 60% +单合伙人：订单佣金 + 核销佣金 ≤ 5%（默认 0% + 3%） +核销码 TTL = 3 分钟；试核销固定 ¥100 +订单 Tab：待付款 | 已付款 | 已完成 +C 端门店仅 status=OPEN 且审核通过 +``` + +## 三波交付（严格顺序） + +``` +Wave 1 (7.10) → Wave 2 (7.15) → Wave 3 (7.22) +``` + +实现前**必须确认当前 Wave**；不得提前做后续 Wave 功能（除非用户明确要求）。 + +| Wave | 门禁 | 一句话 | +|------|------|--------| +| W1 | W1-S1~S4 | 下单+核销+拓店+合伙人子账号 | +| W2 | W2-S1~S5 | 提现+推广码+现场提货+门店子账号+多合伙人 | +| W3 | 全量 G1~G5 | 代下单+弱网+多仓+跨城+工单+发票+增长 | + +详情：[reference-waves.md](reference-waves.md) + +## 需求变更规则 + +- **只改** `杜康好客-v3-PRD.md` 作为 V3.0 业务事实源 +- 同步 `杜康好客-v3编码手册.md` + `packages/shared-types` + `packages/domain` +- V2/preV1 与 V3.0 冲突时 **V3.0 PRD 优先** +- 编码 Agent 不得边写代码边改业务规则 + +## 原型 → 模块映射 + +| 端 | PRD 形态 | 当前代码 | 后端 Module | +|----|----------|----------|-------------| +| C 端 | 微信小程序 | `apps/h5-user`（过渡） | iam, catalog, trade, benefit | +| 门店 | H5 | `apps/h5-shop` | iam, redeem, store | +| 合伙人 | H5 | `apps/h5-partner` | iam, store, trade, settlement | +| 总部 | H5 | `apps/admin-web`（过渡） | catalog, store, trade, settlement, ops | + +## 任务卡命名（V3.0） + +- **DLV-W{n}-M{m}**：阶段交付（如 `DLV-W1-M2`） +- **REQ-{U|S|P|H}-{nnn}**：功能需求 ID +- **ACC-{nnn}** / **ACC-P{nn}** / **ACC-W{nn}**：验收 ID +- preV1 `P1-*` 与 V2 `M*-*` 为历史命名，V3.0 新任务以 DLV/REQ/ACC 为准 + +领取 DLV 任务时配合 `@dukang-coding` + 对应 Owner agent。 + +## 团队 OWNER（2 人） + +| 负责人 | 前端 | 后端 Module | +|--------|------|-------------| +| jacy-dukang | h5-user/mini-user, admin-web | iam, trade, benefit, catalog, settlement, ops, analytics | +| 刘景尧 | h5-shop, h5-partner | store, redeem | + +## 需求评审输出格式 + +```markdown +## V3.0 需求评审 · {主题} + +**关联**：REQ-xxx / ACC-xxx / Wave N +**影响模块**：（NestJS module + app） +**Owner**：jacy-dukang | 刘景尧 | 双方 +**与现状差异**：（代码/手册冲突点） +**建议任务**：DLV-Wx-Mx +**阻塞/依赖**：（外部对接、前置 Wave） +``` + +## 子 Agent 选用 + +| 场景 | Agent | +|------|-------| +| V3 波次统筹、跨 Wave 排期 | `v3-delivery-lead` | +| C 端下单/权益/支付 | `owner-a-user-trade` | +| 总部开城/结算/运营 | `owner-c-catalog-ops` | +| 合伙人拓店 | `owner-b-partner-store` | +| 门店核销 | `owner-d-shop-redeem` | +| packages/integrations/Prisma | `backend-lead` | +| PR 边界审查 | `boundary-reviewer` | diff --git a/.cursor/skills/dukang-v3/reference-acc.md b/.cursor/skills/dukang-v3/reference-acc.md new file mode 100644 index 0000000..7cc930e --- /dev/null +++ b/.cursor/skills/dukang-v3/reference-acc.md @@ -0,0 +1,72 @@ +# V3.0 ACC 验收标准索引 + +> 事实源：[`杜康好客-v3-PRD.md`](../../../杜康好客-v3-PRD.md) §8 + +## 交易与履约 + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-001 | S1 | 访客可浏览；下单须登录；支付成功→权益 1:1 | +| ACC-002 | 同城 | ≥2 瓶免运费；小飞侠；取送拍照；24h 自动完成 | +| ACC-003 | 现场提货 | 隐藏入口；支付即完成；有码归码/无码归总部 | +| ACC-004 | 跨城 | 未开通城市≥1箱；总部物流到付；佣金归总部 | +| ACC-015 | 锁单 | 30 分钟取消；7 天免登 | + +## 核销与门店账号 + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-005 | S2 | 扫码+手机号两通道；码/验证码 3 分钟；成功短信 | +| ACC-006 | 多店子账号 | W2：一号多店；主账号唯一；店员权限隔离 | +| ACC-006a | 门店登录 | 单店直达；多店含角色；记住所选 | +| ACC-017 | 弱网 | W1~2 重试+人工；W3 5次拍照兜底；不重复扣款 | +| ACC-017a | 弱网 SLA | W3：总部 T+0 处理；超时预警 | + +## 拓店与 SOP + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-007 | S3 | 合伙人三步提交；总部审；C 端营业中可见 | +| ACC-019 | SOP | 筛选字段；附件一一致；试核销100；负责人复核；合同同日 | +| ACC-020 | 结算细则 | T+1 顺延；异议3日；店内公示；签约主体 | + +## 资金与佣金 + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-008 | S4 | 未出账可提；总部打款；FIN 护栏；T+0 审 | +| ACC-009 | 佣金 | 默认 0%+3%；门店结算×60%；§4.3 归属 | +| ACC-P21 | 多合伙人 | 区域区县互斥；全城唯一 | +| ACC-P22 | 佣金配置 | 独立配置；≤5%；快照 | +| ACC-P23 | 订单佣金 | 同城区县解析；余量归总部/全城 | +| ACC-P24 | 核销佣金 | 归门店归属合伙人；变更不溯及 | +| ACC-P25 | 独立账单 | T+30 独立确认打款 | +| ACC-P26 | 数据隔离 | 仅本管辖；推广员仅自己的店 | +| ACC-P27 | 推广码 | 绑定合伙人；现场有码归码 | +| ACC-P28 | 审计 | 管辖/比例/归属变更留痕 | + +## 售后与增长 + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-010 | 工单 | 四类型；总部决策；补发/退款流转 | +| ACC-011 | 发票 | 四组合申请；2 工作日回传；可下载 | +| ACC-012 | 代下单 | W3：手机号建用户；权益自动发 | +| ACC-013 | 问卷评价 | 成交问卷无激励；核销评价；总部可看 | +| ACC-014 | 推广分享 | 推广码归因；商品分享带渠道 | +| ACC-018 | 话术 | OPT-012 3 日内对齐 | +| ACC-021 | 热力图 | 腾讯位置服务按城市 | + +## 多仓（Wave 3） + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-W01 | 多仓 | 同城多仓；启停 | +| ACC-W02 | 仓-合伙人 | 一仓一合伙人；未关联总部直管 | +| ACC-W03 | 管仓协同 | 管仓合伙人只读仓+工单协同 | + +## UI 与隐私 + +| ACC | 关联 | 验收条件 | +|-----|------|----------| +| ACC-016 | UI/隐私 | §8 规范；按角色脱敏 | diff --git a/.cursor/skills/dukang-v3/reference-req-index.md b/.cursor/skills/dukang-v3/reference-req-index.md new file mode 100644 index 0000000..fe44cc0 --- /dev/null +++ b/.cursor/skills/dukang-v3/reference-req-index.md @@ -0,0 +1,124 @@ +# V3.0 REQ 需求索引 + +> 事实源：产品 PRD v1.3 → [`杜康好客-v3-PRD.md`](../../../杜康好客-v3-PRD.md) + +## 用户端 REQ-U + +| ID | 模块 | 结论摘要 | +|----|------|----------| +| REQ-U-001 | 导航 | 首页/门店/好客权益/个人中心 | +| REQ-U-002 | 登录 | 无感登录；下单强制手机号；微信/短信；7 天免登 | +| REQ-U-003 | 支付 | 仅微信支付 | +| REQ-U-004 | 定位 | 右上角市区；默认 IP；可授权精确定位 | +| REQ-U-005 | 首页商品 | 4 款酒祖杜康；大图、标题加粗、价格标红、权益金额 | +| REQ-U-006 | 商品详情 | 规格瓶/箱、度数、价格、权益、详情图 | +| REQ-U-007 | 同城 | 小飞侠；≥2 瓶免运费；物流节点+拍照；24h 自动完成 | +| REQ-U-008 | 现场提货 | 隐藏入口；支付即完成；强提示在现场 | +| REQ-U-009 | 跨城 | 未开通城市；≥1 箱；总部物流到付 | +| REQ-U-010 | 锁单 | 待付款 30 分钟取消 | +| REQ-U-011 | 权益 | 支付成功 1:1 永久 | +| REQ-U-012 | 客服 | 已付款起电话/微信客服 | +| REQ-U-013 | 门店列表 | 营业中；搜索；省市区筛选；立即核销 | +| REQ-U-014 | 门店详情 | 门头/电话/星级/地址/营业时间/规则/相册 | +| REQ-U-015 | 核销页 | 剩余总额；输入金额；码 3 分钟有效 | +| REQ-U-016 | 规则弹窗 | 核销前展示（OPT-011） | +| REQ-U-017 | 评价 | 核销后引导门店评价 | +| REQ-U-018 | 权益页 | 待使用总额；Tab 待使用/已使用；明细 | +| REQ-U-019 | 个人中心 | 手机号、权益总额、订单入口 | +| REQ-U-020 | 订单 | 待付款/已付款/已完成；物流时间线 | +| REQ-U-021 | 发票 | 四组合；总部 2 工作日回传（OPT-001） | +| REQ-U-022 | 工单 | 四类型；客服引导建单 | +| REQ-U-023 | 问卷 | 支付成功引导；无激励（OPT-004） | +| REQ-U-024 | 推广码 | 扫码归因；现场提货有码归码 | +| REQ-U-025 | 分享 | 微信商品分享+渠道参数 | +| REQ-U-026 | 门店规则 | 附件一完整展示 | + +## 门店端 REQ-S + +| ID | 模块 | 结论摘要 | +|----|------|----------| +| REQ-S-001 | 导航 | 首页/核销记录/门店信息 | +| REQ-S-002 | 登录 | 主账号/店员；§4.6 流程；7 天免登 | +| REQ-S-003 | 多店 | 一号多店选店（Wave 2） | +| REQ-S-004 | 扫码核销 | 大按钮；确认即成功 | +| REQ-S-005 | 手机号核销 | 查余额→用户验证码→确认 | +| REQ-S-006 | 短信 | 核销中/成功文案 | +| REQ-S-007 | 今日汇总 | 首页今日核销总金额 | +| REQ-S-008 | 弱网 | W1~2 重试；W3 §4.8 | +| REQ-S-008a | 弱网弹窗 | W3 拍照兜底文案 | +| REQ-S-009 | 核销记录 | 筛今日/7日/1月/全部；到账×60% | +| REQ-S-010 | 门店信息 | 营业状态；结算入口；切换门店 | +| REQ-S-011 | 结算信息 | T+1；核销额/结算额/状态 | +| REQ-S-012 | 提现 | 未出账可提（Wave 2）；FIN 护栏 | +| REQ-S-013 | 提现记录 | 待审/已打款/驳回 | +| REQ-S-014 | 结算异议 | 3 工作日 | +| REQ-S-015 | 店内公示 | 模板下载 | +| REQ-S-016 | 提现护栏 | 白名单/单日上限提示 | +| REQ-S-017 | 子账号 | 创建/停用店员（Wave 2） | +| REQ-S-018 | 权限 | §4.6 矩阵 | +| REQ-S-019 | 多店选店 | 记住上次所选 | +| REQ-S-020 | 待处理核销 | Wave 3 弱网单 | + +## 合伙人端 REQ-P + +| ID | 模块 | 结论摘要 | +|----|------|----------| +| REQ-P-001 | 导航 | 首页/门店管理/合伙人中心 | +| REQ-P-002 | 登录 | 7 天免登 | +| REQ-P-003 | 推广员 | 菜单裁剪；仅本管辖范围 | +| REQ-P-004 | 管理员 | 完整能力 | +| REQ-P-005 | 子账号 | 管理员·推广员 | +| REQ-P-006 | 门店管理 | 筛审核/营业/区县/创建人 | +| REQ-P-007 | 列表字段 | 名称/地址/状态/录入 | +| REQ-P-008 | 一号多店 | 创建时二次确认 | +| REQ-P-009 | 创建三步 | 基础/证照+附件一/结算 | +| REQ-P-010 | 编辑规则 | 待审可改；通过后改资料再审 | +| REQ-P-011 | 试核销 | 100 元激活（OPT-009） | +| REQ-P-012 | 入驻短信 | OPT-008 | +| REQ-P-013 | 首页数据 | GMV/核销/订单三卡 | +| REQ-P-014 | 功能区 | 子账号/订单/权益/工单/代下单 | +| REQ-P-015 | 排行 | 核销/订单 Top10 | +| REQ-P-016 | 订单管理 | 筛时间状态 | +| REQ-P-017 | 订单详情 | 佣金快照下钻 | +| REQ-P-018 | 好客权益 | 送出/已核销/待核销 | +| REQ-P-019 | 工单 | 只读 | +| REQ-P-020 | 财务对账 | 本合伙人月账 | +| REQ-P-021 | 代下单 | Wave 3 | +| REQ-P-022 | 筛选校验 | 不达标标黄 | +| REQ-P-023 | 附件一 | 结构化录入 | +| REQ-P-024 | 负责人复核 | 待复核→待总部审 | +| REQ-P-025 | 合同同日 | 同日提交校验 | +| REQ-P-026 | 我的仓库 | Wave 3 管仓只读 | + +## 总部端 REQ-H + +| ID | 模块 | 结论摘要 | +|----|------|----------| +| REQ-H-001 | 登录 | 权限账户；7 天免登 | +| REQ-H-002 | 商品 | 增删改；上下架排序 | +| REQ-H-003 | 营销 | 1:1 权益永久 | +| REQ-H-004 | 开通城市 | 省/市/配送/是否开通 | +| REQ-H-004a | 创建合伙人 | 全城/区域+佣金；W3 管仓 | +| REQ-H-004b | 仓库 | Wave 3 多仓 | +| REQ-H-005 | 门店管理 | +归属合伙人筛选 | +| REQ-H-006 | 门店审核 | 通过/失败；改归属 | +| REQ-H-007 | 管辖佣金 | 区县全覆盖校验 | +| REQ-H-008 | 订单 | 全量+佣金快照 | +| REQ-H-009 | 权益 | 全量+合伙人筛 | +| REQ-H-010 | 工单 | 同意/拒绝+备注+日志 | +| REQ-H-011 | 发票 | 2 工作日；上传回传 | +| REQ-H-012 | 代下单 | 同合伙人 | +| REQ-H-013 | 结算 | 门店+合伙人双 Tab | +| REQ-H-014 | 提现审 | T+0；FIN-003 | +| REQ-H-014a | 白名单 | FIN-001/002 | +| REQ-H-015 | 合伙人账单 | 待确认/待打款 | +| REQ-H-016 | 报表 | 城市/合伙人/区县+热力图 | +| REQ-H-017 | 推广码 | 绑定合伙人+统计 | +| REQ-H-018 | 问卷 | 回收看板 | +| REQ-H-019 | 门店评价 | 查看数据 | +| REQ-H-020 | 核销异常 | W1~2 人工；W3 列表 | +| REQ-H-020a | 待处理核销审 | W3 补核销/驳回 | +| REQ-H-021 | 话术 | OPT-012 | +| REQ-H-022 | 签约主体 | 山西领势酒业 | +| REQ-H-023 | 热力图 | 腾讯位置服务 | +| REQ-H-024 | 结算异议 | 门店 3 日异议处理 | diff --git a/.cursor/skills/dukang-v3/reference-waves.md b/.cursor/skills/dukang-v3/reference-waves.md new file mode 100644 index 0000000..8a57389 --- /dev/null +++ b/.cursor/skills/dukang-v3/reference-waves.md @@ -0,0 +1,109 @@ +# V3.0 三波交付参考 + +> 事实源：[`杜康好客-v3-PRD.md`](../../../杜康好客-v3-PRD.md) §9 + +## Wave 1 — 核心交易 + 拓店（2026-07-10） + +### 门禁 + +| 门禁 | 能力 | ACC | +|------|------|-----| +| W1-S1 | 用户下单支付，权益 1:1 到账 | ACC-001 | +| W1-S2 | 门店核销（扫码 + 手机号） | ACC-005、OPT-007、OPT-011 | +| W1-S3 | 合伙人子账号 | REQ-P-005 | +| W1-S4 | 合伙人创建门店 → 总部审核 → C 端可见 | ACC-007、OPT-009、OPT-008 | + +### 纳入 + +四端登录 7 天免登、商品、**同城**下单支付、小飞侠履约、出码/扫码/手机号核销、规则弹窗、合伙人子账号、门店三步录入、负责人复核、总部审核、试核销 100 元、登录短信。 + +### 不含 + +提现/打款、推广码、现场提货、代下单、弱网拍照、多合伙人、门店子账号、**跨城**、工单、发票。 + +### DLV 拆分 + +| ID | 内容 | +|----|------| +| DLV-W1-M1 | 四端登录、权限、UI Token、商品管理/展示 | +| DLV-W1-M2 | 支付、锁单 30 分、同城小飞侠、权益 1:1 | +| DLV-W1-M3 | 出码/扫码/手机号核销、规则弹窗 OPT-011 | +| DLV-W1-M4 | 合伙人子账号、门店三步、负责人复核、审核、试核销 OPT-009、短信 OPT-008 | + +### Wave 1 弱网/代下单 SOP + +- 弱网：重试 + 总部人工补核销（OPT-006 完整版在 W3） +- 代下单：运营人工 SOP（系统能力在 W3 OPT-002） + +--- + +## Wave 2 — 资金 + 品鉴会 + 组织扩展（2026-07-15） + +### 门禁 + +| 门禁 | 能力 | ACC | +|------|------|-----| +| W2-S1 | 未出账可手动提现 + FIN 护栏 | ACC-008、OPT-010、FIN-001~003 | +| W2-S2 | 总部审核打款 | REQ-H-014 | +| W2-S3 | 推广码 + 现场提货 | ACC-003/014、OPT-005 | +| W2-S4 | 门店主子账号 + 一号多店选店 | REQ-S-017~019、ACC-006 | +| W2-S5 | 多合伙人管辖/佣金/数据隔离 | ACC-P21~P28 | + +### 不含 + +代下单、弱网 5 次拍照、一城多仓、跨城、工单、发票、问卷、热力图。 + +### DLV 拆分 + +| ID | 内容 | +|----|------| +| DLV-W2-M1 | T+1 出账、未出账提现 OPT-010 + FIN、总部审打款 | +| DLV-W2-M2 | 现场提货 OPT-005、推广码 REQ-H-017 | +| DLV-W2-M3 | 多合伙人 REQ-H-004a/007、区县互斥、佣金快照 | +| DLV-W2-M4 | 门店子账号 REQ-S-017~019、多店选店 | + +--- + +## Wave 3 — 旁路 + 弱网 + 本期全量（2026-07-22） + +### 门禁 + +| 门禁 | 能力 | ACC | +|------|------|-----| +| W3-S1 | 代下单（总部/合伙人） | ACC-012、OPT-002 | +| W3-S2 | 弱网 5 次拍照兜底 + 总部补核销 | ACC-017、OPT-006 | +| W3-S3 | 一城多仓 + 合伙人管仓 | ACC-W01~W03 | +| W3-S4 | 跨城、工单、发票、合伙人 T+30 对账、问卷/评价/热力图 | G5、OPT-001/003/004/012 | + +### 完成定义 + +G1–G5 + OPT-001～012 + 门店签约 SOP S1–S12 全部勾选。 + +### DLV 拆分 + +| ID | 内容 | +|----|------| +| DLV-W3-M1 | 代下单 OPT-002 | +| DLV-W3-M2 | 弱网 OPT-006 完整版 | +| DLV-W3-M3 | 多仓、跨城、工单 OPT-003、发票 OPT-001 | +| DLV-W3-M4 | 合伙人月账、问卷/评价/热力图、OPT-012 | +| DLV-W3-M5 | ACC 全量回归 | + +--- + +## OPT 波次对照 + +| OPT | 名称 | 波次 | +|-----|------|------| +| OPT-001 | 发票 | W3 | +| OPT-002 | 代下单 | W3 | +| OPT-003 | 工单 | W3 | +| OPT-004 | 问卷 | W3 | +| OPT-005 | 现场提货 | W2 | +| OPT-006 | 弱网兜底 | W3（W1~2 简化版） | +| OPT-007 | 手机号核销 | W1 | +| OPT-008 | 入驻成功短信 | W1 | +| OPT-009 | 试核销 100 元 | W1 | +| OPT-010 | 未出账提现 | W2 | +| OPT-011 | 核销规则弹窗 | W1 | +| OPT-012 | 话术对齐 | W3 | diff --git a/AGENTS.md b/AGENTS.md index b6e5b9b..74d308d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,9 +8,10 @@ | 阶段 | 手册 | 说明 | |------|------|------| -| **当前 V3 交付** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 业务闭环交付验收标准 | +| **当前 V3.0 交付** | [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) | 产品需求事实源（三波交付） | +| **V3 实现验收** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 业务闭环、核销、分工 | | **preV1 历史** | [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md) | Mock 联调裁剪（历史参考） | -| **V2 蓝图** | [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) | 完整产品蓝图（与 V3 冲突时 V3 优先） | +| **V2 蓝图** | [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) | 完整产品蓝图（与 V3 冲突时 V3 PRD 优先） | **禁止**：臆造 PRD 未定义规则；依赖 `doc/` 下过时文档；跨 OWNER 直写他人 Prisma 表。 @@ -45,8 +46,9 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 ## 文档优先级（冲突时） -1. `杜康好客-v3编码手册.md` — V3 交付业务规则与验收 -2. `杜康好客-V2编码手册.md` §二 — 完整蓝图（与 V3 冲突时 V3 优先） +1. `杜康好客-v3-PRD.md` — V3.0 产品需求与三波交付范围 +2. `杜康好客-v3编码手册.md` — V3 实现验收、核销规则、分工 +3. `杜康好客-V2编码手册.md` §二 — 完整蓝图（与 V3 冲突时 V3 PRD 优先） 3. `杜康好客-preV1编码手册.md` — preV1 裁剪（历史参考） 4. [`conventions.md`](./conventions.md) — 协作与模块边界 5. V2 手册 §四 §五 §六 — 架构 / DB / API @@ -81,9 +83,10 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 |------|------|------| | Rules | `.cursor/rules/` | 自动加载的编码规范 | | 编码 Skill | `.cursor/skills/dukang-coding/` | @dukang-coding | +| V3.0 需求 Skill | `.cursor/skills/dukang-v3/` | @dukang-v3（PRD、Wave、REQ/ACC） | | 需求 Skill | `.cursor/skills/dukang-project/` | @dukang-project | | preV1 Skill | `.cursor/skills/dukang-prev1/` | Mock / Feature Flag | -| 任务卡 Skill | `.cursor/skills/dukang-task-card/` | P1-* / M*-* | +| 任务卡 Skill | `.cursor/skills/dukang-task-card/` | DLV-W* / P1-* / M*-* | ## 子 Agent（按职责选用） @@ -91,7 +94,9 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 | 子 Agent | 负责人 | 适用场景 | |----------|--------|----------| -| `owner-a-user-trade` | jacy-dukang | C 端 H5、订单、支付、权益、埋点 | +| `v3-delivery-lead` | jacy-dukang | V3.0 三波交付统筹、DLV 拆分、跨 Owner 协调 | +| `v3-req-reviewer` | — | V3.0 需求只读审查、REQ/ACC 缺口分析 | +| `owner-a-user-trade` | jacy-dukang | C 端、订单、支付、权益、埋点 | | `owner-c-catalog-ops` | jacy-dukang | admin-web、开城商品、结算、运营 | | `backend-lead` | jacy-dukang | packages、callbacks、jobs、Prisma 横切 | | `owner-b-partner-store` | 刘景尧 | 合伙人 H5、门店 CRUD/审核 | @@ -102,15 +107,18 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 | Skill | 何时用 | |-------|--------| +| `dukang-v3` | V3.0 PRD、Wave 门禁、REQ/ACC 对照、三波交付规划 | | `dukang-coding` | 实现功能、修 Bug（通用编码流程） | | `dukang-project` | PRD/需求评审、原型对照、任务卡规划（**不用于日常编码**） | | `dukang-prev1` | Mock 开关、preV1 裁剪、Feature Flag | -| `dukang-task-card` | 领取任务卡 `P1-*` / `M*-*` 并按 DoD 交付 | +| `dukang-task-card` | 领取任务卡 `DLV-W*-*` / `P1-*` / `M*-*` 并按 DoD 交付 | ## 快速指令 -- 实现任务卡：`@dukang-coding 实现 P1-M2-002` -- 需求评审：`@dukang-project 对照 pages/partner/ 评审 PRD` +- V3.0 需求评审：`@dukang-v3 对照 REQ-U-007 评审现状` +- 实现 DLV 任务：`@dukang-coding 实现 DLV-W1-M2` +- 波次规划：`/v3-delivery-lead 拆分 Wave 2 任务` +- 需求缺口审查：`/v3-req-reviewer 审查门店提现` - PR 前审查：`/boundary-reviewer` - 原型参照：`pages/{user,shop,partner}/`（只读） @@ -119,16 +127,16 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 ``` 权益额 = benefit_amount ?? price 同城起购 2 瓶 / 跨城 6 瓶 -核销：直接核销 0 < amount ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额；Redis 码 5 分钟 +核销：直接核销 0 < amount ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额；Redis 码 3 分钟 C 端门店仅 status=OPEN -订单 Tab：all | pending_pay | pending_ship | pending_receive | completed +订单 Tab：待付款 | 已付款 | 已完成 ``` ## 提交与 PR - Conventional Commits：`feat(trade):`、`fix(redeem):`；scope = 端或模块 - 跨模块 PR → jacy-dukang + 刘景尧 共同 Review（若涉及双方模块） -- 改 API/表 → 同步 V2 手册 §五/§六 + `shared-types` +- 改 API/表 → 同步 v3-PRD + v3编码手册 + `shared-types` - 不提交 `.env`、`dist/`、`node_modules/` ## 完成定义（DoD） diff --git a/杜康好客-v3-PRD.md b/杜康好客-v3-PRD.md new file mode 100644 index 0000000..85bfa66 --- /dev/null +++ b/杜康好客-v3-PRD.md @@ -0,0 +1,427 @@ +# 杜康好客 · 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 入口） + +--- + +## 0. 文档说明 + +| 字段 | 内容 | +|------|------| +| 项目名称 | 杜康好客 — 四端系统 | +| 覆盖端 | 用户端（**微信小程序**）、门店端（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 待付款/已付款/已完成为准** | + +--- + +## 1. 背景与目标 + +### 1.1 商业模型 + +总部供酒 → 城市合伙人分销拓店 → 门店核销好客权益 → C 端买酒送 **1:1 等价好客权益**，覆盖「酒 + 餐」。 + +**成本与分润锚点**： + +- 酒水成本约售价 **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 | 推广码归因合伙人；订单佣金按履约规则解析（跨城归总部） | + +--- + +## 2. 角色与场景 + +### 2.1 角色 + +| 角色 | 端 | 核心诉求 | +|------|-----|----------| +| C 端用户 | 小程序 | 买酒、收权益、门店核销、售后/发票 | +| 门店主账号 | H5 | 核销、子账号管理、营业状态、结算提现 | +| 门店店员子账号 | H5 | 仅核销 + 本店记录（Wave 2） | +| 合伙人管理员 | H5 | 子账号、管辖范围经营数据、代下单等 | +| 合伙人推广员 | H5 | 仅门店入驻 + 看自己提交的店 | +| 总部运营/客服/财务 | H5 | 商品、审核、工单、发票、结算打款、报表 | + +### 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 | 代下单 | 总部/合伙人手机号建用户下单（Wave 3） | +| SC-08 | 问卷+评价 | 成交后问卷；核销后门店评价 | +| SC-09 | 推广归因 | 推广码进小程序→绑定合伙人→统计成交/佣金 | + +### 2.3 权限摘要 + +- 合伙人数据**平级隔离**（全城/区域不可互查） +- 推广员：仅门店入驻 + 看自己提交的店（须在管辖范围内） +- 门店主账号：子账号、核销、提现、营业状态；店员：仅核销+本店记录 +- 总部：审核、管辖与佣金配置、打款、全数据 +- 手机号脱敏：门店/合伙人中间 4 位加密；总部仅管理员看全号 + +--- + +## 3. 业务闭环与核心规则 + +### 3.1 五条主闭环 + +| 闭环 | 触发 | 关键节点 | 终点 | +|------|------|----------|------| +| 购酒履约 | 用户下单 | 同城小飞侠/跨城总部物流/现场提货 | 已完成 + 权益 1:1 | +| 权益核销 | 用户出码/报号 | 门店确认 | 权益扣减 + 门店账本×60% + 核销佣金释放 | +| 拓店入驻 | 合伙人录入 | 总部审核 + 试核销 | 营业中 C 端可见 | +| 售后工单 | 用户发起 | 总部审 + 协同 | 补发/退款或驳回 | +| 结算提现 | 核销入账 | T+1 出账 + 未出账可提 | 总部审后打款 | + +### 3.2 订单状态机 + +``` +待付款 ──支付成功──► 已付款 ──履约完成/确认收货/24h自动──► 已完成 + └─ 30 分钟未付取消 +``` + +- **同城**：推小飞侠（已取货拍照→已发出→已送达拍照）；送达未确认 24h 自动完成 +- **跨城**：推总部物流（到付）；订单佣金归总部 +- **现场提货**：支付后直接已完成；有现场推广码则订单佣金归码所属合伙人，无码归总部 + +### 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 名管仓合伙人 +- 佣金与仓无关；仓用于工单协同 +- 未关联合伙人的仓 → 总部直派 + +### 3.8 弱网核销兜底（Wave 3 · OPT-006） + +- Wave 1~2：网络异常明确提示+重试；总部预警+人工补核销 +- Wave 3：连续**网络类**失败 5 次→拍照兜底→上传→总部 T+0 补核销 +- 业务错误（码过期、余额不足等）不计入 5 次；幂等防重复扣款 + +--- + +## 4. 功能需求（REQ 索引） + +> 完整 REQ 结论见 [`.cursor/skills/dukang-v3/reference-req-index.md`](./.cursor/skills/dukang-v3/reference-req-index.md) + +### 4.1 用户端（小程序）— REQ-U-001 ~ 026 + +| 模块 | 要点 | +|------|------| +| 导航账号 | 四 Tab；无感登录；确认下单强制手机号；仅微信支付；7 天免登 | +| 商品下单 | 4 款酒祖杜康 SKU；同城≥2瓶免运费；跨城≥1箱；现场提货隐藏；锁单30分钟 | +| 权益核销 | 1:1 发放；出码 3 分钟；核销前规则弹窗（OPT-011）；附件一规则详情 | +| 门店 | 列表/详情/搜索/省市区筛选；仅营业中展示；立即核销 | +| 增长售后 | 四类型工单；发票四组合；成交问卷（无激励）；推广码；微信商品分享 | +| 评价 | 核销后门店评价 | + +**SKU 价格锚点** + +| 商品 | 瓶价 | 箱价(6瓶) | +|------|------|-----------| +| 酒祖杜康（国标特级10）53° | ¥128 | ¥768 | +| 酒祖杜康（国标特级15）53° | ¥168 | ¥1008 | +| 酒祖杜康（国标特级20）53° | ¥298 | ¥1788 | +| 酒祖杜康（国标特级30）53° | ¥498 | ¥2988 | + +### 4.2 门店端（H5）— REQ-S-001 ~ 020 + +| 模块 | 要点 | +|------|------| +| 登录 | 主账号/店员；多店选店（Wave 2）；7 天免登 | +| 核销 | 扫码大按钮 + 手机号通道；今日汇总；弱网处理 | +| 记录结算 | 筛今日/7日/1月/全部；到账金额×60%；T+1 出账 | +| 提现 | 未出账可提（FIN 护栏）；提现记录；结算异议 3 工作日 | +| 账号 | 主账号管理店员（Wave 2）；待处理核销单（Wave 3） | + +### 4.3 合伙人端（H5）— REQ-P-001 ~ 026 + +| 模块 | 要点 | +|------|------| +| 权限 | 管理员 vs 推广员菜单裁剪 | +| 拓店 | 三步录入；一号多店确认；负责人复核；试核销100元；附件一 | +| 经营 | 首页三卡；排行；订单/权益/工单；佣金快照下钻 | +| 财务 | 本合伙人月账对账（Wave 2/3） | +| 扩展 | 代下单（Wave 3）；管仓只读（Wave 3） | + +### 4.4 总部端（H5）— REQ-H-001 ~ 024 + +| 模块 | 要点 | +|------|------| +| 基础 | 商品管理；营销规则 1:1 权益；签约主体：山西领势酒业有限责任公司 | +| 城市合伙人 | 开通城市；创建合伙人（全城/区域+佣金）；仓库管理（Wave 3） | +| 审核交易 | 门店审核；全量订单/权益/工单；发票 2 工作日；补核销 | +| 结算 | 门店+合伙人双 Tab；提现审；白名单配置 | +| 增长 | 推广码；问卷；评价；腾讯位置热力图 | + +### 4.5 端职责矩阵 + +| 能力 | 用户端 | 门店端 | 合伙人端 | 总部端 | +|------|:------:|:------:|:--------:|:------:| +| 下单/支付/权益 | ● | | 代下单 | 代下单 | +| 核销 | 出码 | ● | 看记录 | 看全量 | +| 拓店 | 看门店 | 改营业 | ●录入 | ●审核 | +| 工单 | ●发起 | 查看 | 查看 | ●决策 | +| 结算提现 | | ● | 对账确认 | ●审打款 | +| 推广码/问卷/评价 | ● | 被评价 | 看数据 | 配置/看板 | + +--- + +## 5. 非功能需求 + +| 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 | 归因 | 推广码与佣金归属下单时落库 | + +--- + +## 6. 数据实体与外部依赖 + +### 6.1 核心实体（TECH-001 ~ 019） + +用户、商品、订单（含佣金快照）、好客权益账本、门店（主账号/店员）、核销单、工单、结算/提现、合伙人（管辖+佣金）、推广码、仓库（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% +- 核销码 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 | W2 前运营人工代下单 | +| 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. 变更记录 + +| 版本 | 日期 | 说明 | +|------|------|------| +| 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 需刘景尧） diff --git a/杜康好客-v3编码手册.md b/杜康好客-v3编码手册.md new file mode 100644 index 0000000..15641f6 --- /dev/null +++ b/杜康好客-v3编码手册.md @@ -0,0 +1,180 @@ +# 杜康好客 · V3 编码手册（交付业务版） + +> **版本定位**：V3 是基于当前数据库 v3.1 的完整交付版本，目标不是 Mock 联调，而是把「购酒 → 发券 → 到店核销 → 门店打款 → 合伙人结算 → 总部运营」全流程跑通。 +> **产品事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)（V3.0 PRD，源自产品文档 v1.3） +> **对照文件**：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 = **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 运营 + +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.0 业务规则**以 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) 为准；本编码手册为实现与验收补充。 +- 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 |