PRD对照

.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`
 
 ## 原型 → 模块映射
 

.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`
 
 ## 领取流程
 

.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 不可偏离常量
 
 ```

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 审查门店提现`

杜康好客-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 |

杜康好客-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 与本手册。