Migration Startup

---
name: migration-startup
description: 数据库 migration、新增或修改升级钩子、启动数据转换，以及迁移性能排查或评审时使用。要求同时验证性能、真实进度与中英文翻译，并保持数据完整性、耐久性和可恢复性。
---

# Migration：性能、进度与翻译

每次迁移更新都必须检查这三个验收面；它们是迁移功能的一部分，不是可选的界面收尾。仅涉及 DDL 的迁移也必须说明性能风险和启动期呈现方式；没有可信工作总量时使用不定进度。

## 1. 明确工作量与恢复边界

读取根 `AGENTS.md` 的数据库规则、相关 ADR、现有迁移钩子及测试，列出：

- SQLite 与 PostgreSQL 各自经过的 schema 准备、数据转换、验证及收尾阶段。
- 工作量随节点数、引用数、共享正文大小、链深度增长的方式；首次升级与已完成库再次启动的区别。
- 每批的事务边界、完成标记、恢复位置和删除旧结构的条件；哪些步骤可以并行，哪些有前后依赖。

完成条件：上述路径逐项对应到现有实现；已完成阶段不会在正常启动时重复全库转换；中断后只使用已提交状态继续或幂等重跑。schema 同步、参考导出与双后端验证遵循根规则，不另建一套要求。

## 2. 测量后优化吞吐

先建立隔离基线：使用合成数据、现有测试夹具或经授权取得的安全副本，覆盖共享正文、批次边界和大单元。记录阶段 wall time、数据规模、构建模式、数据库同步配置；根据瓶颈采样线程 CPU、SQL 次数、事务数、I/O 或锁等待。观察正在运行的实例时只读采样，不重启或改写它；`ps` 的平均 CPU 与短时采样分别标注，低 CPU 本身不能证明是磁盘瓶颈。

优化优先顺序：

1. 消除逐行读取、共享正文重复恢复、逐引用自动提交和已完成阶段的重复扫描；复用现有批读、去重与批写路径。
2. 按逻辑字节和记录数限制批次，先读薄元数据再选连续前缀；首个不可拆大单元允许独占一批，明确逻辑预算不等于 RSS 硬上限。
3. 独立的解压、摘要校验、解析与准备工作使用有界 CPU worker；保留顺序依赖和 scope 隔离。SQLite 保留单个迁移 writer，增加核数不等于增加写连接。
4. 保持内容校验、外键约束、迁移锁、事务原子性和同步耐久性；不要通过降低 `synchronous`、跳过校验、裁掉大输入或盲目重试换取成绩。

完成条件：相同口径下比较优化前后阶段耗时，核对输出一致；数据量、并发和驻留工作集有界。报告未测项目和波动，不把小夹具或单阶段的倍率写成完整升级、所有硬件或生产数据的保证。新迁移至少提供代表性负载的耗时与资源观测；性能故障修复必须有前后对照。

## 3. 报告真实进度并本地化

复用 `backend/crates/stravia-core/src/startup_progress.rs` 的报告链路及 Server／Desktop 共用的启动界面：

- 每个可能耗时的阶段在工作开始前进入可见状态；已知总量报告当前阶段真实的 `completed / total`，同一阶段的计数单位和分母保持一致。
- 数据转换在批事务提交或文件可靠落盘后才推进完成量；当前批失败不递增，中断重启后依据实际恢复策略重建计数。
- DDL、锁等待、清理等无法取得可信总量的操作报告 `total: None`，显示阶段与不定进度；不按时间或固定阶段权重伪造百分比，也不把单阶段 100% 当作服务已就绪。
- 新增或修改阶段码时，同步检查 `frontend/stravia-webui/src/lib/startup-progress.ts` 和 `frontend/stravia-webui/messages/` 下的 `en-US.json`、`zh-CN.json`；已知阶段必须有两种语言的映射，不能依靠后端英文 `label` 回退冒充翻译。生成物通过现有 i18n 命令重建。

完成条件：真实启动事件能持续更新界面；中英文均显示正确阶段、数量和百分比，未知总量无虚构数字，失败保持可恢复状态而非跳转登录。窄屏能容纳翻译后的阶段文字。

## 4. 用行为证据交付

- 回归保护数据完整性、scope 隔离、批次边界、大单元、失败批回滚与重跑，以及提交进度和阶段切换；按受影响范围选择现有测试，不编写绑定源码文本的断言。
- 用实际服务对隔离库完成升级，验证受影响的 HTTP 行为和两种数据库；进度或翻译变化须在浏览器观察已知／未知总量、持续更新及中英文。桌面宿主有改动时验证实际桌面应用，并说明无法覆盖的宿主。
- 更新现有设计文档与 changelog，记录实测条件及限制，移除临时探针，清理本次创建的测试服务与数据。报告本次没有部署或改动的线上边界。

完成条件：性能、进度、翻译各有实际运行证据，或明确指出不可取得的前置条件；编译成功不替代升级与界面冒烟。

## 实现与证据入口

- 升级编排：`backend/crates/stravia-core/src/migrations.rs`。
- 批量引用回填：`backend/crates/stravia-core/src/turn_chain/upgrade/retention.rs`。
- 迁移专用多核恢复：`backend/crates/stravia-core/src/turn_chain/content.rs`。
- 消费者回归：`tests/e2e/storage/test_shared_content_upgrade.py`、`frontend/stravia-webui/e2e/standalone-pages.spec.ts`。
- 设计边界和带口径的实测：`docs/design/data-layout-performance.md` 第 10.2、10.5 节。该历史测量不是未来迁移的性能基线，须对当前变更重新取证。