docs(platform): Add database documentation system and restructure deployment docs
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
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
# 数据库开发规范
|
||||
|
||||
> 版本: v2.0
|
||||
> 更新日期: 2026-01-26
|
||||
> 重要更新: 统一使用 Prisma Schema 管理所有数据库变更
|
||||
> 版本: v3.0
|
||||
> 更新日期: 2026-02-27
|
||||
> v3.0 更新: 新增部署变更实时记录规则、Shadow DB 降级方案、0227 事故教训
|
||||
|
||||
---
|
||||
|
||||
@@ -10,14 +10,27 @@
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ 🎯 统一原则：所有数据库变更必须通过 Prisma Schema 管理 │
|
||||
│ 🎯 三条铁律 │
|
||||
│ │
|
||||
│ ✅ 使用 prisma migrate dev/deploy 进行变更 │
|
||||
│ ❌ 禁止直接执行手工 SQL 修改表结构 │
|
||||
│ ❌ 禁止使用 prisma db push（仅用于原型开发） │
|
||||
│ 1. ✅ 所有数据库变更必须通过 Prisma migrate 管理 │
|
||||
│ 2. ✅ 变更同时必须记录到「待部署变更清单」 │
|
||||
│ 3. ❌ 绝对禁止 prisma db push（除非你愿意花一天修 drift） │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 变更记录规则（v3.0 新增）
|
||||
|
||||
**每次修改 schema.prisma 并生成迁移后，立即做两件事**：
|
||||
|
||||
1. 提交迁移文件到 Git
|
||||
2. 在 `docs/05-部署文档/03-待部署变更清单.md` 追加一行记录
|
||||
|
||||
```markdown
|
||||
| DB-N | 简述变更 | `迁移文件名` | 高/中/低 | 备注 |
|
||||
```
|
||||
|
||||
> Cursor Rule `.cursor/rules/deployment-change-tracking.mdc` 会在你修改 schema.prisma 时自动提醒。
|
||||
|
||||
---
|
||||
|
||||
## 1. 开发流程规范
|
||||
@@ -273,21 +286,24 @@ cat backup_before_migration.sql | docker exec -i ai-clinical-postgres psql -U po
|
||||
|
||||
### 5.1 当前 Schema 列表
|
||||
|
||||
> 完整的表级清单见 `docs/01-平台基础层/07-数据库/00-数据库架构总览.md`
|
||||
|
||||
| Schema | 用途 | 表数量 | 管理方式 |
|
||||
|--------|------|--------|----------|
|
||||
| `platform_schema` | 平台基础设施（用户、租户、pg-boss） | 19 | Prisma + pg-boss |
|
||||
| `aia_schema` | AI智能问答 | 3 | Prisma |
|
||||
| `asl_schema` | 文献筛选 | 7 | Prisma |
|
||||
| `pkb_schema` | 个人知识库 | 5 | Prisma |
|
||||
| `iit_schema` | IIT 临床试验管理 Agent | 20 | Prisma |
|
||||
| `asl_schema` | AI 智能文献 | 11 | Prisma |
|
||||
| `ssa_schema` | 智能统计分析 | 11 | Prisma |
|
||||
| `dc_schema` | 数据清洗 | 6 | Prisma |
|
||||
| `iit_schema` | IIT项目管理 | 5 | Prisma |
|
||||
| `agent_schema` | Agent框架 | 6 | Prisma |
|
||||
| `ekb_schema` | 企业知识库 | 3 | Prisma |
|
||||
| `capability_schema` | 通用能力 | 2 | Prisma |
|
||||
| `protocol_schema` | 方案设计 | 2 | Prisma |
|
||||
| `rvw_schema` | 论文预审 | 1 | Prisma |
|
||||
| `agent_schema` | 通用 Agent 框架 | 6 | Prisma |
|
||||
| `pkb_schema` | 个人知识库 | 5 | Prisma |
|
||||
| `capability_schema` | Prompt 管理 + 系统知识库 | 4 | Prisma |
|
||||
| `aia_schema` | AI 智能问答 | 3 | Prisma |
|
||||
| `ekb_schema` | 企业知识库（向量） | 3 | Prisma |
|
||||
| `admin_schema` | 运营管理 | 2 | Prisma |
|
||||
| `public` | 兼容旧数据 | 2 | Prisma |
|
||||
| `protocol_schema` | 方案 Agent | 2 | Prisma |
|
||||
| `rvw_schema` | 稿件审查 | 1 | Prisma |
|
||||
| `public` | 遗留 + Prisma 迁移表 | 3 | Prisma |
|
||||
|
||||
### 5.2 新增 Schema 规范
|
||||
|
||||
@@ -492,6 +508,32 @@ npx prisma migrate dev # 从 Schema 推送
|
||||
|
||||
---
|
||||
|
||||
## 10. Shadow DB 失败时的降级方案（v3.0 新增）
|
||||
|
||||
当 `prisma migrate dev` 因 Shadow DB 重放失败时（例如引用了 `db push` 创建的表），使用以下降级流程：
|
||||
|
||||
```bash
|
||||
# 1. 手动创建迁移目录
|
||||
mkdir prisma/migrations/YYYYMMDD_migration_name
|
||||
|
||||
# 2. 编写迁移 SQL（参考 prisma migrate diff 的输出）
|
||||
npx prisma migrate diff \
|
||||
--from-url "$DATABASE_URL" \
|
||||
--to-schema-datamodel prisma/schema.prisma \
|
||||
--script > prisma/migrations/YYYYMMDD_migration_name/migration.sql
|
||||
|
||||
# 3. 审查 SQL，确认无破坏性操作
|
||||
|
||||
# 4. 手动执行 SQL 到数据库
|
||||
|
||||
# 5. 标记为已应用
|
||||
npx prisma migrate resolve --applied YYYYMMDD_migration_name
|
||||
```
|
||||
|
||||
> 详见 `docs/01-平台基础层/07-数据库/03-技术债务追踪.md` TD-001
|
||||
|
||||
---
|
||||
|
||||
## 附录：历史事故
|
||||
|
||||
### 案例1：2026-01-11 数据库重置事故
|
||||
@@ -506,7 +548,36 @@ npx prisma migrate dev # 从 Schema 推送
|
||||
**影响**：Prisma Schema 与数据库不一致，后续迁移失败
|
||||
**教训**：所有变更必须通过 Prisma Schema
|
||||
|
||||
### 案例3：2026-02-27 prisma db push 引发的部署 drift（v3.0 新增）
|
||||
|
||||
**原因**：开发过程中大量使用 `prisma db push` 快速迭代，绕过了迁移系统
|
||||
**影响**：
|
||||
- 部署到测试环境时发现 6 张表 + 10 个列不在任何迁移文件中
|
||||
- 部署后运行时报错 `column does not exist`（ssa_sessions.data_profile, review_tasks.context_data）
|
||||
- 需要紧急编写 drift patch 迁移 + 线上热修 SQL
|
||||
- Shadow DB 重放失败，`prisma migrate dev` 不可用
|
||||
|
||||
**修复耗时**：约 3 小时（drift 分析 + patch 编写 + 线上热修 + Schema 类型对齐）
|
||||
**教训**：
|
||||
1. `prisma db push` 是"技术债 ATM"——每用一次就欠一笔
|
||||
2. 即使是快速原型，也应使用 `prisma migrate dev --create-only` 生成迁移后再审查执行
|
||||
3. 变更后必须立即记录到 `03-待部署变更清单.md`
|
||||
|
||||
---
|
||||
|
||||
## 附录：相关文档索引
|
||||
|
||||
| 文档 | 位置 |
|
||||
|------|------|
|
||||
| 数据库架构全景（96 张表） | `docs/01-平台基础层/07-数据库/00-数据库架构总览.md` |
|
||||
| 迁移历史（14 个迁移） | `docs/01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md` |
|
||||
| 环境差异对照 | `docs/01-平台基础层/07-数据库/02-环境状态对照表.md` |
|
||||
| 技术债务追踪 | `docs/01-平台基础层/07-数据库/03-技术债务追踪.md` |
|
||||
| 种子数据管理 | `docs/01-平台基础层/07-数据库/04-种子数据管理.md` |
|
||||
| 待部署变更清单 | `docs/05-部署文档/03-待部署变更清单.md` |
|
||||
|
||||
---
|
||||
|
||||
> 📌 **记住**：Prisma Schema 是唯一真相来源（Single Source of Truth）
|
||||
> 所有数据库结构变更必须先修改 Schema，再通过迁移应用到数据库
|
||||
> 所有数据库结构变更必须先修改 Schema，再通过迁移应用到数据库
|
||||
> **v3.0 补充**：变更后必须同步更新「待部署变更清单」，否则部署时一定会遗漏
|
||||
|
||||
Reference in New Issue
Block a user