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 最新结构，缺表补表、缺字段补字段，保留已有数据。”