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

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

> **状态：Planning 占位；尚未拆解任务卡，尚未锁定架构。** Pre-M8 人工 bring-up 已确认
> 两个累计量，但 M8 仍须等待 [Pre-M8 真机概念验证](./pre-m8-warmtelink-p1-poc.md)
> 的正式 probe、测试和长时间复验完成后再进入正式设计。

## 1. 候选目标

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

- 区域供暖累计热量（GJ）。
- 生活热水累计量（真机已确认为 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`。
- 真机实测一个 WarmteLink serial source 同时输出两个累计 channel：channel 1 为生活热水
  `m³`，channel 2 为区域供暖 `GJ`；两者均已与物理表对照一致。
- 当前 P1 telegram 约每 10 秒一帧，没有瞬时流量、热功率、供水温度或回水温度字段。
- 当前线材/设备组合以 `115200 7N1` 才能稳定解析正文；header/CRC 仍不可验证，正式 ingestion
  必须显式处理该数据质量状态。

## 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 通过并留下脱敏字段清单。
- 用正式 probe 复验两个累计量及其单位、equipment id/channel 和更新时间。
- 确认原始 telegram 的长期稳定性、parser 适配方式和异常 CRC 的接纳策略。
- 重新走查现有 DSMR ingest、Meter epoch、Modbus device、expose/HA 和 Energy 前端边界。
- 与用户讨论并锁定 Meter ↔ source 的配置体验后，再决定 migration/API/UI 方案。

## 5. 当前明确不做

- 本占位不创建 implementation task，不授权 schema/API/frontend 变更。
- 不承诺当前 P1 未提供的瞬时流量、热功率或温度，也不承诺可拆分“空间供暖 GJ”和
  “生活热水 GJ”。
- 不提前把 WarmteLink 塞进 `modbus_device` 或现有 `dsmr_reading`。
- 不在缺少真机证据时设计通用 telemetry framework。