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

SQLite 启动结构补齐设计

输入：已确认 requirements.md。仅影响 internal/database，不改变公开 API 或配置。

结构来源与流程

将现有初始化及迁移后最终表定义收敛为随二进制嵌入的 schemas/*.sql，作为最新结构的唯一来源。启动在临时内存 SQLite 中执行定义，使用 SQLite 自身解析 SQL，再从 sqlite_master / pragma_table_xinfo 读取期望表、列、索引。在真实数据库事务中先创建缺表、再按最新列定义 ADD COLUMN，最后创建索引。已有字段、额外表及数据不删除。

flowchart LR
 A[嵌入的最新 SQL] --> B[内存 SQLite 解析]
 B --> C[对比实际表和列]
 C --> D[事务补表和补字段]
 D --> E[创建索引与历史数据处理]
 E --> F[开始接收请求]

边界与失败

• 结构对象：table(name, ddl, columns)、column(name, definition)、index(name, ddl)。它们只在启动期间存在，无新增业务对象。
• 列定义保留最新 SQL 的类型、默认值和内联约束；拆分器尊重引号、注释和嵌套括号，避免以简单逗号切割 SQL。
• 不重建表、不凭空为旧数据编造必填值。SQLite 不支持安全 ADD COLUMN 的主键、唯一约束或缺默认值的必填字段，明确报错并回滚结构补齐事务；修复定义/数据后可重新启动。
• 表级约束不自动改变。结构补齐独立于历史数据回填和既有漏洞外键语义迁移；保留外键迁移时应保留额外字段与数据，避免固定列复制造成损失。
• 全部结构补齐必须在索引及业务 SQL 之前完成；任一步失败阻止启动。现有连接保持外键配置；内存参考库用单连接并在结束时关闭。
• 新字段仅更新 SQL 定义即可，不新增手写补字段列表。删除纯字段迁移列表；既有测试改为验证统一结构补齐。

兼容与验证

保证已有字段不被改写；默认值用于新列的已有行，未知表/字段保留。针对空库、旧库、重复启动、带引号和复杂默认值、失败回滚、非迁移列表字段、额外字段及外键数据保留做测试。已有时间回填继续保持兼容。

维护性门禁选择 adapter_extraction：从 1,822 行 database.go 提取静态 DDL 与补齐行为，旧入口薄委托；不进行无关重构。

覆盖检查与维护门禁补充

全仓库搜索发现处理器另有 HITL 两表与通知已读表，统一移入 application.sql，处理器仅保留数据恢复职责。HITL 文件 1,227 行（high）、通知文件 837 行（medium），只删除静态 DDL 并保留原入口/请求行为，不增加业务复杂度。最终定义覆盖 52 张表（含各数据库文件的同名表）。knowledge 的兼容入口复用同一结构引擎，不再维护字段列表。漏洞历史外键迁移仍按既有语义执行，但基于最新定义、动态复制旧列，保留额外字段、索引、触发器和依赖记录。