Add Home Assistant outbound adapter

docs/architecture-overview.md

@@ -36,7 +36,8 @@
 - `services/`
   - 业务服务层
 - `integrations/`
-  - 外部系统适配层占位
+  - 外部系统适配层
+  - 当前已迁入 Home Assistant outbound adapter
 - `templates/`
   - Jinja2 模板
 - `static/`
@@ -76,4 +77,3 @@ Notion 在 Go 版本中仍是现状模块，但在 Python 重构中已经明确
 - 不预留 Notion 相关业务流
 
 如果未来需要回顾其历史作用，应继续参考 Go 版本和现有迁移盘点文档，而不是在 Python 骨架中保留它。
-

docs/homeassistant-outbound.md

@@ -0,0 +1,51 @@
+# Home Assistant Outbound Integration
+
+本文档说明当前 Python 项目中已经迁入的 Home Assistant outbound integration layer。
+
+这里的 outbound 指：
+
+- 由当前 app 主动调用 Home Assistant
+
+当前不包含：
+
+- `/homeassistant/publish`
+- Home Assistant inbound command gateway
+- Home Assistant 驱动当前 app 的入站消息路由
+
+## 当前已支持能力
+
+当前 `app/integrations/homeassistant.py` 提供一个轻量的 `HomeAssistantClient`，已支持：
+
+- 发布 / 更新 sensor state
+  - `POST /api/states/{entity_id}`
+- 触发 Home Assistant webhook
+  - `POST /api/webhook/{webhook_id}`
+
+这两项能力是按 legacy Go 中 `util/homeassistantutil/homeassistantutil.go` 的出站行为迁入的。
+
+## 当前配置
+
+当前 outbound adapter 依赖以下配置：
+
+- `HOME_ASSISTANT_BASE_URL`
+- `HOME_ASSISTANT_AUTH_TOKEN`
+- `HOME_ASSISTANT_TIMEOUT_SECONDS`
+
+如果缺少必要配置，client 会直接抛出配置错误，而不是静默跳过。
+
+## 错误处理策略
+
+当前策略保持保守和简单：
+
+- 配置缺失：抛出 `HomeAssistantConfigError`
+- 参数明显非法：抛出 `ValueError`
+- Home Assistant 返回非 200/201：抛出 `HomeAssistantRequestError`
+- 网络请求失败：抛出 `HomeAssistantRequestError`
+
+当前还没有做：
+
+- 自动重试
+- 熔断
+- 更复杂的 backoff 策略
+
+这一轮重点是先把 app -> Home Assistant 的出站契约和可复用结构迁进来。