docs(hass): 马桶换气电源 Matter 插座接入 + 功率积分补电量 (VPS-92)

Matter Smart Plug (SIXWGH model 3596) 的 cluster 0x0091 声明 IMPE+CUME+PERE 但
CumulativeEnergyImported 恒为 null -> HA 能量实体永久 unknown。功率计量正常
(实测 24.7 W)，故用 Integration (Riemann sum) 辅助元素补电量实体
sensor.wei_sheng_jian_ma_tong_huan_qi_dian_yuan_energy：
能源仪表盘 grid 源 [8] 与 Quick「用电量(按插座)」图换到该实体，Quick 另加
span-2「开关」区块。记录 config-flow 经 supervisor 代理走 REST 的 Agent 方法、
备份路径与回滚方式；energy/validate 已全绿。

hosts/hass.windy.lan.md

@@ -629,6 +629,87 @@ advertised correctly over v4+v6. Both ESP32-C2 bulbs now announce `_matter._tcp`
 :5540 sessions** (device-side failure mode C; no errors logged — see
 [docs/matter-pairing-troubleshoot.md §8](../docs/matter-pairing-troubleshoot.md)).
 
+## 马桶换气电源（Matter 插座，半计量）+ 电量估算 (2026-09-13)
+
+**设备**：Matter `Smart Plug`（SIXWGH，`model_id 3596`，hw 1.0 / sw 1.3.0），node 18
+(0x12)，`device_id 5ef1850953466d6e7a9c6b901fbebe1c`，config entry
+`01JF51VQ48PGJGXX3RNAG6MVAA`，区域**卫生间** (`wei_sheng_jian`)，label `power`；
+2026-09-13 17:58 CST 配对。实体：
+`switch.wei_sheng_jian_ma_tong_huan_qi_dian_yuan`（插座）、
+`sensor.…_dian_yuan`（电源 W）、`sensor.…_dian_ya`（电压 V）、
+`sensor.…_you_gong_dian_liu`（有功电流 A）、`sensor.…_dian_li`（电力 kWh，
+**永久 unknown**）。
+
+**根因（实测 Matter 属性，node 18）**：电量簇 0x0091 `FeatureMap = 13`
+(IMPE|CUME|PERE，即**声明**支持导入/累计/周期电量)，但
+`CumulativeEnergyImported (0x0001)` 恒为 `null`，`PeriodicEnergyImported
+(0x0003)` 带载也恒为 `{Energy: 0}`；`CumulativeEnergyExported (0x0002)`
+不存在（EXPE 未声明，自洽）。HA 只用 `CumulativeEnergyImported` 建能量实体
+（`components/matter/sensor.py:1083`，`allow_none_value=True`）→ 该实体
+**永远不会出数**。**功率计量本身正常**：0x0090 `FeatureMap = 2` (ALTC)，
+Voltage / ActiveCurrent / ActivePower 都随负载变化（实测 220.3 V / 118 mA /
+24.7 W，HA `电源` 0.0→24.9 W 有历史）。厂商 `update` 实体报无新固件。
+
+**处理（方案 A：功率积分补电量）**：
+
+- 新建 **Integration (Riemann sum) 辅助元素**：config entry
+  `01M2D53T188FW8WEC547ENHSVH`（domain `integration`，state `loaded`），
+  source `sensor.wei_sheng_jian_ma_tong_huan_qi_dian_yuan_dian_yuan`，
+  `method: trapezoidal`、`unit_prefix: k`、`unit_time: h`、`round: 3`、
+  `max_sub_interval: 60s`。
+- 实体 `sensor.wei_sheng_jian_ma_tong_huan_qi_dian_yuan_energy`（创建时 HA
+  自动生成 `…_dian_yuan_ma_tong_huan_qi_dian_yuan_dian_liang`，随后立即
+  `config/entity_registry/update` 改名为 `<插座>_energy` 以对齐约定；
+  该实体新建、无引用，改名安全），friendly name「马桶换气电源 电力」，
+  unit kWh、`device_class: energy`、**`state_class: total`**——能源仪表盘
+  允许 `TOTAL` 与 `TOTAL_INCREASING`（`components/energy/validate.py:279`）。
+- **能源仪表盘** (`/energy`)：grid 源 `[8]` 由 `…_dian_li` 改为 `…_energy`，
+  其余 8 条插座源未动。注意这 9 条「插座」全部以 `type: grid` 注册，被当作
+  全屋用电代理；`switch` 卡片所在的 Grid 卡片此前第 9 行是空的，即本次修复点。
+- **Quick 仪表盘**：「用电量(按插座)」图第 11 项由 `…_dian_li` 改为
+  `…_energy`；新增 `column_span: 2` 的「开关」区块（heading + tile
+  `switch.…` + `toggle` feature + 功率徽标）→ 视图 6→7 分区。
+
+**口径警告**：`…_energy` 是**估算值**（Riemann 积分，只在 HA 运行期间累计、
+非账单级），与另外 8 个原生计量插座的累计电量口径不同；功率传感器更新
+间隔约 5–10 s（实测 24.9/24.8/25.0 W 抖动），加 `max_sub_interval: 60s`
+保证静默时也继续累计。
+
+**Agent 侧建辅助元素的方法（2026-09-13 实测）**：HA 的 config flow 走
+**REST**（WS 只有 `config_entries/flow/progress|subscribe`，没有 start）。
+经 supervisor 代理即可，无需 HA 长连接/长寿命 token：
+
+```bash
+# SUPERVISOR_TOKEN 由 sudo -n -i 提供
+curl -s -X POST -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
+  -H "Content-Type: application/json" -d '{"handler":"integration"}' \
+  http://supervisor/core/api/config/config_entries/flow      # → {flow_id, step_id:"user", data_schema}
+curl -s -X POST -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"…","source":"sensor.x","method":"trapezoidal","round":3,
+       "unit_prefix":"k","unit_time":"h","max_sub_interval":{"minutes":1}}' \
+  http://supervisor/core/api/config/config_entries/flow/<flow_id>   # → create_entry
+```
+
+`auth/long_lived_access_token` 在 supervisor 代理身份下**失败**
+（`unknown_error`），故无法用长寿命 token 开浏览器会话；`DurationSelector`
+的值是 `{"minutes":1}` 形式（`cv.time_period`）。
+
+**备份/回滚**：`.lovelace-backups/dashboard-quick-20260913-181251-pre-ma-tong-plug.json`
+（改动前原件）、`…-20260913-183210-pre-repoint.json`（改名/换源前）；
+`.ha-backups/energy-20260913-183135-pre-ma-tong-repoint.json`（能源 prefs）。
+回滚 = 把能源 prefs 的源 [8] 指回 `…_dian_li` + 还原 Quick 面板 JSON；
+如需彻底放弃估算电量 = 删除 config entry `01M2D53T188FW8WEC547ENHSVH`。
+
+**验证 (2026-09-13 18:3x)**：`…_energy` 0.002→0.003 kWh 且随 24.6 W 负载
+增长（换气扇关掉后回落 0.0 W，累计值保留）；`recorder/list_statistic_ids`
+已含该实体；Quick 面板 WS 读回 7 分区、用电量图 11 项指向新实体、旧
+`_dian_li` 引用 0 处；能源 prefs 读回 9 源、第 9 条为新实体。
+**`energy/validate` 已全绿**（9 源 0 issue）：创建后 ~5 min 内曾报
+`statistics_not_defined`（recorder 的统计任务周期是 5 min，`statistics_meta`
+行由该任务建立），18:39 复核时已自动消失——建辅助元素后**不要**把这条
+瞬时告警当作失败。
+
 ## Related docs
 
 - [runbooks/home-assistant-maintenance.md](../runbooks/home-assistant-maintenance.md) — `ha` CLI maintenance runbook + [script](../runbooks/scripts/ha-maintenance.sh); custom-component zip install is §7