# 数据库迁移按发布版本维护

从 App 140（1.4.0）起，发生结构变更的数据库以该次 App `versionCode` 作为目标版本，不再每增加一个功能就递增数据库版本。版本号显式声明，不从运行时 BuildConfig 动态读取。

## 发布基线

以已发布 Git tag 的 `@Database` 声明为准，而不是按当前目录中最大的 schema 编号推测：

| App 发布版本 | AppDatabase | FeatureDatabase |
| --- | --- | --- |
| 139 / tag `1.3.9` | 2 | 4 |
| 140 / 尚未发布 | 140 | 140 |

140 的全部增量集中在 `core/database/src/main/java/com/shifenmiao/database/Release140Migrations.kt`：

- AppDatabase：记忆、技能、会话记忆策略及主题玻璃边界透明度。
- FeatureDatabase：AI 检测、健康记录、家庭物品/位置图标、经期记录及转盘字段/索引/历史标题回填。
- 已发布版本之前的历史迁移继续保留，老安装先到达 139 的数据库基线，再升级到 140。

## 开发规则

1. **140 发布前**，新功能继续追加到本次发布的迁移中，并重新生成两库各自的 `140.json`；不要新增 140→141 或按功能编号的迁移。
2. **140 发布后**，冻结该发布迁移及 schema。下一次需要修改结构时，以对应 App 发布版本创建新的迁移入口；无结构变化的数据库不必升版。
3. 不修改已发布 schema、不伪造 DB 139 起点，也不通过破坏性迁移或降版清库来掩盖遗漏。
4. AppDatabase 3/4、FeatureDatabase 5–9 是未发布周期中出现过的开发版。它们复用 140 的同一套幂等 SQL 直接升级；相应 schema 仅保留为开发版兼容性参考，**不是新的功能发布策略**。
5. 新建表、补列、索引和默认值应与 Room 实体一致。仅在首次添加 `wheelTitle` 时回填历史标题，避免覆盖开发版已保存的历史快照。
6. 修改现有发布草稿时，应同时验证已发布起点、开发版起点及新建库。开发库若已经标为 140，而 140 发布前又修改了实体结构，需要单独处理开发数据备份/重建；不要为此给未发布功能再叠一层生产版本号。

## 验证

在仓库根目录执行：

```sh
./gradlew :core:database:compileOneboxArm64DebugKotlin
```

编译由 Room KSP 导出实际目标 schema。发布前应做真实旧 APK 升级验证，检查已发布基线及开发版升级后的表、列、默认值、外键、索引，以及用户数据保留。临时校验脚本放在工程外；需要长期维护的迁移测试应纳入项目的 Android/Room 测试体系。