tliu93/home-automation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

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

Browse Source 
- 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).
This commit is contained in:
tliu93
2026-06-23 23:52:07 +02:00
parent 96e88861d4
commit 78f3cc4776
5 changed files with 124 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+70 -2
View File
@@ -17,6 +17,10 @@
- **Modbus 设备采集**：通过 YAML profile（首个：SDM120 电表）按设备周期轮询 Modbus-TCP 网关，解码工程量并落通用读数表（`modbus_device` + `modbus_reading`）
- **MQTT + Home Assistant Discovery**：以可勾选方式把 Modbus 设备/工程量注册为 HA device/entity（含 binary_sensor online），state 周期发布；配置变更可重连重发
- **前端侧边栏 + Energy 视图**：侧边导航替换顶栏；Energy 页管理 Modbus 设备、展示最新读数与 Recharts 走势图；Config 页 Accordion 分区展开；Expose 设置勾选 HA 可暴露实体
- **DSMR 实时电表接入**：订阅 DSMR Reader 的 `dsmr/json`（每秒一帧）、整帧 JSON blob 按 10 秒降采样落库（`dsmr_reading`）
- **通用电价合同层**：YAML profile 定合同结构（manual 固定/双费率 / tibber 动态电价）；`EnergyContract`+`EnergyContractVersion` 存 UI 可填的数值，改价加新版本旧版本保留；price strategy 按 kind 出价
- **实时买卖电费计算**：每 15 分钟按寄存器差值（`_1`=dal/低、`_2`=normal/高）× 买/卖价算计量电费，快照不可变；日/月/年汇总加固定费减 heffingskorting
- **反哺 Home Assistant Energy**：当前买/卖价 + 累计买电支出/卖电收入（`total_increasing`）发成 HA 实体，可直接挂 HA Energy 仪表盘
- pytest 测试与 OpenAPI 导出脚本
- Docker / Compose 部署入口
@@ -36,6 +40,10 @@
- Modbus 设备定义（`modbus_device` 表）
- Modbus 通用读数（`modbus_reading` 表，JSON payload）
- HA 实体暴露开关（`exposed_entity_toggle` 表）
- DSMR 电表实时读数（`dsmr_reading` 表，整帧 JSON blob，10s 降采样）
- 电价合同（`energy_contract` 表）与版本（`energy_contract_version` 表，values JSON）
- Tibber 15 分钟电价缓存（`tibber_price` 表，不可变）
- 每 15 分钟计量电费（`energy_cost_period` 表，快照价，不可变）
配置层只保留一个数据库环境变量：
@@ -47,7 +55,7 @@
python -m scripts.run_migrations
```
该命令会通过 Alembic 将 `app.db` 初始化或升级到最新 head（含全部表，包括 M5 新增的 `modbus_device`、`modbus_reading`、`exposed_entity_toggle`）。
该命令会通过 Alembic 将 `app.db` 初始化或升级到最新 head（含全部表，包括 M5 新增的 `modbus_device`、`modbus_reading`、`exposed_entity_toggle`，以及 M6 新增的 `dsmr_reading`、`energy_contract`、`energy_contract_version`、`tibber_price`、`energy_cost_period`）。
## 当前目录
@@ -55,7 +63,7 @@ python -m scripts.run_migrations
- `app/`: FastAPI 应用代码（包含 JSON API、业务服务、数据模型）
- `frontend/`: React SPA 前端（Vite + React + TypeScript + Mantine）
- `alembic_app/`: App DB 的 Alembic migration 环境（管理所有表，含 M5 新增的 `modbus_device`、`modbus_reading`、`exposed_entity_toggle`）
- `alembic_app/`: App DB 的 Alembic migration 环境（管理所有表，含 M5 新增的 `modbus_device`、`modbus_reading`、`exposed_entity_toggle`，以及 M6 新增的 `dsmr_reading`、`energy_contract`、`energy_contract_version`、`tibber_price`、`energy_cost_period`）
- `tests/`: pytest 测试
- `docs/`: 当前系统说明文档
- `scripts/`: 辅助脚本，例如 OpenAPI 导出
@@ -366,6 +374,64 @@ CLI 工具为受控手工验证而设（设备需接市电），仅暴露读功
- **Config 页 Accordion**：各大 config section 可独立折叠/展开；「Home Assistant Expose」面板按设备分组勾选可暴露实体、显示 MQTT/Discovery 连接状态、「重新发布 discovery」按钮。
- SPA 路由新增 `/energy`。
## M6 DSMR 接入 / 电价合同 / 实时电费计算 / HA Energy 反哺
M6 在 M5 IoT 基建之上接入 DSMR 实时智能电表数据，建立通用电价合同层，按每 15 分钟算出实际买卖电费并反哺 HA Energy。
### 依赖
M6 **不新增任何 Python 依赖**，复用 M5 已有的 `httpx`（Tibber GraphQL）、`paho-mqtt`（DSMR 订阅）、`pyyaml`（pricing profile 加载）、`apscheduler`（抓价 job、计费 job）。
### DSMR 实时电表接入
订阅 DSMR Reader 的 `dsmr/json` topic（每秒一帧完整 telegram），整帧存为 JSON blob、按 `dsmr_sample_interval_s`（默认 10 秒）降采样落 `dsmr_reading`（`source_id` 幂等去重）。`dsmr_ingest_enabled`（默认 false，opt-in）。
### 电价合同层
- **YAML profile 定结构**（仓库内，不放数值）：`manual.yaml`（固定/双费率：buy_normal/dal、sell_normal/dal、energy_tax、ode、固定费、heffingskorting）；`tibber.yaml`（动态：source=tibber_api，energy_tax、sell_adjust）
- **`EnergyContract` + `EnergyContractVersion`**（UI 填数值）：改价 = 加新版本行（带 `effective_from`），旧版本保留（审计链）；一次只有一个 active 合同
- **price strategy**：`manual` 用双费率常数（`buy = energy_buy_档 + energy_tax`，`sell = sell_档`）；`tibber` 用 `tibber_price.total` 作买价（已含税，demo 确认 `total=energy+tax`），`total − energy_tax − sell_adjust` 作卖价（卖价残差 `sell_adjust` 默认 0，待真实账单核定）
### 每 15 分钟计量电费（不可变）
APScheduler 1 分钟 tick，取每个闭合 15 分钟窗口的 DSMR 寄存器差值（`delivered_1/2`，`returned_1/2`；`_1`=dal/低，`_2`=normal/高，NL 惯例）× 当时合同版本的 strategy 出价，upsert `energy_cost_period`（快照当时价 + `contract_version_id`）。缺价/缺数据时标 `degraded`。`POST /api/energy/costs/recompute` 显式重算。
日/月/年汇总 = Σnet + 固定费（network_fee + management_fee 按月→天 × 天数）- heffingskorting（按年→天 × 天数），读时计算、不落表。能源税 `energy_tax` 参考值约 0.1108 EUR/kWh（2026 第一档含 VAT，待真实账单核定；该值由 UI 填入合同版本，YAML profile 仅声明字段 unit，代码无写死默认数值）。
### Tibber 动态电价
`app/integrations/tibber/client.py` httpx POST GraphQL（`priceInfoRange(QUARTER_HOURLY, first=96)`），解析 `startsAt`/`total`/`energy`/`tax`/`level`，按 `starts_at` upsert `tibber_price`（幂等）。启动 + 每小时抓取今明两天 15 分钟价、幂等 upsert（hourly trigger，确保每日刷新且可补重试）；仅当 active 合同 kind=tibber 且 `tibber_api_token` 存在时运行。`POST /api/energy/tibber/test` 试连三态（success 带当前价 / config-error / failed）。
### 反哺 Home Assistant Energy
`_energy_cost_provider` 向 expose 框架注册 4 个实体：`buy_price_now`、`sell_price_now`（€/kWh sensor）、`import_cost_total`、`export_revenue_total`（`total_increasing` monetary，可直接挂 HA Energy 仪表盘）。默认未勾选，在 Expose 面板启用。
### API 端点（M6 新增）
| 端点 | 用途 |
| --- | --- |
| `GET /api/energy/contracts` | 列出合同 + active 标记 |
| `POST /api/energy/contracts` | 新建合同（kind + 首版本值，按 profile 校验）|
| `GET /api/energy/contracts/{id}` | 单个合同 + 版本历史 |
| `PATCH /api/energy/contracts/{id}` | 改名 / 激活 |
| `POST /api/energy/contracts/{id}/versions` | 加新版本（改价，带生效日期）|
| `GET /api/energy/profiles` | 列出 pricing profile 结构（前端按它渲染表单）|
| `GET /api/energy/prices` | 区间价格点（曲线）|
| `GET /api/energy/costs` | 区间 `energy_cost_period`（走势/明细）|
| `GET /api/energy/costs/summary` | 区间汇总（计量电费 + 固定费 − 抵扣）|
| `POST /api/energy/costs/recompute` | 幂等重算 |
| `GET /api/energy/dsmr/latest` | 最新 `dsmr_reading` |
| `POST /api/energy/tibber/test` | 试连 Tibber + 拉当前价，三态 |
DSMR/Tibber 标量配置复用现有 `GET/PUT /api/config`（新增 `dsmr_ingest_enabled`、`dsmr_mqtt_topic`、`dsmr_sample_interval_s`、`tibber_api_token`（secret）、`tibber_home_id`）。
### 前端视图（M6 新增，并入 Energy 视图）
- **Contracts Tab**：合同列表 + 新建/编辑（表单按 `/api/energy/profiles` 结构渲染，不 hardcode 字段）+ 激活 + 改价加版本 + 版本历史只读。
- **Prices Tab**：15 分钟价格曲线（tibber 动态或 manual 档位），复用 Recharts。
- **Costs Tab**：费用走势/明细 + 汇总卡片（含固定费/抵扣）。
- **Config 页 Tibber 测试**：三态（success/config-error/failed）。
## Config 持久化
当前 config 页面不会把修改写回 `.env`。
@@ -394,6 +460,8 @@ CLI 工具为受控手工验证而设（设备需接市电），仅暴露读功
- MQTT broker 配置（`MQTT_ENABLED`、`MQTT_BROKER_HOST/PORT/USERNAME/PASSWORD`、`MQTT_TLS_ENABLED`）
- Home Assistant Discovery 配置（`HA_DISCOVERY_ENABLED`、`HA_DISCOVERY_PREFIX`）
- Modbus 采集配置（`MODBUS_POLLING_ENABLED`）
- DSMR 接入配置（`DSMR_INGEST_ENABLED`、`DSMR_MQTT_TOPIC`、`DSMR_SAMPLE_INTERVAL_S`）
- Tibber 凭据（`TIBBER_API_TOKEN`（secret）、`TIBBER_HOME_ID`）
其中 SMTP password 与其他 secret 字段一致：
docs/architecture-overview.md
+11 -5
View File
@@ -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/`
- 极简静态资源
docs/design/README.md
+3 -2
View File
@@ -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 反哺
本文件定义**所有任务共用的格式与协作规则**，三个里程碑文档不再重复这些约定。
本文件定义**所有任务共用的格式与协作规则**，各个里程碑文档不再重复这些约定。
---
docs/design/m6-tibber-dynamic-energy.md
+1 -1
View File
@@ -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/` 无未提交差异；校验闸门全绿。
docs/roadmap.md
+39 -1
View File
@@ -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 — 开放与移动端（远期试水）
### 目标