home-automation/docs/homeassistant-inbound.md

Home Assistant Inbound Gateway

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

这里的 inbound 指：

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

当前已恢复的入口是：

• POST /homeassistant/publish

Request Envelope

当前沿用 legacy Go 的 envelope 形状：

{
  "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 的响应体保持简洁，不暴露过多内部细节；更详细原因只写日志。