CyberStrikeAI/docs/feature/startup-schema-reconcile/requirements.md

# 启动时自动补齐数据库结构

- Status: Confirmed
- Created: 2026-10-10
- Source: 用户要求启动时自动对比所有表的最新结构，缺表、缺字段自动补齐，不依赖迁移代码列出的字段。
- Confirmed by: 用户（当前对话）
- Confirmation date: 2026-10-10

## 问题与目标

当前会创建缺表，但只检查手写迁移列表中的字段。希望以项目最新表结构定义为依据，在服务接收请求之前检查所有应用管理的表，自动补齐缺表、缺字段。以后新增字段只需更新最新表结构定义，无需再维护同一字段的补齐迁移列表。

## 功能需求

| ID | 需求 | 来源 |
| --- | --- | --- |
| REQ-001 | 每次启动时对比所有应用管理表的最新定义和实际结构。 | 用户要求 |
| REQ-002 | 缺表时自动创建，缺字段时自动补齐，不依赖逐字段迁移列表。 | 用户要求 |
| REQ-003 | 项目实际使用的 SQLite 数据库文件均执行上述检查，逐文件检查项目定义的所有表。 | 范围边界 |
| REQ-004 | 已有数据与额外表、字段予以保留；本次不自动删除、重命名字段或修改已有字段类型、约束。 | 范围边界 |
| REQ-005 | 无法安全补齐时停止启动，并报告表、字段和原因。 | 范围边界 |
| REQ-006 | 重复启动不重复添加表或字段，结构检查在依赖相关字段的索引创建及业务访问之前完成。 | 范围边界 |

## 用户场景与验收

| ID | 关联需求 | 验收标准 |
| --- | --- | --- |
| AC-001 | REQ-001、REQ-002、REQ-003 | 空数据库启动后具备最新定义中的全部应用表和字段。 |
| AC-002 | REQ-001、REQ-002 | 旧数据库缺少最新定义中的表或字段时，启动后自动补齐，即使该字段没有手写迁移。 |
| AC-003 | REQ-004 | 补齐后原有数据和额外字段、表仍存在。 |
| AC-004 | REQ-005 | 补齐操作失败时服务不开始接收请求，错误明确指出失败位置和原因。 |
| AC-005 | REQ-006 | 连续启动两次成功，第二次无重复字段错误，依赖新字段的索引可正常创建。 |

## 范围与执行边界

- “所有表”指项目定义并管理的表，不包含 SQLite 内部表或其他应用自行添加的表。
- 本次需求是补齐缺表、缺字段；完整的已有类型、默认值及约束变更不纳入自动修复范围。
- SQLite 不能直接添加的字段定义应明确报错，不擅自降低约束或清空已有数据。
- 历史数据回填、外键修正等语义迁移仍需保留；它们与缺字段检查是不同职责。
- 执行范围：项目使用的 SQLite 文件、保留已有数据、补齐失败阻止启动。

## 工作流与维护性检查

- Workflow Gate：P1 产品契约；后端数据库初始化功能。已有启动入口、建表定义和迁移测试；缺少本功能已确认需求与设计。需求已获明确确认，设计和实现允许推进。
- 执行范围：数据库启动初始化；不改变对外 API。
- Maintainability Gate：database.go 为 1,822 行，风险 high。采用独立模块与薄委托的 adapter_extraction，避免继续在大文件中堆积结构对比逻辑；设计与实现阶段需明确提取边界。
- Feature Lifecycle：F0 完成仓库检查，原 main 工作区干净；专用分支 codex/startup-schema-reconcile。F1 已确认（2026-10-10 当前对话）。文档为本文件；后续阶段记录设计、实现、验证及变更说明。

## 确认

Decision: Confirmed — 用户明确要求按启动对比、缺表补表、缺字段补字段、保留已有数据实施。

用户原文：“对，就按这个改，启动时自动对比 SQLite 最新结构，缺表补表、缺字段补字段，保留已有数据。”