diff --git a/docs/feature/startup-schema-reconcile/requirements.md b/docs/feature/startup-schema-reconcile/requirements.md new file mode 100644 index 00000000..2be824a4 --- /dev/null +++ b/docs/feature/startup-schema-reconcile/requirements.md @@ -0,0 +1,53 @@ +# 启动时自动补齐数据库结构 + +- Status: Pending Confirmation +- Created: 2026-10-10 +- Source: 用户要求启动时自动对比所有表的最新结构,缺表、缺字段自动补齐,不依赖迁移代码列出的字段。 +- Confirmed by: Pending +- Confirmation date: Pending + +## 问题与目标 + +当前会创建缺表,但只检查手写迁移列表中的字段。希望以项目最新表结构定义为依据,在服务接收请求之前检查所有应用管理的表,自动补齐缺表、缺字段。以后新增字段只需更新最新表结构定义,无需再维护同一字段的补齐迁移列表。 + +## 功能需求 + +| ID | 需求 | 来源 | +| --- | --- | --- | +| REQ-001 | 每次启动时对比所有应用管理表的最新定义和实际结构。 | 用户要求 | +| REQ-002 | 缺表时自动创建,缺字段时自动补齐,不依赖逐字段迁移列表。 | 用户要求 | +| REQ-003 | 主数据库和知识库数据库均执行上述检查。 | 假设,待确认 | +| 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 不能直接添加的字段定义应明确报错,不擅自降低约束或清空已有数据。 +- 历史数据回填、外键修正等语义迁移仍需保留;它们与缺字段检查是不同职责。 +- 推荐默认:覆盖主库和知识库、保留已有数据、补齐失败阻止启动。 + +## 工作流与维护性检查 + +- Workflow Gate:P1 产品契约;后端数据库初始化功能。已有启动入口、建表定义和迁移测试;缺少本功能已确认需求与设计。当前仅允许需求文档,确认后推进设计和实现。 +- 执行范围:数据库启动初始化;不改变对外 API。 +- Maintainability Gate:database.go 为 1,822 行,风险 high。采用独立模块与薄委托的 adapter_extraction,避免继续在大文件中堆积结构对比逻辑;设计与实现阶段需明确提取边界。 +- Feature Lifecycle:F0 完成仓库检查,原 main 工作区干净;专用分支 codex/startup-schema-reconcile。F1 待确认。文档为本文件;后续阶段记录设计、实现、验证及变更说明。 + +## 确认 + +Decision: Pending user confirmation + +请确认上述需求快照,或指出需要调整的需求 ID。确认后进入设计和实现。