From e28140a0b34285b46b0207f46fc8490a1603222a Mon Sep 17 00:00:00 2001 From: que01 Date: Fri, 18 Sep 2026 14:15:49 +0800 Subject: [PATCH] docs: define initial product requirements --- agent.md | 158 ++++++++ docs/01-prototype-spec.md | 121 ++++++ docs/02-architecture-and-decisions.md | 85 +++++ docs/03-data-and-api-design.md | 179 +++++++++ docs/04-implementation-plan.md | 106 ++++++ docs/05-pilot-case-food-stall.md | 144 +++++++ docs/06-domain-extension-strategy.md | 56 +++ docs/07-requirements-interview-decisions.md | 106 ++++++ docs/PRD.md | 391 ++++++++++++++++++++ 9 files changed, 1346 insertions(+) create mode 100644 agent.md create mode 100644 docs/01-prototype-spec.md create mode 100644 docs/02-architecture-and-decisions.md create mode 100644 docs/03-data-and-api-design.md create mode 100644 docs/04-implementation-plan.md create mode 100644 docs/05-pilot-case-food-stall.md create mode 100644 docs/06-domain-extension-strategy.md create mode 100644 docs/07-requirements-interview-decisions.md create mode 100644 docs/PRD.md diff --git a/agent.md b/agent.md new file mode 100644 index 0000000..c80885f --- /dev/null +++ b/agent.md @@ -0,0 +1,158 @@ +# Project Agent Guide + +## 项目定位 + +这是一个面向个体户和手艺人的个人品牌小程序试点项目。当前第一个交付对象是朋友的真实品牌。 + +第一版的核心闭环是： + +```text +品牌展示 -> 服务/作品了解 -> 客户预约或咨询 -> 管理员后台处理 -> 客户反馈 +``` + +产品目标是帮助个人建立自己的品牌入口；后台和多品牌能力是实现手段，不要把项目优先级转向 SaaS、套餐、租户注册或平台流量。 + +## 必读文档 + +开始开发或修改需求前，按以下顺序阅读： + +1. `docs/PRD.md`：产品范围、功能需求和验收标准。 +2. `docs/01-prototype-spec.md`：页面、字段、状态和交互要求。 +3. `docs/02-architecture-and-decisions.md`：技术选型和架构决策。 +4. `docs/03-data-and-api-design.md`：数据模型、接口边界和上传流程。 +5. `docs/04-implementation-plan.md`：里程碑、测试和发布清单。 +6. `docs/05-pilot-case-food-stall.md`：当前首个试点的餐饮场景假设和待确认内容。 +7. `docs/06-domain-extension-strategy.md`：个人品牌核心能力与行业扩展边界。 +8. `docs/07-requirements-interview-decisions.md`：首轮访谈确认的订单与客户身份规则；冲突时优先于早期文档。 + +## 已安装的成熟 Skills + +项目当前复用以下外部 skill，不重复维护同类自定义规则： + +- `playwright-testing`：仅在编写或调试 Playwright E2E 测试时使用。重点遵循用户可见角色/标签定位、Page Object、失败截图和 trace。 +- `codex-review-workflow`：在用户要求代码审查、自动质量验证，或功能完成需要正式 review 时使用。默认最多执行初审和一次复审，不把它用于普通探索任务。 + +这两个 skill 安装在用户级 `/Users/que01/.agents/skills/`，不属于项目源码。项目规则、产品边界和技术决策仍以本文件及 `docs/` 为准。 + +## 当前已接受的技术决策 + +- Monorepo：`pnpm workspace + Turborepo` +- 小程序：原生微信小程序 + TypeScript +- 管理后台：Next.js + TypeScript +- API：NestJS + TypeScript +- 数据库：PostgreSQL +- ORM：Prisma +- 图片：S3 兼容对象存储 +- 后台登录：第一版账号密码，未来可绑定微信身份 +- 发布：第一版人工使用微信开发者工具发布 + +## 第一版范围 + +必须实现： + +- 小程序首页、品牌介绍、服务、作品集 +- 客户无需注册提交预约/咨询 +- 公开内容匿名浏览；下单使用微信无感身份，并提供“我的订单”。 +- 普通套餐支持数量、自取/配送和预计总价；私厨由经营者人工报价。 +- 后台支持订单未读、标签和内部备忘。 +- 客户提交反馈，后台审核后公开 +- 后台登录和权限校验 +- 品牌、服务、作品内容管理 +- 预约列表、状态和内部备注 +- 图片上传、预览和基本错误处理 + +明确不实现： + +- 支付、退款、发票、财务对账 +- 订单和支付状态 +- 自动发布微信小程序 +- 多商户注册、套餐和计费 +- 多员工、多门店、复杂排班 +- 会员、优惠券、营销自动化 +- 自动消息通知 + +价格可以作为展示文本；可以预留金额字段，但不得在第一版创建支付入口或支付状态。未来支付应使用独立的 `Order`、`Payment`、`Refund` 模型，不能把支付状态塞进 `Booking`。 + +## 开发规则 + +- 先确认原型和字段，再修改数据库；不要根据临时页面直接添加字段。 +- 公开 API 与管理 API 分离。 +- 前端隐藏管理入口不是权限控制，所有管理接口必须服务端鉴权。 +- 联系方式、预约备注等敏感数据不得从公开接口返回。 +- 内容删除优先使用停用、隐藏或软删除，保留预约和审核记录。 +- 新增功能必须说明用户问题、优先级、数据影响和是否影响支付兼容性。 +- 不要为了未来 SaaS 过早实现租户注册、计费和复杂权限。 +- 不要将品牌文案、服务和作品写死在前端代码中。 +- 共享类型和状态枚举放在 `packages/`，避免前后端重复定义。 +- 任何涉及真实客户数据的调试输出都必须脱敏。 + +## 推荐目录 + +```text +apps/miniapp # 微信小程序 +apps/admin # Next.js 管理后台 +apps/api # NestJS API +packages/types +packages/api-client +packages/validation +packages/config +prisma/ +docs/ +``` + +## 工作方式 + +每完成一个里程碑，都要验证对应闭环，而不是只检查页面是否能打开： + +1. 后台保存品牌资料，小程序能看到更新。 +2. 后台创建服务，小程序能展示并支持预约。 +3. 客户提交预约，后台能看到并更新状态。 +4. 客户提交反馈，后台审核后小程序才能展示。 +5. 未登录用户无法修改任何管理数据。 + +真实朋友使用前，先完成文档中的发布前检查和数据库备份方案。试点上线后再根据实际使用频率决定是否抽象多品牌和自动化能力。 + +## Vibe Coding 最小规范 + +以下规则用于控制后续 AI 辅助开发的范围和上下文成本。 + +### 开始任务前 + +1. 先阅读本文件和与任务直接相关的文档，不要一次加载全部代码。 +2. 用一句话写清楚本次任务的结果和不包含的内容。 +3. 先搜索现有实现，再决定新增文件还是修改现有文件。 +4. 涉及数据库、公共类型或 API 契约时，先检查调用方。 + +### 实现任务时 + +- 一次只处理一个可验证的小目标。 +- 优先复用现有模式，不为单一需求新增抽象层。 +- 每次修改保持在必要文件范围内，不顺手重构无关代码。 +- 先实现业务闭环，再补样式、优化和扩展能力。 +- 不实现 PRD 明确排除的功能，除非用户明确改变范围。 +- 新增依赖前说明用途、替代方案和维护成本。 +- 不把临时数据、品牌文案或密钥写死在代码中。 + +### 完成任务前 + +1. 运行与改动匹配的最小验证：类型检查、单元测试、API 测试或手工流程。 +2. 检查错误状态、空状态、权限边界和重复提交。 +3. 检查是否引入敏感信息、无关文件或未记录的数据库变更。 +4. 用简短记录说明改了什么、为什么改、如何验证、剩余风险。 + +### 上下文和 token 控制 + +- 默认只读取完成当前任务所需的文件。 +- 大文件先搜索相关符号和行号，再读取局部内容。 +- 不重复输出已经确定的背景和完整代码。 +- 计划超过三个步骤时，先写出短计划再执行。 +- 遇到不确定的产品决策，优先依据 PRD；PRD 没有覆盖时记录假设，不要扩大实现范围。 + +### 任务完成定义 + +任务只有同时满足以下条件才算完成： + +- 代码或文档已落盘。 +- 相关验证已执行，或明确说明无法执行的原因。 +- 变更符合第一版范围和数据/API 约束。 +- 用户能根据结果继续下一步工作。 diff --git a/docs/01-prototype-spec.md b/docs/01-prototype-spec.md new file mode 100644 index 0000000..9b56860 --- /dev/null +++ b/docs/01-prototype-spec.md @@ -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 个页面的低保真线框。 +- 预约和反馈两条流程图。 +- 字段表、文案表、空状态和错误状态清单。 +- 一份朋友确认过的真实内容样例。 diff --git a/docs/02-architecture-and-decisions.md b/docs/02-architecture-and-decisions.md new file mode 100644 index 0000000..2c60452 --- /dev/null +++ b/docs/02-architecture-and-decisions.md @@ -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` 依赖页面组件。 diff --git a/docs/03-data-and-api-design.md b/docs/03-data-and-api-design.md new file mode 100644 index 0000000..9cf2529 --- /dev/null +++ b/docs/03-data-and-api-design.md @@ -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` 表示微信支付交易；三者必须独立建模。支付成功不能直接等价于预约完成，预约仍由业务流程决定。 diff --git a/docs/04-implementation-plan.md b/docs/04-implementation-plan.md new file mode 100644 index 0000000..5cb4c13 --- /dev/null +++ b/docs/04-implementation-plan.md @@ -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. 试点后的评估 + +上线两周后评估： + +- 朋友是否能自行维护内容。 +- 客户是否完成浏览到联系/预约。 +- 预约是否比原有聊天记录更可追踪。 +- 哪些功能被重复使用。 +- 哪些功能造成理解成本。 +- 是否出现第二个真实品牌项目。 + +只有重复需求出现后，才抽象多品牌、租户、计费和自动化发布能力。 diff --git a/docs/05-pilot-case-food-stall.md b/docs/05-pilot-case-food-stall.md new file mode 100644 index 0000000..bbdfd3d --- /dev/null +++ b/docs/05-pilot-case-food-stall.md @@ -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. 对第一版需求的影响 + +此试点不改变整体产品边界，但会调整预约表单的字段。支付仍然不实现；私厨报价、订金和最终确认全部通过经营者与客户沟通完成。 + +如果朋友的真实业务以“日常成品套餐”为主，首页应优先展示今日/常见套餐；如果以“私厨定制”为主要增长方向，首页主按钮应优先引导私厨需求提交。这个选择需要用真实经营目标确认，而不是由系统默认。 diff --git a/docs/06-domain-extension-strategy.md b/docs/06-domain-extension-strategy.md new file mode 100644 index 0000000..9cb3c02 --- /dev/null +++ b/docs/06-domain-extension-strategy.md @@ -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`，不增加行业专用表和页面。 diff --git a/docs/07-requirements-interview-decisions.md b/docs/07-requirements-interview-decisions.md new file mode 100644 index 0000000..a4d5b02 --- /dev/null +++ b/docs/07-requirements-interview-decisions.md @@ -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` 状态允许客户取消。 + +## 待确认项 + +普通套餐采用固定菜单、每日菜单，还是“固定套餐 + 每日可用状态”，仍需朋友结合真实维护习惯确认。第一版不得提前实现复杂每日菜单、库存或截止时间规则。 diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..8796474 --- /dev/null +++ b/docs/PRD.md @@ -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，也不是电商系统。支付作为远期能力被保留在产品边界和数据设计中，但当前不实现、不测试、不展示入口。任何新增需求都必须说明它是否直接帮助“展示品牌、承接预约、维护内容”这三个目标；否则进入后续需求池。