59 lines
1.4 KiB
Markdown
59 lines
1.4 KiB
Markdown
|
# 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`
|
||
|
|
|
||
|
|
它会把 `content` 解析为 location recorder 请求，并直接走当前 Python 项目里的 location 写入逻辑。
|
||
|
|
|
||
|
|
## 当前尚未接回
|
||
|
|
|
||
|
|
以下 legacy 路径在当前阶段还没有迁入：
|
||
|
|
|
||
|
|
- `poo_recorder / get_latest`
|
||
|
|
- `ticktick / create_action_task`
|
||
|
|
- 其他未定义 target/action
|
||
|
|
|
||
|
|
这些请求当前会返回：
|
||
|
|
|
||
|
|
- `500 internal server error`
|
||
|
|
|
||
|
|
## 错误处理
|
||
|
|
|
||
|
|
当前策略保持简洁：
|
||
|
|
|
||
|
|
- envelope 非法、缺字段、unknown field、`content` 非法：返回 `400 bad request`
|
||
|
|
- target/action 当前未迁入：返回 `500 internal server error`
|
||
|
|
|
||
|
|
对 caller 的响应体保持简洁，不暴露过多内部细节；更详细原因只写日志。
|