# 数据库迁移与大数据升级指南

本文约束已发布用户数据的数据库升级。具体字段、存储表示和功能行为由对应功能文档负责；
本文不建立通用迁移框架、回滚引擎或独立状态日志。

## 先确认问题和数据边界

1. 先只读统计文件大小、WAL、页数、空闲页、表与字段的字节数，不先删除或压缩数据库。
2. 区分有效内容、重复存储、索引和已释放但未回收的空间。空闲页少时，单独
   `VACUUM` 不能消除重复记录。
3. 查清实际写入、读取、删除、重放与恢复入口。修改 Runtime 相关持久化时，同时检查
   本机和 GoodBuddy Agent 的桌面路径，不假设一个入口覆盖另一个入口。
4. 明确用户必须保留的信息、稳定 ID、顺序、时间、引用与远程去重字段。
   分支内未发布、可安全重建的内部记录不需要兼容机制。

## 实现原则

- 先修新增数据路径，再修历史数据。历史转换与新写入尽量使用同一套转换函数。
- 普通 schema 变更使用既有 `PRAGMA user_version` 和 SQLite 事务；
  已升级 schema 不允许旧客户端强行打开，不通过回写版本号支持降级。
- 大数据转换不得同步阻塞 Electron Main 或 Renderer。放到工作线程，在业务连接
  打开前处理，并使用应用的共享字体、主题与页面组件显示进度和可执行的失败提示。
- 根据实测设置有界读取批次与缓存，批次提交后再报告进度。保持 SQLite 事务与
  checkpoint，不靠关闭同步落盘、取消约束或一次性读入整库提速。
- 从已提交数据直接重试和还原即可完成的迁移，不增加 durable snapshot、journal、
  receipt 或多阶段恢复状态。退出及失败至少回滚未提交批次，保留已完成部分。
- 差量编码必须能精确还原原始事件。更新内容、删除或重排都要覆盖；涉及远程来源时，
  去重、冲突判断、消息投影和恢复序号不得失效。
- 释放数据库页和归还文件系统空间是不同步骤。先减少实际存储内容，再执行需要的
  空间回收；保留足够临时空间，磁盘不足时明确失败并允许重试。
- SQLite 同库写入是串行的。是否增加读取／转换并行，应由实际读取、解析、写入、
  提交与 checkpoint 的耗时决定，不把增加写线程当作默认优化。

## 验证与备份

### 合成回归

覆盖正常转换、无变化记录、重复打开、内容修订、失败事务和退出续跑。数据库大小问题
必须同时验证新增写入的增长量、旧记录可还原性以及文件实际缩小，而不只检查 schema。
对象比较必须覆盖真实生产形状和 JSON 往返，尤其是可选字段值为 `undefined` 时与字段缺省
的差异。再次修复已发布迁移产生的数据时，提高目标 schema，并覆盖已升级用户的入口；
不能只处理尚未迁移的旧库。

### 真实旧库

1. 关闭占用源数据库的应用，确认 WAL 状态。没有 WAL 时可复制已关闭的数据库；
   有活动 WAL 时使用 SQLite 一致性备份机制，不只复制主文件。
2. 备份到空间足够的位置，记录字节数并校验 SHA-256。备份和测试副本分离，
   不直接在唯一原件或唯一备份上试跑。
3. 使用当前源码或用户要求的 portable 正常启动入口执行升级，不用手工 SQL 代替
   产品升级过程。退出一次后重新启动，验证已提交数据可以继续处理。
4. 比较升级前后消息、任务、成果等用户表的内容；对转换事件逐条还原后比较原始内容、
   ID、顺序、时间和去重来源，不只比较行数。日志只能包含统计和断言结果，不记录正文。
5. 运行数据库完整性检查，记录主文件和 WAL 的实际字节数、回收比例、耗时、平台、
   源 schema 与目标 schema。确认原件和备份未被改写。
6. 运行 `npm test`、`npm run typecheck`、`npm run lint`；生产构建变化按开发验证规则
   检查，发布准备则遵循[发布手册](./release-runbook.md)，不重复本地打包。
7. 用真实模型模拟正常用户任务，允许主代理与子代理按需调用工具、修改独立测试项目、
   运行测试和处理失败；只读纯文字模型调用不能证明工具事件增长正常。记录实际提供商
   请求数与统计范围，不把 Runtime 用量上报数当成全部 HTTP 请求数。

## 发布与维护

发布说明应告知升级范围、可能耗时、退出重试、额外磁盘空间和降级边界。不得把一个测试库
的回收比例当作所有用户都能获得的保证。功能文档记录具体转换规则，进度文档记录实际
证据和未完成项；未经验证的阶段不能标为完成。

### 已有实例

- Desktop 0.13.1：子任务累计过程重复保存导致数据库膨胀，转换到 schema 34 的差量事件
  表示，并回收空间。具体规则见
  [执行记录存储与升级回收](../features/assistant-workbar/execution-history-storage.md)，
  数据保留与真实旧库验证见[工作栏进度](../features/assistant-workbar/progress.md)。
- 当前未发布源码：schema 35 同时整理旧快照和 schema 34 的重复工具块，工具字段按
  JSON 可保存的值比较，不因 `undefined` 被省略而误判变化。