315 lines
8.7 KiB
Markdown
315 lines
8.7 KiB
Markdown
# Python 重构方案
|
||
|
||
本文档基于当前 Go 实现，给出迁移到 Python + FastAPI 的设计输入与建议顺序。本文档只讨论迁移方案，不代表已经开始实现。
|
||
|
||
## 重构原则
|
||
|
||
- 以当前 Go 实现为唯一事实来源
|
||
- 先保持对外行为兼容，再考虑内部清理和优化
|
||
- 明确区分“行为兼容”和“内部实现升级”
|
||
- 默认不把 Notion 纳入新的 Python 主版本目标，除非后续重新决策
|
||
- 尽量按模块迁移，并在模块之间建立清晰契约
|
||
|
||
## 目标形态
|
||
|
||
建议的 Python 目标架构：
|
||
|
||
- 用 FastAPI 提供 HTTP 路由，并自然生成 OpenAPI
|
||
- 业务逻辑按模块拆分到 service layer
|
||
- 外部系统对接放到 adapter layer
|
||
- SQLite 访问放到 repository layer
|
||
- 配置采用显式 settings model
|
||
- scheduler 是否内嵌在应用进程内，需要在启动语义明确后再决定
|
||
- 仅保留极轻量的服务端页面，用于 OAuth 跳转或简单配置
|
||
|
||
## 建议的 Python 模块边界
|
||
|
||
### 应用外壳层
|
||
|
||
- 职责：
|
||
- 读取 settings
|
||
- 依赖注入与对象装配
|
||
- 路由注册
|
||
- lifespan hooks
|
||
- scheduler 启停
|
||
- 在 FastAPI 中可对应：
|
||
- `main.py` 或 app factory
|
||
- settings 类
|
||
|
||
### Poo 领域模块
|
||
|
||
- 职责：
|
||
- 校验 poo record 输入
|
||
- 持久化 poo record
|
||
- 查询 latest poo
|
||
- 通过接口触发外部副作用
|
||
- 建议把副作用依赖抽象为端口：
|
||
- `PooRepository`
|
||
- `HomeAssistantPublisher`
|
||
- `HomeAssistantWebhookClient`
|
||
- 如有需要，可保留临时 `LegacyPooMirror` 作为 Notion 过渡适配器
|
||
|
||
### Location 领域模块
|
||
|
||
- 职责：
|
||
- 校验并持久化位置点
|
||
- 可保持简洁：
|
||
- `LocationRepository`
|
||
- `LocationService`
|
||
|
||
### Home Assistant 命令网关
|
||
|
||
- 职责：
|
||
- 暴露 `/homeassistant/publish`
|
||
- 解析 `target/action/content`
|
||
- 将命令分发到内部服务
|
||
- 兼容性注意：
|
||
- 第一阶段应保留当前 `content` 的处理习惯，包括对字符串 payload 的兼容解析
|
||
|
||
### TickTick 集成模块
|
||
|
||
- 职责：
|
||
- OAuth start / callback
|
||
- token 存储
|
||
- task 查询
|
||
- 去重
|
||
- task 创建
|
||
- 建议：
|
||
- 把 token persistence 抽象成独立能力，而不是把“改写配置文件”直接塞进业务逻辑
|
||
|
||
### Home Assistant 出站适配层
|
||
|
||
- 职责：
|
||
- 发布 sensor state
|
||
- 触发 webhook
|
||
- 该层小而独立，适合较早迁移
|
||
|
||
### Legacy Notion 适配层
|
||
|
||
- 职责：
|
||
- 只在分析或过渡阶段表示当前行为
|
||
- 默认建议：
|
||
- 不放入 Python 第一版正式目标
|
||
- 如 cutover 期间确有需要，可以 feature flag 或独立迁移工具的方式暂存
|
||
|
||
## 实现前需要冻结的兼容契约
|
||
|
||
在正式编码前，建议先把以下当前行为写成明确契约：
|
||
|
||
### API 契约
|
||
|
||
- `POST /poo/record` 的请求字段与当前“成功时空响应体”的行为
|
||
- `POST /location/record` 的请求字段与数值解析行为
|
||
- `POST /homeassistant/publish` 的 envelope 格式与支持的 `target/action`
|
||
- `GET /ticktick/auth/code` 的成功 / 失败语义
|
||
|
||
### 副作用契约
|
||
|
||
- `POST /poo/record` 在什么时机会发布 Home Assistant sensor
|
||
- `POST /poo/record` 在什么条件下会触发 Home Assistant webhook
|
||
- Home Assistant 消息如何映射为 TickTick task title 与 due date
|
||
- Home Assistant sensor payload 的结构
|
||
|
||
### 持久化契约
|
||
|
||
- 当前 SQLite 表名与主键
|
||
- 当前磁盘上的时间戳格式
|
||
- Python 第一阶段是否直接复用现有 DB 文件，还是做显式迁移
|
||
|
||
## 建议的迁移决策
|
||
|
||
### 决策 1：第一阶段保持对外 API 形状不变
|
||
|
||
原因：
|
||
|
||
- 当前 API 面很小
|
||
- 保持兼容能显著降低切换风险
|
||
- 即使保持兼容，FastAPI 仍然可以生成 OpenAPI 文档
|
||
|
||
### 决策 2：把内部 self-HTTP 改成直接服务调用
|
||
|
||
原因：
|
||
|
||
- 当前 Go 代码中的 `localhost` 自调用，本质上是内部编排手段
|
||
- 这不是一个必须暴露给外部的契约
|
||
- Python 版改为直接函数 / service 调用，可以提升清晰度和可测试性
|
||
|
||
### 决策 3：先继续使用 SQLite
|
||
|
||
原因：
|
||
|
||
- 当前系统已经使用 SQLite
|
||
- 数据模型规模很小
|
||
- PostgreSQL 更适合作为 parity 之后的下一阶段演进
|
||
|
||
### 决策 4：默认不迁 Notion，但要明确记录影响
|
||
|
||
原因：
|
||
|
||
- 你已经明确表示 Notion 很可能不继续保留
|
||
- 当前 Notion 不是“代码里有但没在用”，而是真正参与运行逻辑
|
||
- 所以不能静默删除，而要在方案中写清楚删掉后有什么影响
|
||
|
||
### 决策 5：把 token / auth persistence 做成显式设计
|
||
|
||
原因：
|
||
|
||
- 当前 TickTick token 处理虽然可用，但运维上比较脆弱
|
||
- Python 重构是一个把这件事规范化的机会
|
||
|
||
## 建议迁移顺序
|
||
|
||
### Phase 0：盘点与契约确认
|
||
|
||
- 完成当前系统 inventory
|
||
- 确认哪些当前行为是“必须兼容的契约”，哪些只是历史偶然实现
|
||
- 明确把 Notion 标为 non-migration scope，除非后续重新决定
|
||
|
||
### Phase 1：Python 骨架与通用基础设施
|
||
|
||
- 建立 FastAPI app shell
|
||
- 定义 settings / config model
|
||
- 定义日志方案
|
||
- 定义 SQLite 访问方式
|
||
- 定义测试框架与 fixture 策略
|
||
- 定义 OpenAPI 生成与导出方式
|
||
|
||
这一阶段不需要大量迁移业务逻辑，只要搭好后续模块可持续迁入的基础即可。
|
||
|
||
### Phase 2：先迁最独立、最稳定的业务模块
|
||
|
||
推荐优先迁移：`location recorder`
|
||
|
||
原因：
|
||
|
||
- 独立 SQLite 表
|
||
- 没有复杂外部副作用
|
||
- 没有 OAuth
|
||
- 没有 scheduler
|
||
|
||
这一阶段的交付物可以包括：
|
||
|
||
- `POST /location/record`
|
||
- 与现有 SQLite 兼容的写入逻辑
|
||
- 校验与 repository 的单元测试
|
||
- 基于临时 SQLite 的 integration test
|
||
|
||
### Phase 3：迁移 Home Assistant 出站适配层
|
||
|
||
原因：
|
||
|
||
- 功能面小
|
||
- 能为后面的 poo 迁移做铺垫
|
||
|
||
这一阶段的交付物可以包括：
|
||
|
||
- sensor publish client
|
||
- webhook trigger client
|
||
- 针对请求格式与错误处理的 mock tests
|
||
|
||
### Phase 4：迁移 TickTick adapter
|
||
|
||
原因：
|
||
|
||
- 相对自洽
|
||
- 在完成 Home Assistant 命令网关前就需要它
|
||
|
||
这一阶段的交付物可以包括：
|
||
|
||
- OAuth callback endpoint
|
||
- token persistence abstraction
|
||
- task 创建与去重行为
|
||
- 基于 mock HTTP 的集成式测试
|
||
|
||
### Phase 5：迁移 Home Assistant 命令网关
|
||
|
||
原因：
|
||
|
||
- 这是外部 automations 的核心编排入口
|
||
- 在 location 与 TickTick adapter 准备好后，网关迁移会顺很多
|
||
|
||
这一阶段的交付物可以包括：
|
||
|
||
- `/homeassistant/publish`
|
||
- 兼容当前 `target/action` 的分发逻辑
|
||
- 用进程内 service 调用替代 self-HTTP
|
||
- 把现有 Go 测试场景迁成 Python contract tests
|
||
|
||
### Phase 6：迁移 poo recorder 核心，但默认不带 Notion
|
||
|
||
原因：
|
||
|
||
- 这是最复杂的模块
|
||
- 它既有本地 DB，又有 Home Assistant 副作用，当前还耦合 Notion
|
||
|
||
建议拆成两个子阶段：
|
||
|
||
- phase 6a：
|
||
- 本地 poo DB
|
||
- latest poo 查询
|
||
- sensor publish
|
||
- 可选 webhook trigger
|
||
- `/poo/record`
|
||
- `/poo/latest`
|
||
|
||
- phase 6b：
|
||
- 如果 cutover 期间必须保留旧逻辑，再做一个临时 legacy Notion 兼容层
|
||
|
||
### Phase 7：运维加固与切换验证
|
||
|
||
- 做 Go / Python 路由级契约比对
|
||
- 用现有 SQLite 文件或其副本做兼容验证
|
||
- 在 staging 环境手动验证 TickTick OAuth
|
||
- 用真实 Home Assistant automation payload 做验证
|
||
- 导出 OpenAPI YAML
|
||
- 再补容器化与部署方案
|
||
|
||
## 哪些模块适合先迁，哪些适合后迁
|
||
|
||
### 适合优先迁移
|
||
|
||
- location recorder
|
||
- Home Assistant 出站 client
|
||
- TickTick adapter
|
||
|
||
### 更适合后迁
|
||
|
||
- Home Assistant 命令网关
|
||
- poo recorder 核心
|
||
|
||
### 现状存在，但建议不迁
|
||
|
||
- Notion sync adapter
|
||
- `poo_recorder_helper` 的 Notion 表反转 CLI
|
||
- `location_recorder` helper CLI 脚手架
|
||
|
||
## 建议的验证策略
|
||
|
||
### Contract tests
|
||
|
||
- 基于当前 Go 行为建立 request / response fixtures
|
||
- 先把现有 `homeassistant` 测试案例迁成 Python
|
||
- 补上 `poo` 与 `location` API 的契约测试
|
||
|
||
### Integration tests
|
||
|
||
- 每个模块使用临时 SQLite DB
|
||
- Home Assistant 与 TickTick 出站流量通过 mock HTTP 替代
|
||
- 若仍保留 scheduler，则为其补定时行为测试
|
||
|
||
### 手工 staging 验证
|
||
|
||
- TickTick OAuth callback
|
||
- Home Assistant sensor 更新
|
||
- Home Assistant webhook 触发
|
||
- 当前真实自动化 payload 样例
|
||
|
||
## 开始实现前仍需明确的问题
|
||
|
||
- Python 第一阶段是否还要保留“缺少 `notion.token` 就启动失败”的行为，还是直接把 Notion 变成可关闭能力？
|
||
- `POST /location/record` 是否要继续保留“非法数字静默变成 0”的兼容行为？
|
||
- TickTick token 在第一阶段是否继续写回 YAML，还是立即切到独立 token store？
|
||
- 当前 Home Assistant automations 是否真实依赖 `content` 中的单引号 pseudo-JSON？
|
||
|
||
这些问题不影响当前 inventory，但会影响第一阶段“兼容到什么程度”的具体定义。
|