Migration Notes

本文档记录 Python skeleton 阶段的迁移说明，帮助后续继续推进时快速恢复上下文。

当前阶段完成内容

建立 FastAPI 应用骨架
建立环境变量配置体系
接入 SQLAlchemy 与 Alembic
建立 Jinja2 模板基础
建立 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
未实现真实 OAuth 流程
未做数据迁移

Location recorder 说明

当前 Python 项目已经接入 POST /location/record，并对齐 legacy SQLite schema：

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

当前还额外提供了一个最小 runbook / script 组合，用于保守接管 legacy location DB：

先严格校验 schema
再严格校验 PRAGMA user_version = 2
只有全部匹配才执行 Alembic stamp
不匹配则直接失败，不自动修复

同时，应用启动阶段现在也会对 location DB 做保守的只读校验：

DB 文件不存在时拒绝启动
DB 尚未被 Alembic 接管时拒绝启动
DB revision 与当前应用预期不一致时拒绝启动

后续建议顺序

建议继续沿用既有迁移文档中的顺序：

先迁 location recorder
再迁 Home Assistant 出站适配层
再迁 TickTick adapter
再迁 Home Assistant 命令网关
最后迁 poo recorder

开发约束提醒

保持对当前 Go 外部行为的兼容意识
不要把旧 Python 版本当作设计基线
不要重新引入 Notion 作为 Python 主系统能力
在迁业务模块时，优先补 contract tests

2.6 KiB Raw Blame History Unescape Escape