docs: define initial product requirements

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` 依赖页面组件。