M5-T13: document Modbus/Energy/MQTT, mark M5 done, finalize OpenAPI

docs/architecture-overview.md

@@ -19,31 +19,36 @@
 
 - `main.py`
   - FastAPI app factory
-  - lifespan
+  - lifespan（APScheduler 启停、MQTT 客户端起停、连接后触发 HA Discovery 发布）
   - 基础路由注册
 - `config.py`
-  - 环境变量驱动的 settings
+  - 环境变量驱动的 settings（含 M5 新增的 MQTT/HA Discovery/Modbus 配置项）
 - `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
+  - `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`）
   - 裸 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）共用同一个 `Base`，均落在单一 `app.db` 中
+  - 所有模型（auth / config / public_ip / location / poo / modbus / expose）共用同一个 `Base`，均落在单一 `app.db` 中
+  - M5 新增：`ModbusDevice`（设备部署层）、`ModbusReading`（通用遥测，JSON payload）、`ExposedEntityToggle`（HA 实体暴露开关）
 - `schemas/`
-  - Pydantic schemas
+  - Pydantic schemas（M5 新增 `modbus.py`、`expose.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）
 - `integrations/`
   - 外部系统适配层
-  - 当前已迁入 Home Assistant outbound adapter
+  - 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 实体目录）
 - `static/`
   - 极简静态资源
 
@@ -76,6 +81,7 @@ React SPA 前端（M2 引入）。Vite + React + TypeScript + Mantine，由 Fast
 - `app_db_adopt.py`：App DB 接管 / 初始化
 - `migrate_legacy_data.py`：一次性历史数据搬迁脚本
 - `admin_cli.py`：Admin CLI 逃生通道（M4），见下方"登录加固"说明
+- `modbus_cli.py`（M5）：Modbus 手工试读 CLI（`read`/`probe` 两个只读子命令），不依赖 DB，供受控手工验证链路连通性
 
 ### `openapi/`
 
@@ -93,12 +99,69 @@ M4 在基础 Argon2 + server-side session 鉴权之上叠加了三层防御：
 
 详细说明：[`docs/auth.md`](./auth.md)
 
+## M5 — 通用 Modbus 采集链路与 MQTT 通道
+
+### Modbus 采集链路
+
+```
+YAML profile（协议知识）         modbus_device 行（部署信息，DB）
+  - 寄存器块/地址/类型             - host / port（网关 IP）
+  - 每量：key/unit/device_class    - unit_id（Modbus slave 地址）
+  - ha_component                   - friendly_name / profile / poll_interval_s / enabled
+          │                                    │
+          └────────────┬───────────────────────┘
+                       │ APScheduler job（轮询所有 enabled 设备）
+                       │  driver.py: ModbusTcpClient → FC04 块读 → 大端 float32 解码
+                       │  profiles.py: decode(profile, registers) → dict[key → value]
+                       ▼
+              modbus_reading 行
+              device_id · recorded_at · payload(JSON)
+              {"voltage": 230.2, "current": 1.3, "active_power": 295.0, ...}
+```
+
+**关键设计决策**：
+- 命名分层：存储/采集/API 全部通用 `modbus_*`（`/api/modbus/devices`）；面向用户的领域视图叫 **Energy**（第一个）。接入新设备型号只需新增 YAML profile，不改表/不改 API。
+- 读数为 JSON `payload`（无固定列），SQLite `json_extract` 在 DB 端做 AVG/GROUP BY（被 `(device_id, recorded_at)` 索引圈住）。
+- FK `ON DELETE RESTRICT`：有读数的设备拒删，引导改为 `enabled=false`。
+- 设备 `uuid`（uuid4 内部生成）是**稳定身份锚点**：API 路径键、HA Discovery `unique_id` 来源，不随 friendly_name 改变。
+
+### 第二条 MQTT 通道（HA Discovery 发布）
+
+与已有 REST 通道（`app/integrations/homeassistant.py`、`POST /homeassistant/publish`）**并行、不冲突**：
+
+```
+MQTT 通道（M5 新增）：
+  paho-mqtt MqttManager（lifespan 长连接，配置变更可重连）
+        │
+        ├─► Discovery config（retained）
+        │     topic: <prefix>/<component>/<node>/<object>/config
+        │     内容：device 块（identifiers=uuid）、state_topic、unique_id（uuid+key）、
+        │           name（friendly_name）、device_class、unit_of_measurement、availability
+        │     时机：连接成功时 / 目录或勾选变更时（全量重发）；
+        │           取消勾选时发空 payload（清除 entity）
+        │
+        └─► State / Availability（非 retained）
+              时机：每次轮询成功后推该设备所有 enabled entity 的最新值；
+                    周期兜底 job 重推所有 enabled entity + online topic
+
+expose 框架：
+  provider 动态产出 ExposableEntity 目录（元数据从 YAML profile 派生）
+  ExposedEntityToggle 表：只存逐 key 开关（default=disabled）
+  build_catalog(session) → 目录 + 勾选状态（合并所有 provider）
+```
+
+**HA entity 身份模型（Z2M 语义）**：
+- `unique_id` = `f"{device.uuid}_{metric.key}"`（稳定，改名不变）
+- `name` = `friendly_name`（改名重发 discovery，HA 显示名跟着变、历史不丢）
+- 每设备除各 sensor entity 外，另有 `binary_sensor` `online`（取 `last_poll_ok`）——这是"不止 sensor"的体现
+
 ## 当前约束
 
 - 当前数据库继续使用 SQLite
 - ~~当前不引入前后端分离~~ **已退役（M2）**：现为 React SPA + JSON `/api` 层，由 FastAPI 同源托管
 - 当前不设计 Notion 模块
 - 当前通知能力仍保持极小范围，不引入独立通知中心或多渠道抽象
+- Modbus 当前**仅 TCP**（Waveshare RTU↔TCP 网关），**只读**（FC03/04），不写设备寄存器
 
 ## 关于 Notion
 

docs/design/m5-iot-energy.md

@@ -461,7 +461,7 @@ Phase C（MQTT / Discovery，依赖 B 的设备数据与 provider 接口）
 - **Reviewer checklist**: PUT 只改 toggle 不误碰其它配置；republish 真触发 T11；类型化 client。
 
 ### M5-T13 — 文档 + OpenAPI + roadmap 收尾
-- **Status**: `todo` · **Depends**: 全部
+- **Status**: `done` · **Depends**: 全部
 - **Files**: `modify README.md`（Modbus/Energy/MQTT 段、新依赖）、`docs/roadmap.md`（M5 行 + 把"MQTT/IoT"从"下一阶段"毕业、新增 Modbus 采集方向）、`docs/architecture-overview.md`（新增 MQTT 通道与 Modbus 采集）；`modify docs/design/README.md`（列入 m5）；`run python scripts/export_openapi.py` 并提交 `openapi/`
 - **Acceptance criteria**:
   - [ ] 文档反映新链路；`git diff --exit-code openapi/` 无未提交差异。

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)。这些文档为 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)。这些文档为 Orchestrator→Implementer→Reviewer 的多模型流水线设计。
 
 ## 当前基线（v1.0.3）
 
@@ -37,7 +37,7 @@
 | **M1** ✅ | 单库化地基 | 把三库合并成单一 `app.db`，清理散落数据层，删掉 Grafana |
 | **M2** ✅ | 前端 v2 | React SPA 取代 Jinja，承载 config + 可视化 + 记录增删改 |
 | **M4** ✅ | 登录加固 | 防爆破/指数退避 + CLI 逃生通道 + 可选 TOTP 二次验证（**先于 M5**） |
-| **M5** | IoT / 能耗采集 | Modbus/Energy + MQTT/HA Discovery + 前端侧边栏 |
+| **M5** ✅ | IoT / 能耗采集 | 通用 Modbus 采集（YAML profile + JSON readings）+ MQTT/HA Discovery + 前端侧边栏 + Energy 视图 |
 | **M3** | 开放与移动端（远期试水） | token 鉴权 + React Native 移动端 |
 
 排序原则：**先清地基，再在干净结构上盖楼。** M2 的新 API 和 React 必须建立在合并后的单库之上；M4 是公网安全加固，在 M5 IoT 集成之前先堵住裸密码这个洞；M5 在安全基座就绪后再做 IoT 接入。
@@ -150,6 +150,32 @@
 
 ---
 
+## M5 — IoT 集成与能耗采集（✅ 已完成）
+
+### 目标
+
+给后端接入家庭 IoT 生态，建立通用 Modbus 设备采集链路（首个领域：能耗），接入 MQTT + Home Assistant Discovery，并重构前端为侧边导航并新增 Energy 视图。
+
+### 范围
+
+- **两层数据模型（协议与部署分离）**：YAML profile（随代码走，声明协议知识：寄存器/解码/key/unit/ha_component）+ `modbus_device`（部署层 DB 行：friendly_name/host/port/unit_id/profile/poll_interval/enabled）+ `modbus_reading`（通用遥测：device_id + recorded_at + JSON payload）。多设备可共享同一 profile。
+- **通用 Modbus-TCP 采集**：pymodbus，APScheduler 后台 job 轮询所有 enabled 设备；per-device `last_poll_at`/`last_poll_ok`；全局开关 `MODBUS_POLLING_ENABLED`（CONFIG_FIELDS）。首个 profile：SDM120 单相电表。
+- **手工 CLI 试读**：`scripts/modbus_cli`（`read`/`probe` 两个只读子命令），供受控手工验证，不进自动化。
+- **MQTT + HA Discovery**：paho-mqtt 长连接；通用 expose 框架（provider 动态产出可暴露实体目录，元数据从 YAML profile 派生）；`exposed_entity_toggle` 表存逐 key 开关（默认不暴露）；每设备 = 一个 HA device，各量 = sensor entity + online binary_sensor；`unique_id` 锚定于设备 `uuid`（稳定，不随改名变）；配置变更可重连重发 discovery。
+- **前端侧边栏**：`AppShell` 侧边导航（Home / Records / Energy / Config + 主题切换 + 注销），移动端可折叠，当前路由高亮。
+- **Energy 视图**（`/energy`）：设备 CRUD；最新读数卡片（标签/单位取自 profile metrics 端点）；Recharts 走势图（时间范围 + limit）。
+- **Config 页 Accordion**：各大 section 折叠/展开；「Home Assistant Expose」面板勾选可暴露实体 + 连接状态 + 重新发布按钮。
+- **API**（`/api/modbus/*` + `/api/expose` + `/api/config/mqtt/test`）：完整 CRUD + readings + metrics + test + expose 勾选 + 重发 discovery。
+- `pytest`/`ruff`/`export_openapi` + 前端 `lint/typecheck/test/build` 全绿，`openapi/` 已入库。
+
+### 命名决策（已锁定）
+
+存储/采集/API 全部使用通用 `modbus_*`（`/api/modbus/devices`），**不锁死"电表"**；面向用户的领域呈现叫 **Energy**。接入新 Modbus 设备型号只需新增 YAML profile，无需改表/改 API。
+
+> 详细设计与任务卡：[`docs/design/m5-iot-energy.md`](./design/m5-iot-energy.md)
+
+---
+
 ## M3 — 开放与移动端（远期试水）
 
 ### 目标
@@ -169,13 +195,13 @@
 
 ## 下一阶段：已确定要做（尚未拆解为任务卡）
 
-> 这些是 M4 之后**已经定下来要做**的方向——区别于下面的 Future Ideas（仅备忘、未必做）。这里只记到 roadmap 粒度：确定**做什么、为什么**；具体排期、依赖与原子任务，等动手时再展开成 `docs/design/` 的任务卡。**先后顺序未定**，具体排期等动手时再定。
+> 这些是 M5 之后**已经定下来要做**的方向——区别于下面的 Future Ideas（仅备忘、未必做）。这里只记到 roadmap 粒度：确定**做什么、为什么**；具体排期、依赖与原子任务，等动手时再展开成 `docs/design/` 的任务卡。**先后顺序未定**，具体排期等动手时再定。
 
 ### 1. 前端优化
 
 **动机**：M2 的 React SPA 先把功能跑通，性能 / 体验层面的打磨还没做。这一项**确定要做，但具体优化什么还没定**。
 
-**范围（待定）**：方向先留空，想清楚再细化。可能的候选（仅占位、非承诺）：打包体积与代码分割（M2 构建已提示存在 > 500 kB 的单 chunk）、首屏加载、热力图 / 地图的渲染性能、移动端适配、可访问性等。等确定具体目标后再拆任务卡。
+**范围（待定）**：方向先留空，想清楚再细化。可能的候选（仅占位、非承诺）：打包体积与代码分割（M2/M5 构建已提示存在 > 500 kB 的单 chunk）、首屏加载、热力图 / 地图的渲染性能、移动端适配、可访问性等。等确定具体目标后再拆任务卡。
 
 ### 2. 设置页生成 Long-lived Token（供 API 调用）