PRE-M8: add WarmteLink P1 planning placeholders

docs/design/pre-m8-warmtelink-p1-poc.md

@@ -0,0 +1,96 @@
+# Pre-M8 — WarmteLink P1 真机概念验证
+
+> **状态：等待 USB→P1 线到货后执行。** 本文只定义验证边界与证据要求；当前仓库尚未实现下文所示的 probe 命令。
+
+## 1. 目的
+
+在进入 M8 正式设计和实现前，先用新家的 Vattenfall WarmteLink 做一次只读真机验证，回答以下问题：
+
+1. 当前 USB→P1 线、主机串口权限和 WarmteLink P1 端口能否稳定输出完整 telegram。
+2. telegram 的 framing、CRC、时间戳、OBIS/M-Bus channel 和单位能否被 parser 正确识别。
+3. 实际能够读取哪些累计量：区域供暖热量（GJ）、生活热水体积（m³）或其它字段。
+4. 读数的精度、更新频率和累计语义，是否与热力表/水表面板上的数字一致。
+
+Pre-M8 是 M8 的证据门：在真机字段和语义确认前，不决定数据库结构、Meter 数据源绑定、后台采集服务或前端布局。
+
+## 2. 执行边界
+
+本阶段只建立下面这条最短链路：
+
+```text
+WarmteLink P1 → USB serial → 完整 telegram → CRC 校验 → 字段解析 → 终端输出
+```
+
+明确不做：
+
+- 不写入 `app.db`，不新增 Alembic migration。
+- 不新增 FastAPI API、后台常驻 worker、配置页面或 Energy 前端。
+- 不发布 MQTT / Home Assistant Discovery。
+- 不修改现有 DSMR Reader MQTT、电费计算或 Meter 逻辑。
+- 不在本阶段决定 WarmteLink 应落在哪个正式 Device/Source 模型中。
+
+## 3. 预期操作方式
+
+线到货后，在 workspace 的 virtual environment 中实现并运行一个只读 probe。命令形态暂定为：
+
+```bash
+source .venv/bin/activate
+python -m scripts.p1_probe \
+  --device /dev/serial/by-id/<usb-p1-device> \
+  --duration 600 \
+  --show-changes \
+  --raw-output /tmp/warmtelink-p1-telegram.txt
+```
+
+最终参数名可在实现 probe 时调整，但应保留这些能力：
+
+- 使用稳定的 `/dev/serial/by-id/...` 路径，而不是依赖可能变化的 `/dev/ttyUSB0`。
+- 连续读取多帧，而不是只看一帧偶然样本。
+- 同时显示完整帧/CRC 结果、原始 OBIS 字段和解析后的值/单位。
+- 枚举 telegram 中出现的所有 M-Bus channel、device type、equipment id、capture timestamp、value 和 unit，不依赖固定字段顺序。
+- 可只显示发生变化的字段，便于观察更新频率。
+- 原始 telegram 默认只写到 `/tmp`；未经脱敏不提交到 Git。
+
+## 4. 人工对照
+
+probe 运行期间，人工从热力表和相关水表面板记录同一时间附近的显示值，并与终端结果对照：
+
+| 检查项 | 需要记录 |
+| --- | --- |
+| 区域供暖 | 面板累计值、P1 值、单位、两者时间差 |
+| 生活热水 | 面板累计值、P1 是否存在对应字段、单位、两者时间差 |
+| 更新时间 | 连续 telegram 中数值变化的间隔 |
+| 累计语义 | 数值是否单调累计，是否出现每日归零或其它重置 |
+
+允许 P1 capture time 与按表时间之间存在合理延迟；不能只凭数值接近就认定字段含义，必须同时核对单位、channel/device type 和时间戳。
+
+## 5. 通过条件
+
+Pre-M8 完成需留下以下证据：
+
+- [ ] 连续收到可识别为 WarmteLink 的完整 telegram。
+- [ ] CRC 校验通过；若失败，已区分串口/线材问题与 parser 问题。
+- [ ] parser 不依赖字段固定顺序，并列出全部实际 channel/OBIS 字段。
+- [ ] 找到 GJ 累计值并与热力表面板对照，误差可由显示精度或 capture 延迟解释。
+- [ ] 明确实际 telegram 是否包含独立的生活热水 m³ 累计量；若包含，已与水表面板对照。
+- [ ] 记录数值精度、telegram 频率、字段更新频率和累计/重置行为。
+- [ ] 形成一份脱敏结果摘要，足以支持下一轮 M8 Planning。
+
+如果只能确认 GJ、没有独立生活热水 m³，这也是有效结论，不视为 Pre-M8 失败。
+
+## 6. 失败分类
+
+- 完全无数据：优先检查 USB 识别、串口权限、P1 request line、线材方向/供电。
+- 输出乱码或不成帧：优先检查串口参数、信号反相和线材兼容性。
+- 原始帧完整但解析失败：保存脱敏样本，调整 parser/字段映射。
+- 解析成功但面板对不上：检查 capture timestamp、累计语义、单位和 WarmteLink firmware 差异。
+
+## 7. 向 M8 的交付物
+
+Pre-M8 只向 M8 交付事实，不交付正式架构：
+
+- 已脱敏的 telegram 结构与字段清单。
+- GJ / 可选 m³ 的实际 channel、OBIS、单位、精度和更新时间。
+- 串口参数、稳定设备路径与部署权限要求。
+- parser 适配结论以及需要保留的异常样本。
+- 对“一个来源包含几个可用计量通道”的实测结论。