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

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

> **状态：Planning 已解锁；尚未拆解任务卡，尚未锁定架构。** [Pre-M8 真机概念验证](./pre-m8-warmtelink-p1-poc.md)
> 已完成正式 probe、测试和 10 分钟复验；这只满足进入
> Planning 的证据门，不授权 schema、API、worker 或前端实现。

## 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`。
- 正式 CLI 复验中，一个 WarmteLink serial source 在 60/60 帧均输出两个累计 channel：channel 1
  为生活热水 `m³`（device type `006`、`5.900 m³`），channel 2 为区域供暖 `GJ`（device type
  `012`、基线 `0.017 GJ`）；同日与物理表复核一致。最终人工走查开启供暖后，channel 2 又从
  `0.017 GJ` 增至 `0.018 GJ`，物理热量表同步显示 `0.018 GJ`。
- 设备 timestamp 严格每 10 秒递进；frame 平均 256 bytes、范围 237–275，不能假定固定帧长。
  当前 P1 telegram 没有瞬时流量、热功率、供水温度或回水温度字段。
- 当前线材/设备组合以 `115200 7N1` 才能稳定解析正文。60/60 frame 缺少标准 `/`，故均为
  `unverifiable`；即使部分 footer 恰为四位十六进制也不能验证 CRC。正式 ingestion 必须显式
  处理该数据质量状态，不能将数值与表盘相符视为 CRC valid。

## 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 Planning 的证据门已满足：

- [x] Pre-M8 通过并留下脱敏字段清单。
- [x] 正式 probe 复验两个累计量、单位、channel、device type 与更新时间；equipment identifier
  保持脱敏。
- [x] 记录 parser 适配结论和异常 framing/CRC 状态；10 分钟样本的稳定累计值不构成消费更新、
  reset/wrap 或长期稳定性的证明。
- [x] 最终人工走查确认供暖消费时累计量按 `0.001 GJ` 更新并与物理表一致；精确更新延迟、
  reset/wrap 和长期接纳策略仍留给 Planning。

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

- 重新走查现有 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。