From b74e4e4fe56b816b7950ba21adf8ed1dd9faeff4 Mon Sep 17 00:00:00 2001 From: jacy-dukang Date: Sun, 12 Jul 2026 07:29:14 +0800 Subject: [PATCH] =?UTF-8?q?PRD=E5=AF=B9=E7=85=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/skills/dukang-project/SKILL.md | 20 +- .cursor/skills/dukang-task-card/SKILL.md | 4 +- .cursor/skills/dukang-v3/SKILL.md | 14 +- AGENTS.md | 27 +-- 杜康好客-v3-现状对照.md | 268 +++++++++++++++++++++++ 杜康好客-v3编码手册.md | 30 ++- 6 files changed, 326 insertions(+), 37 deletions(-) create mode 100644 杜康好客-v3-现状对照.md diff --git a/.cursor/skills/dukang-project/SKILL.md b/.cursor/skills/dukang-project/SKILL.md index e46aa9b..50e40aa 100644 --- a/.cursor/skills/dukang-project/SKILL.md +++ b/.cursor/skills/dukang-project/SKILL.md @@ -22,20 +22,20 @@ disable-model-invocation: true | 优先级 | 文档 | 用途 | |--------|------|------| -| 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 联调范围（历史） | +| 1 | `杜康好客-v3-PRD.md` | **唯一需求事实源** | +| 2 | `杜康好客-v3-现状对照.md` | 已完成/冲突/缺口 | +| 3 | `杜康好客-v3编码手册.md` | 实现验收、分工 | +| 4 | `conventions.md` | 协作与模块边界 | +| 5 | V2 手册 §四 §五 §六 | 仅架构/DB/API 参考（与 V3 冲突时忽略） | +| 6 | `pages/{user,shop,partner,hq}/` | UI 参照 | + +> V2 / preV1 **不再作为需求依据**。 ## 需求变更规则 -- **V3.0 交付**：只改 `杜康好客-v3-PRD.md` 作为业务事实源，同步 v3编码手册 -- **V2 蓝图**：改 `杜康好客-V2编码手册.md`（与 V3 冲突时 V3 PRD 优先） +- **只改** `杜康好客-v3-PRD.md`；进度同步 `杜康好客-v3-现状对照.md` - 编码 Agent **不得**边写代码边改业务规则 -- 改 API/表结构 → 同步手册 §五/§六 + `packages/shared-types` +- 改 API/表结构 → 同步 v3-PRD + `packages/shared-types` ## 原型 → 模块映射 diff --git a/.cursor/skills/dukang-task-card/SKILL.md b/.cursor/skills/dukang-task-card/SKILL.md index 52913ff..94320c2 100644 --- a/.cursor/skills/dukang-task-card/SKILL.md +++ b/.cursor/skills/dukang-task-card/SKILL.md @@ -11,8 +11,8 @@ description: >- ## 原则 - **一次只做一个任务卡** -- 任务卡 ID 命名空间：`DLV-W*-*`（V3.0）· `P1-*`（preV1）· `M*-*`（V2）；勿混用验收标准 -- 需求变更只改 `杜康好客-v3-PRD.md`（V3.0），不在任务实现中私改业务规则 +- 任务卡 ID 命名空间：`DLV-W*-*`（V3.0）· `P1-*` / `M*-*`（**历史，不再作验收依据**） +- 需求变更只改 `杜康好客-v3-PRD.md`；进度查 `杜康好客-v3-现状对照.md` ## 领取流程 diff --git a/.cursor/skills/dukang-v3/SKILL.md b/.cursor/skills/dukang-v3/SKILL.md index dce946a..13de81f 100644 --- a/.cursor/skills/dukang-v3/SKILL.md +++ b/.cursor/skills/dukang-v3/SKILL.md @@ -23,14 +23,16 @@ disable-model-invocation: true | 优先级 | 文档 | 用途 | |--------|------|------| -| 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 优先） | +| 1 | [`杜康好客-v3-PRD.md`](../../../杜康好客-v3-PRD.md) | **唯一需求事实源** | +| 2 | [`杜康好客-v3-现状对照.md`](../../../杜康好客-v3-现状对照.md) | 已完成/冲突/缺口 | +| 3 | [`杜康好客-v3编码手册.md`](../../../杜康好客-v3编码手册.md) | 实现验收、分工 | +| 4 | [reference-waves.md](reference-waves.md) | Wave 门禁与 DLV 映射 | +| 5 | [reference-req-index.md](reference-req-index.md) | REQ-U/S/P/H 全表 | +| 6 | [reference-acc.md](reference-acc.md) | ACC 验收条件 | | 7 | `pages/{user,shop,partner,hq}/` | UI 参照 | +> V2 / preV1 手册**不再作为需求依据**。 + ## V3.0 不可偏离常量 ``` diff --git a/AGENTS.md b/AGENTS.md index 74d308d..05e6ded 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,10 +8,10 @@ | 阶段 | 手册 | 说明 | |------|------|------| -| **当前 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 PRD 优先） | +| **V3.0 唯一需求源** | [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) | 产品需求与三波交付（**只看这个**） | +| **现状对照** | [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md) | 已完成 / 冲突 / 缺口审计 | +| **V3 实现验收** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 核销规则、分工、闭环 | +| ~~V2 / preV1~~ | 历史参考 | **不再作为需求依据** | **禁止**：臆造 PRD 未定义规则；依赖 `doc/` 下过时文档；跨 OWNER 直写他人 Prisma 表。 @@ -46,13 +46,14 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 ## 文档优先级（冲突时） -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 -6. `pages/{user,shop,partner}/` + [`pages/ROUTE_MAP.md`](./pages/ROUTE_MAP.md) — UI 参照 +1. `杜康好客-v3-PRD.md` — **唯一需求事实源** +2. `杜康好客-v3-现状对照.md` — 实现进度审计 +3. `杜康好客-v3编码手册.md` — 实现验收、核销、分工 +4. `conventions.md` — 协作与模块边界 +5. V2 手册 §四 §五 §六 — 仅作架构/DB/API **参考**（与 V3 冲突时忽略） +6. `pages/{user,shop,partner,hq}/` — UI 参照 + +> **V2 / preV1 手册不再作为需求依据。** ## 团队与 OWNER 边界（2 人） @@ -107,7 +108,7 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 | Skill | 何时用 | |-------|--------| -| `dukang-v3` | V3.0 PRD、Wave 门禁、REQ/ACC 对照、三波交付规划 | +| `dukang-v3` | V3.0 PRD、现状对照、Wave/REQ/ACC | | `dukang-coding` | 实现功能、修 Bug（通用编码流程） | | `dukang-project` | PRD/需求评审、原型对照、任务卡规划（**不用于日常编码**） | | `dukang-prev1` | Mock 开关、preV1 裁剪、Feature Flag | @@ -115,7 +116,7 @@ Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。 ## 快速指令 -- V3.0 需求评审：`@dukang-v3 对照 REQ-U-007 评审现状` +- 现状审计：`@dukang-v3` + [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md) - 实现 DLV 任务：`@dukang-coding 实现 DLV-W1-M2` - 波次规划：`/v3-delivery-lead 拆分 Wave 2 任务` - 需求缺口审查：`/v3-req-reviewer 审查门店提现` diff --git a/杜康好客-v3-现状对照.md b/杜康好客-v3-现状对照.md new file mode 100644 index 0000000..7976aab --- /dev/null +++ b/杜康好客-v3-现状对照.md @@ -0,0 +1,268 @@ +# 杜康好客 · 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 冲突（需改造） · ❌ 未实现 + +--- + +## 0. 总览 + +| 维度 | 结论 | +|------|------| +| **整体完成度（粗估）** | Wave 1 约 **45%**；Wave 2 约 **10%**；Wave 3 约 **5%** | +| **可跑通的主链路** | 登录 → 浏览商品 → 同城下单 Mock/微信支付 → 权益 1:1 → **扫码核销** → T+1 门店 payout 记录 → 总部确认打款 | +| **最大阻塞** | 端形态（无小程序 C 端）、规则常量冲突（TTL/Tab/SKU/佣金）、Wave 1 缺口（手机号核销/规则弹窗/试核销/自动推小飞侠） | +| **冒烟覆盖** | `scripts/smoke-v3.mjs` 仅覆盖窄 W1 切片，**不等于** V3.0 ACC 全量 | + +### Wave 门禁状态 + +| 门禁 | 状态 | 一句话 | +|------|------|--------| +| **W1-S1** 下单+支付+权益 | 🔶 | 链路可跑，SKU/订单 Tab/TTL 不合规 | +| **W1-S2** 门店核销双通道 | 🔶 | 扫码 ✅；手机号核销 ❌ | +| **W1-S3** 合伙人子账号 | ✅ | CRUD + 推广员菜单裁剪已有 | +| **W1-S4** 拓店→审核→C 端可见 | 🔶 | 三步录入有；试核销100/负责人复核/SOP 缺失 | +| **W2-S1~S5** | ❌ | 提现/FIN/现场提货/多合伙人/门店子账号 基本未做 | +| **W3-S1~S4** | ❌ | 代下单/弱网拍照/多仓/跨城履约/四类型工单/发票/问卷/热力图 基本未做 | + +--- + +## 0.1 已确认的工程口径（非冲突） + +| 项 | PRD 原文 | V3 工程决策 | +|----|----------|-------------| +| 总部端形态 | 总部 H5 | **`apps/admin-web`（WebAdmin）为唯一交付端，不改为 H5** | +| 验收方式 | REQ-H-* | 功能在 admin-web 实现即可；不要求微信内 H5 或小程序总部端 | +| `mini-hq` | — | 非主交付；与 admin-web 重叠能力以 **admin-web 补齐** 为准 | + +--- + +## 1. ⚠️ 冲突项（必须先改） + +> 代码已存在，但与 V3.0 PRD **直接矛盾**，继续开发会累积返工。 + +| # | V3.0 要求 | 当前实现 | 证据位置 | 改造建议 | +|---|-----------|----------|----------|----------| +| C1 | C 端 = **微信小程序** | `apps/h5-user` H5；无 `mini-user` | `apps/h5-user/` | 新建小程序或明确 H5 为过渡并排迁移 | +| C2 | 核销码 TTL **3 分钟** | **300 秒（5 分钟）** | `packages/shared-types/src/enums.ts` `REDEEM_TOKEN_TTL_SECONDS=300`；`apps/h5-user/src/pages/RedeemPage.tsx` 文案 | 改常量为 180 + 全端文案 | +| C3 | 短信验证码 **3 分钟** | Redis TTL **300 秒** | `server/dukang-api/src/integrations/sms/sms-code.store.ts` | 改 `CODE_TTL_SECONDS=180` | +| C4 | 订单 Tab：**待付款 / 已付款 / 已完成** | **5 Tab**（含待发货/待收货） | `apps/h5-user/src/pages/OrderListPage.tsx`；`OrderTab` enum | 改 Tab 映射与列表 API | +| C5 | 订单状态机三态展示 | **9 态** `OrderStatus` | `packages/shared-types/src/enums.ts` | PRD 三 Tab 映射到细粒度状态，或收敛状态机 | +| C6 | 4 款 **酒祖杜康** + 锚点价 | preV1 杜康系列 ¥399–1299 | `server/dukang-api/prisma/seed-v31.ts` | 替换 seed + 商品管理数据 | +| C7 | 默认佣金 **0% 订单 + 3% 核销** | seed **5% 订单佣金** | `seed-v31.ts` `orderCommissionRate: 0.05` | 改 seed 与开城默认 | +| C8 | **一号多店**（同号可多店主账号） | `StoreAccount.phone @unique`；创建时**拒绝**重复手机 | `schema.prisma` `StoreAccount`；`store.service.ts` `partnerCheckStorePhone` | 改模型：主账号与门店多对多 | +| C9 | 支付后**自动推小飞侠**（同城） | 支付后 delivery `MANUAL`；总部手动推单 | `trade.service.ts`；`admin-xiaofeixia.service.ts` | 支付回调后接 xiaofeixia | +| C10 | 门店结算 = **门店主动提现**（W2） | 核销后**自动生成** `StorePayout` | `settlement.service.ts` `createStorePayout` | 增加余额账本 + 提现申请流 | +| C11 | 工单 **四类型** | enum 仅 **3 类** `REFUND/RESHIPMENT/ALERT` | `schema.prisma` `TicketType` | 扩展 enum + 用户建单 UI | +| C12 | 配送类型含 **现场提货** | `DeliveryType` 仅 `LOCAL/CROSS_CITY` | `packages/shared-types/src/enums.ts` | 新增 `ON_SITE_PICKUP` | +| C13 | 多合伙人（全城/区域平级） | 城市 `partnerId` **单合伙人** | `schema.prisma` `CommonCity.partnerId` | 新增合伙人管辖/区县/佣金快照模型 | +| C14 | 文档/规则残留 5min、5 Tab | `apps/AGENTS.md`、backend rules 仍写旧口径 | `.cursor/rules/`、`apps/AGENTS.md` | 批量对齐 V3.0 | + +--- + +## 2. ✅ 已完成（与 V3.0 对齐或基本对齐） + +### 2.1 用户端 `apps/h5-user` + +| REQ | 功能 | 证据 | 备注 | +|-----|------|------|------| +| REQ-U-001 | 四 Tab 导航 | `src/layouts/TabLayout.tsx` | 形态为 H5 非小程序 | +| REQ-U-002 | 登录 + 下单强制手机号 | `OrderConfirmPage.tsx`、`PhoneVerifiedGuard` | ✅ | +| 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` | ⚠️ SKU 数据见 C7 | +| 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 见 C3 | +| 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** 多合伙人管辖与佣金 | 无全城/区域、区县互斥、佣金快照 | +| **ACC-P21~P28** 多合伙人全套 | 数据模型与 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** 一城多仓 + 管仓合伙人 | schema 无 warehouse | +| **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** 话术对齐 | 无运营文档交付机制 | + +--- + +## 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 有；现场提货归码 ❌ | + +--- + +## 6. 建议改造顺序（仅 V3.0 视角） + +### P0 — 消除冲突（1~2 天） + +1. C2/C3：核销码 + 短信 TTL → 3 分钟 +2. C6/C7：seed SKU + 佣金默认值 +3. C4/C5：订单三 Tab 与 API 映射 +4. C14：更新 `apps/AGENTS.md`、`.cursor/rules` 残留旧口径 + +### 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. 变更记录 + +| 日期 | 说明 | +|------|------| +| 2026-07-12 | 明确总部端保持 WebAdmin，不改为 H5；移除原 C2 端形态冲突 | +| 2026-07-11 | 首版：V3.0 PRD 全量对照当前 monorepo | diff --git a/杜康好客-v3编码手册.md b/杜康好客-v3编码手册.md index 15641f6..e5ca061 100644 --- a/杜康好客-v3编码手册.md +++ b/杜康好客-v3编码手册.md @@ -1,9 +1,9 @@ # 杜康好客 · 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 不默认新增大表，优先补齐业务闭环、第三方集成、任务调度、验收测试与运营后台。 +> **版本定位**：V3 实现与验收补充；**产品事实源**见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。 +> **现状审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)（已完成/冲突/缺口） +> **对照文件**：V2 / preV1 手册**不再作为需求依据**，仅作历史参考。 +> **数据库事实**：当前 Prisma schema 已是 v3.1，优先按 V3.0 PRD 补齐业务闭环。 --- @@ -27,6 +27,21 @@ 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`、配送/核销联调 | 负责门店、合伙人、录店、核销、门店体验与辖区履约 | +### 2.1 四端交付形态（工程口径） + +产品 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。 @@ -102,7 +117,9 @@ V3 必须达到可业务验收状态： 6. 异常时发起/处理补发、改址拦截、配送异常。 7. 合伙人查看月度账单、佣金、经营周报。 -### 4.4 WebAdmin 运营 +### 4.4 WebAdmin 运营（总部端） + +> 交付载体：`apps/admin-web`。本节即总部端验收口径，**不要求改为 H5**。 1. 管理员登录。 2. 配置开城、商品、合伙人、门店分类。 @@ -158,13 +175,14 @@ V3 必须达到可业务验收状态： | P1 | shared-types DTO 不全 | 按接口稳定度分批上提 | | P1 | 跨模块直写 Prisma 表 | 逐步改为 exported Service | | P1 | 真实短信、配送、退款未闭环 | 按 4.1、4.3、4.4 对应业务闭环完成 | -| P2 | `admin-web` 与 V2 HQ 小程序形态不一致 | V3 先以 WebAdmin 交付，是否迁小程序另立版本 | +| 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 与本手册。