home-automation/docs/migration-notes.md

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：

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 与当前应用预期不一致时拒绝启动

Poo recorder 说明

当前 Python 项目已经接入：

• POST /poo/record
• GET /poo/latest

并对齐当前真实 baseline schema：

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 实现使用：

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

后续建议顺序

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

1. 先迁 location recorder
2. 再迁 Home Assistant 出站适配层
3. 再迁 Home Assistant 命令网关
4. 再迁 poo recorder
5. 最后迁 TickTick adapter

开发约束提醒

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