86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# 技术架构与决策记录
|
||
|
||
## 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` 依赖页面组件。
|