141 lines
3.0 KiB
Markdown
141 lines
3.0 KiB
Markdown
# Poo Recorder
|
||
|
||
本文档说明 `poo recorder` 在 Python 项目中的当前行为边界，以及 poo SQLite 的 Alembic 接管策略。
|
||
|
||
## 当前基线
|
||
|
||
当前生产版本中的真实 SQLite 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;
|
||
```
|
||
|
||
当前 Python 迁移以这套 schema 为事实基线，不重新设计表结构。
|
||
|
||
## 当前已迁入的 API
|
||
|
||
当前 Python 项目已经接入：
|
||
|
||
- `POST /poo/record`
|
||
- `GET /poo/latest`
|
||
|
||
### `POST /poo/record`
|
||
|
||
用途：
|
||
|
||
- 记录一条 poo event
|
||
- 最佳努力地刷新 Home Assistant sensor
|
||
- 如果配置了 `POO_WEBHOOK_ID`，最佳努力地触发 Home Assistant webhook
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"status": "done",
|
||
"latitude": "1.23",
|
||
"longitude": "4.56"
|
||
}
|
||
```
|
||
|
||
当前策略：
|
||
|
||
- unknown field：`400 bad request`
|
||
- 数值非法：`400 bad request`
|
||
- 记录成功后，即使 Home Assistant side effect 失败，也不会回滚本地 DB 写入
|
||
|
||
### `GET /poo/latest`
|
||
|
||
用途：
|
||
|
||
- 读取最新一条 poo 记录
|
||
- 将其重新发布到 Home Assistant sensor
|
||
|
||
当前外部行为与 legacy 保持一致：
|
||
|
||
- 成功：空响应体，HTTP 200
|
||
- 如果当前 DB 里还没有任何 poo 记录：仍返回空响应体，HTTP 200，但不会发布 sensor
|
||
- 真正的发布失败：简洁 `internal server error`
|
||
|
||
## Home Assistant side effects
|
||
|
||
当前已复用 Python 项目中已有的 Home Assistant outbound adapter。
|
||
|
||
当前支持：
|
||
|
||
- 发布 / 更新 poo status sensor
|
||
- 可选触发 webhook
|
||
|
||
相关配置：
|
||
|
||
- `HOME_ASSISTANT_BASE_URL`
|
||
- `HOME_ASSISTANT_AUTH_TOKEN`
|
||
- `HOME_ASSISTANT_TIMEOUT_SECONDS`
|
||
- `POO_SENSOR_ENTITY_NAME`
|
||
- `POO_SENSOR_FRIENDLY_NAME`
|
||
- `POO_WEBHOOK_ID`
|
||
|
||
## Alembic 接管策略
|
||
|
||
poo 的接管逻辑刻意保持与 location 一致。
|
||
|
||
当前 baseline revision：
|
||
|
||
- `20260420_01_poo_baseline`
|
||
|
||
当前提供的脚本入口：
|
||
|
||
```bash
|
||
python scripts/poo_db_adopt.py
|
||
```
|
||
|
||
或：
|
||
|
||
```bash
|
||
python -m scripts.poo_db_adopt
|
||
```
|
||
|
||
规则如下：
|
||
|
||
1. 如果本地不存在 poo DB 文件：
|
||
- 视为新库初始化
|
||
- 通过 `alembic_poo upgrade head` 创建新库
|
||
2. 如果本地已经存在 legacy DB：
|
||
- 先检查 `poo_records` 表 schema
|
||
- 再检查 `PRAGMA user_version = 1`
|
||
- 只有完全匹配，才通过 Alembic `stamp` 接管
|
||
3. 如果 schema 或 `user_version` 不匹配：
|
||
- 直接失败
|
||
- 不自动修复
|
||
4. 如果数据库已经存在 `alembic_version`：
|
||
- 只有 revision 与当前 baseline 一致才接受
|
||
- 否则直接失败
|
||
|
||
同时，应用启动时也会对 `POO_DATABASE_URL` 做只读校验：
|
||
|
||
- 文件不存在：拒绝启动
|
||
- DB 尚未被 Alembic 接管：拒绝启动
|
||
- revision 不匹配：拒绝启动
|
||
|
||
## 明确移除 Notion
|
||
|
||
这一轮不会迁入任何 Notion 逻辑。
|
||
|
||
也就是说，当前 Python 版的 poo recorder：
|
||
|
||
- 不保留 Notion adapter
|
||
- 不保留 Notion sync
|
||
- 不保留 `tableId` 依赖
|
||
- 不因为 legacy 中存在 Notion 就继续保留兼容层
|