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
124 lines
4.6 KiB
Markdown
124 lines
4.6 KiB
Markdown
# 数据库技术债务追踪
|
||
|
||
> 版本: 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 项技术债务 |
|