Migrate location recorder and refine db config

docs/location-recorder.md

@@ -0,0 +1,96 @@
+# Location Recorder
+
+本文档说明 `location recorder` 在 Python 项目中的当前数据库接管策略。
+
+## Legacy 事实基线
+
+当前 legacy SQLite 中 `location` 表的真实 schema 为：
+
+```sql
+CREATE TABLE location (
+  person TEXT NOT NULL,
+  datetime TEXT NOT NULL,
+  latitude REAL NOT NULL,
+  longitude REAL NOT NULL,
+  altitude REAL,
+  PRIMARY KEY (person, datetime)
+);
+```
+
+历史上 legacy Go 实现使用：
+
+```sql
+PRAGMA user_version = 2;
+```
+
+这代表旧系统曾依赖 `user_version` 管理 location 数据库版本，但这不再是 Python 项目的长期 migration 机制。
+
+## 当前策略
+
+当前采用的最小必要接管方案是：
+
+1. 把上述 `location` schema 视为 Alembic baseline
+2. 新数据库通过 Alembic `upgrade head` 初始化
+3. 已有 legacy SQLite 数据库，只要确认 schema 与 baseline 一致，就通过 `alembic stamp` 接管
+4. 未来不再以 `PRAGMA user_version` 作为主 migration 机制
+
+当前 baseline revision 是：
+
+- `20260419_01_location_baseline`
+
+## 新数据库初始化
+
+对于一个全新 SQLite 数据库，执行：
+
+```bash
+alembic upgrade head
+```
+
+这会创建与 legacy 相同的 `location` 表结构，并在库中建立 Alembic revision 记录。
+
+## 旧数据库接管
+
+对于已经存在的 legacy SQLite 数据库：
+
+1. 先确认其 `location` 表 schema 与 baseline 一致
+2. 旧库里的 `PRAGMA user_version = 2` 仅视为历史事实，不再继续沿用
+3. 确认无误后，对该数据库执行 `stamp`，而不是重新跑创建表 migration
+
+示例：
+
+```bash
+LOCATION_DATABASE_URL=sqlite:///./data/locationRecorder.db alembic stamp 20260419_01_location_baseline
+```
+
+这样做的含义是：
+
+- 告诉 Alembic：这个数据库已经处于 baseline 结构
+- 不修改已有 `location` 表数据
+- 后续 migration 由 Alembic 接管
+
+## 关于 `data/locationRecorder.db`
+
+你本地放在 `data/locationRecorder.db` 的 legacy 样本库，可以用于：
+
+- 人工核对 schema
+- 手动验证 `stamp` 接管流程
+- 做开发时的兼容性确认
+
+但当前代码不应硬依赖这个文件存在。
+
+## 测试样本的安全使用方式
+
+如果要用 legacy SQLite 样本做测试或验证，应遵守：
+
+1. 不直接在原始样本文件上跑测试
+2. 先复制到临时路径
+3. 所有 `stamp`、写入、实验性 migration 都只针对副本执行
+
+自动化测试里当前采用的方式是：
+
+- 构造一个“legacy 风格”的临时 SQLite 文件
+- 建出同样的 `location` 表
+- 设置 `PRAGMA user_version = 2`
+- 再执行 Alembic `stamp`
+
+这样可以验证接管路径，同时不污染真实样本库。

docs/migration-notes.md

@@ -11,16 +11,56 @@
 - 建立 pytest 基础设施
 - 建立 Docker / Compose 基础骨架
 - 建立 OpenAPI 导出脚本
+- 迁入 `location recorder` 第一版
+
+## 数据库配置现状
+
+当前系统在配置层上已明确保留两个独立 SQLite DB 文件：
+
+- `LOCATION_DATABASE_URL`
+- `POO_DATABASE_URL`
+
+当前阶段不打算把这两个数据库合并。
+
+其中：
+
+- `location` 模块已经实际接到 `LOCATION_DATABASE_URL`
+- `poo` 目前只保留 `POO_DATABASE_URL` 配置占位，等待模块迁入
 
 ## 当前阶段未做内容
 
 - 未迁移 TickTick 业务逻辑
 - 未迁移 Home Assistant 业务逻辑
 - 未迁移 poo records
-- 未迁移 location / life trajectory
 - 未实现真实 OAuth 流程
 - 未做数据迁移
 
+## Location recorder 说明
+
+当前 Python 项目已经接入 `POST /location/record`，并对齐 legacy SQLite schema：
+
+```sql
+CREATE TABLE location (
+  person TEXT NOT NULL,
+  datetime TEXT NOT NULL,
+  latitude REAL NOT NULL,
+  longitude REAL NOT NULL,
+  altitude REAL,
+  PRIMARY KEY (person, datetime)
+);
+```
+
+当前已经补上最小 Alembic baseline / 接管策略：
+
+- `location` 当前 schema 被视为 Alembic baseline
+- 新数据库通过 `alembic upgrade head` 初始化
+- 已有 legacy SQLite 数据库通过 `alembic stamp` 接管
+- `PRAGMA user_version = 2` 仅保留为历史事实，不再作为新的主 migration 机制
+
+详见：
+
+- [location-recorder.md](location-recorder.md)
+
 ## 后续建议顺序
 
 建议继续沿用既有迁移文档中的顺序：
@@ -37,4 +77,3 @@
 - 不要把旧 Python 版本当作设计基线
 - 不要重新引入 Notion 作为 Python 主系统能力
 - 在迁业务模块时，优先补 contract tests
-