AIclinicalresearch/docs/01-平台基础层/07-数据库/03-技术债务追踪.md

数据库技术债务追踪

版本: 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 项技术债务