Add Home Assistant inbound gateway

docs/architecture-overview.md

@@ -29,6 +29,7 @@
   - 通用依赖注入
 - `api/`
   - HTTP routes
+  - 当前已迁入 `POST /homeassistant/publish` 第一版入口
 - `models/`
   - SQLAlchemy models
 - `schemas/`

docs/homeassistant-inbound.md

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