Harden location db startup validation

docs/location-recorder.md

@@ -31,8 +31,10 @@ PRAGMA user_version = 2;
 
 1. 把上述 `location` schema 视为 Alembic baseline
 2. 新数据库通过 Alembic `upgrade head` 初始化
-3. 已有 legacy SQLite 数据库，只要确认 schema 与 baseline 一致，就通过 `alembic stamp` 接管
-4. 未来不再以 `PRAGMA user_version` 作为主 migration 机制
+3. 已有 legacy SQLite 数据库，只要确认 schema 与 baseline 一致，再通过 `alembic stamp` 接管
+4. 如果数据库已经存在 `alembic_version`，则必须先确认当前 revision 与项目预期 baseline 一致
+5. 只有 revision 一致时，才视为该库已经被正确接管
+6. 未来不再以 `PRAGMA user_version` 作为主 migration 机制
 
 当前 baseline revision 是：
 
@@ -56,6 +58,15 @@ python -m scripts.location_db_adopt
 - 本地没有 DB 文件：按新库初始化
 - 任一校验不通过：立即报错并停止
 
+应用本身在启动时不会自动替你初始化 `location` 数据库。
+应用启动时会对 `LOCATION_DATABASE_URL` 做只读校验：
+
+- 文件不存在：直接报错，并提示先运行接管脚本
+- 文件存在但还没有 `alembic_version`：直接报错，要求先完成 legacy 接管
+- 文件已被 Alembic 管理但 revision 不匹配：直接报错并拒绝启动
+
+这是有意为之，用来避免应用在错误路径上静默创建新库，或带着错误数据库版本继续跑业务。
+
 ## 新数据库初始化
 
 如果本地不存在 `LOCATION_DATABASE_URL` 指向的 DB 文件：
@@ -77,11 +88,14 @@ alembic upgrade head
 对于已经存在的 legacy SQLite 数据库：
 
 1. 先确认 DB 文件存在
-2. 读取当前 DB 中 `location` 表的实际 schema
-3. 与 baseline schema 做严格比对
-4. 再检查 `PRAGMA user_version`
-5. 只有 schema 匹配且 `user_version = 2` 时，才执行 Alembic `stamp`
-6. 接管完成后，后续 migration 才交给 Alembic 管理
+2. 如果已经存在 `alembic_version` 表，则先读取当前 revision
+3. 如果 revision 等于 `20260419_01_location_baseline`，则视为该库已经被 Alembic 正确接管
+4. 如果 revision 不匹配，立即报错并停止，不做任何自动修复
+5. 如果还没有 `alembic_version` 表，则读取当前 DB 中 `location` 表的实际 schema
+6. 与 baseline schema 做严格比对
+7. 再检查 `PRAGMA user_version`
+8. 只有 schema 匹配且 `user_version = 2` 时，才执行 Alembic `stamp`
+9. 接管完成后，后续 migration 才交给 Alembic 管理
 
 示例：
 
@@ -110,6 +124,7 @@ LOCATION_DATABASE_URL=sqlite:///./data/locationRecorder.db python scripts/locati
 - 找不到 `location` 表
 - `location` 表 schema 与 baseline 不一致
 - `PRAGMA user_version` 不等于 `2`
+- 已有 `alembic_version`，但 revision 与预期 baseline 不一致
 - 目标 DB 不是 SQLite URL
 
 当前不会尝试：

docs/migration-notes.md

@@ -68,6 +68,12 @@ CREATE TABLE location (
 - 只有全部匹配才执行 Alembic `stamp`
 - 不匹配则直接失败，不自动修复
 
+同时，应用启动阶段现在也会对 location DB 做保守的只读校验：
+
+- DB 文件不存在时拒绝启动
+- DB 尚未被 Alembic 接管时拒绝启动
+- DB revision 与当前应用预期不一致时拒绝启动
+
 ## 后续建议顺序
 
 建议继续沿用既有迁移文档中的顺序：