PRD对照

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