技术架构与决策记录

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. 仓库结构

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

4.2 KiB Raw Blame History Unescape Escape