HaHafeng
6124c7abc6
Completed: - Add 6 core database documents (docs/01-平台基础层/07-数据库/) Architecture overview, migration history, environment comparison, tech debt tracking, seed data management, PostgreSQL extensions - Restructure deployment docs: archive 20 legacy files to _archive-2025/ - Create unified daily operations manual (01-日常更新操作手册.md) - Add pending deployment change tracker (03-待部署变更清单.md) - Update database development standard to v3.0 (three iron rules) - Fix Prisma schema type drift: align @db.* annotations with actual DB IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100) - Add migration: 20260227_align_schema_with_db_types (idempotent ALTER) - Add Cursor Rule for auto-reminding deployment change documentation - Update system status guide v6.4 with deployment and DB doc references - Add architecture consultation docs (Prisma guide, SAE deployment guide) Technical details: - Manual migration due to shadow DB limitation (TD-001 in tech debt) - Deployment docs reduced from 20+ scattered files to 3 core documents - Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes Made-with: Cursor
96 lines
5.5 KiB
Markdown
96 lines
5.5 KiB
Markdown
# **Prisma 数据库同步与生产部署规范 (SOP)**
|
||
|
||
针对本地 schema.prisma 与真实数据库不同步（Schema Drift）的问题，结合我们平台的“Postgres-Only”架构特性（存在大量非 Prisma 管理的底层函数，如 pg-boss），特制定本规范。
|
||
|
||
## **一、 当前差距有多大？如何安全评估？**
|
||
|
||
由于我无法直接连接您的本地数据库，当前的“具体差距”需要您通过命令行来测量。基于系统近期的 V2.1 迭代（引入了 SSA QPER 架构、RVW 模块 Schema 隔离、IIT 模块表等），大概率存在未提交的 Migration 或手动修改的字段。
|
||
|
||
### **安全测量差距的指令（只读，绝对安全）**
|
||
|
||
请在 backend 目录下运行以下命令来查看差距，**不要直接跑 push**：
|
||
|
||
\# 查看本地 Schema 与当前数据库的差异 (Diff)
|
||
npx prisma migrate diff \--from-schema-datamodel prisma/schema.prisma \--to-schema-datamodel prisma/schema.prisma
|
||
|
||
\# 或者更直观地查看哪些迁移尚未应用
|
||
npx prisma migrate status
|
||
|
||
**差距通常分为三类：**
|
||
|
||
1. **Prisma 超前**：你在 schema.prisma 里加了新模型（如 IitProject），但还没在数据库建表。
|
||
2. **数据库超前**：你或队友手动在数据库里跑了 SQL 加了字段，但没更新到 schema.prisma。
|
||
3. **平台边界对象（预期内差距）**：数据库中存在 platform\_schema.job\_common 表和 create\_queue() 函数。由于我们是 Postgres-Only 架构使用了 pg-boss，这些对象**不由 Prisma 管理**，在对比时 Prisma 可能会认为这些是“多余的”，这是正常的，**绝对不能让 Prisma 删掉它们**。
|
||
|
||
## **二、 如何彻底解决并确立规范操作？**
|
||
|
||
要彻底解决不同步问题，必须明确\*\*“唯一事实来源 (Single Source of Truth)”**。在现代 ORM 开发流程中，**schema.prisma 必须是数据库结构的唯一事实来源\*\*。
|
||
|
||
### **🔴 绝对红线（重申 2026-01-11 事故教训）**
|
||
|
||
任何情况下，**严禁**使用以下命令（除非是全新的空数据库）：
|
||
|
||
* ❌ npx prisma db push \--force-reset （会清空所有数据并删除 pg-boss 队列！）
|
||
* ❌ npx prisma migrate reset （会重置整个数据库）
|
||
* ❌ npx prisma db push （在生产环境**绝对禁用**，在本地也尽量少用，因为它不生成迁移历史，容易导致状态撕裂）
|
||
|
||
### **✅ 规范 1：本地开发环境同步 SOP（解决当前不同步）**
|
||
|
||
当你在本地发现 schema.prisma 和数据库不一致时，请严格按照以下 4 步操作：
|
||
|
||
**Step 1: 强制备份（生命线）**
|
||
|
||
docker exec ai-clinical-postgres pg\_dump \-U postgres \-d ai\_clinical\_research \> backup\_$(date \+%Y%m%d).sql
|
||
|
||
**Step 2: 确定谁才是对的？**
|
||
|
||
* **情况 A（正常开发）：schema.prisma 是最新的，数据库旧了。**
|
||
执行生成迁移文件的命令：
|
||
npx prisma migrate dev \--name describe\_your\_changes
|
||
|
||
*说明：这会根据 Prisma Schema 生成一段完整的 SQL (.sql 文件)，并安全地应用到本地数据库。如果报错说有冲突，通常是因为存在手动修改的数据。*
|
||
* **情况 B（特殊情况）：数据库是最新的（比如 DBA 直接改了库），schema.prisma 旧了。**
|
||
执行反向拉取：
|
||
npx prisma db pull
|
||
|
||
*说明：这会将数据库当前的真实结构覆盖写入你的 schema.prisma 中。完成后别忘了执行 npx prisma generate 更新 Node.js 客户端。*
|
||
|
||
**Step 3: 重新生成 Client**
|
||
|
||
无论采用哪种情况，同步完成后必须刷新客户端：
|
||
|
||
npx prisma generate
|
||
|
||
### **✅ 规范 2：生产环境部署 SOP（未来如何部署）**
|
||
|
||
在云端（阿里云 SAE \+ RDS）部署时，数据库的操作极其敏感。生产环境**只允许通过标准的 SQL 迁移文件进行变更**。
|
||
|
||
**Step 1: 确保本地已生成 Migration**
|
||
|
||
在本地开发完成后，所有的变更都应该已经通过 npx prisma migrate dev 生成在了 prisma/migrations/ 目录下，并随代码提交到了 Git 仓库。
|
||
|
||
**Step 2: 生产环境应用迁移**
|
||
|
||
在后端服务部署时（可以通过 CI/CD 管道，或在单独的部署容器中），执行以下命令：
|
||
|
||
\# 设置生产环境变量
|
||
export DATABASE\_URL="postgresql://user:password@rds-host:5432/ai\_clinical\_research"
|
||
|
||
\# 执行生产部署专属命令
|
||
npx prisma migrate deploy
|
||
|
||
*原理：migrate deploy **不会**去对比 schema.prisma，它只会傻瓜式地检查 \_prisma\_migrations 表，把还没跑过的 .sql 脚本按顺序执行一遍。这是业界最安全、最规范的做法。*
|
||
|
||
### **✅ 规范 3：Postgres-Only 架构特殊边界守护**
|
||
|
||
因为我们平台利用了 PostgreSQL 作为队列（pg-boss）和缓存，Prisma 在执行某些深度同步时，可能会误删这些非 Prisma 表。
|
||
|
||
**防范策略：**
|
||
|
||
1. 始终保留恢复脚本（目前我们已有 restore\_job\_common.sql 和 restore\_pgboss\_functions.sql）。
|
||
2. 在执行 migrate dev 之后，如果发现 pg-boss 服务崩溃，立即通过 psql 执行上述恢复脚本，将函数重新注入到 platform\_schema 中。
|
||
3. 团队成员之间必须达成共识：所有针对业务表的修改必须走 schema.prisma；所有针对平台底层调度机制（如缓存、队列函数）的修改，直接走原生 SQL，并将其文档化。
|
||
|
||
## **结语**
|
||
|
||
遵循 **“以 schema.prisma 为核心 \-\> 生成 Migration \-\> 本地 migrate dev \-\> 生产 migrate deploy”** 这条标准流水线，就能彻底告别环境撕裂，且为百人并发、多实例部署提供最坚实的数据底座。 |