home-automation/docs/homeassistant-outbound.md

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 的出站契约和可复用结构迁进来。