|
|
@@ -0,0 +1,225 @@
|
|
|
+# Prisma V1 Baseline Migration 设计
|
|
|
+
|
|
|
+## 1. 背景
|
|
|
+
|
|
|
+当前项目的 `backend/prisma/schema.prisma` 已经基本代表了当前数据库的稳定结构，可以视为第一版数据库模型。但仓库中的 `backend/prisma/migrations` 目录存在以下问题：
|
|
|
+
|
|
|
+- 历史 migration 数量很少，但依赖顺序已经不健康。
|
|
|
+- `20260628050000_add_customer_follow_content` 依赖 `customer` 表存在，却早于 `20260628120000_add_customer_table`。
|
|
|
+- `20260628173000_add_template_used_count` 是后补增量，而用户已经手动执行过对应 SQL。
|
|
|
+- 当前 migration 历史更像是开发过程痕迹，而不是可长期维护的基线。
|
|
|
+
|
|
|
+用户希望把现在这一版数据库正式收敛为“第一个稳定版本”，后续新功能再继续追加新的 migration。
|
|
|
+
|
|
|
+## 2. 目标
|
|
|
+
|
|
|
+本次调整后，需要满足以下目标：
|
|
|
+
|
|
|
+1. `schema.prisma` 继续作为当前稳定数据库结构的唯一事实来源。
|
|
|
+2. `backend/prisma/migrations` 目录只保留一条 `v1 baseline migration`。
|
|
|
+3. 这条 baseline migration 能用于新环境从零初始化数据库。
|
|
|
+4. 现有旧增量 migration 全部移除，不再保留开发阶段的历史痕迹。
|
|
|
+5. 后续数据库改动从 `v1 baseline` 继续追加新的增量 migration。
|
|
|
+
|
|
|
+## 3. 非目标
|
|
|
+
|
|
|
+以下内容不在本次范围内：
|
|
|
+
|
|
|
+1. 不保留旧 migration 的增量演进历史。
|
|
|
+2. 不再尝试修复旧 migration 的依赖顺序。
|
|
|
+3. 不修改当前数据库表结构语义，只做基线重置。
|
|
|
+4. 不做业务字段增删改设计。
|
|
|
+5. 不把 `schema.prisma` 回退到旧版本状态。
|
|
|
+
|
|
|
+## 4. 方案选择
|
|
|
+
|
|
|
+### 方案 A：保留旧 migration，只新增一个 baseline
|
|
|
+
|
|
|
+做法：
|
|
|
+
|
|
|
+- 保留当前 3 条旧 migration。
|
|
|
+- 再新增一条 `init_v1` 作为“以后认这个版本”的基线。
|
|
|
+
|
|
|
+优点：
|
|
|
+
|
|
|
+- 旧历史还在。
|
|
|
+
|
|
|
+缺点：
|
|
|
+
|
|
|
+- 目录仍然不干净。
|
|
|
+- 新成员会被旧历史误导。
|
|
|
+- 无法真正达到“第一版稳定基线”的目标。
|
|
|
+
|
|
|
+### 方案 B：删除全部旧 migration，只保留一个新的 baseline
|
|
|
+
|
|
|
+做法：
|
|
|
+
|
|
|
+- 删除当前所有旧 migration。
|
|
|
+- 基于当前稳定 `schema.prisma` 与数据库设计，新增一条 `init_v1`。
|
|
|
+- 后续所有数据库变更从该基线继续新增。
|
|
|
+
|
|
|
+优点：
|
|
|
+
|
|
|
+- 目录结构最干净。
|
|
|
+- 与“当前稳定结构就是 v1”完全一致。
|
|
|
+- 未来维护成本最低。
|
|
|
+
|
|
|
+缺点：
|
|
|
+
|
|
|
+- 旧增量历史不再保留。
|
|
|
+
|
|
|
+### 结论
|
|
|
+
|
|
|
+采用 **方案 B：删除全部旧 migration，只保留一个新的 baseline**。
|
|
|
+
|
|
|
+## 5. 目标目录结构
|
|
|
+
|
|
|
+调整后，`backend/prisma` 的目标结构如下：
|
|
|
+
|
|
|
+```text
|
|
|
+backend/prisma/
|
|
|
+ schema.prisma
|
|
|
+ migrations/
|
|
|
+ 20260628_init_v1/
|
|
|
+ migration.sql
|
|
|
+```
|
|
|
+
|
|
|
+要求：
|
|
|
+
|
|
|
+- 不再保留：
|
|
|
+ - `20260628050000_add_customer_follow_content`
|
|
|
+ - `20260628120000_add_customer_table`
|
|
|
+ - `20260628173000_add_template_used_count`
|
|
|
+- `migrations` 目录内只保留一个 `init_v1`
|
|
|
+
|
|
|
+## 6. Baseline 定义
|
|
|
+
|
|
|
+### 6.1 基线语义
|
|
|
+
|
|
|
+`20260628_init_v1` 表示当前项目第一版稳定数据库结构。
|
|
|
+
|
|
|
+它不是增量修改脚本，而是一个完整初始化脚本，语义是：
|
|
|
+
|
|
|
+- 在一个空数据库中，直接创建当前版本所需的全部表结构、字段、索引和约束。
|
|
|
+
|
|
|
+### 6.2 基线内容来源
|
|
|
+
|
|
|
+baseline migration 的 SQL 内容必须与以下两处保持一致：
|
|
|
+
|
|
|
+1. `backend/prisma/schema.prisma`
|
|
|
+2. `backend/docs/数据库设计.md`
|
|
|
+
|
|
|
+其中：
|
|
|
+
|
|
|
+- `schema.prisma` 是代码层的事实来源。
|
|
|
+- `数据库设计.md` 用于校验字段注释、表注释和索引注释是否完整。
|
|
|
+
|
|
|
+### 6.3 基线必须包含的结构
|
|
|
+
|
|
|
+至少包含当前稳定版本中的全部核心表：
|
|
|
+
|
|
|
+- `hairstylist_user`
|
|
|
+- `customer`
|
|
|
+- `customer_treatment_record`
|
|
|
+- `ai_hair_simulation`
|
|
|
+- `ai_hair_simulation_task`
|
|
|
+- `hair_template`
|
|
|
+- `hair_template_make_task`
|
|
|
+- `system_config`
|
|
|
+
|
|
|
+并包含：
|
|
|
+
|
|
|
+- 当前稳定字段定义
|
|
|
+- 当前稳定索引
|
|
|
+- 当前稳定注释
|
|
|
+- `hair_template.used_count`
|
|
|
+
|
|
|
+## 7. 现有环境的处理策略
|
|
|
+
|
|
|
+### 7.1 已存在数据库的前提
|
|
|
+
|
|
|
+当前开发环境数据库已经存在，且用户已手动执行过部分 SQL。此时不能把新的 `init_v1` 当成一条要“重新执行建表”的 migration 直接运行到现有数据库上，否则会和已有表冲突。
|
|
|
+
|
|
|
+### 7.2 仓库层与数据库层分开处理
|
|
|
+
|
|
|
+本次设计把处理分成两层：
|
|
|
+
|
|
|
+- 仓库层：
|
|
|
+ - 清理旧 migration
|
|
|
+ - 新增 `20260628_init_v1/migration.sql`
|
|
|
+- 数据库层：
|
|
|
+ - 将当前数据库视为已经处于 `v1 baseline` 状态
|
|
|
+ - 用 Prisma 的 migration 状态对齐手段把这条 baseline 标记为已应用
|
|
|
+
|
|
|
+### 7.3 对齐原则
|
|
|
+
|
|
|
+原则上，现有开发库不需要重建，也不需要重新执行 baseline SQL。
|
|
|
+
|
|
|
+需要做的是：
|
|
|
+
|
|
|
+- 确保当前数据库结构与 `schema.prisma` 一致
|
|
|
+- 确保 Prisma 侧知道 `20260628_init_v1` 已经是“已应用状态”
|
|
|
+
|
|
|
+## 8. 实施约束
|
|
|
+
|
|
|
+### 8.1 不修改稳定结构
|
|
|
+
|
|
|
+本次重置 migration 历史时，不允许顺手修改当前数据库结构定义。`schema.prisma` 中现有的稳定结构应保持不变。
|
|
|
+
|
|
|
+### 8.2 保留注释完整性
|
|
|
+
|
|
|
+因为用户对 SQL 质量有明确要求，所以 baseline SQL 必须保留：
|
|
|
+
|
|
|
+- 表注释
|
|
|
+- 字段注释
|
|
|
+- 索引注释
|
|
|
+
|
|
|
+不能只生成“无注释的最小 SQL”。
|
|
|
+
|
|
|
+### 8.3 baseline 只作为起点
|
|
|
+
|
|
|
+一旦 `init_v1` 建立完成，后续新增字段或表时：
|
|
|
+
|
|
|
+- 不能回头修改 `init_v1`
|
|
|
+- 必须新增新的 migration
|
|
|
+
|
|
|
+除非未来再次明确决定整体重置数据库基线。
|
|
|
+
|
|
|
+## 9. 风险与规避
|
|
|
+
|
|
|
+### 风险 1：仓库中的 baseline 与当前数据库不一致
|
|
|
+
|
|
|
+如果 `migration.sql` 漏了字段或索引，新环境初始化会和当前开发环境不一致。
|
|
|
+
|
|
|
+规避方式：
|
|
|
+
|
|
|
+- 生成 baseline 后，对照 `schema.prisma` 和 `数据库设计.md` 做逐项校验。
|
|
|
+
|
|
|
+### 风险 2：现有环境误执行 baseline SQL
|
|
|
+
|
|
|
+如果在已有数据库上直接执行 `init_v1`，会因为表已存在而失败。
|
|
|
+
|
|
|
+规避方式：
|
|
|
+
|
|
|
+- 本次只把 baseline 作为仓库中的初始化基线。
|
|
|
+- 对现有环境采用“标记为已应用”的方式对齐，而不是重新执行完整建表 SQL。
|
|
|
+
|
|
|
+### 风险 3：后续开发者继续改 baseline
|
|
|
+
|
|
|
+如果未来继续把字段直接改进 `init_v1`，新的迁移历史会再次失真。
|
|
|
+
|
|
|
+规避方式：
|
|
|
+
|
|
|
+- 明确规定 `init_v1` 只代表第一版稳定结构。
|
|
|
+- 后续所有变更必须新增新的 migration。
|
|
|
+
|
|
|
+## 10. 验收标准
|
|
|
+
|
|
|
+本次完成后，应满足以下验收标准：
|
|
|
+
|
|
|
+1. `backend/prisma/migrations` 中只剩一个 `20260628_init_v1` 目录。
|
|
|
+2. `migration.sql` 能完整表达当前稳定数据库结构。
|
|
|
+3. `migration.sql` 包含 `used_count` 等当前稳定字段。
|
|
|
+4. `schema.prisma` 与 baseline SQL 一致。
|
|
|
+5. 旧 3 条 migration 不再保留。
|
|
|
+6. 后续数据库开发可以在 `v1 baseline` 之上继续新增 migration。
|
ChenYu