压缩文档

2026-08-06 01:09:19 +08:00
parent 4f363fa9e7
commit 53a79d1255
14 changed files with 469 additions and 7237 deletions
@@ -11,7 +11,7 @@
 | **V3.0 唯一需求源** | [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) | 产品需求与三波交付（**只看这个**） |
 | **现状对照** | [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md) | 已完成 / 冲突 / 缺口审计 |
 | **V3 实现验收** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 核销规则、分工、闭环 |
-| ~~V2 / preV1~~ | 历史参考 | **不再作为需求依据** |
+| ~~V2 / preV1~~ | 历史参考（**已压缩**；V2 全文见 git 2026-08-06 前） | **不再作为需求依据** |

 **禁止**：臆造 PRD 未定义规则；依赖 `doc/` 下过时文档；跨 OWNER 直写他人 Prisma 表。

@@ -1,435 +1,41 @@
-# 杜康好客 · preV1 编码手册（Mock 联调版）
+# 杜康好客 · preV1 编码手册（Mock 联调）

-> **V3 交付提示**：preV1 不再作为交付验收标准。核销规则以 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) §3 为准（无 ¥500 上限）。
+> **非 V3 验收标准**。核销等规则以 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 为准。  
+> 原则：**同 V2 库表与 API 路径**，用 Mock/Flag/Seed 跳过外部依赖。

-> **版本**：preV1（在 V2 完整规格之上的**裁剪实现阶段**）  
-> **完整规格（V2）**：[`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) — PRD、DB v3.1、API、任务卡均以 V2 为准  
-> **原则**：**不删表、不删 V2 API 路径、不改 V2 字段语义**；preV1 用 Mock / Feature Flag / Seed 跳过外部依赖，开关关闭即切回 V2 真实流程。
+## 六条裁剪

---
+| # | 裁剪 | 替代 |
+|---|------|------|
+| 1 | 无 HQ 前端 | `/admin/*` 脚本或后续 admin-web |
+| 2 | 三端均 H5 | `h5-user` / `h5-shop` / `h5-partner` |
+| 3 | 登录 | 手机号 + 固定码 `999888` |
+| 4 | 支付 | Mock 即时成功 |
+| 5 | 配送 | Mock 状态推进 |
+| 6 | 短信 | Mock |

-## 文档索引
+## Feature Flag（`.env`）

-| 章节 | 内容 |
+| Flag | 作用 |
 |------|------|
-| §0 | 版本关系（preV1 vs V2） |
-| §1 | preV1 范围：六条裁剪规则 |
-| §2 | 三端 H5 与仓库结构 |
-| §3 | 认证 Mock（无微信） |
-| §4 | 支付 Mock |
-| §5 | 配送与订单状态 Mock |
-| §6 | 无总部端：能力替代 |
-| §7 | preV1 功能清单 |
-| §8 | Feature Flag 与 V2 切换 |
-| §9 | preV1 里程碑与任务卡 |
-| §10 | API / 数据行为差异速查 |
+| `MOCK_SMS` | 验证码 999888 |
+| `MOCK_PAY` | 支付同步成功 |
+| `MOCK_DELIVERY` | 配送 Mock 推进 |

---
-
-# §0、版本关系
-
-| 维度 | preV1（本文） | V2（完整版） |
-|------|---------------|--------------|
-| 定位 | 三端 H5 联调，跑通购酒→发券→核销主链路 | 四端小程序/H5 + 真实微信/物流/支付 |
-| 客户端 | **用户 / 门店 / 合伙人 均为 H5** | C端+合伙人+总部小程序，门店 H5 |
-| 总部 HQ | **无独立端** | `pages/hq/` + AdminAuth |
-| 登录 | **仅手机号 + 固定验证码** | 短信 + 微信授权/绑定 |
-| 支付 | **Mock 即时成功** | 微信 JSAPI + 回调 |
-| 配送 | **Mock 状态推进** | 小飞侠/物流回调 |
-| 数据库 | **同 V2 v3.1（28 表）** | 同左 |
-| API 路径 | **同 V2 §六**（行为可 Mock） | 完整实现 |
-
-**升级路径**：preV1 完成后，按 §8 逐项打开 Flag、补小程序端与 HQ 端，**无需重构表结构**。
-
---
-
-# §1、preV1 范围：六条裁剪规则
-
-### 1.1 删掉 HQ 端
-
- **不做**：`apps/mini-hq`、`pages/hq/` 任何页面、AdminAuth 前端。
- **保留**：`hq_account` 表、§六 全部 `/admin/*` 路由（preV1 可不实现 Controller，或仅内部/脚本调用）。
- **替代**：见 §6。
-
-### 1.2 用户 / 门店 / 合伙人 均改为 H5
-
-| V2 端 | preV1 App | `X-Client-App` | 原型参照 |
-|-------|-----------|----------------|----------|
-| C端小程序 | `apps/h5-user` | `USER_H5` | `pages/user/` |
-| 门店 H5 | `apps/h5-shop` | `SHOP_H5` | `pages/shop/` |
-| 合伙人小程序 | `apps/h5-partner` | `PARTNER_H5` | `pages/partner/` |
-
- JWT `actorType` 不变：`USER` / `STORE` / `PARTNER`。
- V2 的 `USER_MINI` / `PARTNER_MINI` / `HQ_MINI` 枚举**保留**，preV1 不用即可。
-
-### 1.3 微信登录与授权暂不走
-
- **不调用**：微信 `code2session`、获取手机号组件、微信 OAuth。
- **不写入**：`wx_open_id` / `wx_union_id`（保持 NULL）。
- **仅实现**：`POST /auth/sms/send` + `POST /auth/login/sms`（及三端等价路径 `/shop/auth/*`、`/partner/auth/*`）。
- V2 的 `POST /auth/login/wechat`、`/auth/wechat/bind-phone`：**保留路由**，preV1 返回 `501 FEATURE_DISABLED` 或 Flag 关闭时不注册。
-
-### 1.4 手机号验证固定 Mock
-
-| 项 | preV1 约定 |
-|----|------------|
-| 验证码 | 固定 **`123456`**（全端、全 scene 通用） |
-| 开关 | `MOCK_SMS=true` 时：不调用短信网关，不写入 `log_third_party(SMS)` 真实外呼 |
-| 校验 | `AuthService.verifyCode(phone, code)` 内：`if (MOCK_SMS && code === '123456') return ok` |
-| 限流 | preV1 可放宽；V2 打开真实短信后启用频率限制 |
-
-**测试账号（Seed，见 §6.1）**
-
-| 角色 | 手机号 | 表 |
-|------|--------|-----|
-| C端用户 | `13800000001` | `user_user` |
-| 门店 | `13900000001` | `store_account` |
-| 合伙人主账号 | `13700000001` | `partner_account` |
-
-### 1.5 配送与订单状态 Mock（跳过第三方）
-
- **不调用**：小飞侠 API、物流查询 API；`log_third_party` 的 `XFX` / `LOGISTICS` 在 preV1 可不写入（或写 MOCK 占位）。
- **仍创建**：支付成功后 `user_order_delivery` 空壳（与 V2 一致 1:1）。
- **状态推进**（任选其一，推荐 A+B）：
-  - **A. 自动任务**：`MOCK_DELIVERY_AUTO=true` 时，支付成功 30s 后 BullMQ 任务：`PENDING_SHIP → OUT_WAREHOUSE → SHIPPING → PENDING_RECEIVE → COMPLETED`，并写 `common_event(ORDER_STATUS)`。
-  - **B. 合伙人手动**：`POST /partner/orders/:id/mock-advance-delivery`（preV1 专用，V2 可保留为内部测试接口或 Flag 保护）。
- **user_order** 冗余时间字段 `shipped_at` / `completed_at` 与 `user_order_delivery.shipping_at` / `delivered_at` **双写**（同 V2）。
-
-### 1.6 跳过支付
-
- **不调用**：微信统一下单、支付回调验签。
- **用户侧**：确认订单页按钮文案可为「提交订单（Mock 支付）」；仍调用 **`POST /trade/orders/:id/pay`**（路径与 V2 相同）。
- **服务端**：`MOCK_PAY=true` 时 `PayService` 同步：
-  1. `user_order.pay_status=PAID`，`paid_at=NOW()`，`pay_external_no='MOCK-{orderNo}'`
-  2. 可选写 `log_third_party(WECHAT_PAY, scene=ORDER_PAY, status=SUCCESS, external_no=MOCK-...)`
-  3. 订单 `status=PENDING_SHIP` + `common_event(ORDER_STATUS)`
-  4. 调用 `BenefitService.grantOnOrderPaid(orderId)`（**真实发券逻辑，非 Mock**）
-  5. 预创建 `user_order_delivery`
- V2 切换：`MOCK_PAY=false` 时走 `wechatpay-node-v3` + `/callbacks/wechat/pay`。
-
---
-
-# §2、三端 H5 与仓库结构
-
-preV1 Monorepo（在 V2 目标结构上演进，**暂不建 mini-* / mini-hq**）：
-
-```
-dukang/
-├── apps/
-│   ├── h5-user/          # C端 H5（Taro H5 或 Vite+React，与 V2 技术栈一致即可）
-│   ├── h5-shop/          # 门店 H5
-│   └── h5-partner/       # 合伙人 H5
-├── packages/
-│   ├── shared-types/     # 含 USER_H5 / PARTNER_H5 / SHOP_H5
-│   └── domain/
-├── server/dukang-api/    # 同 V2 单体 NestJS
-├── pages/{user,shop,partner}/   # UI 参照（hq 仅 V2 用）
-├── 杜康好客-V2编码手册.md
-└── 杜康好客-preV1编码手册.md   # 本文
-```
-
-**请求头**：各 H5 固定 `X-Client-App: USER_H5 | SHOP_H5 | PARTNER_H5`。
-
-**页面实现**：字段、Tab、跳转以 V2 手册 §二、§三 原型为准；C 端订单 **5 Tab（含待发货）** 不变。
-
---
-
-# §3、认证 Mock（无微信）
-
-### 3.1 实现的登录路径
-
-| 端 | 发送验证码 | 登录 |
-|----|------------|------|
-| C端 | `POST /auth/sms/send` scene=`USER_LOGIN` | `POST /auth/login/sms` |
-| 门店 | `POST /auth/sms/send` scene=`STORE_LOGIN` | `POST /shop/auth/login/sms` |
-| 合伙人 | `POST /auth/sms/send` scene=`PARTNER_LOGIN` | `POST /partner/auth/login/sms` |
-
-### 3.2 preV1 不实现的登录路径
-
-| 路径 | preV1 行为 |
-|------|------------|
-| `POST /auth/login/wechat` | 501 或 Flag 关闭 |
-| `POST /auth/wechat/bind-phone` | 501 |
-| `POST /shop/auth/login/wechat` | 501 |
-| `POST /partner/auth/login/wechat` | 501 |
-| `POST /admin/auth/*` | 不暴露给前端（无 HQ 端） |
-
-### 3.3 实现要点（便于 V2 切换）
-
-```typescript
-// packages/shared-types 或 server config
-export const AppConfig = {
-  mockSms: process.env.MOCK_SMS === 'true',
-  mockSmsCode: process.env.MOCK_SMS_CODE ?? '123456',
-  mockPay: process.env.MOCK_PAY === 'true',
-  mockDeliveryAuto: process.env.MOCK_DELIVERY_AUTO === 'true',
-};
-
-// AuthService — 单一验证码入口，V2 只改内部实现
-async verifySmsCode(phone: string, code: string, scene: string) {
-  if (AppConfig.mockSms && code === AppConfig.mockSmsCode) return;
-  // V2: 查 Redis / log_third_party / 真实短信平台
-}
-```
-
---
-
-# §4、支付 Mock
-
-### 4.1 用户流程（与 V2 UI 一致，跳过收银台）
-
-```
-确认订单 → POST /trade/orders（锁单 PENDING_PAY）
-         → POST /trade/orders/:id/pay
-              [MOCK_PAY=true] 同步成功，无跳转微信
-         → 订单列表可见「待发货」
-         → 权益页可见新券
-```
-
-### 4.2 字段与表（与 V2 相同）
-
-| 写入 | 说明 |
-|------|------|
-| `user_order.pay_status` | `PAID` |
-| `user_order.paid_at` | 当前时间 |
-| `user_order.pay_external_no` | `MOCK-{orderNo}` |
-| `user_order.status` | `PENDING_SHIP` |
-| `log_third_party` | 可选 MOCK 记录，便于 V2 对账逻辑联调 |
-| `user_benefit_coupon` + `common_event(BENEFIT_LEDGER,GRANT)` | **真实业务**，非 Mock |
-
-### 4.3 preV1 不做的支付相关能力
-
- 微信 prepay 参数、支付回调、`/callbacks/wechat/pay` 验签（路由保留，Mock 模式不触发）。
- 退款微信 API：preV1 **整模块可跳过**（§7）；表与 `common_ticket(REFUND)` 仍保留。
-
---
-
-# §5、配送与订单状态 Mock
-
-### 5.1 自动推进状态机（推荐默认开启）
-
-`MOCK_DELIVERY_AUTO=true` 时，支付成功后注册延时任务：
-
-| 延时 | from → to | 配送表 |
-|------|-----------|--------|
-| T+0 | `PENDING_SHIP` → `OUT_WAREHOUSE` | `out_warehouse_at` |
-| T+10s | → `SHIPPING` | `shipping_at`，`user_order.shipped_at` |
-| T+30s | → `PENDING_RECEIVE` | — |
-| T+60s | → `COMPLETED` | `delivered_at`，`user_order.completed_at` |
-
-每次 transition 写 `common_event(ORDER_STATUS)`；`provider` 填 `MANUAL` 或 `MOCK`。
-
-### 5.2 合伙人端手动推进（可选）
-
-`POST /partner/orders/:id/mock-advance-delivery`
-
- Guard：`PartnerAuth` + 订单 `city_id` 属合伙人辖区。
- Body：`{ targetStatus: 'SHIPPING' | 'COMPLETED' | ... }`
- preV1 专用；V2 生产环境 `MOCK_DELIVERY=false` 时返回 403。
-
-### 5.3 改址拦截（preV1 简化）
-
- V2 PRD：用户改址 → 合伙人拦截配送。
- preV1：`PUT /trade/orders/:id/address` **仅更新** `user_order` 收货字段 + `common_event`；**不**调第三方、不建复杂 intercept 表（V2 仍用 `common_ticket(ALERT)`，preV1 可省略工单）。
-
---
-
-# §6、无总部端：能力替代
-
-HQ 能力在 preV1 通过 **Seed + 合伙人 H5 子集 + 可选内部 API** 覆盖，**表结构不删**。
-
-### 6.1 启动 Seed（`prisma/seed-prev1.ts` 或 SQL）
-
-| 数据 | 内容 |
-|------|------|
-| `common_city` | 郑州 `ACTIVE`，`local_min_qty=2`，`cross_min_qty=6` |
-| `common_city_commission_rule` | 默认佣金比例 |
-| `common_product_item` | 4 款清香型 `ON_SALE`，含 `barcode_69` |
-| `common_store_category` | 火锅/地方菜等 |
-| `partner_partner` + `partner_account` | 郑州合伙人 + 主账号 `13700000001` |
-| `store_store` + `store_account` | 至少 2 家 `OPEN` 门店 |
-| `user_user` | 测试用户 `13800000001` |
-| `hq_account` | 可 Seed 1 条供未来 V2，preV1 无 UI |
-
-商品图/门头图：preV1 可用 **占位 URL** 或 `common_resource` 写死 CDN；V2 换 OSS 上传流程即可。
-
-### 6.2 原 HQ 功能 → preV1 替代
-
-| V2 HQ 功能 | preV1 替代 |
-|------------|------------|
-| 开城 / 商品 CRUD | **Seed 固定**；变更改 Seed 或直连 DB（开发环境） |
-| 门店审核 | 合伙人提交后 **`AUTO_APPROVE_STORE=true` 自动通过**，写 `common_event(STORE_AUDIT,APPROVED)` |
-| 订单中心 / 发货 | 合伙人 H5 看辖区订单；跨城发货 preV1 跳过或 Mock 运单号 |
-| 推广码 | **跳过 UI**；`channel_source` 可手填或 Seed 一条 `common_promo_code` |
-| 退款 / 客服工单 | **跳过**（或合伙人 H5 仅查看，不发起微信退款） |
-| 结算中心 T+1/T+30 | **Mock 状态**：核销后 `store_payout.status=PENDING`；合伙人 `partner_bill` 可 Seed 一条 `CONFIRMED` 演示 |
-| 数据报表 / 埋点 | 埋点 **可写 `log_user_analytics`**；总部报表 **不做** |
-
-### 6.3 合伙人 H5 在 preV1 的扩展（承接部分 HQ）
-
-在 V2 合伙人 API 基础上，preV1 **额外开放**（Flag 保护）：
-
-| 能力 | 说明 |
-|------|------|
-| 门店审核自动通过 | 配置项，非新表 |
-| Mock 推进配送 | §5.2 |
-| 查看辖区订单 | V2 已有 `GET /partner/orders` |
-
---
-
-# §7、preV1 功能清单
-
-### 7.1 必做（跑通主链路）
-
-| 模块 | 功能 | V2 预留 |
-|------|------|---------|
-| IAM | 三端短信 Mock 登录 | 微信登录路由保留 |
-| Catalog | 读商品/开城（Seed） | `/admin/products` 未实现 |
-| Trade | 预览、下单、Mock 支付、5 Tab 订单、改址 | 真实微信支付 |
-| Benefit | 发券、券列表、明细 | 同 V2 |
-| Redeem | Redis 核销码、门店扫码确认、评价 | 同 V2 |
-| Store | C 端门店列表/详情；合伙人录店；**自动审核** | HQ 人工审核 |
-| Settlement | 核销后 `store_payout` PENDING | T+1 打款任务可 Mock 为手动改 PAID |
-| Analytics | 可选：批量写 `log_user_analytics` | 同 V2 |
-
-### 7.2 preV1 明确跳过（V2 补）
-
-| 模块 | 跳过内容 |
-|------|----------|
-| HQ 端 | 全部页面与 AdminAuth 前端 |
-| 微信 | 登录、支付、退款、订阅消息 |
-| 第三方 | 小飞侠、物流、真实短信 |
-| 运营 | 退款工单、推广码管理 UI、总部报表 |
-| 合伙人 | 拦截配送完整流程、T+30 真实打款、提现 |
-| 小程序 | 全部（preV1 仅 H5） |
-
-### 7.3 业务规则（与 V2 相同，Mock 不减免）
-
- 同城起购 **2 瓶** / 跨城 **6 瓶**（`packages/domain`）
- 权益金额 `benefit_amount ?? price`
- 核销上限 **¥500**，Redis 码 **5 分钟**
- C 端门店仅 **`OPEN`**
- 订单 **5 Tab**（含 `pending_ship`）
-
---
-
-# §8、Feature Flag 与 V2 切换
-
-### 8.1 环境变量（`.env.example`）
+## 启动验证

 ```bash
-# preV1 Mock 开关（true = Mock 模式）
-MOCK_SMS=true
-MOCK_SMS_CODE=123456
-MOCK_PAY=true
-MOCK_DELIVERY_AUTO=true
-AUTO_APPROVE_STORE=true
-
-# V2 就绪后逐项 false，并配置真实密钥
-WECHAT_PAY_ENABLED=false
-WECHAT_AUTH_ENABLED=false
-XFX_ENABLED=false
-SMS_PROVIDER=mock
+pnpm dev:api && pnpm dev:user && pnpm dev:shop && pnpm dev:partner
+node scripts/smoke-prev1.mjs
 ```

-### 8.2 切换检查表（preV1 → V2）
+## 与 V2 差异速查

-| 步骤 | 动作 |
-|------|------|
-| 1 | `MOCK_PAY=false`，配置商户号，启用 `/callbacks/wechat/pay` |
-| 2 | `MOCK_SMS=false`，接入短信，`log_third_party(SMS)` |
-| 3 | `MOCK_DELIVERY_AUTO=false`，对接小飞侠/物流回调 |
-| 4 | `AUTO_APPROVE_STORE=false`，上线 `apps/mini-hq` + 门店审核 |
-| 5 | 新增 `apps/mini-user`、`apps/mini-partner`，`X-Client-App` 改 MINI |
-| 6 | `WECHAT_AUTH_ENABLED=true`，实现 wechat 登录/bind-phone |
-| 7 | 启用退款、结算 Job、推广码 HQ 页面 |
+| 项 | preV1 | V2/V3 |
+|----|-------|-------|
+| 客户端 | 三 H5 | 小程序 + H5 |
+| 总部 | 无 UI | admin-web |
+| 微信 | 无 | JSAPI/OAuth |
+| 表结构 | v3.1 同左 | 同左 |

-### 8.3 代码组织（避免 Mock 散落）
-
-```
-server/dukang-api/src/
-├── integrations/
-│   ├── sms/
-│   │   ├── sms.interface.ts      # ISmsProvider
-│   │   ├── sms.mock.provider.ts  # preV1
-│   │   └── sms.aliyun.provider.ts # V2
-│   ├── pay/
-│   │   ├── pay.interface.ts
-│   │   ├── pay.mock.provider.ts
-│   │   └── pay.wechat.provider.ts
-│   └── delivery/
-│       ├── delivery.interface.ts
-│       ├── delivery.mock.provider.ts
-│       └── delivery.xfx.provider.ts
-```
-
-`TradeModule` / `AuthModule` 只依赖 **interface**，由 `ConfigModule` 注入 Mock 或 Real 实现。
-
---
-
-# §9、preV1 里程碑与任务卡
-
-> 详细 API/表结构见 V2 手册 §五、§六；任务 ID 前缀 **`P1-`**，与 V2 `M0~M6` 并行命名空间。
-
-| 里程碑 | 交付 | 出口标准 |
-|--------|------|----------|
-| **P1-M0** | Monorepo 三 H5 + API 骨架 + Seed | 三端登录页、`GET /health`、Seed 郑州+4 SKU |
-| **P1-M1** | IAM Mock + 商品/门店读 | 三端 Mock 登录；C 端首页 4 款酒 |
-| **P1-M2** | 下单 + Mock 支付 + 5 Tab 订单 | 2 瓶起购；支付后待发货+发券 |
-| **P1-M3** | 权益 + 核销 + 门店 H5 | 端到端核销；`store_payout` PENDING |
-| **P1-M4** | 合伙人录店 + 自动审核 | C 端可见新门店 |
-| **P1-M5** | Mock 配送自动推进 | 订单可到已完成 |
-| **P1-M6** | 埋点可选 + 联调修复 | 主链路冒烟通过 |
-
-### 任务卡（精简）
-
-| ID | 任务 | 验收 |
-|----|------|------|
-| P1-M0-001 | pnpm workspace + `h5-user/shop/partner` | 三端 `dev` 可编译 |
-| P1-M0-002 | `shared-types` + Mock Flags | 导出 `AppConfig` |
-| P1-M0-003 | NestJS + Prisma + `init_v3.sql` | `prisma validate` |
-| P1-M0-004 | `seed-prev1.ts` | 郑州/4SKU/测试账号 |
-| P1-M1-001 | `SmsMockProvider` + 三端 login/sms | 123456 登录 |
-| P1-M1-002 | C 端首页/详情 Public catalog | 对照 `pages/user/2,3` |
-| P1-M2-001 | preview + create order | 起购校验 |
-| P1-M2-002 | `PayMockProvider` + grant benefit | Mock 支付发券 |
-| P1-M2-003 | 订单 5 Tab | `pending_ship` 有数据 |
-| P1-M3-001 | 权益页 + redeem token | ¥500 上限 |
-| P1-M3-002 | 门店扫码核销 | `pages/shop/3~5` |
-| P1-M4-001 | 合伙人录店 + AUTO_APPROVE | C 端门店可见 |
-| P1-M5-001 | `DeliveryMockProvider` 自动推进 | 订单 COMPLETED |
-
---
-
-# §10、API / 数据行为差异速查
-
-| API / 行为 | V2 | preV1 |
-|------------|-----|-------|
-| `X-Client-App` | USER_MINI / … | USER_H5 / SHOP_H5 / PARTNER_H5 |
-| `/admin/*` | AdminAuth 小程序 | 无前端；Seed/脚本 |
-| `/auth/login/wechat` | 实现 | 501 或 Flag 关 |
-| `/auth/sms/send` | 真实短信 | 固定码，不外呼 |
-| `/trade/orders/:id/pay` | 微信 prepay | 同步 Mock 成功 |
-| `/callbacks/wechat/pay` | 验签回调 | 不触发 |
-| `/callbacks/xfx/delivery` | 配送回调 | 不触发 |
-| `log_third_party` | 真实流水 | 可选 MOCK 行或跳过 |
-| 门店审核 | HQ 审 | `AUTO_APPROVE_STORE` |
-| 退款 | HQ 工单+微信退款 | **跳过** |
-| 推广码 UI | HQ | **跳过** |
-| 核销 / 权益 / 订单表 | 真实 | **真实（同 V2）** |
-
---
-
-## 原型参照（preV1 仍用 V2 映射）
-
-| H5 App | 原型目录 |
-|--------|----------|
-| h5-user | `pages/user/` |
-| h5-shop | `pages/shop/` |
-| h5-partner | `pages/partner/` |
-
-C 端订单列表：**5 Tab（含待发货）**；个人中心无会员标签；城市示例以 **郑州** 为准。
-
---
-
-*preV1 为 V2 的 Mock 联调阶段；完整 PRD、DB DDL、全量 API 见 [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md)。*
+升级：逐项关 Mock → 接真实集成 → 补 admin-web / mini-user。
@@ -1,169 +1,3 @@
-# 杜康好客 · V3 编码手册（交付业务版）
+# 杜康好客 · v2.1 编码手册

-> **版本定位**：V3 是基于当前数据库 v3.1 的完整交付版本，目标不是 Mock 联调，而是把「购酒 → 发券 → 到店核销 → 门店打款 → 合伙人结算 → 总部运营」全流程跑通。  
-> **对照文件**：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 = 5 分钟。
- 生成核销码前必须校验金额，门店确认核销时必须二次校验。
- 门店确认时使用券 `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 业务规则以本文件为准。
- V2 手册仍作为完整蓝图参考，但与 V3 冲突时，V3 优先。
- preV1 手册只作为 Mock 联调历史参考，不再作为交付验收标准。
- 未写入本文件的新增需求，不进入 V3 交付范围；如必须加入，先更新本手册与任务表负责人。
+> **已合并**。内容与 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 重复，请以 **v3 编码手册** 为准。本文件保留作历史链接占位。
@@ -1,571 +1,147 @@
-# 杜康好客 · V3.0 产品需求文档（PRD）
+# 杜康好客 · 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 入口）
+> **v3.0**（2026-07-10）· 产品事实源 · 冲突时 **V3 > V2**  
+> 实现：[`v3编码手册`](./杜康好客-v3编码手册.md) · 审计：[`v3-现状对照`](./杜康好客-v3-现状对照.md)

---
+## 0. 说明

-## 0. 文档说明
+| 项 | 内容 |
+|----|------|
+| 四端 | C 小程序 · 门店/合伙人 H5 · 总部 **WebAdmin**（工程口径，非 H5） |
+| 试点 | 郑州 · 同城小飞侠 · 跨城总部物流到付 |
+| 工程差异 | C 端现 `mini-user`/h5-user；核销 TTL **3min**；订单 Tab **三态** |

-| 字段 | 内容 |
-|------|------|
-| 项目名称 | 杜康好客 — 四端系统 |
-| 覆盖端 | 用户端（**微信小程序**）、门店端（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 待付款/已付款/已完成为准** |
-
-### 0.2 变更：3.4.10 门店套餐
-
-| 版本 | 日期 | 说明 |
-|------|------|------|
-| **3.4.10** | 2026-08-03 | 新增 §3.9 门店套餐；REQ-P-027 / REQ-S-021 / REQ-H-025 / REQ-U-027；开发设计见 [`杜康好客-门店套餐功能开发文档-v3.4.10.md`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) |
-
-### 0.3 变更：3.4.11 开发计划
-
-| 版本 | 日期 | 说明 |
-|------|------|------|
-| **3.4.11** | 2026-08-04 | 新增 §3.10 开发计划、§3.11 企微机器人角色与权限重构；REQ-H-026 ~ REQ-H-028；开发设计见 [`杜康好客-开发计划功能开发文档-v3.4.11.md`](./杜康好客-开发计划功能开发文档-v3.4.11.md) |
-
-### 0.4 变更：3.4.12 工单迭代
-
-| 版本 | 日期 | 说明 |
-|------|------|------|
-| **3.4.12** | 2026-08-04 | 售后退款回滚、mini-user 门店详情、酒厂 T+3、门店多笔提现、开发计划批量编辑/审批企微派发、技术支持编辑/附件/批量改状态、套餐 imageUrl；开发设计见 [`杜康好客-v3.4.12-工单迭代开发文档.md`](./杜康好客-v3.4.12-工单迭代开发文档.md) |
-
-### 0.5 变更：3.4.13 体验优化
-
-| 版本 | 日期 | 说明 |
-|------|------|------|
-| **3.4.13** | 2026-08-05 | 推广码归因统计 + **指标事件日志/高峰趋势**、核销用户信息 + **权益券详情加宽/核销详情增强**、技术支持工单优先级、mini-user **我的页版本号/低于 min 强制退出**、门店/商品/提货/**物流增强（签收照/拨号/ETA/路由回调签收→已完成）**、H5 登录校验、合伙人微信暂停禁登、**OSS 图片超 10MB 客户端压缩**；开发设计见 [`杜康好客-v3.4.13-体验优化开发文档.md`](./杜康好客-v3.4.13-体验优化开发文档.md) |
+| 版 | 日期 | 要点 | 开发文档 |
+|----|------|------|----------|
+| 3.4.10 | 08-03 | 门店套餐 | [`门店套餐`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) |
+| 3.4.11 | 08-04 | 开发计划 + 企微机器人/消息推送 | [`开发计划`](./杜康好客-开发计划功能开发文档-v3.4.11.md) |
+| 3.4.12 | 08-04 | 退款回滚/财务/批量任务·工单/套餐 imageUrl | [`v3.4.12`](./杜康好客-v3.4.12-工单迭代开发文档.md) |
+| 3.4.13 | 08-05 | metrics/核销详情/版本联动 PUBLISHED/mini 体验/H5 OAuth | [`v3.4.13`](./杜康好客-v3.4.13-体验优化开发文档.md) |

 ---

 ## 1. 背景与目标

-### 1.1 商业模型
+**模型**：总部供酒 → 合伙人拓店 → 门店核销 1:1 好客权益（酒+餐）。

-总部供酒 → 城市合伙人分销拓店 → 门店核销好客权益 → C 端买酒送 **1:1 等价好客权益**，覆盖「酒 + 餐」。
+| 锚点 | 值 |
+|------|-----|
+| 酒水成本 | ~售价 3 折 |
+| 门店结算 | 核销额 × **60%** |
+| 合伙人佣金池 | 订单+核销 ≤ 订单额 **5%**（默认 **0%+3%**） |
+| 权益 | 实付 **1:1**，永久；口径 `benefit_amount ?? price` |

-**成本与分润锚点**：
+**G1~G5**：四端闭环 · 购酒履约 · 权益核销结算 · 合伙人拓店对账 · 售后/发票/代下单/推广/评价。

- 酒水成本约售价 **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 | 推广码归因合伙人；订单佣金按履约规则解析（跨城归总部） |
+**门禁 S1~S4**：下单+权益(W1) · 核销(W1) · 拓店(W1) · 门店提现(W2)。

 ---

 ## 2. 角色与场景

-### 2.1 角色
+| 角色 | 端 | 诉求 |
+|------|-----|------|
+| C 用户 | 小程序 | 买酒、权益、核销、售后 |
+| 门店/店员 | H5 | 核销、营业、提现(W2) |
+| 合伙人 | H5 | 拓店、订单、账单 |
+| 总部 | WebAdmin | 审核、结算、运营 |

-| 角色 | 端 | 核心诉求 |
-|------|-----|----------|
-| C 端用户 | 小程序 | 买酒、收权益、门店核销、售后/发票 |
-| 门店主账号 | H5 | 核销、子账号管理、营业状态、结算提现 |
-| 门店店员子账号 | H5 | 仅核销 + 本店记录（Wave 2） |
-| 合伙人管理员 | H5 | 子账号、管辖范围经营数据、代下单等 |
-| 合伙人推广员 | H5 | 仅门店入驻 + 看自己提交的店 |
-| 总部运营/客服/财务 | H5 | 商品、审核、工单、发票、结算打款、报表 |
+**SC-01~09**：同城购酒 · 现场提货 · 跨城 · 核销 · 拓店 · 售后 · 代下单 · 问卷评价 · 推广归因（见 PRD 原文路径摘要）。

-### 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 | 代下单 | 总部/合伙人手机号建用户下单；在线支付（商家收款码 / 合伙人微信代付）后发权益；配送进入待发货由总部履约，现场提货走自提闭环；订单记代下单人 |
-| SC-08 | 问卷+评价 | 成交后问卷；核销后门店评价 |
-| SC-09 | 推广归因 | 推广码进小程序→绑定合伙人→统计成交/佣金 |
-
-### 2.3 权限摘要
-
- 合伙人数据**平级隔离**（全城/区域不可互查）
- 推广员：仅门店入驻 + 看自己提交的店（须在管辖范围内）
- 门店主账号：子账号、核销、提现、营业状态；店员：仅核销+本店记录
- 总部：审核、管辖与佣金配置、打款、全数据
- 手机号脱敏：门店/合伙人中间 4 位加密；总部仅管理员看全号
+**权限**：合伙人平级隔离；推广员仅拓店+看自己店；手机号脱敏（门店/合伙人中间4位）。

 ---

-## 3. 业务闭环与核心规则
+## 3. 核心规则

-### 3.1 五条主闭环
+### 3.1 五条闭环

-| 闭环 | 触发 | 关键节点 | 终点 |
-|------|------|----------|------|
-| 购酒履约 | 用户下单 | 同城小飞侠/跨城总部物流/现场提货 | 已完成 + 权益 1:1 |
-| 权益核销 | 用户出码/报号 | 门店确认 | 权益扣减 + 门店账本×60% + 核销佣金释放 |
-| 拓店入驻 | 合伙人录入 | 总部审核 + 试核销 | 营业中 C 端可见 |
-| 售后工单 | 用户发起 | 总部审 + 协同 | 补发/退款或驳回 |
-| 结算提现 | 核销入账 | T+1 出账 + 未出账可提 | 总部审后打款 |
+购酒履约 · 权益核销(60%+核销佣金) · 拓店入驻 · 售后工单 · 结算提现(T+1 出账+未出账可提)。

-### 3.2 订单状态机
+### 3.2 订单

-```
-待付款 ──支付成功──► 已付款 ──履约完成/确认收货/24h自动──► 已完成
-  └─ 30 分钟未付取消
-```
-
- **同城**：仓配履约——有仓且绑 API 承运商则自动推单（首期小飞侠）；有仓选自管则管仓方手工填单；**无仓**则总部传统快递填单
- **大单拦截**：同城订单 **≥10 箱（箱规 6 瓶，即 ≥60 瓶）** 不自动推小飞侠；订单打标「大单待确认」，由总部确认后推小飞侠或自配送（填快递单）
- **跨城**：总部传统快递到付填单；订单佣金归总部
- **现场提货**：支付后直接已完成；有现场推广码则订单佣金归码所属合伙人，无码归总部
+`待付款 → 已付款 → 已完成`；30min 未付取消。同城自动推小飞侠（有仓+API）；**≥10箱(60瓶)** 大单待 HQ 确认。跨城总部物流到付。现场提货支付即完成。

 ### 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 名管仓合伙人
- **仓配管理**（总部）：注册第三方履约接口（小飞侠、京东、顺丰等）；启用后仓库方可选择；**承运商需配置银行账户、结算方式（充值/挂账月结）、计价标准**
- **仓库设置**：履约方式 = API 自动推单（选已注册承运商）或 **自管**（手工填运单号 + 查询链接模板）
- 同城有仓订单支付后自动按仓配置推单；自管仓由管仓合伙人/总部代填单；**≥10 箱大单除外**（见 §3.2）
- 同城无仓 / 跨城：总部传统快递填单
- 佣金与仓无关（订单佣金仍按 §3.3.1）；仓用于履约与工单协同
- 未关联合伙人的仓 → 总部直派
-
-#### 3.7.1 物流对账（总部财务）
-
-| 规则 | 结论 |
-|------|------|
-| 汇总维度 | 按快递/仓配承运商（`FulfillmentProvider`）独立月账单 |
-| 计费口径 | 账期内已发货订单瓶数 × 承运商计价标准（账单落快照） |
-| 小飞侠默认价 | **2 瓶 6 元**；每加 1 瓶 **+2 元**；**6 瓶一箱 14 元**（整箱按箱费，余瓶按起送阶梯） |
-| 结算方式 | **前期充值扣款**（`PREPAID`）：总部向承运商账户充值，月账单自动/确认扣余额；**后期挂账月结**（`MONTHLY_CREDIT`）：生成应付账单后总部确认打款 |
-| 银行账户 | 每承运商配置收款户名/开户行/支行/账号，打款对照 |
-| 出账节奏 | 自然月；每月 1 日汇总上月；可手工按承运商/月生成 |
-### 3.8 弱网核销兜底（Wave 3 · OPT-006）
-
- Wave 1~2：网络异常明确提示+重试；总部预警+人工补核销
- Wave 3：连续**网络类**失败 5 次→拍照兜底→上传→总部 T+0 补核销
- 业务错误（码过期、余额不足等）不计入 5 次；幂等防重复扣款
-
-### 3.9 门店套餐（引入于 **3.4.10**）
-
-> 实现设计见 [`杜康好客-门店套餐功能开发文档-v3.4.10.md`](./杜康好客-门店套餐功能开发文档-v3.4.10.md)
-
-门店可向 C 端展示餐饮套餐信息（与酒水 SKU 无关），用于核销前用户了解可核销内容；**套餐变更审核与整店入驻审核独立**。
-
-#### 3.9.1 套餐数据结构
-
-| 字段 | 说明 | 示例 |
+| 类型 | 默认 | 释放 |
 |------|------|------|
-| 套餐名称 | 必填（单条内） | 套餐A |
-| 价格 | 元 | 198 |
-| 菜品 | 文本 | 红烧肉、红烧鱼、油焖茄子 |
-| 使用时间 | 文本 | 节假日除外 |
-| 其他说明 | 文本 | 不可叠加 |
+| 订单佣金 | 配置(0%) | 支付快照 |
+| 核销佣金 | 配置(3%) | 核销时按门店归属合伙人 |
+| 门店结算 | 60% | T+1；未出账可提现 |

- 可不填；可多条；**同一门店最多 10 条**
- C 端仅展示**已审核通过（生效中）**的套餐，自上而下标题+内容形式
+**多合伙人**：全城/区域管辖；同城订单佣金按收货区县解析；核销佣金归拓店合伙人。  
+**FIN-001~003**：白名单未出账提现 · 单店日限 ¥5000 · T+0 审完预警。  
+合伙人 **T+30** 独立月账/打款。

-#### 3.9.2 维护与审核
+### 3.4~3.8 Wave 能力

-| 端 | 能力 | 审核 |
-|----|------|------|
-| 合伙人拓店 | 新建流程增加「套餐」页（可跳过） | 随门店或独立提审（见开发文档） |
-| 合伙人门店详情 | 套餐列表 → 编辑 → **提交审核** | 是 |
-| 门店端 | 套餐列表 → 编辑 → **提交审核** | 是 |
-| 总部 | 门店详情新增「套餐」Tab | **直接保存生效，无需审核** |
+- **3.4** 门店一号多店、主账号、店员子账号(W2)
+- **3.5** 拓店三步 + SOP + 试核销100
+- **3.6** 工单四类型：仅退款/破损补发/破损退货/退货退款
+- **3.7** 多仓、承运商、物流月结对账（小飞侠：2瓶6元 +2/瓶，6瓶箱14元）
+- **3.8** 弱网5次拍照兜底(W3)

- 合伙/门店提交后 → 总部收到套餐变更审核 → **通过/驳回**
- **通过**：自动替换该店生效套餐；**驳回**：保留上一版生效套餐
- 提审中：C 端仍展示上一版已通过套餐（从未通过则不展示）
+### 3.9~3.11 增量（详开发文档）

-#### 3.9.3 客服异议
+| § | 主题 | 文档 |
+|---|------|------|
+| 3.9 | 门店套餐 ≤10 条、独立审核 | v3.4.10 |
+| 3.10 | 开发计划/任务/版本/技术支持联动 | v3.4.11 |
+| 3.11 | 企微智能机器人 + 消息推送 Webhook | v3.4.11 |

- 用户对核销过程中套餐内容有异议 → 可提交客服申诉
- 工单/客服类型新增：**套餐异议**（`PACKAGE_DISPUTE`）
+---

-### 3.10 开发计划（引入于 **3.4.11**）
+## 4. REQ 索引

-> 实现设计见 [`杜康好客-开发计划功能开发文档-v3.4.11.md`](./杜康好客-开发计划功能开发文档-v3.4.11.md)
+> 完整 REQ：`.cursor/skills/dukang-v3/reference-req-index.md`

-总部 admin-web 新增一级菜单 **开发计划**，含版本列表、任务列表、开发设置；与 **技术支持** 工单审批联动（通过后创建开发任务）。
+| 端 | ID 范围 | 模块要点 |
+|----|---------|----------|
+| 用户 | U-001~027 | 四Tab/支付/权益3min/门店/套餐/工单/发票/推广/评价 |
+| 门店 | S-001~021 | 核销双通道/记录×60%/提现/子账号/套餐提审 |
+| 合伙人 | P-001~027 | 子账号/拓店+套餐/订单账单/代下单(W3) |
+| 总部 | H-001~028 | 开城/审核/结算/推广/套餐/开发计划 |

-| 子模块 | 要点 |
-|--------|------|
-| 版本 | CRUD；多选关联任务；状态流转自动写时间戳/用时 |
-| 任务 | 全局任务池 CRUD；勾选 → **评审派发** → 任务派发助手 Webhook（@ 开发者 userid） |
-| 设置 | 任务派发助手（单例）；本地审核 AI 助手 |
-| 技术支持 | 单一「审批」入口；通过须 ≥1 开发任务；批量 AI 预审 → 人工确认 |
+**SKU 锚价**：128/168/298/498（瓶）· 768/1008/1788/2988（箱6瓶）。

-企微接入：开发计划任务派发、运营告警、技术支持工单通知均走 HQ「企微机器人 → 消息推送」（Webhook 多实例 + 条件勾选）；对话能力由「智能机器人」WebSocket SDK 承担。
+---

-### 3.11 企微机器人（引入于 **3.4.11**）
+## 5. 非功能 NFR-001~010

-> HQ 菜单：**企微机器人** → 智能机器人 `/wecom/bots`、消息推送 `/wecom/pushes`、智能机器人日志 `/logs/wecom-bots`
+7天免登 · 微信单支付 · 验证码3min · 脱敏鉴权 · 幂等 · 弱网/兜底 · 兼容 · 审计 · 24h履约 · 推广归因落库。

-#### 3.11.1 智能机器人（长连接）
+---

-| 角色 | 默认能力 |
-|------|----------|
-| **客服助手** | 订单/配送/门店/核销/售后工单只读 + 创建售后工单 + 短信验证查用户 |
-| **财务助手** | 门店/合伙人/酒厂/物流账单、打款、提现 **只读** |
-| **运营助手** | 订单/门店/用户/核销/配送 **只读** |
-| **技术支持** | 技术支持工单只读/创建；**审批**（通过/驳回）；开发计划只读 |
-| **自定义** | HQ 手工勾选模块化权限 |
+## 6. 数据与集成

-**权限模型**：按模块划分（如 `order.read`、`finance.store_bill.read`、`support_ticket.review`）；废弃 `api.read.all`、`db.read`。聊天回复仅 Markdown 业务摘要，禁止 JSON/tool 泄露。
+**实体**：用户/商品/订单(佣金快照)/权益/门店/套餐/核销/工单/结算/合伙人/推广/仓(W3)/待处理核销(W3)。

-**审批**：仅机器人配置的 **SuperAdmin 企微 userid 白名单** 可执行 `support_ticket.review`；「通过」须自动从工单标题创建 **1 条** 开发任务（类型映射同 HQ 审批）。
-
-**审计**：每条查询/审批写入 `log_wecom_bot`，Admin 可筛选 bot、userid、action、时间。
-
-#### 3.11.2 消息推送（Webhook 多实例，v3.4.11）
-
-| 字段 | 说明 |
+| TECH | 系统 |
 |------|------|
-| 名称 / 头像 | HQ 列表展示 |
-| Webhook URL | 企微群机器人 Webhook（**运行时仅读 DB，不读 .env**） |
-| 启用 | 列表开关 |
-| @ userid | 可选，markdown `<@userid>` |
-| 推送条件 | 多选 eventKey，可同时匹配多条推送 |
+| 011~012 | 微信支付/短信 |
+| 013 | 小飞侠 |
+| 014~016 | 微信能力/分享/腾讯位置 |

-**推送条件（eventKey）**：
-
-| key | 触发场景 |
-|-----|----------|
-| `alert.ops` | 售后工单、客户端错误等运营告警 |
-| `support_ticket.created` | 新建技术支持工单（独立 Markdown，可与 alert.ops 并行） |
-| `alert.pay` / `alert.redeem` | 支付/核销异常 |
-| `alert.system` | 5xx、监控、回调 |
-| `alert.settlement` | 结算 scheduler |
-| `dev_plan.task_dispatch` | 开发任务评审派发 |
-
-**迁移**：首次空表时从 `.env` `WECOM_ALERT_WEBHOOK_URL` seed「运营告警」；原 `dev_plan_settings.task_dispatch_*` seed「开发任务派发」。废弃系统设置 `WECOM_ALERT_ENABLED` 与开发设置任务派发 Webhook UI。
+**金额**：权益=实付1:1 · 门店结算=核销×60% · 试核销=**100元** · 码TTL=**3min**。

 ---

-## 4. 功能需求（REQ 索引）
+## 7~8. UI 与 ACC

-> 完整 REQ 结论见 [`.cursor/skills/dukang-v3/reference-req-index.md`](./.cursor/skills/dukang-v3/reference-req-index.md)
-
-### 4.1 用户端（小程序）— REQ-U-001 ~ 027
-
-| 模块 | 要点 |
-|------|------|
-| 导航账号 | 四 Tab；无感登录；确认下单提示绑定手机号（可选、不强制）；仅微信支付；7 天免登 |
-| 商品下单 | 4 款酒祖杜康 SKU；同城≥2瓶免运费；跨城≥1箱；现场提货隐藏；锁单30分钟 |
-| 权益核销 | 1:1 发放；出码 3 分钟；核销前规则弹窗（OPT-011）；附件一规则详情 |
-| 门店 | 列表/详情/搜索/省市区筛选；仅营业中展示；立即核销 |
-| **门店套餐（3.4.10）** | 门店详情展示生效套餐（标题+内容）；套餐异议申诉入口（REQ-U-027） |
-| 增长售后 | 四类型工单 + **套餐异议**；发票四组合；成交问卷（无激励）；推广码；微信商品分享 |
-| 评价 | 核销后门店评价 |
-
-**SKU 价格锚点**
-
-| 商品 | 瓶价 | 箱价(6瓶) |
-|------|------|-----------|
-| 酒祖杜康（国标特级10）53° | ¥128 | ¥768 |
-| 酒祖杜康（国标特级15）53° | ¥168 | ¥1008 |
-| 酒祖杜康（国标特级20）53° | ¥298 | ¥1788 |
-| 酒祖杜康（国标特级30）53° | ¥498 | ¥2988 |
-
-### 4.2 门店端（H5）— REQ-S-001 ~ 021
-
-| 模块 | 要点 |
-|------|------|
-| 登录 | 主账号/店员；多店选店（Wave 2）；7 天免登 |
-| 核销 | 扫码大按钮 + 手机号通道；手机号、金额、验证码与确认核销同页完成，先按手机号和金额发送验证码，验证成功后直接核销；今日汇总；弱网处理 |
-| 记录结算 | 筛今日/7日/1月/全部；到账金额×60%；T+1 出账 |
-| 提现 | 未出账可提（FIN 护栏）；提现记录；结算异议 3 工作日 |
-| 账号 | 主账号管理店员（Wave 2）；待处理核销单（Wave 3） |
-| **门店套餐（3.4.10）** | 套餐列表/编辑；提交审核（REQ-S-021） |
-
-### 4.3 合伙人端（H5）— REQ-P-001 ~ 027
-
-| 模块 | 要点 |
-|------|------|
-| 权限 | 管理员 vs 推广员菜单裁剪 |
-| 拓店 | 三步录入 + **套餐页（3.4.10，可跳过）**；一号多店确认；负责人复核；试核销100元；附件一 |
-| 经营 | 首页三卡；排行；订单/权益/工单；佣金快照下钻 |
-| 财务 | 本合伙人月账对账（Wave 2/3） |
-| 扩展 | 代下单（Wave 3）；管仓只读（Wave 3） |
-| **门店套餐（3.4.10）** | 拓店套餐页；门店详情套餐列表/编辑/提审（REQ-P-027） |
-
-### 4.4 总部端（H5）— REQ-H-001 ~ 028
-
-| 模块 | 要点 |
-|------|------|
-| 基础 | 商品管理；营销规则 1:1 权益；签约主体：山西领势酒业有限责任公司 |
-| 城市合伙人 | 开通城市；创建合伙人（全城/区域+佣金）；仓库管理（Wave 3） |
-| 审核交易 | 门店审核；**套餐变更审核（3.4.10）**；全量订单/权益/工单；发票 2 工作日；补核销 |
-| 结算 | 门店+合伙人双 Tab；提现审；白名单配置；**物流对账**（按承运商月结） |
-| 增长 | 推广码；问卷；评价；腾讯位置热力图 |
-| **门店套餐（3.4.10）** | 门店详情「套餐」Tab 直存；套餐变更审核通过/驳回（REQ-H-025） |
-| **开发计划（3.4.11）** | 版本/任务/设置；企微 Agent；任务评审派发；技术支持审批联动（REQ-H-026~028） |
-
-### 4.5 端职责矩阵
-
-| 能力 | 用户端 | 门店端 | 合伙人端 | 总部端 |
-|------|:------:|:------:|:--------:|:------:|
-| 下单/支付/权益 | ● | | 代下单 | 代下单 |
-| 核销 | 出码 | ● | 看记录 | 看全量 |
-| 拓店 | 看门店 | 改营业 | ●录入 | ●审核 |
-| 工单 | ●发起 | 查看 | 查看 | ●决策 |
-| 结算提现 | | ● | 对账确认 | ●审打款 |
-| 推广码/问卷/评价 | ● | 被评价 | 看数据 | 配置/看板 |
-| **门店套餐（3.4.10）** | 看生效套餐 | 编辑提审 | 编辑提审 | ●直存/●审核 |
+主色杜康红 `#8B1E1E` · 权益金 `#C4A35A` · 空态人话+下一步。  
+ACC 全量：`.cursor/skills/dukang-v3/reference-acc.md`

 ---

-## 5. 非功能需求
+## 9. 三波交付

-| 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 | 归因 | 推广码与佣金归属下单时落库 |
+| 波 | 日期 | 门禁 | 含 | 不含 |
+|----|------|------|-----|------|
+| W1 | 7.10 | S1~S4 | 登录商品支付核销拓店子账号 | 提现推广现场跨城工单发票 |
+| W2 | 7.15 | S1~S5 | 提现FIN推广现场门店子账号多合伙 | 代下单弱网多仓跨城发票问卷 |
+| W3 | 7.22 | 全量 | 代下单弱网多仓跨城工单发票看板 | — |

---
-
-## 6. 数据实体与外部依赖
-
-### 6.1 核心实体（TECH-001 ~ 019）
-
-用户、商品、订单（含佣金快照）、好客权益账本、门店（主账号/店员）、**门店套餐（3.4.10）**、核销单、工单、结算/提现、合伙人（管辖+佣金）、推广码、仓库（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%
- 物流费 = 按承运商计价标准对单票瓶数计价（小飞侠默认见 §3.7.1）
- 核销码 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 | 合伙人主账号：选品/履约（配送须勾选自动收货或现场提货）→创建待支付订单→收款码或微信代付（合伙人 openId）→支付成功发权益；配送单 PENDING_SHIP 由总部发货，合伙人可看物流；现场提货支付后自提闭环；新用户 sourceType=PARTNER_PROXY；总部代下单同为在线收款码支付 |
-| 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. 变更记录
-
-| 版本 | 日期 | 说明 |
-|------|------|------|
-| **3.4.10** | 2026-08-03 | 新增 §3.9 门店套餐；REQ-P-027 / REQ-S-021 / REQ-H-025 / REQ-U-027；套餐异议工单类型 |
-| v3.0.2 | 2026-08-02 | OPT-002/SC-07：代下单改为在线支付（收款码/合伙人微信代付）；去掉线下已收款直完成；配送单总部履约、合伙人可看物流 |
-| v3.0.1 | 2026-07-27 | ACC-012/OPT-002/SC-07：明确合伙人代下单双短信、线下完成、来源 PARTNER_PROXY、C 端展示代下单人 |
-| 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 需刘景尧）
+DLV 任务卡：`.cursor/skills/dukang-task-card/`
@@ -1,86 +1,38 @@
 # 杜康好客 · V3 埋点规范

-> **版本**：2026-08-03  
-> **存储**：C 端 → `log_user_analytics`；门店 → `log_store_analytics`；合伙人 → `log_partner_analytics`  
-> **契约**：[`packages/shared-types/src/*-log.ts`](../packages/shared-types/src/)  
-> **查询**：admin-web `/logs/users` · `/logs/stores` · `/logs/partners`
+> 存储：C→`log_user_analytics` · 门店→`log_store_analytics` · 合伙人→`log_partner_analytics`  
+> 契约：`packages/shared-types/src/*-log.ts` · HQ：`/logs/users|stores|partners`

 ## 原则

-1. 端侧 **page_view / 点击** 走客户端 `track()`；业务结果（支付成功、核销确认）走后端 `AnalyticsService.track*Safe`
-2. 所有客户端事件携带 `sessionId`（localStorage `dukang_session_id`），支持匿名漏斗
-3. `extraJson` 不含密码/令牌；手机号脱敏
-4. eventName 必须先登记在 shared-types taxonomy，再 emit
+1. 端侧 page_view/点击 → `track()`；支付/核销结果 → 后端 `AnalyticsService.track*Safe`
+2. 携带 `sessionId`（`dukang_session_id`）
+3. `extraJson` 无密码/令牌；手机号脱敏
+4. eventName 先登记 taxonomy 再 emit

 ## API

 | 端 | 路由 | 鉴权 |
 |----|------|------|
-| C 端 | `POST /api/v1/analytics/events` | OptionalJwt |
-| 门店 | `POST /api/v1/analytics/store-events` | Jwt + STORE |
-| 合伙人 | `POST /api/v1/analytics/partner-events` | Jwt + PARTNER |
-| 推广 | `POST /api/v1/promo/touch` | OptionalJwt（双写 `promo_touch` 埋点） |
+| C | `POST /analytics/events` | OptionalJwt |
+| 门店 | `POST /analytics/store-events` | Jwt+STORE |
+| 合伙人 | `POST /analytics/partner-events` | Jwt+PARTNER |
+| 推广 | `POST /promo/touch` | OptionalJwt（双写 touch） |

-## 完整 eventName 清单
+## eventName

-见 shared-types：
+完整清单 → `user-log.ts` / `store-log.ts` / `partner-log.ts`

- [`user-log.ts`](../packages/shared-types/src/user-log.ts) — C 端 13 个 category
- [`store-log.ts`](../packages/shared-types/src/store-log.ts) — 门店 8 个 category
- [`partner-log.ts`](../packages/shared-types/src/partner-log.ts) — 合伙人 9 个 category
+## extraJson 要点

-## extraJson 字段约定
+| 端 | 常用字段 |
+|----|----------|
+| C | sessionId, cityCode, productId, storeId, orderId, amount, pagePath, failReason |
+| 门店 | redeemChannel, amount, durationMs, failReason |
+| 合伙人 | storeId, orderId, billId, cityCode |

-### C 端（UserAnalyticsExtra）
+## 漏斗（摘要）

-| 字段 | 说明 |
-|------|------|
-| sessionId | 会话 ID，漏斗串联 |
-| cityCode | 开城/地域 |
-| productId / skuId | 商品偏好 |
-| storeId | 门店偏好 |
-| orderId | 订单归因 |
-| amount / quantity | 客单价 |
-| sourceType / sourceRefId | 获客渠道 |
-| failReason | 失败原因 |
-| pagePath | 页面路径 |
-
-### 门店（StoreAnalyticsExtra）
-
-| 字段 | 说明 |
-|------|------|
-| redeemChannel | scan / phone / pending |
-| amount | 核销金额 |
-| durationMs | 耗时 |
-| failReason | 失败原因 |
-
-### 合伙人（PartnerAnalyticsExtra）
-
-| 字段 | 说明 |
-|------|------|
-| storeId / orderId / billId | 业务关联 |
-| cityCode | 城市维度 |
-
-## 转化漏斗（C 端）
-
-```
-session_start → home_view → product_detail_view → order_confirm_view
-  → order_submit → pay_page_view → pay_success
-  → benefit_redeem_start → redeem_code_view → benefit_redeem_success
-```
-
-## 核销漏斗（门店）
-
-```
-store_home_view → store_redeem_scan_start → store_redeem_preview
-  → store_redeem_confirm | store_redeem_confirm_fail
-```
-
-## 合伙人经营漏斗
-
-```
-partner_home_view → partner_store_create_view → partner_store_create
-  → partner_store_audit_approved
-partner_order_list_view → partner_order_ship
-partner_bills_view → partner_bill_detail_view → partner_bill_confirm
-```
+- **C**：session→home→detail→confirm→submit→pay→redeem
+- **门店**：home→scan→preview→confirm
+- **合伙人**：home→store_create→audit / orders→ship / bills→confirm
@@ -1,124 +1,37 @@
-# 杜康好客 · V3 城市 / 仓库 / 日志架构
+# 杜康好客 · 城市 / 仓库 / 日志架构

-> **版本**：2026-07-12  
-> **状态**：P1 城市多合伙 + P2 仓库 **已实现**（2026-07-12）；合伙人端管仓日志仍待 Wave 3  
-> **分工**：刘景尧任务暂由 `jacy-dukang` 代管（见 `AGENTS.md`）
+> **2026-07-12** P1 多合伙 + P2 仓库 ✅ · 合伙人管仓日志 ⏳ Wave 3

---
-
-## 1. 目标数据模型（城市顶层）
+## 数据模型（摘要）

 ```
-CommonCity (开城)
-  ├── PartnerAccount[]  1:N 主账号（isPrimary=1，含城市绑定 + 购酒/核销佣金）
-  ├── CityWarehouse[]   1:N 城市仓库（HQ 管 / 合伙人管）
-  └── CatalogProduct[]  按城市上架
-
-PartnerAccount (主账号 = 城市合伙人主体)
-  ├── cityId / scopeType / districtCodes / bindingStatus
-  ├── orderCommissionRate / redeemCommissionRate
-  ├── companyName / 银行 / 合同等主体信息
-  ├── managedWarehouseId?  可选管仓
-  └── PartnerAccount[]     子账号（parentAccountId，permissions JSON）
-
-CityWarehouse
-  ├── cityId
-  ├── managerType: HQ | PARTNER
-  └── partnerAccountId?    合伙人管仓时绑定主账号
-
-Store
-  ├── partnerAccountId     FK → 主账号
-  └── settlementRate       门店核销结算比例（默认 0.60）
+CommonCity → PartnerAccount(主) → Store(partnerAccountId, settlementRate)
+          → CityWarehouse(HQ|PARTNER 管仓)
+          → CatalogProduct
+PartnerAccount → 子账号(parentAccountId, permissions JSON)
 ```

-**迁移要点（2026-07）**：删除 `partner_partner`、`common_city_partner`、`common_city_commission_rule`；城市绑定与购酒分佣合并至 `partner_account` 主账号；门店结算比例下沉至 `store_store.settlementRate`；订单快照字段为 `partnerAccountIdAtPay` + `orderCommissionRateAtPay`。
+迁移：城市绑定/购酒分佣合并至 `partner_account`；订单快照 `partnerAccountIdAtPay` + `orderCommissionRateAtPay`。

---
+## 日志职责

-## 2. 日志表与职责划分
+| 主体 | 表 | 入口 |
+|------|-----|------|
+| HQ 写操作 | `common_event` HQ_OPERATION | `@HqOperation` → `/logs/hq` |
+| 合伙人 | `log_partner_analytics` | `/logs/partners` |
+| 门店 | `log_store_analytics` | `/logs/stores` |
+| C 端 | `log_user_analytics` | `/logs/users` |
+| 权益/订单 | `common_event` BENEFIT_LEDGER / ORDER_STATUS | 领域查询 |

-| 操作主体 | 日志表 | eventType / eventName | 查询入口 |
-|----------|--------|----------------------|----------|
-| **HQ WebAdmin** 写操作 | `common_event` | `HQ_OPERATION` + `param1=action` | admin-web `/logs/hq` |
-| **合伙人端** 行为 | `log_partner_analytics` | `partner_*` eventName | admin-web `/logs/partner` |
-| **门店端** 行为 | `log_store_analytics` | `store_*` | admin-web `/logs/store` |
-| **C 端** 行为 | `log_user_analytics` | 埋点 eventName | admin-web `/logs/user` |
-| 权益/订单状态机 | `common_event` | `BENEFIT_LEDGER` / `ORDER_STATUS` | 领域查询 |
+## HQ action（新业务）

-**原则**：HQ 侧 **CRUD / 审核 / 结算确认** 一律 `@HqOperation` → `common_event`；端侧 **登录 / 业务操作** 走对应 `log_*_analytics`。
+`CITY_*` · `WAREHOUSE_*` · `PARTNER_*` · `PARTNER_ACCOUNT_*` · `HQ_ACCOUNT_*` · `HQ_PERMISSION_*`  
+常量：`hq-operation.constants.ts` · 筛选项：`apps/admin-web/src/lib/hq-log.ts`

---
+## 合伙人子账号 eventName

-## 3. CRUD → 日志映射（新业务）
+`partner_staff_create|update|permission_update|delete` ✅ · `partner_warehouse_*` ⏳

-### 3.1 HQ 侧（`common_event.HQ_OPERATION`）
+## DoD

-| 实体 | refType | action 常量 | 装饰器状态 |
-|------|---------|-------------|------------|
-| 开城城市 | `CITY` | `CITY_CREATE` / `CITY_UPDATE` | ✅ 已接入 |
-| 开城城市 | `CITY` | `CITY_DELETE` | ⏳ 待 API |
-| 城市仓库 | `WAREHOUSE` | `WAREHOUSE_CREATE` / `UPDATE` / `DELETE` | ✅ 已接入 |
-| 城市合伙人（主账号） | `PARTNER` | `PARTNER_CREATE` / `PARTNER_UPDATE` | ✅ 已接入 |
-| 合伙人账号（HQ） | `PARTNER_ACCOUNT` | `PARTNER_ACCOUNT_CREATE` / `UPDATE` / `DELETE` | ✅ 已接入 |
-| HQ 管理员 | `HQ_ACCOUNT` | `HQ_ACCOUNT_CREATE` / `UPDATE` | ✅ 已接入 |
-| HQ 权限 | `HQ_PERMISSION` | `HQ_PERMISSION_UPDATE` | ✅ 已接入 |
-
-实现约定：
-
- Controller 方法加 `@HqOperation({ action, refType, refIdField|refIdParam, includeBody })`
- `extraJson` 自动写入 `requestBody`（脱敏 password）+ `response` 摘要
- 常量定义：`server/.../hq-operation.constants.ts`；admin 筛选项：`apps/admin-web/src/lib/hq-log.ts`
-
-### 3.2 合伙人端子账号（`log_partner_analytics`）
-
-| 操作 | eventName | refType | 状态 |
-|------|-----------|---------|------|
-| 主账号新增子账号 | `partner_staff_create` | `PARTNER_ACCOUNT` | ✅ `PartnerStaffService` |
-| 编辑子账号 | `partner_staff_update` | `PARTNER_ACCOUNT` | ✅ |
-| 仅改角色/权限 | `partner_staff_permission_update` | `PARTNER_ACCOUNT` | ✅ |
-| 删除子账号 | `partner_staff_delete` | `PARTNER_ACCOUNT` | ✅ |
-| 仓库查看/维护（合伙人管仓） | `partner_warehouse_view` / `partner_warehouse_update` | `WAREHOUSE` | ⏳ Wave 3 |
-
-分类：`packages/shared-types/src/partner-log.ts` → `account_ops` / `warehouse_ops`。
-
-### 3.3 门店子账号
-
-| 操作 | 日志表 | action / eventName | 状态 |
-|------|--------|-------------------|------|
-| HQ 创建/编辑门店账号 | `common_event` | `STORE_ACCOUNT_CREATE` / `UPDATE` | ✅ |
-| 门店端自助（若有） | `log_store_analytics` | 待定义 `store_staff_*` | ⏳ |
-
---
-
-## 4. 实现检查清单（DoD）
-
-每条 CRUD 合并前确认：
-
- [ ] HQ 写接口有 `@HqOperation`，且 `HqOperationAction` + `hq-log.ts` 标签已同步
- [ ] 合伙人端写接口调用 `AnalyticsService.trackPartnerOneSafe`，eventName 已登记在 `partner-log.ts`
- [ ] `extraJson` 不含明文密码/令牌；手机号脱敏
- [ ] admin-web 日志页可按 action / category 筛选到新事件
- [ ] 跨模块不直写他人日志表（经 Analytics / HqOperationLogService）
-
---
-
-## 5. 分阶段交付
-
-| 阶段 | 内容 | 依赖 |
-|------|------|------|
-| **P0 日志补全** | 子账号 CRUD 落 `log_partner_analytics`；扩展 HQ action 常量 | 无 |
-| **P1 城市架构** | `city_partner` 表、迁移 `partner_id`、HQ CRUD + `@HqOperation` | ✅ 2026-07-12 |
-| **P2 仓库** | `city_warehouse` 表、HQ CRUD + 合伙人管仓校验 | ✅ 2026-07-12 |
-| **P3 权限 JSON** | `PartnerAccount.permissions` 替代纯 `staffRole`；权限变更双写 HQ/合伙人日志 | P1 |
-
---
-
-## 6. 相关文件
-
-| 路径 | 说明 |
-|------|------|
-| `server/dukang-api/src/common/hq-operation/` | HQ 审计装饰器 + 拦截器 |
-| `server/dukang-api/src/modules/iam/partner-staff.service.ts` | 合伙人子账号 + 日志 |
-| `packages/shared-types/src/partner-log.ts` | 合伙人日志分类 |
-| `apps/admin-web/src/pages/HqLogsPage.tsx` | HQ 操作日志 |
-| `apps/admin-web/src/pages/PartnerLogsPage.tsx` | 合伙人日志 |
+HQ 写接口有 `@HqOperation`；合伙人写走 `trackPartnerOneSafe`；extraJson 脱敏；不跨模块直写他人日志表。
@@ -1,359 +1,66 @@
-# 杜康好客 · V3.0 现状对照表
+# 杜康好客 · 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 冲突（需改造） · ❌ 未实现
+> 基准：仅 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · 总部 = **`admin-web`**（非 H5）  
+> 图例：✅ 完成 · 🔶 部分 · ❌ 未做 · ⚠️ 曾冲突已修

---
-
-## 0. 总览
+## 0. 总览（2026-08-06）

 | 维度 | 结论 |
 |------|------|
-| **整体完成度（粗估）** | 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 全量 |
+| 主链路 | 登录→下单支付→权益→扫码核销→payout→HQ 打款 **可跑通** |
+| C 端 | `mini-user` 小程序 + h5-user；v3.4.13 版本门控/门店/物流已上 |
+| 近期版本 | v3.4.10 套餐 · v3.4.11 开发计划/企微 · v3.4.12 工单迭代 · v3.4.13 体验优化 **已发生产** |
+| 冒烟 | `scripts/smoke-v3.mjs` 窄路径 ≠ 全量 ACC |
+| REQ 明细 | PRD §4 + `.cursor/skills/dukang-v3/reference-req-index.md` |

-### Wave 门禁状态
+## 1. P0 冲突（2026-07-12 ✅）

-| 门禁 | 状态 | 一句话 |
-|------|------|--------|
-| **W1-S1** 下单+支付+权益 | 🔶 | TTL/Tab/SKU/佣金已对齐；仍缺小程序形态 |
-| **W1-S2** 门店核销双通道 | 🔶 | 扫码 ✅；手机号核销 ❌ |
-| **W1-S3** 合伙人子账号 | ✅ | CRUD + 推广员菜单裁剪已有 |
-| **W1-S4** 拓店→审核→C 端可见 | 🔶 | 三步录入有；试核销100/负责人复核/SOP 缺失 |
-| **W2-S1~S5** | ❌ | 提现/FIN/现场提货/多合伙人/门店子账号 基本未做 |
-| **W3-S1~S4** | ❌ | 代下单/弱网拍照/多仓/跨城履约/四类型工单/发票/问卷/热力图 基本未做 |
+| # | 项 | 状态 |
+|---|-----|------|
+| C2~C3 | 核销/短信 TTL **3min** | ✅ |
+| C4~C5 | 订单 Tab/列表 **三态** | ✅ |
+| C6~C7 | 4 SKU + 佣金 **0%+3%** | ✅ |
+| C13 | 多合伙人主账号模型 | ✅ |
+| C14 | 文档旧口径清理 | ✅ |
+| C1 | C 端小程序 | 🔶 mini-user 进行中 |
+| C8~C12 | 一号多店/自动推单/提现/四类型工单/现场提货 | 🔶~❌ 见 PRD Wave |

---
+## 2. 按域快照

-## 0.1 已确认的工程口径（非冲突）
+| 域 | ✅ 已有 | 🔶/❌ 主要缺口 |
+|----|---------|----------------|
+| **mini-user** | 购酒/权益/核销/门店/物流/版本门控 | 规则弹窗、发票、四类型工单、问卷 |
+| **h5-shop** | 扫码核销、记录、营业、iOS 扫码 OAuth | 手机号核销、提现、子账号、弱网兜底 |
+| **h5-partner** | 子账号、拓店、订单/账单、套餐 | 试核销100、负责人复核、代下单 |
+| **admin-web** | 商品/开城/门店/订单/权益/核销/结算/推广码 metrics/开发计划/技术支持 | 完整 SOP 审核 UI、发票、热力图 |
+| **后端** | 主模块、支付、权益、核销、payout、Courier 适配 | 30min 取消 job、部分 Wave3 |

-| 项 | PRD 原文 | V3 工程决策 |
-|----|----------|-------------|
-| 总部端形态 | 总部 H5 | **`apps/admin-web`（WebAdmin）为唯一交付端，不改为 H5** |
-| 验收方式 | REQ-H-* | 功能在 admin-web 实现即可；不要求微信内 H5 或小程序总部端 |
-| `mini-hq` | — | 非主交付；与 admin-web 重叠能力以 **admin-web 补齐** 为准 |
+## 3. 场景 SC-01~09

---
-
-## 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` |
+| SC-01 同城 | 🔶 支付权益✅；自动推单/24h 完成 部分 |
+| SC-02 现场提货 | 🔶 |
+| SC-03 跨城 | 🔶 |
+| SC-04 核销 | 🔶 扫码✅；手机号通道❌ |
+| SC-05 拓店 | 🔶 三步✅；试核销/SOP 部分 |
+| SC-06 售后 | 🔶 REFUND 有；四类型 部分 |
+| SC-07~09 | 代下单❌ · 问卷🔶 · 推广🔶 |

-> **重跑 seed**：本地需 `cd server/dukang-api && pnpm prisma:seed` 后商品/佣金数据才与 C6/C7 一致。
+## 4. 版本交付索引

---
-
-## 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** 话术对齐 | 无运营文档交付机制 |
-
-### 3.4 门店套餐（目标版本 **3.4.10**，未实现）
-
-> 需求：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) §3.9 · 开发设计：[`杜康好客-门店套餐功能开发文档-v3.4.10.md`](./杜康好客-门店套餐功能开发文档-v3.4.10.md)
-
-| REQ / 能力 | 说明 |
-|------------|------|
-| **REQ-P-027** 合伙人拓店套餐页 + 门店套餐编辑提审 | 拓店仍三步；无套餐页；无 `StorePackage` 实体 |
-| **REQ-S-021** 门店端套餐列表/编辑/提审 | 门店端仅营业状态；无资料编辑 API |
-| **REQ-H-025** 总部套餐 Tab 直存 + 套餐变更审核 | 门店 Drawer 无套餐 Tab；无独立套餐审核流 |
-| **REQ-U-027** C 端展示生效套餐 + 套餐异议 | 门店详情无套餐区块；工单无 `PACKAGE_DISPUTE` |
-| **数据模型** | 无 `store_package` / `store_package_change_request` 表 |
-
---
-
-## 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 有；现场提货归码 ❌ |
+| 3.4.10 | [`门店套餐`](./杜康好客-门店套餐功能开发文档-v3.4.10.md) | ✅ |
+| 3.4.11 | [`开发计划`](./杜康好客-开发计划功能开发文档-v3.4.11.md) | ✅ |
+| 3.4.12 | [`工单迭代`](./杜康好客-v3.4.12-工单迭代开发文档.md) | ✅ |
+| 3.4.13 | [`体验优化`](./杜康好客-v3.4.13-体验优化开发文档.md) | ✅ 生产 `0181af0` |

---
-
-## 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. v3.4.11 开发计划（2026-08-04）
-
-| 项 | 状态 | 说明 |
-|----|------|------|
-| Prisma 六表 + shared-types | ✅ | `dev_plan_*` |
-| DevPlanModule API | ✅ | `/admin/dev-plan/*` |
-| 技术支持 review + 批量 AI | ✅ | `SupportTicketReviewAiService` |
-| admin-web 三页面 + 菜单 | ✅ | `/dev-plan/versions|tasks|settings` |
-| 企微机器人角色/权限重构 | ✅ | 四类角色、模块化权限、`log_wecom_bot`、Capability 门面 |
-| 企微菜单重组 | ✅ | 智能机器人 `/wecom/bots`、消息推送 `/wecom/pushes`、日志 |
-| 消息推送多实例 | ✅ | `wecom_message_push`、eventKey 分发、迁移 env/旧派发配置 |
-| 文档 | ✅ | PRD §3.10 + §3.11 + 开发文档 v3.4.11 |
-
---
-
-## 9. v3.4.12 工单迭代（2026-08-04）
-
-| 项 | 状态 | 说明 |
-|----|------|------|
-| P0 售后退款回滚 | ✅ | `initiateRefund` 微信失败恢复 PAID |
-| mini-user 门店详情 | ✅ | 门头轮播 preview + 环境图双列 |
-| 酒厂 T+3 | ✅ | `WINERY_SETTLEMENT_LAG_DAYS=3` |
-| 门店多笔提现 | ✅ | 移除单 pending 限制 |
-| 审批企微派发 | ✅ | review `dispatchToWecom` |
-| 开发任务批量编辑 | ✅ | `POST /admin/dev-plan/tasks/batch-update` |
-| 技术支持编辑/附件 | ✅ | `PATCH /admin/support-tickets/:id` + `attachmentUrls` |
-| 技术支持批量改状态 | ✅ | domain 状态机 + batch API |
-| 套餐 imageUrl | ✅ | 四端 + Prisma |
-| 文档 | ✅ | PRD §0.4 + v3.4.12 开发文档 |
-
---
-
-## 10. v3.4.13 体验优化（2026-08-05）
-
-| 项 | 状态 | 说明 |
-|----|------|------|
-| 推广码 attributionCount | ✅ | HQ 详情统计卡 + **log_promo_event 事件日志 + metrics/timeline ECharts** |
-| 核销用户信息 | ✅ | RedeemRecordsPage 列表+详情 |
-| 技术支持优先级 | ✅ | Prisma + shared-types + HQ UI |
-| 合伙人微信暂停禁登 | ✅ | loginPartnerWechat |
-| H5 登录前端校验 | ✅ | partner/shop LoginPage |
-| mini-user 门店体验 | ✅ | 电话脱敏/埋点、**列表两段营业时间**、门头 aspectFill 铺满、**套餐页签切换** |
-| mini-user 商品/提货 | ✅ | 去分享、首图 preview、提货确认弹框 |
-| mini-user 版本/物流 | ✅ | 摘要 + 签收照 + 拨号 + 时间线 + ETA；回调签收→**COMPLETED** |
-| OSS 大图压缩 | ✅ | shared-ui compressImage；四端 upload + mini 头像 |
-| 文档 | ✅ | PRD §0.5 + v3.4.13 开发文档 |
-
---
-
-## 11. 变更记录
+## 5. 变更记录

 | 日期 | 说明 |
 |------|------|
-| 2026-08-05 | v3.4.13 体验优化（20 条 ST） |
-| 2026-08-04 | v3.4.12 工单迭代（退款/财务/C端/开发计划/技术支持/套餐） |
-| 2026-08-04 | v3.4.11 开发计划 + 企微智能机器人/消息推送 + 角色权限重构 |
-| 2026-07-12 | **P0 已执行**：C2~C7、C14 代码与文档对齐；§1 改为计划+状态表 |
-| 2026-07-12 | 明确总部端保持 WebAdmin，不改为 H5 |
-| 2026-07-11 | 首版：V3.0 PRD 全量对照当前 monorepo |
+| 2026-08-06 | 文档压缩；现状对照更新 |
+| 2026-08-05 | v3.4.13 |
+| 2026-08-04 | v3.4.11 / v3.4.12 |
+| 2026-07-11 | 首版对照表 |
@@ -1,44 +1,20 @@
-# 杜康好客 · v3.4.12 工单迭代开发文档
+# 杜康好客 · v3.4.12 工单迭代

-> 版本：**v3.4.12** · 日期：2026-08-04  
-> 需求源：ST 工单 + 开发计划/技术支持批量能力补充
+> **2026-08-04** · 已上线 · PRD §0.4

-## 1. 范围
-
-| 模块 | 内容 |
-|------|------|
+| 域 | 交付 |
+|----|------|
 | P0 售后 | `initiateRefund` 微信失败回滚订单状态 |
-| mini-user | 门店详情门头 preview、环境图双列 |
-| 财务 | 酒厂账单 T+3；门店可多笔 pending 提现 |
-| 开发计划 | 审批创建任务可选企微派发；任务批量改状态/关联版本 |
-| 技术支持 | 单条编辑/附件；批量改状态（状态机） |
-| 套餐 | `StorePackage.imageUrl` 四端；HQ 删除至 0 条 UX |
+| mini-user | 门头 preview、环境图双列 |
+| 财务 | 酒厂 T+3；门店可多笔 pending 提现 |
+| 开发计划 | 审批可选企微派发；`POST .../tasks/batch-update` |
+| 技术支持 | PATCH 编辑/附件；`batch-update-status` |
+| 套餐 | `StorePackage.imageUrl` 四端 |

-**不在本版**：ST1785812832352437（门店列表，已完成）
+## API

-## 2. 后端 API
+`POST /admin/dev-plan/tasks/batch-update` · `PATCH /admin/support-tickets/:id` · `POST .../batch-update-status` · review 扩展 `dispatchToWecom`

-| 方法 | 路径 | 说明 |
-|------|------|------|
-| — | `trade.initiateRefund` | 失败时 `REFUNDING→原状态` + 事件 |
-| — | `settlement.generateWineryBillForDay` | `wineryDayWindow(lag=3)` |
-| — | `validateStoreWithdraw` | 移除 `hasPendingRequest` |
-| POST | `/admin/dev-plan/tasks/batch-update` | `{ taskIds, status?, versionId? }` |
-| POST | `/admin/support-tickets/:id/review` | 扩展 `dispatchToWecom`, `dispatchSupplement` |
-| PATCH | `/admin/support-tickets/:id` | 待评审可编辑 |
-| POST | `/admin/support-tickets/batch-update-status` | 批量改状态 |
+## ACC

-## 3. 数据表
-
- `common_support_ticket.attachment_urls` JSON
- `store_package.image_url` VARCHAR(512)
-
-## 4. 验收
-
- [ ] 售后 REFUND 审批后 Mock 退款成功
- [ ] mini-user 门头点击大图、环境图双列
- [ ] 酒厂账单滞后 3 天；门店第二笔提现可提交
- [ ] 审批勾选企微后开发群收到任务
- [ ] 任务多选批量改状态/关联版本
- [ ] 技术支持待评审可编辑附件；批量 TESTING→PASSED
- [ ] 套餐 imageUrl 四端展示；HQ 可删至 0 条
+退款 Mock 成功 · 门头大图 · T+3/多笔提现 · 企微派发 · 批量改任务/工单状态 · 套餐 imageUrl
@@ -1,162 +1,58 @@
-# 杜康好客 · v3.4.13 体验优化开发文档
+# 杜康好客 · v3.4.13 体验优化

-> 版本：**v3.4.13** · 日期：2026-08-05  
-> 需求源：20 条 ST 工单（体验优化 / Bug / 客户端验证）
+> **2026-08-05** · 20 ST · 已发生产 `0181af0` · PRD §0.5 · 现状对照 §10

-## 1. 范围
+## ST 交付一览

-| 模块 | 内容 |
+| ST | 交付要点 |
+|----|----------|
+| ST1785925037781309 | 推广码 attributionCount + `log_promo_event` + metrics/timeline/events + HQ ECharts |
+| ST1785924286682833 | 门店电话 maskPhone + `store_phone_call` 埋点 |
+| ST1785921693982470 | 工单 `priority` + HQ 筛选/编辑 |
+| ST1785921585900725 | 门店 H5：OAuth 单例回调 + iOS JSSDK 预热/重试 + 授权后续扫 |
+| ST1785907536648201 | 我的页 `v3.4.x`；`minClientVersion` 过低 → UpdateManager 或 `exitMiniProgram` |
+| ST1785906800359657 | 合伙人暂停：发码前 `phone/check`，微信/SMS 均拒 |
+| ST1785906592340255 / ST1785901711627824 | partner/shop LoginPage 空字段前端拦截 |
+| ST1785906390321653 | 现场提货提交 `showModal` 确认 |
+| ST1785905773501871 | 核销列表 userNo/nickname/phone；详情含门店/券分摊/结算/评价 |
+| ST1785904849234806 | 工单中心（已有） |
+| ST1785904076632841 | 门店列表「开城合伙人」= `partnerOptionLabel`（company/name/phone） |
+| ST1785902173093977 / ST1785902141731113 | 商品去分享；首图 preview |
+| ST1785901870913349 | 门店列表展示两段营业时间 |
+| ST1785901838948572 | SHOP 未绑定门店（已有） |
+| ST1785901775231811 | 门店套餐页签横滑切换 |
+| ST1785901314893145 | 门头 aspectFill 铺满 + preview |
+| ST1785939375449985 | 物流：签收照/拨号/时间线/ETA；小飞侠回调签收→`COMPLETED` |
+| — | 图片 >10MB：`@dukang/shared-ui/compressImage`（各端 upload + mini 头像） |
+| — | 权益券详情抽屉 980px；核销详情对齐权益券内抽屉 |
+| — | 版本 `RELEASED` → 关联任务 `RELEASED`；关联工单 `PUBLISHED` + `releasedVersionNo` |
+
+## 契约摘要
+
+**API**
+
+| 路径 | 说明 |
 |------|------|
-| admin-web | 推广码 attributionCount + **指标事件日志/ECharts 趋势**；**权益券详情加宽**；**核销记录详情增强（对齐权益券内核销详情）**；技术支持工单优先级；**版本发布联动任务/工单已发布**；**大图上传前压缩** |
-| mini-user | 门店电话脱敏+拨打埋点；**门店列表展示两段营业时间**；**门店详情门头 aspectFill 铺满无留白**；**门店套餐页签切换**；商品去分享+首图 preview；提货确认弹框；**我的页版本号 v3.4.x**；**低于 minClientVersion 强制更新/点我知道了退出**；**物流增强（签收照/拨号/时间线/ETA）**；**头像超 10MB 压缩** |
-| h5-partner / h5-shop / h5-user | 登录 phone/code 前端校验；**门店端 iOS 首次扫码 OAuth 单例 + JSSDK 预热重试**；**OSS 图片超 10MB 自动 canvas 压缩后上传** |
-| 后端 | 工单 priority；**工单 PUBLISHED + releasedVersionNo**；**版本 RELEASED 联动任务/工单**；client-config minClientVersion；合伙人微信暂停禁登；**Courier 适配器**；**log_promo_event 推广码指标日志** |
+| `GET /common/client-config` | `minClientVersion` ← `MINI_USER_MIN_VERSION` |
+| `GET /trade/orders/:id/track` | nodes、signPhotoUrls、estimatedArrival（Courier 100102/108/301） |
+| `POST /callbacks/courier/xfx/track` | 小飞侠路由回调；生产 `api.dukanghaoke.com`，测试 `api-test.dukanghaoke.com` |
+| `GET /admin/promo-codes/:id/metrics/{timeline,events}` | 推广码四指标时序 + 事件分页 |

-## 2. ST 映射
+**表/枚举**

-| ST | 标题 | 状态 |
-|----|------|------|
-| ST1785925037781309 | 总部端-推广码数据跟踪优化 | ✅ attributionCount + **事件日志 + ECharts 趋势** |
-| ST1785924286682833 | 用户端-门店电话加密+拨打埋点 | ✅ maskPhone + store_phone_call |
-| ST1785921693982470 | 技术支持-工单优先级 | ✅ priority 枚举 + HQ UI |
-| ST1785921585900725 | 门店端扫一扫授权异常 | ✅ **OAuth 单例回调 + iOS JSSDK 预热/重试 + 授权后续扫** |
-| ST1785907536648201 | 版本不对提示更新 | ✅ 我的页 v3.4.x + UpdateManager + **低于 min 强制更新/退出** |
-| ST1785906800359657 | 合伙人暂停后禁登 | ✅ **发码前 phone/check + 微信/SMS 登录均拒 DISABLED** |
-| ST1785906592340255 | PARTNER_H5 login 校验 | ✅ 前端空字段拦截 |
-| ST1785906390321653 | 现场提货提交确认弹框 | ✅ showModal |
-| ST1785905773501871 | 核销记录用户信息 | ✅ 列表+详情；**详情含门店/合伙人/券分摊/结算/评价** |
-| ST1785904849234806 | 工单中心 | ✅ 已有 |
-| ST1785904076632841 | 门店列表开城合伙人 | ✅ **列表展示 companyName/name/phone（同 partnerOptionLabel）** |
-| ST1785902173093977 | 去掉商品详情分享按钮 | ✅ 移除 ShareNavButton |
-| ST1785902141731113 | 商品首图大图 | ✅ previewable |
-| ST1785901870913349 | 门店列表营业时间 | ✅ **列表展示两段营业时间** |
-| ST1785901838948572 | SHOP 未绑定门店 | ✅ 已有 |
-| ST1785901775231811 | 门店套餐遮挡 | ✅ **页签切换（可横滑）+ 紧凑内容区** |
-| ST1785901711627824 | SHOP login 校验 | ✅ 前端空字段拦截 |
-| ST1785901314893145 | 门头照裁剪 | ✅ aspectFill 铺满无留白 + preview |
-| ST1785939375449985 | 订单物流追踪页 | ✅ 签收照 + 拨号 + 时间线 + ETA + 路由回调 |
-| — | 上传图片超 10MB 先压缩 | ✅ `@dukang/shared-ui/compressImage` + 各端 upload |
+- `log_promo_event`：SCAN / ATTRIBUTION / REGISTER / ORDER（含 IP/地点；仅统计上线后事件）
+- `common_support_ticket`：`priority`；`status` 增 `PUBLISHED`；`released_version_no`、`published_at`
+- 小飞侠回调：status **5** 或 statusName 含「签收」→ 订单 **COMPLETED**（幂等）；7 取消仅日志

-## 3. 后端 API / 配置
+**HQ 开发计划**

-| 方法 | 路径 / 配置 | 说明 |
-|------|-------------|------|
-| GET | `/common/client-config` | `minClientVersion`（`MINI_USER_MIN_VERSION`）；客户端 semver 比对，低于则强制更新或退出 |
-| — | `CommonSupportTicket.priority` | `LOW \| NORMAL \| HIGH \| URGENT`，默认 NORMAL |
-| — | `CommonSupportTicket.status` | 新增 `PUBLISHED`（已发布）；`releasedVersionNo` + `publishedAt` |
-| — | `DevPlanVersion` → `RELEASED` | 关联任务 → `RELEASED`；关联工单 → `PUBLISHED` 并写入版本号 |
-| — | `loginPartnerWechat` | 非 ACTIVE 账号抛出「合伙人账号已停用」 |
-| GET | `/trade/orders/:id/track` | 聚合：`nodes`（旧→新）、`signPhotoUrls`、`estimatedArrival`；经 `CourierService` 适配小飞侠 cmd 100102/100108/100301 |
-| POST | `/callbacks/courier/xfx/track` | 小飞侠路由变化回调（适配器入口） |
-| POST | `/callbacks/courier/logistics/track` | 跨城物流回调占位（记录日志，后续接入） |
-| POST | `/callbacks/delivery/track` | 兼容旧路径，等同 `xfx` |
-| GET | `/admin/promo-codes/:id/metrics/timeline` | 推广码四指标时间序列（按日/按时 + peak） |
-| GET | `/admin/promo-codes/:id/metrics/events` | 推广码指标事件分页日志（时间/ID/IP/地点） |
+创建版本 `v3.4.13` 并关联 ST 任务；标记 **已发布** 时自动联动任务/工单（见上表最后一行）。

-### 3.1 推广码指标日志（ST1785925037781309）
+## 验收抽样

-**表** `log_promo_event`
-
-| event_type | 统计卡 | 写入时机 | ID |
-|------------|--------|----------|-----|
-| `SCAN` | 扫码进入数 | `POST /promo/touch` 且 `countScan !== false` | userId / sessionId |
-| `ATTRIBUTION` | 归因用户数 | 首次写入 `user_promo_attribution` | userId |
-| `REGISTER` | 扫码注册用户数 | `applyPromoSourceToUser` 成功 | userId |
-| `ORDER` | 订单数 | 带推广码下单 `orderCount++` | orderId + userId |
-
-每条日志含 `created_at`、可选 ID、`client_ip`、`ip_province`/`ip_city`。仅统计**上线后**新事件；累计 Statistic 卡逻辑不变。
-
-**HQ UI**：推广码详情页 → 数据趋势 Card（DatePicker + 按日/按时 + ECharts 四曲线 + 事件 Table）
-
-### 3.2 mini-user 版本门控（ST1785907536648201）
-
-| 项 | 行为 |
-|----|------|
-| 我的页 | 左下角展示 `杜康好客 v3.4.x`（与 `APP_VERSION` / package.json 同步） |
-| 启动校验 | `GET /common/client-config` → `minClientVersion`；`APP_VERSION` 低于最低版本时拦截 |
-| 微信有新包 | `UpdateManager` 弹「立即更新」→ `applyUpdate()` |
-| 无新包 / 仍过低 | 弹「版本过低」→ 点「我知道了」→ `Taro.exitMiniProgram()` 退出小程序 |
-
-### 4. mini-user 物流（ST1785939375449985）
-
-| 页面 | 行为 |
-|------|------|
-| 订单详情 | **配送中**展示最新路由摘要 + 「物流详情」；物流未到时展示 **预估送达**（100301） |
-| 物流详情 | 物流信息；**签收照片**（有则展示，`previewImage` 放大）；**物流动态**旧→新、节点全红点亮、最新在底部 |
-| 电话拨号 | 物流文案中手机号可点击 `makePhoneCall` |
-| 接口 | `GET /trade/orders/:id/track`（`OrderTrackDto`）；C 端禁止直连小飞侠 |
-| 公共模块 | `order-logistics.ts` + `LogisticsRichText` 组件 |
-
-#### 4.1 对外回调 URL（提供给小飞侠）
-
-**生产**
-
-```
-POST https://api.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
-Content-Type: application/json
-```
-
-**测试**
-
-```
-POST https://api-test.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
-```
-
-请求体：
-
-| 字段 | 说明 |
-|------|------|
-| outNumber | 商户单号 |
-| number | 运单号 |
-| status | 1下单 2取件 3中转 4派件 5签收 7取消 |
-| statusName | 中文状态 |
-| trackInfo | 路由描述 |
-| createTime | 路由时间 |
-
-成功响应：`{"code":"100000","message":"success"}`
-
-#### 4.2 Courier 适配器（`integrations/courier`）
-
-| cmd | 能力 | Provider 方法 |
-|-----|------|---------------|
-| 100102 | 路由查询 | `getTrack` |
-| 100108 | 签收照片 | `getSignPhotos` → OSS → `signPhotoUrls` |
-| 100301 | 预估送达 | `checkDeliveryCoverage` → `estimatedArrival` |
-| 回调 | 路由推送 | `parseTrackCallback` + `mapTrackStatus`（**status=5 / statusName 含「签收」→ 订单 `COMPLETED`**） |
-
-**路由回调状态映射（小飞侠）**
-
-| 小飞侠 status / statusName | 系统订单状态 |
-|---------------------------|--------------|
-| 1 下单 | `OUT_WAREHOUSE` |
-| 2 取件 / 3 中转 | `SHIPPING` |
-| 4 派件 | `SHIPPING` |
-| **5 签收** / statusName **已签收** | **`COMPLETED`（已完成）** |
-| 7 取消 | 仅记录日志，不改订单 |
-
-## 5. 数据表
-
- `common_support_ticket.priority` ENUM，默认 `NORMAL`
- `common_support_ticket.status` 新增 `PUBLISHED`；`released_version_no`、`published_at`
- `log_promo_event`：推广码指标事件（`promo_code_id`, `event_type`, `user_id`, `order_id`, `session_id`, `client_ip`, 地点, `created_at`）
-
-## 6. HQ 开发计划
-
-在 admin-web **开发计划 → 版本列表** 创建 `v3.4.13`（状态 `IN_PROGRESS`），审批 ST 后关联 `dev_plan_task`。**版本标记为「已发布」后**，该版本下任务自动 `RELEASED`，关联技术支持工单自动 `PUBLISHED` 并写入 `releasedVersionNo`。
-
-## 7. 验收 ACC
-
- [ ] 推广码详情展示 attributionCount；**四指标事件日志 + ECharts 按日/按时趋势 + 高峰标注**
- [ ] 推广码 SCAN/ATTRIBUTION/REGISTER/ORDER 事件含 time + IP；幂等（重复 touch 不计 SCAN）
- [ ] 核销记录含 userNo/nickname/phone；**详情抽屉展示门店/地址/合伙人/权益券号/关联订单/券分摊/结算单/评价**
- [ ] **权益券详情抽屉加宽（980px），内嵌核销列表无横向滚动条**
- [ ] 技术支持可创建/筛选/编辑优先级；**版本 RELEASED 后关联工单为「已发布」并带版本号**
- [ ] **门店列表「开城合伙人」列展示 companyName / name / phone（与下拉选项一致）**
- [ ] 合伙人/门店登录空字段前端提示；**暂停合伙人发码前即拦截，短信/微信登录均禁止**
- [ ] mini-user：我的页左下角显示 `杜康好客 v3.4.x`；低于 `minClientVersion` 时强制更新，无新包则点「我知道了」退出小程序
- [ ] mini-user：电话脱敏、拨打埋点、提货确认、无分享按钮、首图 preview、**门店列表两段营业时间**、**门店详情门头铺满无留白**、**门店套餐页签切换**
- [ ] mini-user：配送中物流摘要 + 签收照预览 + 电话拨号 + 时间线旧→新全点亮 + 预估送达
- [ ] 小飞侠路由回调 `POST /callbacks/courier/xfx/track`：status=5 或 statusName 已签收 → 订单 **COMPLETED**；重复回调幂等
- [ ] 各端上传 >10MB 图片自动压缩后可上传；仍超限有明确报错
- [ ] **门店 H5（iPhone 微信）**：首次扫码 OAuth 后自动续扫；offline verifying 时提示再点一次扫码
- [ ] `pnpm lint` 无新增错误
+- [ ] 推广码四指标趋势 + 事件日志；重复 touch 不计 SCAN
+- [ ] 核销/权益券详情抽屉字段完整、980px 无横滚
+- [ ] 版本 RELEASED 后工单「已发布」带版本号；门店列表合伙人列非空
+- [ ] mini-user：版本门控、门店/商品/物流/压缩项
+- [ ] 门店 H5 iPhone 微信：OAuth 后续扫可用
+- [ ] 小飞侠回调 status=5 → 订单 COMPLETED
@@ -1,205 +1,57 @@
 # 杜康好客 · V3 编码手册（交付业务版）

-> **版本定位**：V3 实现与验收补充；**产品事实源**见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。  
-> **现状审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)（已完成/冲突/缺口）  
-> **对照文件**：V2 / preV1 手册**不再作为需求依据**，仅作历史参考。  
-> **数据库事实**：当前 Prisma schema 已是 v3.1，优先按 V3.0 PRD 补齐业务闭环。
+> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)  
+> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。

---
+## 1. 交付目标（六条）

-## 1. V3 交付目标
+C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAdmin 运营 · 后端支付/配送/结算/审计 · 主链路冒烟+边界测试。

-V3 必须达到可业务验收状态：
+## 2. 分工

-1. C 端用户能登录、选城、浏览商品、下单、支付、查看订单、获得权益、到店核销。
-2. 门店端能登录、扫码/输码核销、查看核销记录、管理营业状态，并形成待打款记录。
-3. 合伙人端能登录、录入门店、管理门店、查看辖区订单、处理配送/补发、查看账单与经营数据。
-4. WebAdmin 能完成开城、商品、门店审核、订单、权益、核销、配送、退款/补发、结算、资源和账号管理。
-5. 后端能完成真实支付回调、配送状态推进、退款/补发工单、门店 T+1、合伙人 T+30、日志与审计。
-6. 测试能覆盖主链路、关键边界和生产开关，不再只依赖一条 happy path 冒烟。
+| 负责人 | 范围 |
+|--------|------|
+| jacy-dukang | 全部 apps、packages、server 模块、Prisma（2026-07 起代管 B+D） |
+| ~~刘景尧~~ | ~~h5-shop/partner、store/redeem~~（暂停） |

---
+**四端**：C=`mini-user`/h5-user · 门店=h5-shop · 合伙人=h5-partner · 总部=**admin-web**（`/admin/*`，`HQ_WEB`）。

-## 2. V3 端与负责人
+**边界**：apps 只 HTTP+shared-types；跨模块只 inject exported Service；枚举/DTO→shared-types；纯规则→domain。

-| 负责人 | 主责端 | 主责后端/公共范围 | 说明 |
-|---|---|---|---|
-| `jacy-dukang` | **全部四端**（含 `h5-shop`、`h5-partner`） | **全部模块** + `packages/*`、Prisma | Tech lead；**2026-07 起暂代刘景尧 B+D 职责** |
-| `刘景尧` | ~~`apps/h5-shop`、`apps/h5-partner`~~ | ~~`store`、`redeem`~~ | **暂停分工**，恢复前由 jacy 代管 |
+**日志**：见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)

-### 2.1 四端交付形态（工程口径）
+## 3. 核销规则（V3）

-产品 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。
- 后端跨模块只调用 exported Service，禁止为了赶进度直接写他人领域表。
- 涉及 API、枚举、DTO、业务规则变更，必须同步 `packages/shared-types`、`packages/domain` 与本手册。
- Prisma 迁移由 `jacy-dukang` 主导；涉及 `store` / `redeem` 表或核销流程时 `刘景尧` 必须 Review（**恢复分工前由 jacy 全权**）。
-
-### 2.2 日志与审计（新业务）
-
-城市 / 仓库 / 账号 / 子账号 CRUD 须落入对应日志表，规范见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)：
-
- **HQ 写操作** → `common_event(HQ_OPERATION)`，经 `@HqOperation` 装饰器
- **合伙人端子账号** → `log_partner_analytics`（`partner_staff_*`）
- **城市多合伙、仓库表** → schema 待建；action 常量已预留
-
-
-## 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 运营（总部端）
-
-> 交付载体：`apps/admin-web`。本节即总部端验收口径，**不要求改为 H5**。
-
-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 | `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 与本手册。
-
-## 8. V3.0 三波交付（摘要）
-
-详见 v3-PRD §9 与 `@dukang-v3` skill。
-
-| 波次 | 日期 | 门禁 |
+| 入口 | 入参 | 上限 |
 |------|------|------|
-| Wave 1 | 7.10 | 下单+核销+拓店+合伙人子账号 |
-| Wave 2 | 7.15 | 提现+推广码+现场提货+门店子账号+多合伙人 |
-| Wave 3 | 7.22 | 代下单+弱网+多仓+跨城+工单+发票+全量 ACC |
+| 直接核销 | `{ amount }` | ≤ 全部 ACTIVE 权益总余额（FIFO） |
+| 单据核销 | `{ couponId, amount }` | ≤ 该单据可用金额 |
+
+- Redis 码 TTL **3 分钟**；确认时二次校验 + 券 version 乐观锁
+- 成功写：`user_redeem_record` · `common_event(BENEFIT_LEDGER)` · `store_payout(PENDING)`
+- 绑定门店则仅该店可确认；`OPEN` 门店；暂停/关闭不可核销
+- UI 无「单次 ¥500」文案
+
+## 4. 业务闭环（摘要）
+
+| 链路 | 关键节点 |
+|------|----------|
+| C 购酒 | 登录→开城商品→起购(同城2/跨城6)→支付→权益1:1→出码/核销→评价 |
+| 门店 | 登录→扫码确认→记录→store_payout T+1 |
+| 合伙人 | 拓店三步→HQ审核→辖区订单/账单 |
+| HQ | 开城/商品/审核/订单/权益/核销/结算/工单 |
+
+## 5. 验收用例（必过）
+
+**主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30…  
+**后台 8 项**：商品/门店/订单/权益/核销/工单/日志/财务。
+
+## 6. 技术债（摘要）
+
+P0：旧文档¥500 · lint 占位 · smoke 窄覆盖  
+P1：DTO 不全 · 跨模块 prisma · 真实短信/配送  
+P2：mini-hq vs admin-web 重叠
+
+## 7. 版本与波次
+
+规则变更先改 **v3-PRD**。Wave 1/2/3 见 PRD §9。
@@ -1,177 +1,40 @@
-# 杜康好客 · 开发计划功能开发文档 v3.4.11
+# 杜康好客 · 开发计划 v3.4.11

+> PRD §3.10~3.11 · REQ-H-026~028 · 模块 `server/.../dev-plan/`

+## 表

-> 对应 PRD §3.10 · REQ-H-026 ~ REQ-H-028  
-
-> 后端模块：`server/dukang-api/src/modules/dev-plan/`  
-
-> 前端：`apps/admin-web` 开发计划三页面 + 技术支持改造
-
-
-
---
-
-
-
-## 1. 数据模型
-
-
-
-| 表 | 说明 |
-
-|----|------|
-
-| `dev_plan_task` | 任务池；可选 `support_ticket_id` |
-
-| `dev_plan_version` | 版本；状态与时间戳 |
-
-| `dev_plan_version_task` | 版本-任务多对多 |
-
-| `dev_plan_settings` | 单例：审核助手配置（LLM/知识库/提示词） |
-| `dev_plan_task_dispatch` | 派发审计 |
-| `wecom_message_push` | 企微群 Webhook 多实例；推送条件 JSON 数组 |
-
-
-
-枚举与 DTO：`packages/shared-types/src/dev-plan.ts`、`wecom-message-push.ts`
-
-
-
-**任务派发**：不再存于 `dev_plan_settings`；改由 HQ「消息推送」勾选 `dev_plan.task_dispatch`。
-
-
-
---
-
-
-
-## 2. Admin API
+`dev_plan_task` · `dev_plan_version` · `dev_plan_version_task` · `dev_plan_settings`（审核助手） · `dev_plan_task_dispatch` · `wecom_message_push`

+枚举/DTO：`packages/shared-types` `dev-plan.ts` · `wecom-message-push.ts`

+## Admin API（摘要）

 | 路由 | 说明 |
-
 |------|------|
+| `/admin/dev-plan/tasks` | CRUD · dispatch · batch-update（v3.4.12+） |
+| `/admin/dev-plan/versions` | CRUD · 关联任务 · **RELEASED 联动任务/工单（v3.4.13）** |
+| `/admin/dev-plan/settings` | 审核助手 LLM/知识库 |
+| `/admin/wecom-message-pushes` | Webhook 多实例 + eventKey |
+| `/admin/support-tickets/*` | review · batch-review · batch-update-status |

-| `GET/POST /admin/dev-plan/tasks` | 任务列表 / 创建 |
+任务派发：HQ「消息推送」勾选 `dev_plan.task_dispatch`（非 settings 字段）。

-| `GET/PUT/DELETE /admin/dev-plan/tasks/:id` | 任务 CRUD |
+## 技术支持联动

-| `POST /admin/dev-plan/tasks/dispatch` | 评审派发（无需 devBotId） |
+审批 `APPROVE` + `tasks[]`≥1 → 工单 DEVELOPING + 创建 `dev_plan_task`。批量 AI 预审 → confirm。

-| `GET/POST /admin/dev-plan/versions` | 版本列表 / 创建 |
+## 企微机器人（摘要）

-| `GET/PUT/DELETE /admin/dev-plan/versions/:id` | 版本 CRUD |
+四类角色（客服/财务/运营/技术支持）+ 模块化权限；`support_ticket.review` 白名单；审计 `log_wecom_bot`。  
+消息推送 eventKey：`alert.ops` · `support_ticket.created` · `dev_plan.task_dispatch` 等。

-| `PUT /admin/dev-plan/versions/:id/tasks` | 替换关联任务 |
+## ACC 抽样

-| `GET/PUT /admin/dev-plan/settings` | 开发设置（审核助手） |
-
-| `GET/POST/PUT/DELETE /admin/wecom-message-pushes` | 消息推送 CRUD |
-
-| `POST /admin/wecom-message-pushes/:id/test` | 测试消息推送 |
-
-
-
-权限：`dev_plan`（`packages/shared-types/src/hq-permissions.ts`）
-
-
-
---
-
-
-
-## 3. 技术支持联动
-
-
-
-| 路由 | 说明 |
-
-|------|------|
-
-| `POST /admin/support-tickets/:id/review` | 统一审批（SuperAdmin） |
-
-| `POST /admin/support-tickets/batch-review/preview` | 批量 AI 预审 |
-
-| `POST /admin/support-tickets/batch-review/confirm` | 批量确认落库 |
-
-
-
-审批通过：`decision=APPROVE` + `tasks[]`（≥1）→ 工单 `DEVELOPING` + 创建 `dev_plan_task`。
-
-
-
---
-
-
-
-## 4. 企微与开发计划分工
-
-
-
-| 能力 | 入口 | 说明 |
-|------|------|------|
-| **消息推送** | Admin `/wecom/pushes` | Webhook 多实例 + 条件勾选；运营告警 / 工单 / 任务派发 |
-| **智能机器人** | Admin `/wecom/bots` | 四类角色 + 模块化权限；审计 `/logs/wecom-bots` |
-| **任务评审派发** | 任务列表 · 评审 | 匹配 `dev_plan.task_dispatch` 的推送实例（可多条） |
-
-DevPlan Agent（HTTP 回调对话）已移除，避免与「企微机器人」重复。
-
---
-
-## 附录 A · 企微机器人能力矩阵（v3.4.11 重构）
-
-| 模块 | 权限 | 指令示例 |
-|------|------|----------|
-| 订单 | `order.read` | `查订单 DK123` |
-| 配送 | `delivery.read` | `快递 DK123` |
-| 门店 | `store.read` | `查门店 杜康` |
-| 核销 | `redeem.read` | `核销 门店名` |
-| 售后工单 | `ticket.read` / `ticket.create` | `售后工单 TK…` / `工单 订单号 仅退款` |
-| 用户 | `user.read` / `user.read_sms` | `用户号 U…` / `查用户 手机号` |
-| 财务 | `finance.*.read` | `门店账单` / `合伙人账单` / `门店打款` |
-| 技术支持 | `support_ticket.*` | `提单 BUG …` / `通过 ST…` / `驳回 ST… 理由` |
-| 开发计划 | `dev_plan.task.read` / `dev_plan.version.read` | `开发任务` / `版本 v3.4.11` |
-
-**审批**：`support_ticket.review` + 机器人级 `reviewSuperAdminWecomUserIds` 白名单；通过自动建 1 条 dev_plan_task。
-
-**废弃**：`api.read.all`、`db.read`、`TEAM_ASSISTANT`（迁移为 `OPERATIONS`）。
-
-
-
---
-
-
-
-## 5. 验收（ACC）
-
-
-
- [ ] 侧边栏「开发计划」三子页；无 `dev_plan` 权限不可见
- [ ] 侧边栏「企微机器人」：智能机器人 / 消息推送 / 日志
- [ ] 消息推送 CRUD + 测试；条件勾选生效
- [ ] 任务/版本 CRUD；版本多选关联任务
- [ ] 版本状态流转写时间戳；用时正确
- [ ] 新建技术支持工单 → `support_ticket.created` 推送；`alert.ops` 可并行
- [ ] 技术支持：单一审批、通过创建任务、批量 AI 审核
- [ ] 任务勾选评审派发（走消息推送 @ userid）
- [ ] 系统设置无企微告警开关；运行时不再读 `WECOM_ALERT_WEBHOOK_URL`
- [ ] mutation 有 HQ 操作审计
-
-
-
---
-
-
-
-## 6. 发版
-
-
-
-1. `pnpm db:generate` + `prisma db push`（`wecom_message_push` 表；删除 `dev_plan_settings.task_dispatch_*`）
-2. `pnpm prisma:migrate-wecom-push`（发版前，在 drop `task_dispatch_*` 之前）或 API 启动 `ensureDefaults`
-3. staging 验证消息推送 + 任务派发 + 工单通知
-4. tag **`v3.4.11`**
+- [ ] 开发计划三页 + 企微三菜单
+- [ ] 工单审批建任务；任务评审派发 Webhook
+- [ ] v3.4.13：版本 RELEASED → 任务 RELEASED + 工单 PUBLISHED

+## 发版

+`prisma db push`（`wecom_message_push`）· 迁移旧 env Webhook · tag `v3.4.11`
@@ -1,372 +1,38 @@
-# 杜康好客 · 门店套餐功能开发文档
+# 杜康好客 · 门店套餐 v3.4.10

-> **版本**：3.4.10  
-> **日期**：2026-08-03  
-> **状态**：需求已定 / 待实现  
-> **关联**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) §3.9 · REQ-P-027 / REQ-S-021 / REQ-H-025 / REQ-U-027
+> PRD §3.9 · REQ-P/S/H/U-027 · **已实现**（含 v3.4.12 `imageUrl`）

-## 变更记录
+## 要点

-| 版本 | 日期 | 说明 |
-|------|------|------|
-| **3.4.10** | 2026-08-03 | 新增门店套餐需求与开发设计 |
+- 与酒水 SKU 独立；每店 ≤10 条；字段：名称/价格/菜品/使用时间/说明
+- C 端仅展示**已审核生效**套餐；异议类型 `PACKAGE_DISPUTE`
+- 合伙/门店：编辑 → **提交审核**；HQ：门店详情 Tab **直存生效**
+- 审核通过：事务替换 `store_package`；驳回保留上一版；同店仅 1 条 `PENDING`

---
+## 表

-## 目录
-
-1. [背景与目标](#1-背景与目标)
-2. [数据模型](#2-数据模型)
-3. [API 草案](#3-api-草案)
-4. [四端 UI](#4-四端-ui)
-5. [审核与展示状态机](#5-审核与展示状态机)
-6. [客服「套餐异议」](#6-客服套餐异议)
-7. [验收清单（ACC）](#7-验收清单acc)
-8. [实现分期建议](#8-实现分期建议)
-
-### 流程概览
-
-```mermaid
-flowchart LR
-  partnerEdit[PartnerOrShopEdit]
-  draft[PackageChangeRequest]
-  hqReview[HqApproveOrReject]
-  live[LiveStorePackages]
-  mini[MiniStoreDetail]
-  dispute[PackageDisputeTicket]
-  partnerEdit --> draft
-  draft --> hqReview
-  hqReview -->|APPROVED| live
-  live --> mini
-  mini --> dispute
-  hqDirect[HqDirectSave] --> live
-```
-
---
-
-## 1. 背景与目标
-
-门店可向 C 端用户展示餐饮套餐信息，帮助用户在核销前了解可核销内容。套餐与酒水 SKU 无关，需独立数据模型与审核流。
-
-### 1.1 需求原文（10 条）
-
-1. **合伙人新建门店**：在现有拓店流程（基本信息 / 照片 / 结算资质）后增加「套餐」页；可不填、可跳过。
-2. **套餐字段**：套餐名称、价格（元）、菜品、使用时间、其他说明。
-3. **C 端门店详情**：在「门店详情」区块附近，以纵向列表展示套餐；每条为「标题 + 内容」形式。
-4. **数量约束**：可不填；可多条；**同一门店最多 10 条**。
-5. **门店端**：新增套餐列表页，可编辑并**提交审核**。
-6. **合伙人端**：选择门店 → 套餐列表 → 编辑 → **提交审核**。
-7. **总部端**：门店详情新增「套餐」Tab，**直接保存生效、无需审核**。
-8. **审核流**：合伙/门店提交 → 总部通过/驳回；**通过后自动替换生效套餐**。
-9. **C 端展示**：仅展示**已审核通过（生效中）**的套餐。
-10. **客服异议**：用户对核销中套餐有异议 → 客服申诉类型新增 **套餐异议**。
-
-### 1.2 现状对齐
-
-| 现状 | 影响 |
-|------|------|
-| 无门店套餐实体；`Store.tags` Json 未承载套餐 | 需新建表，不复用酒水 SKU |
-| 合伙人拓店三步：基本信息 / 照片 / 结算资质 | 新增「套餐」页（第 4 步或独立页） |
-| 门店端仅改营业状态，**无资料编辑 API** | 需新增门店端套餐 CRUD + 提审 API |
-| 门店审核仅 `NEW`/`RESUBMIT` 整店审，**无「套餐变更」独立审核** | 需独立「套餐变更审核」模型 |
-| 售后工单四类型无「套餐异议」 | 扩展工单/客服类型 |
-| C 端详情已有 intro / 权益规则 / 环境图 | 在「门店详情」区块附近增加套餐纵向列表 |
-
-### 1.3 明确不做（本文档阶段）
-
- 不改 Prisma / 不写 API / 不改四端业务代码（本文档仅设计）
- 不把套餐挂到商品目录 `CommonProductItem`
- 不合并进整店 `Store.auditStatus`（套餐变更独立提审）
-
---
-
-## 2. 数据模型
-
-### 2.1 生效数据 `StorePackage`（表名 `store_package`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | String (cuid) | 主键 |
-| `storeId` | String | 门店 ID，FK → `Store` |
-| `name` | String | 套餐名称，如「套餐A」 |
-| `price` | Decimal | 价格（元） |
-| `dishes` | Text | 菜品文案；前端按顿号/换行展示；或 Json 字符串数组 |
-| `usableTime` | String? | 使用时间，如「节假日除外」 |
-| `otherNotes` | String? | 其他说明，如「不可叠加」 |
-| `sortOrder` | Int | 展示序 0~9 |
-| `createdAt` | DateTime | |
-| `updatedAt` | DateTime | |
-
-**约束**
-
- 同一 `storeId` 下生效套餐 **≤ 10** 条
- 删除/替换由审核通过或总部直存事务完成
-
-### 2.2 变更提审 `StorePackageChangeRequest`（表名 `store_package_change_request`）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | String (cuid) | 主键 |
-| `storeId` | String | 门店 ID |
-| `status` | Enum | `PENDING` / `APPROVED` / `REJECTED` |
-| `packagesJson` | Json | 提审快照（完整套餐数组，最多 10 条） |
-| `submitterType` | Enum | `PARTNER` / `SHOP` |
-| `submitterId` | String | 提交人 ID |
-| `rejectReason` | String? | 驳回原因 |
-| `reviewedAt` | DateTime? | |
-| `reviewerId` | String? | 总部审核人 |
-| `createdAt` | DateTime | |
-
-**规则**
-
- 同门店同时仅允许 **一条 `PENDING`**
- 审核 **通过**：事务内删除该店全部 `StorePackage`，按 `packagesJson` 重建
- 审核 **驳回**：不改动生效表；提审方可修改后再提
-
-### 2.3 提审快照 JSON 结构（`packagesJson` 数组元素）
-
-```json
-{
-  "name": "套餐A",
-  "price": "198.00",
-  "dishes": "红烧肉、红烧鱼、油焖茄子",
-  "usableTime": "节假日除外",
-  "otherNotes": "不可叠加",
-  "sortOrder": 0
-}
-```
-
-### 2.4 总部直存
-
- 写 `StorePackage`，**不写** `StorePackageChangeRequest`
- 可选记 `CommonEvent`（如 `STORE_PACKAGE_UPDATE`）留痕
-
-### 2.5 枚举（建议写入 `packages/shared-types`）
-
-```typescript
-enum StorePackageChangeStatus {
-  PENDING = 'PENDING',
-  APPROVED = 'APPROVED',
-  REJECTED = 'REJECTED',
-}
-
-enum StorePackageSubmitterType {
-  PARTNER = 'PARTNER',
-  SHOP = 'SHOP',
-}
-
-// 扩展工单类型
-enum TicketType {
-  // ...existing
-  PACKAGE_DISPUTE = 'PACKAGE_DISPUTE',
-}
-```
-
---
-
-## 3. API 草案
-
-> 路径前缀均为 `/api/v1`；响应 `{ code, message, data }`。
-
-### 3.1 合伙人端
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| GET | `/partner/stores/:storeId/packages` | 读草稿/生效套餐（见实现约定） | 管辖门店 |
-| PUT | `/partner/stores/:storeId/packages` | 提交套餐变更审核（body=套餐数组） | 管辖门店 |
-| GET | `/partner/stores/:storeId/package-change-requests` | 历史提审记录 | 管辖门店 |
-
-**拓店草稿**：新建流程中套餐可先写入 `storeDraft.packages`，门店创建成功后随首次提审或总部审核入库。
-
-### 3.2 门店端（新增能力）
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| GET | `/shop/store/packages` | 当前门店套餐（草稿+生效） | 门店主账号/店员 |
-| PUT | `/shop/store/packages` | 提交套餐变更审核 | 门店主账号 |
-
-> 现状：门店端无资料编辑 API，本模块为 **新增** Shop Store API。
-
-### 3.3 总部端
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| GET | `/admin/stores/:storeId/packages` | 读生效套餐 | HQ |
-| PUT | `/admin/stores/:storeId/packages` | **直存**生效（无需审核） | HQ |
-| GET | `/admin/store-package-audits` | 待审/历史列表 | HQ |
-| PUT | `/admin/store-package-audits/:requestId/audit` | 通过/驳回 | HQ |
-
-**审核 body 示例**
-
-```json
-{
-  "action": "APPROVE"
-}
-```
-
-```json
-{
-  "action": "REJECT",
-  "rejectReason": "价格描述不清晰"
-}
-```
-
-### 3.4 C 端（公开）
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/stores/:storeId` | 门店详情 **嵌入** `packages[]`（仅生效） |
-| GET | `/stores/:storeId/packages` | 可选独立接口，仅返回生效套餐 |
-
-**响应字段（单条）**
-
-```json
-{
-  "name": "套餐A",
-  "price": "198.00",
-  "dishes": "红烧肉、红烧鱼、油焖茄子",
-  "usableTime": "节假日除外",
-  "otherNotes": "不可叠加",
-  "sortOrder": 0
-}
-```
-
-### 3.5 客服异议
-
-扩展创建售后/客服工单：
-
-| 字段 | 说明 |
-|------|------|
-| `ticketType` | `PACKAGE_DISPUTE` |
-| `storeId` | 必填 |
-| `redeemRecordId` | 可选，关联核销单 |
-
---
-
-## 4. 四端 UI
-
-### 4.1 合伙人端（H5）
-
-| 页面 | 路径建议 | 说明 |
-|------|----------|------|
-| 拓店·套餐 | `/stores/create/packages` | 第 4 步；可跳过；数据进 `storeDraft` |
-| 门店详情·套餐入口 | 门店详情页 | 跳转套餐列表 |
-| 套餐列表 | `/stores/:id/packages` | 展示当前生效 + 待审状态 |
-| 套餐编辑 | `/stores/:id/packages/edit` | 表单：名称/价格/菜品/时间/说明；最多 10 条 |
-| 提交审核 | 编辑页底部 | PUT 提审；同店有 PENDING 时禁用 |
-
-参考：`apps/h5-partner/src/pages/StoreCreatePage.tsx`
-
-### 4.2 门店端（H5）
-
-| 页面 | 路径建议 | 说明 |
-|------|----------|------|
-| 套餐列表 | `/packages` | 新入口（门店信息 Tab 或独立菜单） |
-| 套餐编辑 | `/packages/edit` | 同合伙人表单 |
-| 提交审核 | 编辑页底部 | PUT `/shop/store/packages` |
-
-### 4.3 总部端（admin-web）
-
-| 页面 | 说明 |
-|------|------|
-| 门店详情 Drawer · Tab「套餐」 | 在 `StoresPage.tsx` Drawer 增加 Tab；表单直存 |
-| 套餐变更审核列表 | 独立页或门店内待审提示；通过/驳回 |
-
-参考：`apps/admin-web/src/pages/StoresPage.tsx`
-
-### 4.4 用户端（mini-user）
-
-| 位置 | 说明 |
-|------|------|
-| 门店详情 · 「门店详情」区块上方或下方 | 纵向卡片列表 |
-| 单条样式 | 标题 = 套餐名；内容 = 价格 / 菜品 / 使用时间 / 其他说明 |
-| 空态 | 无生效套餐时不展示该区块 |
-
-参考：`apps/mini-user/src/pages/store-detail/index.tsx`
-
-### 4.5 C 端展示示例
-
-```
-套餐A
-198 元 · 红烧肉、红烧鱼、油焖茄子
-使用时间：节假日除外
-说明：不可叠加
-```
-
---
-
-## 5. 审核与展示状态机
-
-```mermaid
-stateDiagram-v2
-  [*] --> NoLive: 从未通过
-  NoLive --> Live: 首次审核通过 / 总部直存
-  Live --> Pending: 合伙/门店提审
-  Pending --> Live: 审核通过（覆盖）
-  Pending --> Live: 审核驳回（保留旧 Live）
-  Live --> Live: 总部直存（覆盖）
-```
-
-| 状态 | C 端展示 | 编辑方可见 |
-|------|----------|------------|
-| 无生效套餐 | 不展示套餐区块 | 可编辑、可提审 |
-| 有生效 + 无待审 | 展示生效版 | 可编辑、可提审 |
-| 有生效 + 待审中 | **仍展示上一版生效** | 显示「审核中」；不可重复提审 |
-| 审核通过 | 展示新版 | 可再次编辑提审 |
-| 审核驳回 | 仍展示旧版 | 可修改后再提；展示驳回原因 |
-
---
-
-## 6. 客服「套餐异议」
-
-| 项 | 说明 |
+| 表 | 用途 |
 |----|------|
-| 类型文案 | 套餐异议 |
-| 枚举 | `PACKAGE_DISPUTE` |
-| 入口 | C 端核销相关页 / 门店详情 / 客服页可选该类型 |
-| 关联 | `storeId` 必填；可选 `redeemRecordId` |
-| 总部 | 客服工单列表可按类型筛选处理 |
+| `store_package` | 生效套餐（含 `image_url`） |
+| `store_package_change_request` | 提审快照 `packagesJson` |

-与现有四类型工单并列，不替换原有类型。
+## API（前缀 `/api/v1`）

---
+| 端 | 路径 |
+|----|------|
+| partner | `GET/PUT /partner/stores/:id/packages` · 变更历史 |
+| shop | `GET/PUT /shop/store/packages` |
+| admin | `GET/PUT /admin/stores/:id/packages` · `/admin/store-package-audits` 审 |

-## 7. 验收清单（ACC）
+## 流程

-| ID | 对应需求 | 验收项 |
-|----|----------|--------|
-| ACC-PKG-01 | #1 | 合伙人拓店流程有「套餐」页，可跳过；跳过后门店可无套餐 |
-| ACC-PKG-02 | #2 | 单条套餐含名称、价格、菜品、使用时间、其他说明五字段 |
-| ACC-PKG-03 | #3 | C 端门店详情以纵向标题+内容展示套餐 |
-| ACC-PKG-04 | #4 | 同一门店生效套餐 ≤10；第 11 条保存/提审被拒绝 |
-| ACC-PKG-05 | #5 | 门店端可列表、编辑、提交审核 |
-| ACC-PKG-06 | #6 | 合伙人可选门店、编辑套餐、提交审核 |
-| ACC-PKG-07 | #7 | 总部门店详情「套餐」Tab 直存后 C 端立即可见（无需审核） |
-| ACC-PKG-08 | #8 | 合伙/门店提审 → 总部通过后生效表被完整替换；驳回后生效表不变 |
-| ACC-PKG-09 | #9 | C 端 never 展示未通过/待审套餐；提审中仍展示旧版 |
-| ACC-PKG-10 | #10 | 用户可创建「套餐异议」工单；总部可按类型筛选 |
-| ACC-PKG-11 | — | 同门店仅一条 PENDING；重复提审返回业务错误 |
-| ACC-PKG-12 | — | 空套餐数组提审合法；通过后 C 端不展示套餐区块 |
-| ACC-PKG-13 | — | 总部直存记事件或审计日志（若启用 CommonEvent） |
+```
+partner/shop 编辑 → PENDING → HQ 通过/驳回 → 生效 → mini-user 展示
+HQ 直存 ──────────────────────────────→ 生效
+```

---
+## ACC

-## 8. 实现分期建议
-
-| 阶段 | 范围 | 交付 |
-|------|------|------|
-| **M1** | 表结构 + 总部直存 + C 端展示 | Prisma 迁移、`StorePackage` CRUD（admin）、mini-user 展示 |
-| **M2** | 合伙人新建/编辑提审 + 总部审核 | `StorePackageChangeRequest`、partner 页面、admin 审核 |
-| **M3** | 门店端提审 | Shop API + h5-shop 页面 |
-| **M4** | 套餐异议工单类型 | `PACKAGE_DISPUTE` 枚举、C 端入口、admin 筛选 |
-
---
-
-## 附录：REQ 映射
-
-| REQ | 端 | 内容 |
-|-----|----|------|
-| REQ-P-027 | 合伙人 | 拓店套餐页 + 门店套餐列表/编辑/提审 |
-| REQ-S-021 | 门店 | 套餐列表/编辑/提审 |
-| REQ-H-025 | 总部 | 门店详情套餐 Tab 直存；套餐变更审核通过/驳回 |
-| REQ-U-027 | 用户 | 门店详情展示生效套餐；套餐异议申诉入口 |
+- [ ] 四端展示 imageUrl；HQ 可删至 0 条
+- [ ] 提审中 C 端仍见上一版；通过后替换
+- [ ] 套餐异议工单可创建