# 杜康好客 · 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 端小程序迁移（暂缓）、Wave 1 缺口（手机号核销/规则弹窗/试核销/自动推小飞侠） |
| **P0 冲突** | C2~C7、C14 **已修复**（2026-07-12） |
| **冒烟覆盖** | `scripts/smoke-v3.mjs` 仅覆盖窄 W1 切片，**不等于** V3.0 ACC 全量 |

### Wave 门禁状态

| 门禁 | 状态 | 一句话 |
|------|------|--------|
| **W1-S1** 下单+支付+权益 | 🔶 | TTL/Tab/SKU/佣金已对齐；仍缺小程序形态 |
| **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 直接矛盾。**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` |

> **重跑 seed**：本地需 `cd server/dukang-api && pnpm prisma:seed` 后商品/佣金数据才与 C6/C7 一致。

---

## 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** 话术对齐 | 无运营文档交付机制 |

---

## 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 — 消除冲突 ✅ 已完成（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. 变更记录

| 日期 | 说明 |
|------|------|
| 2026-07-12 | **P0 已执行**：C2~C7、C14 代码与文档对齐；§1 改为计划+状态表 |
| 2026-07-12 | 明确总部端保持 WebAdmin，不改为 H5 |
| 2026-07-11 | 首版：V3.0 PRD 全量对照当前 monorepo |