Add location db adoption runbook

docs/location-recorder.md

@@ -1,6 +1,6 @@
 # Location Recorder
 
-本文档说明 `location recorder` 在 Python 项目中的当前数据库接管策略。
+本文档说明 `location recorder` 在 Python 项目中的当前数据库接管策略，以及 legacy SQLite 接管 runbook。
 
 ## Legacy 事实基线
 
@@ -38,9 +38,33 @@ PRAGMA user_version = 2;
 
 - `20260419_01_location_baseline`
 
+当前提供的最小脚本入口是：
+
+```bash
+python scripts/location_db_adopt.py
+```
+
+如果你更喜欢模块方式运行，也可以用：
+
+```bash
+python -m scripts.location_db_adopt
+```
+
+它只针对 `LOCATION_DATABASE_URL` 工作，并且遵守保守接管原则：
+
+- 本地已有 DB 文件：先校验，再接管
+- 本地没有 DB 文件：按新库初始化
+- 任一校验不通过：立即报错并停止
+
 ## 新数据库初始化
 
-对于一个全新 SQLite 数据库，执行：
+如果本地不存在 `LOCATION_DATABASE_URL` 指向的 DB 文件：
+
+- 脚本会先创建父目录
+- 然后执行 Alembic `upgrade head`
+- 最终建立 `location` 表与 `alembic_version` 表
+
+手工执行时也等价于：
 
 ```bash
 alembic upgrade head
@@ -52,9 +76,12 @@ alembic upgrade head
 
 对于已经存在的 legacy SQLite 数据库：
 
-1. 先确认其 `location` 表 schema 与 baseline 一致
-2. 旧库里的 `PRAGMA user_version = 2` 仅视为历史事实，不再继续沿用
-3. 确认无误后，对该数据库执行 `stamp`，而不是重新跑创建表 migration
+1. 先确认 DB 文件存在
+2. 读取当前 DB 中 `location` 表的实际 schema
+3. 与 baseline schema 做严格比对
+4. 再检查 `PRAGMA user_version`
+5. 只有 schema 匹配且 `user_version = 2` 时，才执行 Alembic `stamp`
+6. 接管完成后，后续 migration 才交给 Alembic 管理
 
 示例：
 
@@ -62,12 +89,37 @@ alembic upgrade head
 LOCATION_DATABASE_URL=sqlite:///./data/locationRecorder.db alembic stamp 20260419_01_location_baseline
 ```
 
+或直接执行脚本：
+
+```bash
+LOCATION_DATABASE_URL=sqlite:///./data/locationRecorder.db python scripts/location_db_adopt.py
+```
+
 这样做的含义是：
 
 - 告诉 Alembic：这个数据库已经处于 baseline 结构
 - 不修改已有 `location` 表数据
 - 后续 migration 由 Alembic 接管
 
+## Fail Closed 原则
+
+当前策略是保守接管，不做未知 legacy 状态的自动修复。
+
+如果出现以下任一情况，脚本会直接报错并停止：
+
+- 找不到 `location` 表
+- `location` 表 schema 与 baseline 不一致
+- `PRAGMA user_version` 不等于 `2`
+- 目标 DB 不是 SQLite URL
+
+当前不会尝试：
+
+- 自动修表
+- 自动调整 `user_version`
+- 自动推断未知 legacy 状态
+
+如果发生这些情况，应先人工确认数据库状态，再决定是否需要单独迁移或修复。
+
 ## 关于 `data/locationRecorder.db`
 
 你本地放在 `data/locationRecorder.db` 的 legacy 样本库，可以用于：
@@ -91,6 +143,12 @@ LOCATION_DATABASE_URL=sqlite:///./data/locationRecorder.db alembic stamp 2026041
 - 构造一个“legacy 风格”的临时 SQLite 文件
 - 建出同样的 `location` 表
 - 设置 `PRAGMA user_version = 2`
-- 再执行 Alembic `stamp`
+- 再执行接管脚本中的 adopt 逻辑
+
+同时也覆盖：
+
+- DB 文件不存在时的新库初始化路径
+- schema 不匹配时的失败路径
+- `user_version` 不匹配时的失败路径
 
 这样可以验证接管路径，同时不污染真实样本库。

docs/migration-notes.md

@@ -61,6 +61,13 @@ CREATE TABLE location (
 
 - [location-recorder.md](location-recorder.md)
 
+当前还额外提供了一个最小 runbook / script 组合，用于保守接管 legacy location DB：
+
+- 先严格校验 schema
+- 再严格校验 `PRAGMA user_version = 2`
+- 只有全部匹配才执行 Alembic `stamp`
+- 不匹配则直接失败，不自动修复
+
 ## 后续建议顺序
 
 建议继续沿用既有迁移文档中的顺序：