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

Energy、Source 与热力实体

Expose 框架还可以把已勾选的 Energy 实体通过 MQTT Home Assistant Discovery 发布；开关位于应用 Config 页的 HA Expose 面板，默认均为关闭。M8 增加了 source online、按 Meter UUID 锚定的累计量/today，以及 heating、hot-water-heating、water、water-tax、fixed、all-in total/today 等 thermal 实体。

• source 和 Meter identity 不依赖可变 label；换表会产生新 Meter UUID identity。
• thermal 组合成本 identity 由当前 heating/hot_water Meter UUID 的有序组合锚定，任一换表都会产生新 identity，避免不同累计域拼接。Thermal Hot Water Total/Today 精确为 hot_water_heating + hot_water，不包含 hot_water_tax。
• 每个 HA device 只发布一个完整、home-automation: namespaced identifier；内部 topic/unique-id seed 与该 identifier 分离。所有 discovery node/object segment 都会转为 HA 允许的 [A-Za-z0-9_-]+ 字符集。
• v1.6.1 的 dot-containing thermal retained topics 会在启动、UI 尚未能修改 toggle 前，按当时实际重叠的 Meter epoch、enabled toggle 和 runtime discovery prefix 冻结为精确清单；每个成功 topic 都会持久记账，失败/未尝试项才会重试。冻结清单完成后跨重启不再枚举或发布旧 topic；fresh install 的空清单也会立即完成。没有 wildcard，也不会清理任何应用数据。旧 device 合并修复则以已配置的 Home Assistant WebSocket entity/device registry 实际观察 unload、重建和正确 device identifier；HA 不可达时普通 discovery 继续发布，repair 保持 pending。
• availability、unit、device/state class 与 today reset 由 provider 声明；operator 应在 HA 中核对，而不应假设同名实体可跨换表连续。
• 关闭 toggle 后 retained discovery 会被清理；关闭暴露不删除 source、Meter、合同、读数或成本历史。

WarmteLink 的 P1 质量会原样保留为 unverifiable（若适用），不因发布到 HA 而提升为 valid。不要将 raw telegram、equipment id、串口路径、合同金额或 API secret 作为 HA entity/state/attribute 发布。