# 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 就继续保留兼容层