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:
2026-02-27 14:35:25 +08:00
parent 9b8490b4d0
commit 6124c7abc6
48 changed files with 3009 additions and 582 deletions

View File

@@ -0,0 +1,123 @@
# 数据库技术债务追踪
> 版本: v1.0
> 更新日期: 2026-02-27
> 维护说明: 发现新债务时立即记录,修复后标记状态
---
## 1. 债务总览
| 状态 | 数量 |
|------|------|
| 🔴 待修复 | 2 |
| 🟡 已缓解(带 workaround | 2 |
| 🟢 已修复 | 2 |
---
## 2. 当前债务清单
### TD-001: Shadow DB 重放失败prisma migrate dev 不可用)
| 属性 | 值 |
|------|-----|
| 状态 | 🔴 待修复 |
| 发现日期 | 2026-02-27 |
| 影响范围 | 本地开发环境 |
| 严重程度 | 中 — 不影响部署(`prisma migrate deploy` 不使用 Shadow DB |
| 根因 | 迁移 #10 (`20260223_add_deep_research_v2_fields`) 对 `asl_schema.research_tasks` 执行 ALTER TABLE但该表由 `prisma db push` 创建无对应迁移记录。Shadow DB 重放到 #10 时找不到表 |
| 当前影响 | 无法使用 `prisma migrate dev` 生成新迁移,需手动创建 + `prisma migrate resolve` |
| 修复方案 | 在 #10 之前插入补全迁移,创建 `research_tasks` 及其他 `prisma db push` 表。需同时更新 `_prisma_migrations` 表的记录顺序 |
| 修复难度 | 高 — 需仔细梳理所有 `db push` 创建的表,确保不遗漏 |
### TD-002: equery / critical_events 使用非标准 ID 类型
| 属性 | 值 |
|------|-----|
| 状态 | 🟡 已缓解 |
| 发现日期 | 2026-02-27 |
| 影响范围 | iit_schema |
| 严重程度 | 低 — 不影响功能,仅类型不统一 |
| 根因 | 迁移 #13 使用 PostgreSQL 原生 `UUID` 类型和 `TIMESTAMPTZ`,而系统其他表统一使用 `TEXT` + `TIMESTAMP(3)` |
| Workaround | Schema 中已添加 `@db.Uuid``@db.Timestamptz(6)` 注解对齐,并标注 `// TODO: Tech Debt` |
| 最终修复 | 未来大版本重构时统一 ID 策略(全部 TEXT 或全部 UUID |
### TD-003: ssa_workflows / ssa_workflow_steps 类型精度不一致
| 属性 | 值 |
|------|-----|
| 状态 | 🟢 已修复 |
| 发现日期 | 2026-02-27 |
| 修复日期 | 2026-02-27 |
| 修复方式 | 迁移 #14 (`20260227_align_schema_with_db_types`) 对齐了 VARCHAR 长度和 TIMESTAMP 精度,清理了 2 个重复 FK |
### TD-004: Prisma diff 引擎的 vector 类型噪音
| 属性 | 值 |
|------|-----|
| 状态 | 🟡 已缓解 |
| 发现日期 | 2026-02-27 |
| 影响范围 | ekb_schema, iit_schema, ssa_schema |
| 严重程度 | 低 — 纯噪音,不影响任何功能 |
| 根因 | Prisma 的 `Unsupported("vector(1024)")` 类型无法被 diff 引擎正确比较,每次 diff 都会输出 3 条 `ALTER COLUMN SET DATA TYPE` 假变更 |
| Workaround | 已知噪音,运行 diff 时忽略 vector 相关行 |
| 最终修复 | 等待 Prisma 原生支持 pgvector 类型 |
### TD-005: prisma db push 历史遗留
| 属性 | 值 |
|------|-----|
| 状态 | 🟢 已修复 |
| 发现日期 | 2026-02-27 |
| 修复日期 | 2026-02-27 |
| 影响范围 | iit_schema, ssa_schema, rvw_schema |
| 修复方式 | 迁移 #12 (`20260227_patch_db_push_drift`) 使用 `CREATE TABLE IF NOT EXISTS``ADD COLUMN IF NOT EXISTS` 将所有 db push 创建的结构纳入迁移体系 |
### TD-006: public schema 遗留表
| 属性 | 值 |
|------|-----|
| 状态 | 🔴 待修复 |
| 发现日期 | 2026-02-27 |
| 影响范围 | public schema |
| 严重程度 | 极低 — 不影响任何功能 |
| 根因 | `public.users``public.admin_logs` 是系统早期创建的遗留表,在引入 multi-schema 后已被 `platform_schema.users``admin_schema.admin_operation_logs` 替代 |
| 修复方案 | 确认无引用后安全删除遗留表 |
| 修复难度 | 低 |
---
## 3. 债务产生根因分析
```
prisma db push 的不规范使用
├── 表/列未纳入迁移体系 → TD-005 (已修复)
├── Shadow DB 无法重放 → TD-001 (待修复)
└── 非标准类型创建 → TD-002, TD-003 (已缓解/已修复)
Prisma ORM 限制
└── Unsupported 类型 diff 噪音 → TD-004 (已缓解)
历史架构演进
└── multi-schema 前的遗留表 → TD-006 (待修复)
```
---
## 4. 预防措施
| 措施 | 对应规范 |
|------|---------|
| **禁止** 在开发中使用 `prisma db push`(仅限原型探索) | `docs/04-开发规范/09-数据库开发规范.md` |
| 所有 Schema 变更必须通过 `prisma migrate dev` | 同上 |
| 新增迁移后立即更新迁移日志 | `docs/01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md` |
| 部署前对比环境差异 | `docs/01-平台基础层/07-数据库/02-环境状态对照表.md` |
---
## 5. 更新日志
| 日期 | 操作人 | 变更 |
|------|--------|------|
| 2026-02-27 | AI 助手 | 初始化文档,记录 6 项技术债务 |