M6-T11: document M6 (energy pricing + DSMR + Tibber) across README/roadmap/arch

- README: M6 section + feature list + new tables/config items. - roadmap: M6 row (graduated) + detail section; M6 in milestone index. - architecture-overview: M6 models/services/integrations/routes/jobs/config. - design/README: index m6, drop stale '三个里程碑' wording. - OpenAPI already in sync (no diff).
2026-06-23 23:52:07 +02:00
parent 96e88861d4
commit 78f3cc4776
5 changed files with 124 additions and 11 deletions
@@ -19,36 +19,42 @@

 - `main.py`
  - FastAPI app factory
-  - lifespan（APScheduler 启停、MQTT 客户端起停、连接后触发 HA Discovery 发布）
+  - lifespan（APScheduler 启停、MQTT 客户端起停、连接后触发 HA Discovery 发布；M6 新增 `tibber-refresh` 抓价 job + `energy-cost` 1 分钟计费 tick job；M6 启用时注册 DSMR MQTT 订阅）
  - 基础路由注册
 - `config.py`
-  - 环境变量驱动的 settings（含 M5 新增的 MQTT/HA Discovery/Modbus 配置项）
+  - 环境变量驱动的 settings（含 M5 新增的 MQTT/HA Discovery/Modbus 配置项；M6 新增 `dsmr_ingest_enabled`、`dsmr_mqtt_topic`、`dsmr_sample_interval_s`、`tibber_api_token`（secret）、`tibber_home_id`）
 - `db.py`
  - 统一数据层：一个 `Base`、一个绑定 `app_database_url` 的 cached engine（SQLite WAL）、`get_engine` / `get_session_local` / `reset_db_caches` / `get_db_session`
 - `dependencies.py`
  - 通用依赖注入
 - `api/`
  - HTTP routes
-  - `api/routes/api/`：JSON API（`/api/*` 前缀），供 React SPA 调用：会话/鉴权、配置读写、数据查询、记录 CRUD、Modbus 设备 CRUD + readings + metrics + test（`/api/modbus/*`）、Expose 勾选 + 重发 discovery（`/api/expose`）、MQTT 测试连接（`/api/config/mqtt/test`）
+  - `api/routes/api/`：JSON API（`/api/*` 前缀），供 React SPA 调用：会话/鉴权、配置读写、数据查询、记录 CRUD、Modbus 设备 CRUD + readings + metrics + test（`/api/modbus/*`）、Expose 勾选 + 重发 discovery（`/api/expose`）、MQTT 测试连接（`/api/config/mqtt/test`）、M6 新增合同 CRUD + 版本（`/api/energy/contracts*`）、pricing profile 列表（`/api/energy/profiles`）、价格/费用/汇总/DSMR 最新/重算/Tibber 测试（`/api/energy/prices`、`/api/energy/costs`、`/api/energy/costs/summary`、`/api/energy/dsmr/latest`、`/api/energy/costs/recompute`、`/api/energy/tibber/test`）
  - 裸 ingestion 端点：`GET /public-ip/check`、`POST /homeassistant/publish`、`POST /poo/record`、`GET /poo/latest`、TickTick OAuth 等
 - `models/`
  - SQLAlchemy models
-  - 所有模型（auth / config / public_ip / location / poo / modbus / expose）共用同一个 `Base`，均落在单一 `app.db` 中
+  - 所有模型（auth / config / public_ip / location / poo / modbus / expose / energy）共用同一个 `Base`，均落在单一 `app.db` 中
  - M5 新增：`ModbusDevice`（设备部署层）、`ModbusReading`（通用遥测，JSON payload）、`ExposedEntityToggle`（HA 实体暴露开关）
+  - M6 新增：`DsmrReading`（整帧 DSMR telegram，10s 降采样）、`EnergyContract`（合同头，含 active 标记）、`EnergyContractVersion`（版本/时段，values JSON，只增不改）、`TibberPrice`（15 分钟价缓存，不可变）、`EnergyCostPeriod`（每 15 分钟计量电费，快照价，不可变）
 - `schemas/`
-  - Pydantic schemas（M5 新增 `modbus.py`、`expose.py`）
+  - Pydantic schemas（M5 新增 `modbus.py`、`expose.py`；M6 新增 `energy_contract.py`、`energy.py`）
 - `services/`
  - 业务服务层
  - 当前已迁入 config page 的 DB 持久化逻辑
  - 当前已迁入 public IPv4 检查、状态持久化与变化通知逻辑
  - 当前已迁入 SMTP 发信与测试发信逻辑
  - M5 新增：`modbus_poll.py`（采集 service，逐设备 poll + 落库 + 推 MQTT state）、`ha_discovery.py`（构建 HA Discovery payload、发布 retained config、发布 state）
+  - M6 新增：`tibber_prices.py`（httpx GraphQL 抓 15 分钟价，upsert `tibber_price`，幂等；仅 active=tibber 且 token 存在时运行）、`dsmr_ingest.py`（MQTT handler，整帧 JSON blob + 10s 降采样落库，`source_id` 幂等）、`energy_cost.py`（计费引擎：每 15 分钟寄存器差 × strategy 出价 → `energy_cost_period` 不可变快照；汇总 Σnet + 固定费 − heffingskorting；重算显式 opt-in）
 - `integrations/`
  - 外部系统适配层
  - Home Assistant outbound adapter（REST 通道，原有）
  - M5 新增：`modbus/`（pymodbus 薄封装：`driver.py` 块读 + float32 解码；`profiles.py` YAML profile 加载/校验/解码；`profiles/sdm120.yaml` SDM120 协议声明）
  - M5 新增：`mqtt.py`（paho-mqtt 长连接 `MqttManager`：lifespan 起/停、配置变更重连、`publish(topic, payload, retain)`）
  - M5 新增：`expose.py`（通用 expose 框架：`ExposableEntity`、provider 注册表、`build_catalog`；Modbus provider 从 YAML profile 派生 sensor/binary_sensor 实体目录）
+  - M6 新增：`pricing/`（通用电价层：`profiles.py` pydantic 加载/校验 YAML profile + `validate_values`；`strategies.py` manual/tibber 出价策略注册表；`profiles/manual.yaml` 固定/双费率结构；`profiles/tibber.yaml` 动态电价结构）
+  - M6 新增：`tibber/`（`client.py`：httpx GraphQL 客户端，`priceInfoRange(QUARTER_HOURLY)` 查询，按 `starts_at` 解析，不假设固定节点数）
+  - M6 扩展：`mqtt.py` 新增订阅端（`subscribe(topic, handler)`，`on_connect` 里 subscribe，`on_message` 按 topic 分发，handler 异常吞掉不崩连接）
+  - M6 扩展：`expose.py` 新增 `_energy_cost_provider`（`buy_price_now`、`sell_price_now`、`import_cost_total`/`export_revenue_total` 均 `total_increasing`，反哺 HA Energy）
 - `static/`
  - 极简静态资源

@@ -1,14 +1,15 @@
 # 设计文档与多模型协作约定

-本目录把 `docs/roadmap.md` 里的三个里程碑展开成**可被 coding agent 流水线执行**的详细设计文档。
+本目录把 `docs/roadmap.md` 里的各个里程碑展开成**可被 coding agent 流水线执行**的详细设计文档。

 - [`m1-db-consolidation.md`](./m1-db-consolidation.md) — 单库化地基
 - [`m2-frontend-v2.md`](./m2-frontend-v2.md) — React SPA 前端 v2
 - [`m3-token-mobile.md`](./m3-token-mobile.md) — token 鉴权与移动端（远期）
 - [`m4-login-hardening.md`](./m4-login-hardening.md) — 登录加固（防爆破/指数退避 + CLI 逃生 + 可选 TOTP）**先做**
 - [`m5-iot-energy.md`](./m5-iot-energy.md) — IoT 集成与能耗采集（Modbus/Energy + MQTT/HA Discovery + 前端侧边栏）
+- [`m6-tibber-dynamic-energy.md`](./m6-tibber-dynamic-energy.md) — 通用电价层 + DSMR 实时电表接入 + 实时买卖电费计算 + HA Energy 反哺

-本文件定义**所有任务共用的格式与协作规则**，三个里程碑文档不再重复这些约定。
+本文件定义**所有任务共用的格式与协作规则**，各个里程碑文档不再重复这些约定。

 ---

@@ -427,7 +427,7 @@ Phase D（API + 前端）
 - **Reviewer checklist**: 全走类型化 client；图表组件隔离复用；表单按结构渲染、不 hardcode 字段；窗口/上限；空/错/加载/缺 key 容错。

 ### M6-T11 — 文档 + OpenAPI + roadmap 收尾
- **Status**: `todo` · **Depends**: 全部
+- **Status**: `done` · **Depends**: 全部
 - **Files**: `modify README.md`、`docs/roadmap.md`（M6 行 + 毕业）、`docs/architecture-overview.md`、`docs/design/README.md`（列入 m6）；`run python scripts/export_openapi.py` 并提交 `openapi/`
 - **Acceptance criteria**:
  - [ ] 文档反映新链路；`git diff --exit-code openapi/` 无未提交差异；校验闸门全绿。
@@ -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)。这些文档为 Orchestrator→Implementer→Reviewer 的多模型流水线设计。
+> 每个里程碑的**可执行原子任务**展开在 [`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)。这些文档为 Orchestrator→Implementer→Reviewer 的多模型流水线设计。

 ## 当前基线（v1.0.3）

@@ -38,6 +38,7 @@
 | **M2** ✅ | 前端 v2 | React SPA 取代 Jinja，承载 config + 可视化 + 记录增删改 |
 | **M4** ✅ | 登录加固 | 防爆破/指数退避 + CLI 逃生通道 + 可选 TOTP 二次验证（**先于 M5**） |
 | **M5** ✅ | IoT / 能耗采集 | 通用 Modbus 采集（YAML profile + JSON readings）+ MQTT/HA Discovery + 前端侧边栏 + Energy 视图 |
+| **M6** ✅ | 通用电价层 + DSMR 接入 + 实时电费计算 | 通用电价层（manual/tibber profile + 合同版本）+ DSMR 实时电表接入 + 每 15min 寄存器差×价计量电费（不可变快照）+ 日/月/年汇总 + 反哺 HA Energy + 前端合同/价格/费用视图 |
 | **M3** | 开放与移动端（远期试水） | token 鉴权 + React Native 移动端 |

 排序原则：**先清地基，再在干净结构上盖楼。** M2 的新 API 和 React 必须建立在合并后的单库之上；M4 是公网安全加固，在 M5 IoT 集成之前先堵住裸密码这个洞；M5 在安全基座就绪后再做 IoT 接入。
@@ -176,6 +177,43 @@

 ---

+## M6 — 通用电价层 + DSMR 实时数据 + 实时买卖电费计算（✅ 已完成）
+
+### 目标
+
+在 M5 IoT 基建之上，把"电价合同"与"DSMR 实时电表数据"接起来，按 **15 分钟**周期算出**实际买电支出 / 卖电收入**，自己落库留底（不可变、可审计），并通过 MQTT + HA Discovery 反哺 Home Assistant 的 Energy 仪表盘。
+
+### 关键能力
+
+- **通用电价层（两层模型）**：仓库内 YAML profile 定结构（`manual` 固定/双费率、`tibber` 动态电价）；`EnergyContract`（+ 版本）存 UI 可改的数值；price strategy 按 `kind` 出价。一次激活一个合同。改价 = 加新版本，旧版本保留（审计链）。
+- **DSMR 实时数据接入**：扩 `MqttManager` 订阅 `dsmr/json`（每秒一帧），整帧 JSON blob 按 10 秒降采样落库（电、气、各相全存；字段 allowlist 不做，blob 天然容纳未来字段）。
+- **实时买卖电费计算（两层）**：每 15 分钟用电表累计寄存器差值（`delivered_1/2`、`returned_1/2`）× 当时合同的买/卖价算计量电费（不可变、快照价）。买价：tibber = API `total`（含税全包），manual = `energy_buy_档 + energy_tax`；卖价：tibber = `total − energy_tax − sell_adjust`，manual = `sell_档`（无能源税）。双费率：`_1`=dal/低、`_2`=normal/高（NL 惯例）。日/月/年汇总再加固定费（按月→天）减 heffingskorting（按年→天）。不做净计量。卖价残差（sell_adjust）及能源税等当前数值在真实账单确认后钉死。
+- **反哺 Home Assistant**：`_energy_cost_provider` 发 `buy_price_now`、`sell_price_now`、`import_cost_total`（`total_increasing`）、`export_revenue_total`（`total_increasing`）—— 直接挂 HA Energy 仪表盘。
+- **Tibber 动态电价**：httpx GraphQL 客户端抓 `QUARTER_HOURLY` 15 分钟价（已 demo 验证 `total=energy+tax`）；启动 + 每小时抓取今明两天价格、幂等 upsert `tibber_price`（hourly trigger，确保每日刷新且可补重试）；仅当 active 合同 kind=tibber 且 token 存在时运行。
+- **前端**：Energy 视图新增三个 Tab——Contracts（合同管理，表单按 profile 结构渲染）、Prices（15 分钟价格曲线）、Costs（费用走势/明细/汇总卡片）；Config 页 Tibber 测试三态入口。
+
+### 命名分层（延续 M5）
+
+存储/采集/计算层中性命名（`dsmr_*` / `tibber_price` / `energy_cost_period` / `energy_contract`）；面向用户并入既有 **Energy** 视图。
+
+### 新增 5 张表（单库 app 链，migration `20260623_11_energy_tables`）
+
+| 表 | 关键列 | 说明 |
+| --- | --- | --- |
+| `dsmr_reading` | `recorded_at`(idx)、`source_id`(unique)、`payload`(JSON) | 整帧 DSMR telegram blob，10 秒降采样 |
+| `energy_contract` | `name`、`kind`、`active`、`currency`、时间戳 | 合同头；一次一个 active |
+| `energy_contract_version` | `contract_id`(FK)、`effective_from`、`effective_to`(null)、`values`(JSON)、`created_at` | 版本/时段；改价加新版本、旧版本保留 |
+| `tibber_price` | `starts_at`(unique)、`resolution`、`energy/tax/total`、`level`、`currency`、`fetched_at` | 15 分钟价缓存，不可变 |
+| `energy_cost_period` | `period_start`(unique)、`d1/d2/r1/r2_kwh`、`import_cost/export_revenue/net_cost`、`currency`、`pricing`(JSON 快照)、`contract_version_id`(FK)、`degraded`、`computed_at` | 每 15 分钟计量电费，不可变（快照价+版本） |
+
+### 不新增依赖
+
+httpx / paho-mqtt / pyyaml / apscheduler 均为 M5 已有依赖，M6 复用，不新增任何 Python 包。
+
+> 详细设计与任务卡：[`docs/design/m6-tibber-dynamic-energy.md`](./design/m6-tibber-dynamic-energy.md)
+
+---
+
 ## M3 — 开放与移动端（远期试水）

 ### 目标