M8: finalize WarmteLink implementation plan

docs/roadmap.md

@@ -2,7 +2,7 @@
 
 本文档记录 `home-automation` 在 `v1.0.3` 之后的下一阶段规划。这一阶段不是小修补，而是几次较大的结构性改动：单库化、前端重写、以及远期的移动端试水。
 
-> 每个里程碑的设计与**可执行原子任务**展开在 [`docs/design/`](./design/README.md)：M1 [`m1-db-consolidation.md`](./design/m1-db-consolidation.md)、M2 [`m2-frontend-v2.md`](./design/m2-frontend-v2.md)、M3 [`m3-token-mobile.md`](./design/m3-token-mobile.md)、M4 [`m4-login-hardening.md`](./design/m4-login-hardening.md)、M5 [`m5-iot-energy.md`](./design/m5-iot-energy.md)、M6 [`m6-tibber-dynamic-energy.md`](./design/m6-tibber-dynamic-energy.md)、M7 [`m7-meter-epochs-archival.md`](./design/m7-meter-epochs-archival.md)、Pre-M8 [`pre-m8-warmtelink-p1-poc.md`](./design/pre-m8-warmtelink-p1-poc.md)、M8 [`m8-warmtelink-energy.md`](./design/m8-warmtelink-energy.md)。Pre-M8 已完成；M8 仅解锁 Planning，架构仍开放。
+> 每个里程碑的设计与**可执行原子任务**展开在 [`docs/design/`](./design/README.md)：M1 [`m1-db-consolidation.md`](./design/m1-db-consolidation.md)、M2 [`m2-frontend-v2.md`](./design/m2-frontend-v2.md)、M3 [`m3-token-mobile.md`](./design/m3-token-mobile.md)、M4 [`m4-login-hardening.md`](./design/m4-login-hardening.md)、M5 [`m5-iot-energy.md`](./design/m5-iot-energy.md)、M6 [`m6-tibber-dynamic-energy.md`](./design/m6-tibber-dynamic-energy.md)、M7 [`m7-meter-epochs-archival.md`](./design/m7-meter-epochs-archival.md)、Pre-M8 [`pre-m8-warmtelink-p1-poc.md`](./design/pre-m8-warmtelink-p1-poc.md)、M8 [`m8-warmtelink-energy.md`](./design/m8-warmtelink-energy.md)。Pre-M8 已完成；M8 Planning 也已完成并拆成 M8-T01～M8-T20，等待后续由编排器按依赖逐张实现。
 
 ## 当前基线（v1.0.3）
 
@@ -41,7 +41,7 @@
 | **M6** ✅ | 通用电价层 + DSMR 接入 + 实时电费计算 | 通用电价层（manual/tibber profile + 合同版本）+ DSMR 实时电表接入 + 每 15min 寄存器差×价计量电费（不可变快照）+ 日/月/年汇总 + 反哺 HA Energy + 前端合同/价格/费用视图 |
 | **M7** ✅ | 电表生命周期 / 换表归档 | 引入 Meter epoch，计费永不跨表算 delta，跨表/无表/异常 delta 一律降级，累计按当前表归零，追溯换表可重算，Meter CRUD API + 前端管理 UI |
 | **Pre-M8** ✅ | WarmteLink P1 真机概念验证 | 正式只读 CLI 长测通过；人工开启供暖后累计量 `0.017 → 0.018 GJ` 且与物理表一致，所有 frame 的 CRC 状态仍为 `unverifiable` |
-| **M8** 📝 | WarmteLink P1 与多数据源 Meter | Pre-M8 已解锁 Planning；再讨论一个 serial source 的两个累计 channel 与 Meter 的可配置关系，尚未锁定架构或实施 |
+| **M8** 📋 | WarmteLink P1、多数据源 Meter 与热力计费 | Planning 已完成：统一 Source/Channel/Binding、WarmteLink 双 channel、DSMR 迁移、thermal 合同/成本、HA/UI/部署；M8-T01～M8-T20 待实现 |
 | **M3** | 开放与移动端（远期试水） | token 鉴权 + React Native 移动端 |
 
 排序原则：**先清地基，再在干净结构上盖楼。** M2 的新 API 和 React 必须建立在合并后的单库之上；M4 是公网安全加固，在 M5 IoT 集成之前先堵住裸密码这个洞；M5 在安全基座就绪后再做 IoT 接入。
@@ -282,18 +282,42 @@ httpx / paho-mqtt / pyyaml / apscheduler 均为 M5 已有依赖，M6 复用，
 
 ---
 
-## M8 — WarmteLink P1 与多数据源 Meter（📝 Planning 已解锁）
+## M8 — WarmteLink P1、多数据源 Meter 与热力计费（📋 Planning 已完成，待实现）
 
-### 候选目标
+### 目标
 
-在 Pre-M8 事实基础上，把 WarmteLink P1 已确认存在的区域供暖 GJ 和生活热水 m³ 接入
-Energy 模块，并讨论 Meter 如何与实际数据源建立可配置关系。
+以统一的 `MeterSource → MeterSourceChannel → MeterSourceBinding → Meter epoch` 链路承载现有
+DSMR MQTT 与新的 WarmteLink serial source；从一个 WarmteLink source 只读采集已由真机确认的
+区域供暖累计 `GJ` 和生活热水累计 `m³`，并完成历史、计费、API、前端、HA 与部署闭环。
 
-Pre-M8 的证据门已满足，但当前仍不锁定数据库、API、后台 worker 或 UI 结构；特别是 DSMR MQTT
-source、P1 serial source、Device/Data Source 的定义和多 channel 映射，都留到下一轮 Planning 讨论
-并与用户锁定体验后再拆原子任务。
+### 已锁定范围
 
-> Planning 占位与待决问题：[`docs/design/m8-warmtelink-energy.md`](./design/m8-warmtelink-energy.md)
+- Source、Modbus Device、Meter 分离；channel 先发现、再由用户确认绑定，source 切换与物理换表
+  使用两条独立半开时间线。
+- DSMR JSON 和 WarmteLink Decimal scalar 分表存储，但都显式关联 source/binding；既有 DSMR
+  历史和电费安全回填，正常电费数字保持不变，跨 source/binding 周期降级。
+- WarmteLink `unverifiable` frame 需要连续双帧确认后接纳，质量标签不漂白；约 10 秒更新 latest、
+  每分钟保存 history，不保存 raw telegram 或 raw equipment identifier。
+- 串口 worker 使用 `115200 7N1`、只读、短 DB session、可热更新和 `1…60s` 退避重连；以可选
+  compose overlay、稳定 by-id、serial GID 和非 root 容器部署。
+- 合同增加 electricity/thermal scope；一份 district-heating 合同覆盖 heating GJ 与 hot-water m³，
+  生成按 commodity 的 15 分钟成本和 contract-level 每日固定费。仓库不硬编码真实 tariff。
+- UI 分成 Sources / Modbus Devices / Meters，并让 Contracts / Prices / Costs 按 scope 切换；新增
+  source、meter 与 thermal cost HA entities，开关默认关闭，旧 DSMR latest API 保持兼容。
+
+### 原子实施链
+
+- **M8-T01～T06**：统一 source/channel/binding schema、DSMR 历史/runtime/电费迁移和管理 API。
+- **M8-T07～T11**：共享 P1 parser、WarmteLink 标量存储、质量接纳、serial worker、发现与历史 API。
+- **M8-T12～T16**：合同 scope、district-heating profile、thermal cost 账本/引擎/API。
+- **M8-T17～T20**：HA、Sources/Meters UI、scope-aware 计费 UI、compose/文档/全链收尾。
+
+完成判据不仅是单元闸门全绿，还包括历史副本迁移对账、OpenAPI/codegen、全部前端闸门、真实
+`docker build`、非 root 串口部署和真机端到端 walkthrough。任何任务都不得删除旧数据库、历史
+读数、旧 config 行或 volume；push/tag 仍需用户单独授权。
+
+> 完整架构、HTTP 契约、质量/计费规则、依赖图与 M8-T01～M8-T20 任务卡：
+> [`docs/design/m8-warmtelink-energy.md`](./design/m8-warmtelink-energy.md)
 
 ---