# Home Assistant Inbound Gateway

本文档说明当前 Python 项目中已经迁入的 Home Assistant inbound gateway 第一版。

这里的 inbound 指：

- Home Assistant 主动调用当前 app 的入口

当前已恢复的入口是：

- `POST /homeassistant/publish`

## Request Envelope

当前沿用 legacy Go 的 envelope 形状：

```json
{
  "target": "location_recorder",
  "action": "record",
  "content": "{'person': 'alice', 'latitude': '1.23', 'longitude': '4.56'}"
}
```

说明：

- `target`、`action`、`content` 均为必填
- unknown field 会被拒绝
- `content` 当前仍兼容 legacy 常见的单引号 JSON 字符串风格

## 当前已支持的 Target / Action

当前已接回的路径：

- `location_recorder / record`
- `ticktick / create_action_task`

其中：

- `location_recorder / record` 会把 `content` 解析为 location recorder 请求，并直接走当前 Python 项目里的 location 写入逻辑
- `ticktick / create_action_task` 会沿用 legacy 行为，把 `content` 解析为：
  - `action: string`
  - `due_hour: int`
  - 可选 `title` 字段会被忽略
- TickTick task title 仍使用 `action`
- due date 仍按 legacy 语义计算：先取 `now + due_hour`，再落到该日期的“次日零点”，最后转成 UTC 后写给 TickTick
- 具体 project 仍由 `HOME_ASSISTANT_ACTION_TASK_PROJECT_ID` 提供

## 当前尚未接回

以下 legacy 路径在当前阶段还没有迁入：

- `poo_recorder / get_latest`
- 其他未定义 target/action

这些请求当前会返回：

- `500 internal server error`

## 错误处理

当前策略保持简洁：

- envelope 非法、缺字段、unknown field、`content` 非法：返回 `400 bad request`
- target/action 当前未迁入：返回 `500 internal server error`

对 caller 的响应体保持简洁，不暴露过多内部细节；更详细原因只写日志。