8.6 KiB
8.6 KiB
迁移风险清单
本文档列出将当前 Go 后端重构为 Python 时的主要风险点。这里的风险判断，默认都是以“当前 Go 行为需要尽量兼容”为前提。
最高风险区域
1. POST /homeassistant/publish 存在隐式行为契约
风险：
- 当前 Home Assistant 网关使用
target、action、content这种 envelope content不是标准嵌套 JSON，而是字符串化 payload- 有些 payload 明显依赖单引号 pseudo-JSON，再在代码中做归一化
为什么重要：
- 如果 Python 版过早改成“严格、干净、标准化的嵌套 JSON”，现有 Home Assistant automations 可能直接失效
当前证据：
src/components/homeassistant/homeassistant.go- 测试见
src/components/homeassistant/homeassistant_test.go
缓解建议：
- 在重构前先收集真实线上 payload 样例
- 第一阶段保留兼容性解析
- 为所有当前支持的
target/action增加回归测试
2. TickTick OAuth 与 token 持久化流程
风险：
- OAuth
state当前只保存在进程内 - token 获取后会直接写回 YAML 配置文件
为什么重要：
- Python 重构很容易在不自觉的情况下改变操作流程
- token 持久化语义一变，可能会带来难排查的鉴权失败
当前证据：
- callback 与配置回写逻辑见
src/util/ticktickutil/ticktickutil.go - 授权 URL 初始化见
src/util/ticktickutil/ticktickutil.go
缓解建议：
- 在编码前先确定 token storage 方案
- 保持 callback 契约稳定
- 在 staging 环境用真实 TickTick app 做端到端验证
3. Poo recorder 的副作用比 API 表面看起来更复杂
风险：
POST /poo/record不只是写一条 DB- 它还会镜像到 Notion、发布 Home Assistant sensor、并且可能触发 Home Assistant webhook
为什么重要：
- 即使 Python 版 API 看起来兼容，如果漏掉这些副作用，也会导致真实自动化行为偏差
当前证据：
src/components/pooRecorder/pooRecorder.gosrc/components/pooRecorder/pooRecorder.gosrc/components/pooRecorder/pooRecorder.go
缓解建议：
- 把 endpoint 契约和 side-effect 契约分开写清楚
- 在 Python 中通过显式 service / adapter 接口承接这些行为
- 用 mock Home Assistant / TickTick / Notion 的方式做测试
4. 移除 Notion 会改变当前运行预期
风险：
- Notion 虽然已经被识别为“不计划继续保留”，但它现在并不是边缘代码
- 它当前参与启动、请求处理以及每日同步
为什么重要：
- 去掉 Notion 会实质改变数据流
- 也可能影响历史镜像、人工运维方式以及启动要求
当前证据：
- 启动时强依赖
notion.token，见src/cmd/serve.go - 每日同步逻辑见
src/components/pooRecorder/pooRecorder.go - helper CLI 见
src/helper/poo_recorder_helper/cmd/reverse.go
缓解建议：
- 在文档里显式说明 Notion 将被下线 / 不迁移
- 先决定是否需要一次性历史导出或回填
- 确保移除 Notion 后，
pooRecorder.tableId和notion.token不再阻塞服务启动
中等风险区域
5. SQLite 兼容性与时间戳格式
风险：
- 当前代码把时间戳以文本形式存储
location和poo两个模块使用的时间格式并不相同
为什么重要：
- Python 重构若擅自统一时间格式，可能会破坏旧 DB 的可兼容读取
当前证据：
- poo 时间戳写入逻辑见
src/components/pooRecorder/pooRecorder.go - location 时间戳写入逻辑见
src/components/locationRecorder/locationRecorder.go
缓解建议：
- 先决定 Python 第一阶段是否直接复用现有 DB 文件
- 如果要复用，就要保留当前时间戳序列化行为
- 为数据层建立回归样例
6. 输入校验行为可能与 FastAPI 默认习惯冲突
风险：
- FastAPI / Pydantic 通常更倾向严格校验
- 当前 Go 代码的校验行为并不一致：
- 有些接口拒绝 unknown fields
location数值解析错误会被静默忽略- 很多成功响应是空响应体
为什么重要：
- 更“正确”的校验，也可能是破坏兼容性的改动
当前证据：
- 多个 handler 都开启了严格字段检查
location的静默 float parsing 见src/components/locationRecorder/locationRecorder.go
缓解建议：
- 先明确哪些怪异行为是必须兼容的，哪些可以修正
- 第一阶段如果要保持兼容，可以在 Python 里用自定义校验逻辑模拟当前行为
7. 定时任务行为漂移
风险：
- 当前应用内嵌了一个每天
0 5 * * *执行的 Notion 同步任务
为什么重要：
- 如果 Python 版仍保留类似行为，时区、执行时机、幂等性处理差异都可能导致重复或漏同步
当前证据：
缓解建议：
- 如果 Notion 被移除，就应有意识地同步移除 scheduler 相关逻辑，并写清楚原因
- 如果在过渡期暂时保留，就要明确 timezone 与幂等语义
8. self-HTTP 编排改成 direct service calls 的差异
风险：
- 当前 Home Assistant 网关通过调用
localhost上的本地接口来驱动其它模块
为什么重要：
- 改成直接函数 / service 调用本身是合理的，但可能改变 timeout、错误传播和日志行为
当前证据：
缓解建议：
- 对外 HTTP 行为保持不变
- 但在内部重写后，补足状态码和失败语义测试
风险较低但仍重要的区域
9. 部署模型变化
风险：
- 当前部署方式是 supervisor-based
- 未来目标是容器化
为什么重要：
- 启动文件路径、配置文件写入位置、token persistence 方式，在容器环境下都可能出问题
当前证据：
- 安装脚本见
helper/install.sh
缓解建议：
- 把运行时状态从镜像内容中解耦
- 预先定义 DB/config 是否需要挂载 volume
- 在 cutover 前先写清楚 container env vars 与文件挂载约定
10. 现有测试过少
风险：
- 当前大多数模块没有自动化测试
为什么重要：
- 没有安全网时，重构很容易改坏行为而不自知
当前证据：
缓解建议：
- 把 contract test 建设视作迁移工作的一部分，而不是迁移后的补票
- 每迁一个模块，就同步补该模块的测试
总结
这次重构最大的风险，不是“Go 改 Python”本身，而是几个隐藏得很深的行为契约：
- Home Assistant 命令 payload 的真实格式
- TickTick 的 OAuth / token 生命周期
- poo recorder 的一组副作用行为
- 当前仍活跃、但计划下线的 Notion 耦合
只要先把这些契约写清楚、测清楚，再开始 Python 实现，整个重构路线就会可控很多。