# 技术架构与决策记录

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