que01/persionalBrand
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define initial product requirements

Browse Source
This commit is contained in:
que01
2026-09-18 14:15:49 +08:00
commit e28140a0b3
9 changed files with 1346 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
docs/01-prototype-spec.md Normal file
View File

@@ -0,0 +1,121 @@
# 试点版原型与交互规格
## 1. 文档目的
本文档将 [PRD](./PRD.md) 转换为页面、状态和交互要求，作为线框图、UI 设计和前端开发的依据。第一版优先保证业务闭环，不追求复杂视觉和全量配置能力。
订单相关页面应同时遵循 [首轮需求访谈决策](./07-requirements-interview-decisions.md)，包括微信无感身份、普通套餐/私厨双表单、“我的订单”、配送条件字段和客户取消规则。
## 2. 设计原则
- 客户无需注册即可浏览和提交预约。
- 每个页面只保留一个主要行动按钮。
- 内容为空时显示合理空状态，不显示破损模块。
- 后台编辑内容时，字段名称使用经营者能理解的业务语言。
- 预约提交必须比直接聊天更清晰，但不能让表单比聊天更麻烦。
- 小程序负责展示与承接，后台负责维护与处理。
## 3. 小程序页面规格
### 3.1 首页 `/pages/home`
**模块顺序**
1. 品牌头像、品牌名称、定位短句
2. 主要行动按钮：预约/咨询
3. 服务项目预览（最多 3 项）
4. 代表作品（最多 6 项）
5. 品牌介绍摘要
6. 客户反馈（最多 3 条）
7. 联系方式和地址
**状态**
- 加载中：显示骨架或加载提示。
- 加载失败：显示重试按钮。
- 模块无内容：隐藏该模块；首页仍保持可用。
### 3.2 品牌介绍 `/pages/brand`
展示完整简介、经历、擅长领域、服务理念和联系方式。未配置的字段不展示标题。
### 3.3 服务列表 `/pages/services` 与详情 `/pages/service-detail`
列表仅展示启用的服务，按 `sort_order` 升序排列。详情页展示名称、图片、描述、价格文本、时长和预约方式。
当 `booking_enabled=false` 时，按钮文案为“咨询”，否则为“预约”。第一版的价格只作为展示文本，不出现购买、支付或收款按钮。
### 3.4 作品集 `/pages/portfolio` 与详情 `/pages/portfolio-detail`
作品按排序展示。详情页支持图片浏览、标题和描述。图片点击可预览原图或大图。
### 3.5 预约表单 `/pages/booking`
字段顺序：服务项目、称呼、手机号、微信号、期望日期、备注、隐私/联系同意。
**校验**
- 称呼必填，2-30 个字符。
- 手机号和微信号至少填写一项。
- 手机号按中国大陆常用格式校验；微信号允许字母、数字、下划线和连字符。
- 期望日期不能早于当天，可不填。
- 备注最多 500 个字符。
- 未勾选同意项不能提交。
提交成功后展示预约编号、提交时间和“返回首页”按钮。第一版不承诺具体时段，也不显示自动确认信息。
### 3.6 反馈 `/pages/feedback` 与 `/pages/feedback-submit`
列表仅展示 `approved` 状态反馈。提交页要求称呼和内容，内容 10-500 字，可填写联系方式。提交后显示“等待审核”。
### 3.7 管理入口
小程序可根据后端返回的管理员身份显示入口。入口只用于便利跳转；所有后台操作仍必须在 Web 后台重新登录并通过 API 鉴权。
## 4. Web 后台页面规格
### 4.1 登录 `/login`
字段：账号、密码。登录失败只提示“账号或密码错误”，不暴露具体原因。登录成功跳转概览页。
### 4.2 概览 `/dashboard`
展示待处理预约数、待审核反馈数、本周预约数和最近预约列表。数字点击后跳转到对应列表。
### 4.3 品牌资料 `/brand`
表单分组：基础信息、品牌介绍、联系方式、首页显示控制。图片字段提供上传、替换、删除和预览。保存成功后保留当前页面，不强制跳转。
### 4.4 服务 `/services`
列表字段：名称、价格文本、预约方式、启用状态、排序、更新时间、操作。编辑表单支持保存、停用和删除。删除已有预约关联的服务时，界面应建议停用。
### 4.5 作品 `/portfolio`
支持批量图片上传，但第一版可以先实现单次多图选择。作品编辑支持拖拽或数字排序；上传失败必须显示具体原因并允许重试。
### 4.6 预约 `/bookings`
默认按提交时间倒序。筛选条件：状态、期望日期、服务。详情页显示客户联系方式和备注；联系方式必须有复制按钮。状态变更需要保存并记录操作时间。
### 4.7 反馈 `/feedback`
默认进入待审核列表。审核通过、隐藏和删除均需明确确认；通过后立即可以在小程序反馈列表看到。
## 5. 通用状态与错误
- 空列表：说明没有数据，并提供创建入口（公开页面不提供创建入口）。
- 网络错误：提供重试按钮，不清空已输入内容。
- 权限失效：清除本地登录态并跳转登录页。
- 删除操作：使用二次确认；预约和反馈默认软删除或隐藏。
- 图片错误：显示占位图和重新上传入口。
## 6. 原型交付物
开发前必须完成：
- 小程序 10 个页面的低保真线框。
- 后台 8 个页面的低保真线框。
- 预约和反馈两条流程图。
- 字段表、文案表、空状态和错误状态清单。
- 一份朋友确认过的真实内容样例。

85
docs/02-architecture-and-decisions.md Normal file
View File

@@ -0,0 +1,85 @@
# 技术架构与决策记录
## 1. 架构目标
第一版要以较低复杂度交付单品牌试点，同时保留未来服务多个品牌的结构空间。架构必须让小程序、后台和 API 独立部署，且共享类型和校验规则。
## 2. 技术选型
| 层 | 选型 | 目的 |
|---|---|---|
| Monorepo | pnpm workspace + Turborepo | 统一脚本、缓存构建、共享包 |
| 小程序 | 原生微信小程序 + TypeScript | 直接使用微信能力，减少跨端框架层 |
| 管理后台 | Next.js + TypeScript | 表单、列表、图片管理和路由生态成熟 |
| API | NestJS + TypeScript | 模块化、依赖注入、权限和校验边界清晰 |
| 数据库 | PostgreSQL | 适合预约、服务、反馈之间的关系 |
| ORM | Prisma | 类型安全、迁移和 schema 管理清晰 |
| 文件存储 | S3 兼容对象存储 | 图片不进入数据库，便于扩容和 CDN |
| 校验 | Zod 或 class-validator，统一一种 | API 与前端共享约束 |
| 部署 | Docker Compose 起步，后续迁移托管服务 | 本地与生产环境差异小 |
## 3. 仓库结构
```text
apps/
miniapp/ # 微信小程序
admin/ # Next.js 后台
api/ # NestJS API
packages/
types/ # DTO、状态、枚举
api-client/ # 类型化请求客户端
validation/ # 共享表单规则
config/ # TS、Lint、环境配置
prisma/
schema.prisma
docs/
```
## 4. 环境与配置
至少区分 `development`、`test`、`production`。敏感值只通过环境变量注入，不提交 `.env`。
必要配置：数据库 URL、会话密钥、对象存储 endpoint/bucket/key、API 公网地址、小程序 AppID（仅在需要时使用）。提交 `.env.example`，列出变量名称和用途，不填写真实值。
## 5. ADR（Architecture Decision Record）
### ADR-001：第一版采用单品牌数据模型
- **状态**：已接受
- **决定**：业务表暂不实现商户注册和租户管理，但品牌内容使用独立 `brand_profiles` 表。
- **原因**：当前只有一个真实品牌；保留品牌边界即可避免内容写死，同时不引入 SaaS 计费、租户隔离和复杂权限。
- **影响**：未来多品牌时为主要业务表增加 `brand_id`，或将品牌模型升级为租户模型。
### ADR-002：小程序使用原生开发
- **状态**：已接受
- **原因**：当前只有微信端，页面数量有限，原生能力和审核适配成本最低。
- **影响**：暂不复用 H5 UI；未来跨端需求出现时再评估 Taro。
### ADR-003：后台与小程序分离
- **状态**：已接受
- **原因**：图片上传、长文本编辑、预约处理更适合桌面 Web；小程序专注展示和承接。
- **影响**：需要独立的后台登录态和 API 鉴权。
### ADR-004：价格与支付解耦
- **状态**：已接受
- **决定**：第一版只存 `price_text`，预留 `price_amount`；不创建支付入口和支付状态。
- **原因**：当前没有支付需求，支付涉及订单、退款、对账和微信商户配置。
- **影响**：未来使用独立 `orders/payments/refunds` 模型，不改变预约状态机。
### ADR-005：发布流程人工执行
- **状态**：已接受
- **原因**：第一版只有一个小程序，自动上传、审核和发布的收益不足以抵消配置复杂度。
- **影响**：开发者负责开发工具上传和审核发布；后台不做微信发布控制台。
## 6. 关键工程约束
- API 响应使用统一结构：成功数据、错误码、用户可读消息。
- DTO 和状态枚举放入共享包，避免前后端拼写不一致。
- 公开 API 与 `/admin` API 分离。
- 管理 API 不信任前端传入的管理员身份。
- 业务删除优先采用隐藏/停用；预约、反馈和审计记录保留。
- 任何新增跨模块依赖先记录原因，避免 `api-client` 依赖页面组件。

179
docs/03-data-and-api-design.md Normal file
View File

@@ -0,0 +1,179 @@
# 数据库与 API 设计
## 1. 关系概览
订单模型和接口的最新增量见 [首轮需求访谈决策](./07-requirements-interview-decisions.md)。实现时必须包含客户微信身份、套餐价格快照、标签、未读状态和客户订单查询；与本文早期枚举冲突时，以该文档为准。
```text
BrandProfile 1
├── Services 1..n
└── PortfolioItems 1..n
Service 1 ── n Booking
Booking 1 ── 0..n Feedback
AdminUser 1 ── n AuditLog
```
第一版数据库只有一个品牌记录，但所有内容表仍通过 `brand_id` 关联，便于后续扩展。
## 2. 表与约束
### brand_profiles
- `id` UUID 主键
- `name` 必填
- `is_published` 默认 true
- `created_at`、`updated_at` 必填
### services
- `id` UUID 主键
- `brand_id` 外键
- `name` 必填
- `price_text` 可空
- `price_amount` 可空，单位为分，第一版不用于支付
- `booking_enabled` 默认 true
- `is_enabled` 默认 true
- `sort_order` 默认 0
- 对 `(brand_id, sort_order)` 建索引
### portfolio_items
- `id` UUID 主键
- `brand_id` 外键
- `image_urls` 可使用 JSON 数组，或拆分为 media_assets 表
- `is_visible` 默认 true
- `sort_order` 默认 0
### bookings
- `id` UUID 主键
- `booking_no` 唯一
- `brand_id` 外键
- `service_id` 可空，防止服务删除后历史预约无法读取
- `status` 枚举：`pending/contacted/completed/cancelled`
- `extra_data` JSON，可存储受控的行业扩展字段
- 对 `(brand_id, status, created_at)` 建索引
- 不存支付状态
`extra_data` 不是任意键值存储。字段定义必须由品牌行业配置决定，API 需要校验键名、类型和必填规则；通用字段仍保持结构化。
### feedbacks
- `id` UUID 主键
- `brand_id` 外键
- `booking_id` 可空
- `status` 枚举：`pending/approved/hidden`
- 对 `(brand_id, status, created_at)` 建索引
### admin_users
- `id` UUID 主键
- `username` 唯一
- `password_hash` 必填
- `role` 枚举：`admin/operator`
- `is_enabled` 默认 true
### audit_logs
- `id` UUID 主键
- `admin_user_id` 外键
- `action`、`resource_type`、`resource_id` 必填
- `metadata` JSON，可记录变更摘要，不记录密码和完整联系方式
## 3. API 约定
### 响应格式
```json
{
"data": {},
"error": null,
"requestId": "..."
}
```
失败时：
```json
{
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "请填写有效的联系方式",
"fields": {"phone": "格式不正确"}
},
"requestId": "..."
}
```
### 公开接口
```text
GET /api/public/brand
GET /api/public/services
GET /api/public/services/:id
GET /api/public/portfolio
GET /api/public/portfolio/:id
GET /api/public/feedbacks
POST /api/public/bookings
POST /api/public/feedbacks
```
公开接口只能返回启用、可见和已审核数据。
### 管理接口
```text
POST /api/auth/login
POST /api/auth/logout
GET /api/auth/me
GET /api/admin/brand
PUT /api/admin/brand
GET /api/admin/services
POST /api/admin/services
PUT /api/admin/services/:id
DELETE /api/admin/services/:id
GET /api/admin/portfolio
POST /api/admin/portfolio
PUT /api/admin/portfolio/:id
DELETE /api/admin/portfolio/:id
GET /api/admin/bookings
GET /api/admin/bookings/:id
PATCH /api/admin/bookings/:id/status
GET /api/admin/feedbacks
PATCH /api/admin/feedbacks/:id/status
POST /api/admin/uploads/presign
```
## 4. 预约接口规则
- 服务不存在或已停用时拒绝提交。
- 期望日期早于当天时拒绝提交。
- 联系方式至少一项非空。
- 服务端再次执行所有校验，不能只依赖小程序校验。
- 使用请求幂等键或短时间重复检测避免重复预约。
- 创建成功后返回 `booking_no`，不返回管理员数据。
## 5. 文件上传流程
1. 后台请求上传凭证。
2. API 校验管理员权限和文件元数据。
3. 前端直接上传对象存储。
4. 上传完成后提交文件 URL 和元数据。
5. 内容实体引用该资源。
不得让浏览器上传任意路径或任意 MIME 文件。图片最大尺寸和大小由环境变量配置。
## 6. 远期支付边界
未来新增：
```text
orders
payments
refunds
```
`Booking` 表示客户意向或服务预约；`Order` 表示应收业务；`Payment` 表示微信支付交易；三者必须独立建模。支付成功不能直接等价于预约完成，预约仍由业务流程决定。

106
docs/04-implementation-plan.md Normal file
View File

@@ -0,0 +1,106 @@
# 实施计划与交付管理
## 1. 交付策略
以真实朋友项目为第一个可用版本，采用短迭代，每个迭代都产出可运行结果。所有新增想法先进入需求池，不直接插入当前迭代。
## 2. 里程碑
### M0：确认内容与原型
**产出**：真实品牌资料、页面线框、字段清单、预约流程图、朋友确认记录。
**完成条件**：朋友可以指出页面上每个字段的真实内容和客户要完成的动作。
### M1：项目骨架与本地环境
**产出**：Monorepo、三应用、共享包、环境变量模板、Docker 数据库、统一启动命令。
**完成条件**：新环境按 README 可以启动 API、后台和数据库。
### M2：内容管理闭环
**产出**：管理员登录、品牌资料、服务、作品、图片上传、小程序公开展示。
**完成条件**：后台保存内容后，小程序可以正确展示；停用内容不会出现在公开页面。
### M3：预约与反馈闭环
**产出**：预约表单、预约管理、反馈提交、审核与展示。
**完成条件**：从客户提交到管理员处理的完整流程可演练，权限和重复提交保护有效。
### M4：真实试用与发布
**产出**：真实内容、错误修复、使用说明、发布版本。
**完成条件**：朋友独立完成至少三次内容更新，演练三次预约和两次反馈审核。
## 3. 建议任务顺序
1. 初始化仓库和开发工具链。
2. 创建 Prisma schema 和数据库迁移。
3. 建立 API 模块和统一错误格式。
4. 建立后台登录与权限中间件。
5. 完成品牌、服务和作品管理。
6. 完成小程序首页、详情和内容读取。
7. 完成图片上传和资源管理。
8. 完成预约写入和后台处理。
9. 完成反馈审核和公开展示。
10. 执行验收清单并发布试点版。
## 4. 测试要求
### 必须自动化验证
- API DTO 校验。
- 未授权访问管理接口。
- 服务停用后不能预约。
- 重复提交不能创建重复预约。
- 反馈未审核不能公开。
- 预约状态只能使用定义的枚举。
### 必须人工验收
- 手机端首页在真实图片下不溢出。
- 朋友能独立完成品牌、服务、作品编辑。
- 图片上传失败时可以恢复。
- 联系方式在公开页面和后台的展示边界正确。
- 小程序首次打开、返回、刷新和网络失败状态可用。
## 5. 发布前检查
- 生产环境没有默认管理员密码。
- `.env` 和密钥未提交仓库。
- 数据库已执行迁移并完成初始化。
- 对象存储读写权限正确。
- 公开接口不会返回管理备注和敏感字段。
- 管理接口有登录和角色校验。
- 预约、反馈、内容删除行为符合软删除/隐藏规则。
- 朋友确认品牌文案、联系方式和图片版权。
- 有一份回滚和数据库备份方案。
## 6. 需求变更规则
新增需求必须记录：
- 解决的用户问题
- 是否影响当前里程碑
- 是否需要新增数据表或状态
- 是否影响后续支付兼容性
- 是否由朋友真实使用验证过
以下内容默认进入后续版本：支付、自动通知、排班、多员工、多门店、优惠券、会员、自动发布、多商户注册。
## 7. 试点后的评估
上线两周后评估：
- 朋友是否能自行维护内容。
- 客户是否完成浏览到联系/预约。
- 预约是否比原有聊天记录更可追踪。
- 哪些功能被重复使用。
- 哪些功能造成理解成本。
- 是否出现第二个真实品牌项目。
只有重复需求出现后，才抽象多品牌、租户、计费和自动化发布能力。

144
docs/05-pilot-case-food-stall.md Normal file
View File

@@ -0,0 +1,144 @@
# 首个试点画像：路边餐饮摊主与私厨服务
## 1. 文档状态
- **用途**：为原型、种子数据和流程演示提供一套可运行的虚拟内容。
- **状态**：假设数据，必须在朋友确认后替换。
- **目标**：验证“路边餐饮摊位日常经营 + 私厨定制服务”的个人品牌小程序闭环。
- **访谈结论**：订单流程、微信身份、配送、私厨报价和后台处理规则见 [07-requirements-interview-decisions.md](./07-requirements-interview-decisions.md)。
## 2. 经营者画像
经营者是一名有稳定客源的餐饮摊主，平时通过固定摊位售卖成品套餐，也接受熟客的私厨菜品定制。当前主要依靠路过客流、熟人介绍、朋友圈和聊天沟通获客。
### 当前问题
- 路过客户能看到摊位，但不了解经营者本人和菜品特色。
- 成品套餐、私厨定制和临时菜单分散在聊天记录中。
- 客户询问菜品、人数、预算和日期时，经营者需要反复沟通。
- 私厨案例和客户反馈无法长期沉淀。
- 经营者需要一个可以直接转发给客户的品牌入口。
### 期望结果
- 客户能快速了解摊主和菜品风格。
- 客户能查看日常套餐和私厨服务说明。
- 客户能提交私厨需求，减少重复沟通。
- 经营者能在后台集中查看和处理咨询。
- 通过作品和反馈逐步建立个人餐饮品牌。
## 3. 品牌定位示例
以下内容仅用于原型，不代表最终文案：
**品牌名称**：阿成家常菜 / 待确认
**一句话定位**：街边烟火味的家常菜，也为小型聚餐定制一桌热饭菜。
**品牌介绍**：每天在附近摊位制作现做套餐，主打分量足、口味家常、适合快速用餐。除日常套餐外，也承接家庭聚餐、朋友小聚和小型活动的私厨菜品定制。
**核心信任点**：现做、家常口味、可沟通调整、熟客反馈、经营者本人负责制作。
## 4. 小程序内容示例
### 4.1 首页
- 顶部：品牌头像、摊主照片或招牌照片
- 定位短句：现做家常套餐｜私厨菜品定制
- 主要按钮：查看今日套餐、预约私厨
- 代表服务：日常成品套餐、家庭聚餐私厨、小型活动定制
- 代表作品：招牌菜、聚餐案例、季节菜品
- 反馈：客户对味道、分量和服务的评价
- 联系区域：营业时间、摊位位置、微信/电话
### 4.2 服务项目
#### 日常成品套餐
- 类型：成品餐
- 价格：示例“￥18-35 / 份”，待确认
- 描述：当天现做的家常套餐，适合工作日午餐或晚餐。
- 预约方式：可咨询当日供应情况，不保证预留
#### 家庭聚餐私厨
- 类型：私厨定制
- 价格：示例“根据人数和菜单报价”
- 描述：适合家庭聚餐、生日、小型聚会，可根据人数、口味和预算沟通菜单。
- 预约方式：需要提前沟通日期、人数、地点和预算
#### 小型活动定制
- 类型：私厨定制
- 价格：示例“面议”
- 描述：适合朋友聚会、工作室活动和小型聚餐，提供菜品组合建议。
- 预约方式：提交需求后由经营者联系确认
## 5. 私厨预约字段调整
通用预约表单需要增加餐饮场景字段。第一版仍然不做支付和自动排班，但应收集足够信息，减少来回沟通。
### 必填字段
- 称呼
- 手机号或微信号至少一项
- 服务类型
- 期望日期
- 用餐人数
- 用餐地点或区域
### 可选字段
- 预算范围
- 口味偏好：清淡、辣、家常、其他
- 忌口或过敏信息
- 菜品偏好
- 其他备注
### 表单说明
页面需要明确提示：
> 提交需求后，经营者会根据日期、人数、地点和菜品要求联系确认。提交不代表预约已确认，也不产生费用。
这段说明很重要，因为第一版没有支付、自动排班和即时确认能力。
## 6. 预约状态建议
沿用通用状态，但在餐饮后台显示更容易理解的文案：
| 系统状态 | 页面文案 | 说明 |
|---|---|---|
| pending | 待联系 | 客户刚提交需求 |
| contacted | 沟通中 | 已联系，正在确认菜单或细节 |
| completed | 已完成 | 已完成本次餐饮服务 |
| cancelled | 已取消 | 客户或经营者取消 |
第一版不增加“已确认”状态，避免在没有支付和排班能力时造成履约承诺。若真实业务需要，可在试用后增加 `confirmed`。
## 7. 餐饮场景下的作品分类
- 招牌菜
- 日常套餐
- 家庭聚餐
- 小型活动
- 季节菜单
## 8. 必须向朋友确认的问题
1. 实际品牌名称和摊位名称是什么？
2. 是否允许公开摊位位置、营业时间和联系方式？
3. 私厨服务是否到客户家制作，还是统一地点出餐？
4. 是否接受外送、打包或仅现场用餐？
5. 私厨最少几人起订？
6. 通常需要提前几天预约？
7. 是否有固定价格区间或只接受咨询报价？
8. 是否存在过敏原、忌口和食品安全提示？
9. 哪些作品图片可以公开使用？
10. 客户反馈是否可以公开显示姓名或头像？
## 9. 对第一版需求的影响
此试点不改变整体产品边界，但会调整预约表单的字段。支付仍然不实现；私厨报价、订金和最终确认全部通过经营者与客户沟通完成。
如果朋友的真实业务以“日常成品套餐”为主，首页应优先展示今日/常见套餐；如果以“私厨定制”为主要增长方向，首页主按钮应优先引导私厨需求提交。这个选择需要用真实经营目标确认，而不是由系统默认。

56
docs/06-domain-extension-strategy.md Normal file
View File

@@ -0,0 +1,56 @@
# 个人品牌核心与行业扩展策略
## 1. 目标
产品长期服务的是“个人品牌经营者”，而不是某一个行业。不同职业可以有不同的服务字段和业务流程，但都建立在同一套品牌基础能力之上。第一版以餐饮摊主和私厨为试点，餐饮字段不能写死成所有预约都必须填写的字段。
## 2. 三层模型
### 品牌核心层
所有行业共享：品牌资料、服务项目、作品/案例、预约或咨询、客户反馈、内容管理后台。
### 行业配置层
行业可以配置服务分类、预约字段、字段顺序和必填规则、预约说明、状态文案、作品分类和联系前需要收集的信息。
示例：私厨需要人数、地点、预算、口味和忌口；摄影师需要拍摄类型、人数、地点、日期和交付需求；咨询师需要咨询主题、方式和可接受时段。
### 行业流程层
只有真实需求证明流程不同，才增加行业专属状态或步骤。第一版不实现流程编排，只使用通用预约状态和可扩展文案。
## 3. 数据设计原则
- 品牌名称、服务名称、客户联系方式、期望日期等高频字段保持结构化，便于校验和查询。
- 行业字段使用受控扩展，不让前端提交任意键名。
- 第一版可使用 `bookings.extra_data` JSON 存储行业字段；字段定义由后端配置决定。
- 建议支持的字段类型：`text`、`textarea`、`number`、`date`、`select`、`multiselect`。
- 暂不实现插件系统、行业代码复制和通用字段配置后台。
未来可增加 `industry_profiles`、`booking_field_definitions`，并让每个品牌选择一个行业模板。模板只提供默认值，不能覆盖品牌已经修改的内容。
## 4. 餐饮试点落地
通用字段仍放在 `bookings`：称呼、联系方式、服务、期望日期、备注。餐饮字段放入受控扩展数据：
```json
{
"guest_count": 6,
"location": "杭州市西湖区",
"budget_range": "500-800",
"taste_preferences": ["家常", "微辣"],
"allergy_notes": "对花生过敏",
"dish_preferences": "希望有一道鱼和一道汤"
}
```
第一版可以固定餐饮字段配置，不需要开发字段配置后台；但 API 必须校验字段名、类型和必填规则。
## 5. 稳定的核心接口
不同行业都应复用：获取品牌、获取服务和作品、提交预约/咨询、管理员处理预约、提交反馈、审核反馈。行业差异通过配置、扩展数据和状态文案表达。
## 6. 决策规则
新增行业需求时先判断：这是所有品牌需要的能力，还是行业字段；是否需要查询统计；流程是否真的不同；是否已有第二个真实客户验证；是否影响预约和支付边界。没有重复真实需求时，优先使用配置或 `extra_data`，不增加行业专用表和页面。

106
docs/07-requirements-interview-decisions.md Normal file
View File

@@ -0,0 +1,106 @@
# 首轮需求访谈决策
## 文档效力
本文记录首个餐饮试点经过访谈确认的需求。若与早期 PRD、原型或数据文档冲突，以本文为准，后续实现应同步采用这些规则。
## 产品目标
第一优先级是帮助经营者获得真实订单，覆盖普通套餐和私厨定制。产品方的获利、运营和平台化目标不得损害经营者的实际使用效果。
## 客户身份
- 品牌、服务、作品和公开反馈允许匿名浏览。
- 客户首次下单时通过 `wx.login` 建立无感微信身份，不要求注册账号或设置密码。
- 后端通过 OpenID 识别客户，客户端不得指定其他客户身份。
- 联系方式仍由客户主动填写，用于实际履约。
- “我的订单”只展示当前 OpenID 创建的订单，不支持通过手机号查询其他微信账号的订单。
## 普通套餐订单
- 客户选择套餐和数量，页面展示单价和预计总价。
- 预计总价不代表支付或最终应收金额，最终线下结算。
- 保存套餐名称、单价、数量和小计快照，历史订单不受以后调价影响。
- 支持自取和配送。
- 自取填写期望取餐时间。
- 配送填写地点、宿舍楼/具体位置、期望送达时间和可选备注。
- 页面展示可编辑的配送范围说明；第一版不做地图围栏或自动可达判断。
- 客户可选择微信联系、电话联系或无需联系。
- 提交表示经营者已经收到订单请求，不表示订单已确认或已支付。
- 无法满足套餐、时间或配送要求时，经营者再联系客户。
## 私厨定制需求
- 私厨无法标准化报价，由经营者人工评估、沟通和报价。
- 必填：称呼、手机号或微信号至少一项、期望日期、用餐人数、用餐地点或区域。
- 选填：预算范围、口味偏好、忌口/过敏信息、菜品偏好和补充说明。
- 私厨不自动计算总价，不公开报价和沟通过程。
## 客户侧状态与操作
客户侧统一展示：
```text
已收到 -> 沟通中 -> 已确认 -> 已完成
\-> 已取消
```
- “已确认”只表示经营者接受履约，不表示已经支付。
- 客户仅可在“已收到”状态取消。
- 客户不能直接编辑已提交订单；需要修改时取消后重新提交，或联系经营者。
- 私厨只展示粗粒度状态，不要求经营者录入菜单、报价和沟通细节。
## 后台处理
- 区分普通套餐订单和私厨需求。
- 支持未读标记、状态更新和内部备忘。
- 支持预设标签和管理员自定义标签，一个订单可使用多个标签。
- 建议预设标签：普通套餐、私厨、配送、自取、熟客、重点跟进。
- 标签、备忘、报价和内部沟通内容不得返回客户接口。
- 后台订单可靠落库、未读数和待处理数属于 P0。
- 微信订阅消息属于 P1；仅在主体、服务类目和模板允许时启用，发送失败不得影响订单落库。
## 数据模型增量
`Booking` 增加或明确：
```text
customer_user_id
request_type package | private_chef
contact_preference wechat | phone | none
fulfillment_type pickup | delivery | null
requested_time
delivery_address
estimated_amount 单位为分，仅普通套餐预计金额
extra_data 受控行业扩展字段
is_read
status received | contacting | confirmed | completed | cancelled
```
新增：
- `CustomerUser`：保存 OpenID 和登录时间。
- `BookingItem`：保存套餐名称、单价、数量和小计快照。
- `Tag`、`BookingTag`：保存预设/自定义标签及订单关联。
`Booking` 不包含 `paid` 或 `payment_status`。未来支付仍使用独立的 `Order`、`Payment` 和 `Refund` 模型。
## API 增量
```text
POST /api/customer/session/wechat
GET /api/customer/bookings
GET /api/customer/bookings/:id
POST /api/customer/bookings/:id/cancel
PATCH /api/admin/bookings/:id/read
GET /api/admin/tags
POST /api/admin/tags
PUT /api/admin/bookings/:id/tags
```
所有客户订单接口必须使用服务端登录态解析 OpenID。只有 `received` 状态允许客户取消。
## 待确认项
普通套餐采用固定菜单、每日菜单，还是“固定套餐 + 每日可用状态”，仍需朋友结合真实维护习惯确认。第一版不得提前实现复杂每日菜单、库存或截止时间规则。

391
docs/PRD.md Normal file
View File

@@ -0,0 +1,391 @@
# 个人品牌小程序试点版 PRD
## 1. 文档信息
- **版本**：v0.1
- **产品阶段**：单品牌试点版
- **目标用户**：朋友作为首个品牌经营者；其客户作为小程序访客
- **产品形态**：微信小程序 + Web 内容管理后台
- **当前目标**：让品牌经营者能在微信中展示自己、接收预约/咨询，并自行维护内容
> 需求基线补充：首轮访谈后的订单、微信身份、配送、标签与状态规则见 [07-requirements-interview-decisions.md](./07-requirements-interview-decisions.md)。与本文早期表述冲突时，以该决策文档为准。
## 2. 背景与问题
个体户和手艺人通常依赖朋友圈、聊天记录和零散图片介绍业务。客户难以快速了解其身份、服务、作品和合作方式，经营者也缺少一个可持续维护的品牌入口。
本项目先为一个真实经营者交付可用的小程序，验证“品牌展示 + 预约承接 + 内容自维护”的完整闭环。第一版不做支付、不做多商户平台、不做自动发布流程。
## 3. 产品目标
### 3.1 目标
1. 客户在 1 分钟内了解品牌、服务和代表作品。
2. 客户无需注册即可提交咨询或预约。
3. 经营者可以在后台独立更新品牌、服务和作品内容。
4. 经营者可以查看并处理预约，审核客户反馈。
5. 形成一个可复用的首个品牌案例，为后续自己的品牌和其他客户项目提供基础。
### 3.2 非目标
- 当前不提供支付、退款、发票、分账或财务对账。
- 当前不提供多商户注册、套餐、计费和租户自助开通。
- 当前不提供多员工、多门店、复杂排班和库存管理。
- 当前不提供自动注册、自动审核、自动发布微信小程序。
- 当前不将小程序做成内容社区或平台流量市场。
## 4. 用户与角色
### 4.1 访客/客户
无需登录即可浏览公开内容和提交预约。提交预约时填写必要联系信息。
### 4.2 品牌管理员
朋友本人。可登录后台管理品牌资料、服务、作品、预约和反馈。
### 4.3 平台维护者
开发者本人。负责系统维护、问题排查、内容协助和版本发布。第一版可与品牌管理员共用后台，但权限模型应保留角色字段。
## 5. 核心用户流程
### 5.1 客户浏览并预约
```text
打开小程序 -> 首页了解品牌 -> 查看服务/作品 -> 点击预约
-> 填写称呼、联系方式、服务、期望日期和备注
-> 提交成功 -> 品牌方在后台处理
```
### 5.2 管理员更新内容
```text
登录后台 -> 编辑品牌资料/服务/作品 -> 保存
-> 预览 -> 内容在小程序端展示
```
### 5.3 管理员处理预约
```text
后台查看待处理预约 -> 查看详情 -> 联系客户
-> 更新为已联系/已完成/已取消 -> 添加内部备注
```
### 5.4 反馈发布
```text
客户提交反馈 -> 后台审核 -> 通过后显示在小程序
```
## 6. 功能需求
优先级定义：P0 为第一版必须交付，P1 为第一版可选增强，P2 为后续规划。
### 6.1 小程序：首页（P0）
展示品牌头像、名称、一句话介绍、代表服务、代表作品和主要行动按钮。
**要求**
- 公开访问，无需登录。
- 内容来自后台配置，不得写死在前端。
- 服务和作品无内容时，模块自动隐藏或显示空状态，不出现破损布局。
- 至少提供“查看服务”和“联系/预约”两个主要入口。
### 6.2 小程序：品牌介绍（P0）
- 品牌名称、头像/Logo、封面图
- 个人简介
- 从业经历
- 擅长领域
- 服务理念
- 联系方式、所在地区、地址（可选）
**要求**
- 支持富文本或结构化文本编辑。
- 联系电话、微信号等敏感信息由管理员控制是否展示。
- 地址展示与地图能力解耦，第一版可先展示文字地址。
### 6.3 小程序：服务项目（P0）
每项服务包含：名称、封面图、描述、价格文本、预计时长、预约状态、排序。
**价格规则**
- 第一版只展示价格文本，例如“￥xxx”“面议”“起价 xxx”。
- 价格不参与支付、不计算订单金额。
- 数据模型保留可扩展的数值价格字段，但第一版不展示支付按钮。
**要求**
- 仅展示已启用服务。
- 支持服务详情页。
- 服务可配置“可预约/仅咨询”。
### 6.4 小程序：作品集（P0）
每项作品包含：图片、标题、描述、分类、排序、是否展示。
- 支持多图浏览。
- 支持作品详情页。
- 图片加载失败时显示占位状态。
- 作品数量较多时支持分类筛选或分页加载（P1）。
### 6.5 小程序：预约/咨询表单（P0）
字段：
- 称呼：必填，2-30 字
- 手机号或微信号：至少填写一项
- 服务项目：可选，来自已启用服务
- 期望日期：可选，不能选择过去日期
- 备注：可选，0-500 字
- 用户同意联系/信息使用提示：必选确认
**提交规则**
- 提交前校验字段格式。
- 防止重复提交，提交按钮在请求期间禁用。
- 成功后生成预约编号，并显示提交成功页。
- 失败时保留用户已填内容并给出可理解的错误提示。
- 第一版不承诺具体预约时间，不做自动排班和冲突检测。
### 6.6 小程序：反馈（P0）
- 查看已审核反馈。
- 提交称呼、内容和可选联系方式。
- 内容长度 10-500 字。
- 新反馈默认待审核，不直接公开。
- 后台审核通过后才展示。
### 6.7 小程序：管理员入口（P1）
- 后端返回当前微信身份是否为管理员。
- 仅管理员显示入口。
- 入口可跳转管理后台网页或后续管理页面。
- 隐藏入口不能替代后端鉴权，所有管理 API 必须重新校验权限。
第一版可暂时使用后台独立登录，不要求小程序内完成管理操作。
### 6.8 后台：登录与权限（P0）
- 管理员登录、退出登录。
- 密码不得明文存储，应使用安全哈希。
- 登录态有过期时间，支持主动退出。
- 每个管理 API 校验登录态和角色。
- 角色字段至少保留 `admin`、`operator` 两种值；第一版可只启用 `admin`。
### 6.9 后台：品牌资料管理（P0）
- 编辑品牌名称、头像、封面、简介、经历、擅长领域、服务理念、联系方式和地址。
- 控制首页模块是否显示。
- 保存草稿和发布内容可先合并为“保存即生效”。
- 保存成功后显示明确反馈。
- 提供预览入口。
### 6.10 后台：服务管理（P0）
- 新增、编辑、删除服务。
- 启用/停用服务。
- 修改排序。
- 配置服务描述、价格文本、时长和预约方式。
- 删除前二次确认；已产生预约的服务建议采用停用而非物理删除。
### 6.11 后台：作品管理（P0）
- 上传图片、编辑标题/描述/分类。
- 调整排序。
- 隐藏/显示作品。
- 删除前确认。
- 限制文件类型、大小和图片数量，并展示上传进度/失败原因。
### 6.12 后台：预约管理（P0）
- 列表展示预约编号、客户称呼、联系方式、服务、期望日期、状态、提交时间。
- 支持按状态和日期筛选。
- 查看详情。
- 状态：待处理、已联系、已完成、已取消。
- 添加内部备注。
- 联系方式仅授权管理员可见。
- 第一版不发送自动通知，管理员通过现有联系方式联系客户。
### 6.13 后台：反馈管理（P0）
- 查看待审核、已通过、已隐藏反馈。
- 通过、隐藏、删除。
- 查看提交时间和关联预约（如有）。
- 审核操作记录操作人和时间。
### 6.14 后台：预览（P0）
- 从后台进入小程序预览页。
- 预览内容与当前保存数据一致。
- 第一版不做复杂草稿版本和多人协作。
## 7. 页面清单
### 小程序
1. 首页
2. 品牌介绍页
3. 服务列表页
4. 服务详情页
5. 作品集列表页
6. 作品详情页
7. 预约/咨询表单页
8. 提交成功页
9. 反馈列表页
10. 反馈提交页
### 管理后台
1. 登录页
2. 首页/概览页
3. 品牌资料页
4. 服务列表/编辑页
5. 作品列表/编辑页
6. 预约列表/详情页
7. 反馈列表/审核页
8. 预览入口
## 8. 数据模型
### BrandProfile
`id`, `name`, `avatar_url`, `cover_url`, `intro`, `experience`, `expertise`, `philosophy`, `contact_phone`, `contact_wechat`, `address`, `is_published`, `created_at`, `updated_at`
### Service
`id`, `name`, `description`, `cover_url`, `price_text`, `price_amount`（预留，第一版不用于支付）, `duration_minutes`, `booking_enabled`, `is_enabled`, `sort_order`, `created_at`, `updated_at`
### PortfolioItem
`id`, `title`, `description`, `category`, `image_urls`, `is_visible`, `sort_order`, `created_at`, `updated_at`
### Booking
`id`, `booking_no`, `customer_name`, `phone`, `wechat_id`, `service_id`, `requested_date`, `note`, `status`, `admin_note`, `created_at`, `updated_at`
### Feedback
`id`, `booking_id`（可选）, `customer_name`, `content`, `contact`, `status`, `reviewed_by`, `reviewed_at`, `created_at`, `updated_at`
### AdminUser
`id`, `username`, `password_hash`, `display_name`, `role`, `wechat_openid`（预留）, `is_enabled`, `last_login_at`, `created_at`, `updated_at`
### 远期支付相关预留
第一版不创建可用支付流程，但应避免把预约和支付强绑定。远期可新增：
- `Order`：业务订单，与 `Booking` 一对一或一对多关联
- `Payment`：支付单、微信交易号、金额、状态、支付时间
- `Refund`：退款记录
- `price_amount` 使用整数分，避免浮点金额
- 订单状态与预约状态分离
第一版的 `Booking` 不应包含 `paid`、`payment_status` 等容易造成误解的字段。若必须预留，使用独立扩展表或明确标记为未启用字段。
## 9. 权限与安全要求
- 公开内容接口只返回已发布、已启用、已审核数据。
- 管理接口必须验证登录态和角色。
- 联系方式、预约备注等个人信息不得出现在公开接口和日志中。
- 所有输入进行长度、格式和内容校验。
- 图片上传限制 MIME 类型、文件大小和存储路径。
- 删除采用软删除或保留审计记录，避免误删预约数据。
- 生产环境必须使用 HTTPS。
- 管理操作记录操作人、动作和时间。
- 小程序端隐藏管理员入口仅为体验优化，不是安全边界。
## 10. 非功能要求
- 移动端首屏在正常网络下可用，图片按需加载并压缩。
- 后台适配桌面浏览器，窄屏下不出现不可操作的横向溢出。
- 关键操作有加载、成功、失败和空状态。
- 表单提交具备幂等或重复提交保护。
- 数据库每日备份，至少保留最近 7 天备份（部署条件允许时）。
- 关键错误写入可检索日志，但不得记录明文密码和完整联系方式。
## 11. 验收标准
### 内容闭环
- 管理员登录后可以修改品牌介绍，重新打开小程序可看到更新。
- 管理员可以新增、停用和排序服务。
- 管理员可以上传、隐藏和排序作品。
- 未启用服务和未展示作品不会出现在小程序公开页面。
### 预约闭环
- 客户无需注册即可提交有效预约。
- 缺少称呼和联系方式时不能提交。
- 重复点击不会生成重复预约。
- 管理员可以查看预约详情并更新状态。
- 预约联系方式不出现在公开页面。
### 反馈闭环
- 客户提交的反馈默认不可见。
- 管理员审核通过后才展示。
- 管理员可以隐藏已展示反馈。
### 权限闭环
- 未登录用户无法访问管理页面和管理 API。
- 普通用户即使直接调用管理接口也无法修改数据。
- 管理员退出后旧登录态失效或在有效期内被拒绝。
### 远期支付兼容性
- 第一版没有支付按钮、支付接口和支付状态。
- 服务价格仅作为展示文本，不产生支付金额。
- 预约状态不承担订单和支付状态职责。
- 后续新增支付不会要求重写品牌、服务和预约基础数据。
## 12. 开发阶段与交付顺序
### 阶段一：需求和内容准备
- 确认朋友的品牌资料、服务、作品和预约流程。
- 确认视觉基调和首页结构。
- 收集真实图片和联系方式。
### 阶段二：基础系统
- 数据库和 API。
- 管理员登录。
- 品牌、服务、作品管理。
- 小程序公开展示。
### 阶段三：业务闭环
- 预约表单和预约后台。
- 反馈提交、审核和展示。
- 权限校验、错误处理和日志。
### 阶段四：真实试用
- 用朋友的真实内容上线测试环境。
- 至少完成 3 次内容更新和 3 次预约流程演练。
- 修复影响真实使用的问题。
- 冻结第一版范围，记录后续需求，不在上线前无限扩张。
## 13. 后续评估指标
第一版上线后两周观察：
- 朋友是否能独立完成内容更新。
- 客户是否能在不解释的情况下找到服务和联系方式。
- 是否产生真实咨询或预约。
- 预约处理是否比原有聊天记录更清晰。
- 哪些后台操作被频繁使用或频繁出错。
- 哪些需求是其他品牌也可能复用的。
只有在真实使用出现稳定需求后，再评估支付、微信通知、多品牌和自动发布能力。
## 14. 版本边界结论
本版本的交付结果是一个可用的单品牌展示和预约系统，而不是完整 SaaS，也不是电商系统。支付作为远期能力被保留在产品边界和数据设计中，但当前不实现、不测试、不展示入口。任何新增需求都必须说明它是否直接帮助“展示品牌、承接预约、维护内容”这三个目标；否则进入后续需求池。