# 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`

这样可以验证接管路径，同时不污染真实样本库。