# 数据库技术债务追踪

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