373 lines
12 KiB
Markdown
373 lines
12 KiB
Markdown
# 杜康好客 · 门店套餐功能开发文档
|
||
|
||
> **版本**：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
|
||
|
||
## 变更记录
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| **3.4.10** | 2026-08-03 | 新增门店套餐需求与开发设计 |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
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` |
|
||
| 总部 | 客服工单列表可按类型筛选处理 |
|
||
|
||
与现有四类型工单并列，不替换原有类型。
|
||
|
||
---
|
||
|
||
## 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） |
|
||
|
||
---
|
||
|
||
## 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 | 用户 | 门店详情展示生效套餐；套餐异议申诉入口 |
|