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).

docs/architecture-overview.md

@@ -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/`
   - 极简静态资源