135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
# Migration Notes
|
||
|
||
本文档记录 Python skeleton 阶段的迁移说明，帮助后续继续推进时快速恢复上下文。
|
||
|
||
## 当前阶段完成内容
|
||
|
||
- 建立 FastAPI 应用骨架
|
||
- 建立环境变量配置体系
|
||
- 接入 SQLAlchemy 与 Alembic
|
||
- 建立 Jinja2 模板基础
|
||
- 建立 pytest 基础设施
|
||
- 建立 Docker / Compose 基础骨架
|
||
- 建立 OpenAPI 导出脚本
|
||
- 迁入 `location recorder` 第一版
|
||
- 迁入 `poo recorder` 第一版
|
||
|
||
## 数据库配置现状
|
||
|
||
当前系统在配置层上已明确保留两个独立 SQLite DB 文件：
|
||
|
||
- `LOCATION_DATABASE_URL`
|
||
- `POO_DATABASE_URL`
|
||
|
||
当前阶段不打算把这两个数据库合并。
|
||
|
||
其中：
|
||
|
||
- `location` 模块已经实际接到 `LOCATION_DATABASE_URL`
|
||
- `poo` 模块已经实际接到 `POO_DATABASE_URL`
|
||
|
||
## 当前阶段未做内容
|
||
|
||
- 未迁移 TickTick 业务逻辑
|
||
- 未迁移 Home Assistant inbound / outbound 之外的其他业务逻辑
|
||
- 未实现真实 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)
|
||
|
||
当前还额外提供了一个最小 runbook / script 组合，用于保守接管 legacy location DB：
|
||
|
||
- 先严格校验 schema
|
||
- 再严格校验 `PRAGMA user_version = 2`
|
||
- 只有全部匹配才执行 Alembic `stamp`
|
||
- 不匹配则直接失败，不自动修复
|
||
|
||
同时，应用启动阶段现在也会对 location DB 做保守的只读校验：
|
||
|
||
- DB 文件不存在时拒绝启动
|
||
- DB 尚未被 Alembic 接管时拒绝启动
|
||
- DB revision 与当前应用预期不一致时拒绝启动
|
||
|
||
## Poo recorder 说明
|
||
|
||
当前 Python 项目已经接入：
|
||
|
||
- `POST /poo/record`
|
||
- `GET /poo/latest`
|
||
|
||
并对齐当前真实 baseline schema：
|
||
|
||
```sql
|
||
CREATE TABLE poo_records (
|
||
timestamp TEXT NOT NULL,
|
||
status TEXT NOT NULL,
|
||
latitude REAL NOT NULL,
|
||
longitude REAL NOT NULL,
|
||
PRIMARY KEY (timestamp)
|
||
);
|
||
```
|
||
|
||
历史上 legacy Go 实现使用：
|
||
|
||
```sql
|
||
PRAGMA user_version = 1;
|
||
```
|
||
|
||
当前已经补上与 location 一致风格的 Alembic baseline / 接管策略：
|
||
|
||
- `poo_records` 当前 schema 被视为 Alembic baseline
|
||
- 新数据库通过 `alembic_poo upgrade head` 初始化
|
||
- 已有 legacy SQLite 数据库通过 `alembic stamp` 接管
|
||
- `PRAGMA user_version = 1` 仅保留为历史事实，不再作为新的主 migration 机制
|
||
|
||
同时这一轮明确移除了 Notion：
|
||
|
||
- 不迁 Notion sync
|
||
- 不迁 Notion adapter
|
||
- `POST /poo/record` 不再依赖 `tableId` 才能写入
|
||
|
||
详见：
|
||
|
||
- [poo-recorder.md](poo-recorder.md)
|
||
|
||
## 后续建议顺序
|
||
|
||
建议继续沿用既有迁移文档中的顺序：
|
||
|
||
1. 先迁 `location recorder`
|
||
2. 再迁 Home Assistant 出站适配层
|
||
3. 再迁 Home Assistant 命令网关
|
||
4. 再迁 `poo recorder`
|
||
5. 最后迁 TickTick adapter
|
||
|
||
## 开发约束提醒
|
||
|
||
- 保持对当前 Go 外部行为的兼容意识
|
||
- 不要把旧 Python 版本当作设计基线
|
||
- 不要重新引入 Notion 作为 Python 主系统能力
|
||
- 在迁业务模块时，优先补 contract tests
|