home-automation/docs/design/m8-warmtelink-energy.md

M8 — WarmteLink P1 与多数据源 Meter（Planning 占位）

状态：Planning 占位；尚未拆解任务卡，尚未锁定架构。 M8 必须等待 Pre-M8 真机概念验证完成后再进入正式设计。

1. 候选目标

把 Vattenfall WarmteLink 的 P1 数据接入现有 Energy 模块，至少支持：

• 区域供暖累计热量（GJ）。
• 真机 telegram 确认存在时的生活热水累计量（预计为 m³，最终以实测为准）。
• 历史读数、当前状态以及按需暴露给 Home Assistant。
• 与现有 Meter epoch/换表归档语义兼容。

2. 当前已知边界

• 现有 DSMR 模块独立订阅 dsmr/json，把 DSMR Reader 已解析的 JSON 降采样写入 dsmr_reading。
• 现有 Meter 表示物理计量表的安装 epoch，本身不订阅 MQTT，也不负责解析 telegram。
• 当前 electricity Meter 与 dsmr_reading 之间没有显式 source FK/binding；电费计算通过代码约定直接查询 DSMR 电力寄存器。
• Meter.commodity 后端已为 heating 等品类预留，但“增加 commodity”本身不会自动获得相应数据源或解析能力。
• 当前 Devices UI/模型是 Modbus 专用，不能直接假设 WarmteLink 应复用 modbus_device。

3. 下一轮 Planning 必须讨论的问题

以下问题当前全部保持开放，不在本占位文档中拍板：

1. Meter 是否显式绑定可配置的数据源，以及绑定的生命周期和基数。
2. 如何表示现有 DSMR MQTT source 与新的 WarmteLink P1 serial source。
3. “Device”与“Data Source”是否为同一概念；前端 Devices 是否需要改名或分组。
4. 一个 P1 source 暴露多个 measurement channel 时，如何映射到一个或多个 Meter。
5. 直接 P1 读数是否使用独立存储，还是将现有 dsmr_reading 泛化；如何保证多 source 去重和隔离。
6. heating GJ 与可选 hot-water m³ 的 commodity、单位、累计/换表语义。
7. M8 是否只做采集与展示；区域供暖合同、价格和成本计算是否留到后续里程碑。
8. 串口 worker 的重连、停止、配置热更新、Docker device mapping 与权限边界。

4. Planning 入口条件

正式编写 M8 目标架构、数据模型和原子任务卡前，至少需要：

• Pre-M8 通过并留下脱敏字段清单。
• 确认实际存在几个累计量及其单位、equipment id/channel 和更新时间。
• 确认原始 telegram 的稳定性与 parser 适配方式。
• 重新走查现有 DSMR ingest、Meter epoch、Modbus device、expose/HA 和 Energy 前端边界。
• 与用户讨论并锁定 Meter ↔ source 的配置体验后，再决定 migration/API/UI 方案。

5. 当前明确不做

• 本占位不创建 implementation task，不授权 schema/API/frontend 变更。
• 不假设生活热水 m³ 一定可读，也不承诺可拆分“空间供暖 GJ”和“生活热水 GJ”。
• 不提前把 WarmteLink 塞进 modbus_device 或现有 dsmr_reading。
• 不在缺少真机证据时设计通用 telemetry framework。