docs: update PRD to MQTT architecture, add acceptance criteria

- Replace HTTP/REST with MQTT throughout PRD
- Add MQTT Broker prerequisites section (§2.2)
- Convert architecture and auth flow diagrams to Mermaid
- Add comprehensive Home Energy Management adaptation (§6.2)
- Add product acceptance criteria document (78 items)

Made-with: Cursor

docs/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,283 @@
+# Jackery DIY3 Home Assistant 集成插件 — 产品验收标准
+
+---
+
+## 文档版本历史
+
+| 版本 | 日期 | 作者 | 变更说明 |
+|------|------|------|----------|
+| 1.0 | 2025-03-04 | Jackery IoT PM | 初稿：基于 PRD V1.0 生成全量验收标准 |
+
+> 本文档为 PRD V1.0 的配套验收标准，所有验收项均可追溯到 PRD 中对应章节。
+
+---
+
+## 1. 验收总则
+
+### 1.1 验收范围
+
+本文档覆盖 Jackery DIY3 Home Assistant 集成插件 V1.0 的全部产品需求验收，包括：
+
+- 安装与分发
+- 配置流程（Config Flow）
+- 设备发现与多设备支持
+- 实体映射与数据准确性
+- 只读安全约束
+- 离线与异常处理
+- 性能与兼容性
+- UI/UX 展示
+- 云端共存
+
+### 1.2 验收环境要求
+
+| 项目 | 要求 |
+|------|------|
+| Home Assistant 版本 | ≥ 2024.6.0 |
+| HACS 版本 | ≥ 2.0 |
+| Jackery APP 版本 | ≥ 2.10.18 |
+| 设备固件 | 支持本地 MQTT 功能 |
+| MQTT Broker | 本地 MQTT Broker（如 Mosquitto）已运行，HA 内置 MQTT 集成已连接 |
+| 网络环境 | HA 与 DIY3 主机处于同一局域网 |
+| 测试设备 | DIY3 主机 ×1（最少）、Smart CT ×1、Smart Plug ×2（最少） |
+
+### 1.3 验收结论标准
+
+| 结论 | 条件 |
+|------|------|
+| **通过** | 全部「必须 (MUST)」项通过，「应当 (SHOULD)」项通过率 ≥ 90% |
+| **有条件通过** | 全部「必须」项通过，「应当」项通过率 ≥ 70%，未通过项有明确修复计划 |
+| **不通过** | 任一「必须」项未通过 |
+
+---
+
+## 2. 安装与分发
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| INS-01 | MUST | 通过 HACS 添加自定义仓库并安装 Jackery 集成 | 可在 HACS 中搜索到 "Jackery"，点击安装后提示重启 HA | §3 C-1 |
+| INS-02 | MUST | 重启 HA 后集成可用 | 在「设置 → 设备与服务 → 添加集成」中可搜索到 "Jackery" | §3 C-1 |
+| INS-03 | MUST | HACS 验证与 Hassfest 验证通过 | CI 中 `hacs/action` 与 `hassfest` 均为绿色 | §3 C-1 |
+| INS-04 | SHOULD | 卸载集成后清理完全 | 删除集成后，所有关联的 Device、Entity 被移除，无残留数据 | — |
+
+---
+
+## 3. 配置流程 (Config Flow)
+
+### 3.1 设备发现
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| CFG-01 | MUST | mDNS 自动发现局域网内 DIY3 设备 | 添加集成时，设备列表中展示已开启本地访问的 DIY3 设备（显示设备名称 + SN） | §5.1.2 Step 1 |
+| CFG-02 | MUST | 支持手动输入设备 SN | 设备列表中提供「手动输入」选项，用户可直接键入设备 SN | §5.1.2 Step 1 |
+| CFG-03 | SHOULD | 未开启本地访问的设备不出现在发现列表中 | 仅已启用 MQTT 功能的设备可被发现 | §2.3 |
+
+### 3.2 Token 验证
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| CFG-04 | MUST | 正确 Token 可通过验证 | 输入从 APP 获取的有效 Token 后，验证成功并进入设备创建步骤 | §5.1.2 Step 2–3 |
+| CFG-05 | MUST | 错误 Token 被拒绝并显示明确提示 | 输入错误 Token 后，提示 "Token 验证失败，请检查 Token 是否正确。可在 Jackery APP 中重新生成" | §5.1.3 `invalid_auth` |
+| CFG-06 | MUST | 设备不可达时显示明确提示 | MQTT 不可用或设备未连接 Broker 时，提示 "无法连接到设备，请检查 MQTT 集成与设备是否均已连接到 Broker" | §5.1.3 `cannot_connect` |
+| CFG-07 | MUST | 重复添加同一设备被阻止 | 再次添加已配置的设备时，提示 "该设备已添加到 Home Assistant" | §5.1.3 `already_configured` |
+| CFG-08 | SHOULD | 不支持的设备型号显示明确提示 | 提示 "该设备型号暂不支持，请确认固件已更新至最新版本" | §5.1.3 `unsupported_device` |
+| CFG-09 | SHOULD | 未启用本地访问的设备显示明确提示 | 提示 "设备的本地访问功能未开启，请在 Jackery APP 中开启" | §5.1.3 `local_access_disabled` |
+
+### 3.3 设备创建
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| CFG-10 | MUST | 验证成功后自动创建 DIY3 主机 Device | 在「设备与服务」中可看到 Jackery DIY3 设备，显示型号与 SN | §5.1.2 Step 4 |
+| CFG-11 | MUST | 自动识别并创建已连接的 Smart CT 子设备 | CT 以子设备形式出现在主机设备下 | §5.1.2 Step 4 |
+| CFG-12 | MUST | 自动识别并创建已连接的 Smart Plug 子设备 | 各 Plug 以子设备形式出现在主机设备下 | §5.1.2 Step 4 |
+| CFG-13 | MUST | 所有 Sensor 与 Binary Sensor 实体自动创建 | 主机、CT、Plug 下的全部传感器实体按 PRD 定义自动生成 | §5.2 |
+
+### 3.4 多设备支持
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| CFG-14 | MUST | 支持添加第二台 DIY3 主机 | 重复配置流程可成功添加第二台主机，两台设备独立运行 | §5.1.4 |
+| CFG-15 | MUST | 多台设备的实体互不干扰 | 各设备的传感器数据独立更新，不会混淆 | §5.1.4 |
+| CFG-16 | SHOULD | 删除一台设备不影响其他设备 | 删除其中一台主机的集成配置，另一台继续正常工作 | §5.1.4 |
+
+---
+
+## 4. 实体映射与数据准确性
+
+### 4.1 Entity ID 命名
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ENT-01 | MUST | Entity ID 符合命名规范 | 格式为 `sensor.jackery_{device_sn}_{entity_key}`，SN 全小写 | §5.2.1 |
+| ENT-02 | MUST | 子设备 Entity ID 使用子设备 SN | CT/Plug 实体使用各自的 SN 而非主机 SN | §5.2.1 |
+
+### 4.2 DIY3 主机传感器
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ENT-03 | MUST | 光伏总功率传感器存在且有数值 | `solar_power` 实体存在，单位 W，数值与设备实际一致 | §5.2.2 |
+| ENT-04 | MUST | 光伏分路功率传感器存在 | `solar_power_pv1`、`solar_power_pv2` 实体存在 | §5.2.2 |
+| ENT-05 | MUST | 电池充电/放电功率传感器存在 | `battery_charge_power`、`battery_discharge_power` 实体存在且数值正确 | §5.2.2 |
+| ENT-06 | MUST | 市电购电/馈网功率传感器存在 | `grid_import_power`、`grid_export_power` 实体存在 | §5.2.2 |
+| ENT-07 | MUST | EPS 输出功率传感器存在 | `eps_output_power` 实体存在 | §5.2.2 |
+| ENT-08 | MUST | 家庭用电功率传感器存在 | `home_power` 实体存在，数值为计算值 | §5.2.2 |
+| ENT-09 | MUST | 电池 SOC 传感器存在 | `battery_soc` 实体存在，单位 %，范围 0–100 | §5.2.2 |
+| ENT-10 | SHOULD | 电池 SOH 传感器存在 | `battery_soh` 实体存在 | §5.2.2 |
+| ENT-11 | MUST | 电池温度传感器存在 | `battery_temperature` 实体存在，单位 °C | §5.2.2 |
+| ENT-12 | MUST | 在线状态 Binary Sensor 存在 | `online` 实体存在，设备在线时为 ON | §5.2.2 |
+| ENT-13 | MUST | 错误码传感器存在 | `error_code` 实体存在，正常时为 0 | §5.2.2 |
+| ENT-14 | SHOULD | 错误码文案传感器存在 | `error_message` 实体存在，正常时显示 "Normal" | §5.2.6 |
+
+### 4.3 能量统计传感器 (Energy Dashboard)
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ENT-15 | MUST | 所有能量传感器 `device_class` 为 `energy` | `solar_energy`、`battery_charge_energy`、`battery_discharge_energy`、`grid_import_energy`、`grid_export_energy`、`eps_output_energy` 均为 `energy` | §5.2.2 |
+| ENT-16 | MUST | 所有能量传感器 `state_class` 为 `total_increasing` | 同上所有能量实体 | §5.2.2 |
+| ENT-17 | MUST | 能量传感器单位为 kWh | 同上所有能量实体单位正确 | §5.2.2 |
+| ENT-18 | MUST | 能量实体可被添加到 Energy Dashboard | 在 HA Energy Dashboard 配置中可选择上述实体，且数据正确展示 | §6.2 |
+
+### 4.4 Smart CT 传感器
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ENT-19 | MUST | 电网总功率传感器存在 | `grid_power` 实体存在，单位 W | §5.2.3 |
+| ENT-20 | MUST | 各相功率传感器存在（按实际相数） | 单相时仅 A 相实体；三相时 A/B/C 相实体均存在 | §5.2.3 |
+| ENT-21 | MUST | 各相电压传感器存在（按实际相数） | 电压实体存在，单位 V | §5.2.3 |
+| ENT-22 | MUST | 各相电流传感器存在（按实际相数） | 电流实体存在，单位 A | §5.2.3 |
+| ENT-23 | MUST | CT 能量统计传感器存在 | `grid_import_energy`、`grid_export_energy` 存在，适配 Energy Dashboard | §5.2.3 |
+| ENT-24 | MUST | 单相 CT 不创建 B/C 相实体 | 单相 CT 配置下，仅 A 相相关实体存在 | §5.2.3 |
+
+### 4.5 Smart Plug 传感器
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ENT-25 | MUST | 插座功率传感器存在 | `load_power` 实体存在，单位 W | §5.2.4 |
+| ENT-26 | MUST | 插座能量统计传感器存在 | `load_energy` 实体存在，kWh，`total_increasing` | §5.2.4 |
+| ENT-27 | MUST | 插座开关状态为只读 Binary Sensor | `switch_state` 为 Binary Sensor 类型，反映实际开/关状态 | §5.2.4 |
+| ENT-28 | MUST | 多个 Plug 各自独立 | 每个 Plug 有独立的 Device 与 Entity，数据互不混淆 | §5.2.4 |
+
+### 4.6 Device 信息
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ENT-29 | MUST | Device 名称含 SN 后 4 位 | 格式为 "Jackery DIY3 XXXX"、"Jackery Smart CT XXXX"、"Jackery Smart Plug XXXX" | §5.2.5 |
+| ENT-30 | MUST | 制造商显示为 Jackery | Device 信息中 manufacturer = "Jackery" | §5.2.5 |
+| ENT-31 | MUST | 子设备通过 `via_device` 关联到主机 | CT 和 Plug 的 Device 详情中显示所属主机 | §5.2.5 |
+
+---
+
+## 5. 只读安全约束
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| SEC-01 | MUST | 无 Switch 实体 | 集成中不存在任何 `switch.*` 类型实体 | §3 C-4 |
+| SEC-02 | MUST | 无 Number 实体 | 集成中不存在任何 `number.*` 类型实体 | §3 C-4 |
+| SEC-03 | MUST | 无 Button 实体 | 集成中不存在任何 `button.*` 类型实体 | §3 C-4 |
+| SEC-04 | MUST | 无 Select/Input 等可写实体 | 集成中不存在任何可触发设备端动作的实体 | §3 C-4 |
+| SEC-05 | MUST | Smart Plug 开关状态不可操控 | `switch_state` 为 Binary Sensor，用户在 HA 界面中无法执行开/关操作 | §5.2.4 |
+| SEC-06 | MUST | 集成不向设备发送任何控制指令 | 抓包验证：HA 通过 MQTT 仅发送数据请求（data_get），不发送任何控制类指令 | §3 C-4, C-5 |
+
+---
+
+## 6. 离线与异常处理
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| ERR-01 | MUST | 设备断网后 60 秒内标记为 Unavailable | 断开 DIY3 主机网络，超过 60 秒未收到 MQTT 消息后，该设备及子设备全部实体变为 `Unavailable` | §7.2 |
+| ERR-02 | MUST | 设备恢复后自动恢复 Available | 恢复网络连接后，收到设备 MQTT 消息时全部实体恢复为 `Available` | §7.2 |
+| ERR-03 | MUST | 子设备离线时对应实体标记为 Unavailable | 拔掉某个 Smart Plug，该 Plug 的实体标记为 `Unavailable`，其他设备不受影响 | §7.2 |
+| ERR-04 | MUST | 子设备重新上线后自动恢复 | 重新接入 Plug 后，对应实体恢复为 `Available` | §7.2 |
+| ERR-05 | MUST | Token 失效时提示重新认证 | 模拟 Token 失效（设备拒绝鉴权），HA 集成页面显示 "Reauthentication Required" | §7.2 |
+| ERR-06 | SHOULD | MQTT 消息格式异常时保持上次数据 | 模拟设备发送非法 JSON，传感器保持上次有效值，不显示错误值 | §7.2 |
+| ERR-07 | MUST | 设备离线不影响 HA 运行 | DIY3 主机离线时，HA 系统整体无卡顿或报错 | §7.3 |
+
+---
+
+## 7. 数据刷新与性能
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| PRF-01 | MUST | 数据请求间隔约 5 秒 | 观察传感器更新频率，相邻两次更新时间差约为 5 秒（±1 秒容差） | §7.1 |
+| PRF-02 | MUST | MQTT 消息端到端延迟 < 500ms | 局域网环境下，通过日志或网络抓包验证从发送请求到收到响应的延迟 | §7.3 |
+| PRF-03 | SHOULD | 单台设备 CPU 增量 < 1% | 添加一台设备前后对比 HA 主进程 CPU 占用 | §7.3 |
+| PRF-04 | SHOULD | 10 台设备场景内存占用 < 50MB | 配置 10 台设备后检查集成内存使用 | §7.3 |
+| PRF-05 | MUST | 60 秒无消息标记离线 | 模拟设备断网，验证超过 60 秒无 MQTT 消息后实体变为 Unavailable | §7.1 |
+
+---
+
+## 8. 云端共存
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| CLD-01 | MUST | HA 集成运行时 APP 仍可正常查看设备 | HA 持续通过 MQTT 接收数据期间，Jackery APP 可正常显示设备数据 | §3 C-3 |
+| CLD-02 | MUST | APP 操作不影响 HA 数据采集 | 通过 APP 执行操作（如调整 EMS 策略），HA 传感器数据不中断 | §3 C-3 |
+| CLD-03 | MUST | 断开互联网后 HA 本地数据不中断 | 断开路由器外网，HA 与设备通过本地 MQTT Broker 的通信不受影响 | §1.3 |
+
+---
+
+## 9. UI/UX 展示
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| UIX-01 | MUST | 设备页面结构正确 | 「设置 → 设备与服务 → Jackery」下显示设备列表，主机与子设备层级清晰 | §6.1 |
+| UIX-02 | MUST | 设备详情显示型号与 SN | 点击设备可看到型号、制造商、SN 等信息 | §6.1 |
+| UIX-03 | MUST | 实体列表完整 | 设备详情下展示该设备全部 Sensor 与 Binary Sensor 实体 | §6.1 |
+| UIX-04 | MUST | Energy Dashboard 可配置 | 在 HA Energy Dashboard 配置页中可找到并选择对应的能量实体 | §6.2 |
+| UIX-05 | MUST | Energy Dashboard 数据展示正确 | 配置后 Dashboard 正确显示太阳能、电池、电网的能量流数据 | §6.2 |
+
+---
+
+## 10. 兼容性
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| CMP-01 | MUST | HA 2024.6.0 上可正常运行 | 在 HA 2024.6.0 版本上安装并完成全流程 | §7.4 |
+| CMP-02 | SHOULD | HA 最新稳定版上可正常运行 | 在当前 HA 最新稳定版上安装并完成全流程 | §7.4 |
+| CMP-03 | MUST | HACS ≥ 2.0 可安装 | 通过 HACS 2.0+ 正常安装集成 | §7.4 |
+| CMP-04 | MUST | Jackery APP ≥ 2.10.18 可生成 Token | 使用满足版本要求的 APP 成功生成 Token 并完成配置 | §7.4 |
+
+---
+
+## 11. 授权流程端到端验证
+
+| 编号 | 级别 | 验收项 | 预期结果 | 对应 PRD |
+|------|------|--------|----------|----------|
+| AUTH-01 | MUST | APP 中可开启本地访问开关 | 在 Jackery APP 设备设置中可找到并开启「本地访问 / HA 集成」开关 | §2.3 步骤 1–3 |
+| AUTH-02 | MUST | APP 成功生成 Token 并可复制 | 开启开关后 APP 展示 Token 文本，支持一键复制 | §2.3 步骤 4–6 |
+| AUTH-03 | MUST | APP 显示设备 SN 与 MQTT Broker 配置 | Token 页面同时显示设备 SN，且可配置 MQTT Broker 地址与端口 | §2.3 步骤 4, 7 |
+| AUTH-04 | MUST | HA 中粘贴 Token 后验证成功 | 将 APP 中的 Token 粘贴到 HA Config Flow，验证通过并创建设备 | §2.3 步骤 8–12 |
+| AUTH-05 | MUST | 端到端全流程 ≤ 5 分钟完成 | 从打开 APP 到 HA 中看到设备数据，整个过程不超过 5 分钟 | §1.3 |
+
+---
+
+## 12. 验收检查清单汇总
+
+| 类别 | MUST 项 | SHOULD 项 | 合计 |
+|------|---------|-----------|------|
+| 安装与分发 | 3 | 1 | 4 |
+| 配置流程 | 10 | 3 | 13 |
+| 实体映射与数据 | 25 | 2 | 27 |
+| 只读安全约束 | 6 | 0 | 6 |
+| 离线与异常处理 | 5 | 1 | 6 |（ERR-07 已计入）
+| 数据刷新与性能 | 3 | 2 | 5 |
+| 云端共存 | 3 | 0 | 3 |
+| UI/UX 展示 | 5 | 0 | 5 |
+| 兼容性 | 3 | 1 | 4 |
+| 授权流程 | 5 | 0 | 5 |
+| **合计** | **68** | **10** | **78** |
+
+---
+
+## 附录：验收记录模板
+
+| 编号 | 验收项 | 测试人 | 测试日期 | 结果 (Pass/Fail/N/A) | 备注 |
+|------|--------|--------|----------|---------------------|------|
+| INS-01 | HACS 安装 | | | | |
+| INS-02 | 重启后集成可用 | | | | |
+| ... | ... | | | | |
+
+> 验收时请逐项填写上表，未通过项需附上问题描述与截图。
+
+---
+
+*文档结束*

docs/PRD.md

@@ -28,7 +28,7 @@ Jackery（华宝新能）最新一代户用储能产品 **DIY3** 面向全球市
 
 #### 数据主权 (Data Sovereignty)
 
-- 所有能源数据通过 **局域网 HTTP 直连** 获取，不依赖云端中转。
+- 所有能源数据通过 **局域网 MQTT** 获取，设备连接用户本地 MQTT Broker，不依赖云端中转。
 - 数据在用户自有 HA 实例内存储与处理，完全由用户掌控。
 - 即使互联网中断，本地数据采集与展示不受影响。
 
@@ -49,110 +49,123 @@ Jackery（华宝新能）最新一代户用储能产品 **DIY3** 面向全球市
 
 ### 2.1 整体架构描述
 
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                            用户家庭局域网                             │
-│                                                                      │
-│  ┌──────────────┐    HTTP/REST (局域网)    ┌─────────────────────┐   │
-│  │              │◄──────────────────────────│  Jackery DIY3 主机   │   │
-│  │  Home        │    mDNS 设备发现          │  ┌───────────────┐  │   │
-│  │  Assistant   │◄─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │  │ HTTP API      │  │   │
-│  │              │                           │  │ (Token Auth)  │  │   │
-│  │  ┌────────┐  │                           │  └───────────────┘  │   │
-│  │  │Jackery │  │                           │                     │   │
-│  │  │HACS    │  │                           │  ┌─────┐  ┌──────┐ │   │
-│  │  │集成     │  │                           │  │CT x1│  │Plug  │ │   │
-│  │  └────────┘  │                           │  │     │  │ x10  │ │   │
-│  └──────────────┘                           │  └─────┘  └──────┘ │   │
-│                                             └────────┬────────────┘   │
-└──────────────────────────────────────────────────────┼────────────────┘
-                                                       │
-                                              Cloud (独立通道)
-                                                       │
-                                                       ▼
-                                            ┌─────────────────────┐
-                                            │   Jackery Cloud     │
-                                            │   ┌─────────────┐   │
-                                            │   │ Jackery APP  │   │
-                                            │   └─────────────┘   │
-                                            └─────────────────────┘
+```mermaid
+graph TB
+    subgraph LAN["用户家庭局域网"]
+        subgraph HA["Home Assistant"]
+            MQTT_INT["MQTT 集成"]
+            HACS["Jackery HACS 集成"]
+            HACS --- MQTT_INT
+        end
+
+        BROKER["MQTT Broker\n(如 Mosquitto)"]
+
+        subgraph DIY3["Jackery DIY3 主机"]
+            CLIENT["MQTT Client\n(Token Auth)"]
+            subgraph SUB["子设备"]
+                CT["Smart CT ×1"]
+                PLUG["Smart Plug ×10"]
+            end
+            CLIENT --- CT
+            CLIENT --- PLUG
+        end
+
+        MQTT_INT -- "Subscribe\n(状态/事件主题)" --> BROKER
+        MQTT_INT -- "Publish\n(数据请求)" --> BROKER
+        CLIENT -- "Publish\n(状态/事件上报)" --> BROKER
+        CLIENT -- "Subscribe\n(指令主题)" --> BROKER
+        HACS -. "mDNS 设备发现" .-> DIY3
+    end
+
+    subgraph CLOUD["Jackery Cloud"]
+        APP["Jackery APP"]
+    end
+
+    DIY3 -- "Cloud 独立通道\n(互不干扰)" --> CLOUD
+
+    style LAN fill:#f0f8ff,stroke:#4a90d9,stroke-width:2px
+    style HA fill:#e8f5e9,stroke:#43a047,stroke-width:2px
+    style DIY3 fill:#fff8e1,stroke:#f9a825,stroke-width:2px
+    style CLOUD fill:#fce4ec,stroke:#e53935,stroke-width:2px
+    style SUB fill:#fff3e0,stroke:#ef6c00,stroke-width:1px
+    style BROKER fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
 ```
 
-### 2.2 架构要点
+### 2.2 前置条件（用户侧）
+
+Jackery 集成采用 **MQTT 协议** 通信，设备与 HA 之间需要一个 **本地 MQTT Broker** 作为消息中转。用户需在使用前完成以下准备：
+
+| 序号 | 前置条件 | 说明 | 责任方 |
+|------|----------|------|--------|
+| ① | **部署 MQTT Broker** | 用户需在局域网内运行一个 MQTT Broker。推荐使用 Home Assistant 官方的 **Mosquitto broker Add-on**（在 HA 的「设置 → 加载项 → 加载项商店」中安装），也可使用任何标准 MQTT Broker（如 EMQX、HiveMQ 等） | 用户 |
+| ② | **配置 HA 内置 MQTT 集成** | 在 HA 的「设置 → 设备与服务 → 添加集成」中搜索并配置 **MQTT** 集成，填写 Broker 地址、端口、用户名/密码（如有），确保 HA 成功连接到 Broker | 用户 |
+| ③ | **在 Jackery APP 中配置 MQTT 地址** | 在 APP 的设备设置中开启「本地访问 / HA 集成」，输入步骤 ① 中 Broker 的 **IP 地址与端口**，使设备连接到同一个 Broker | 用户 |
+| ④ | **确保网络互通** | HA 运行设备、MQTT Broker、Jackery DIY3 主机三者需处于 **同一局域网**（或网络可达） | 用户 |
+
+> **为什么需要用户自建 MQTT Broker？**
+>
+> Jackery 集成采用 **Local First** 架构，所有数据在用户本地网络内流转，不经过任何云端服务。MQTT Broker 是实现本地发布/订阅通信的核心组件。Home Assistant 官方提供了开箱即用的 Mosquitto Add-on，安装仅需点击几下，绝大多数用户无需额外配置。
+
+### 2.3 架构要点
 
 | 要点 | 说明 |
 |------|------|
-| **连接方式** | HA 通过局域网 HTTP/REST API 直连 DIY3 主机，Token 鉴权 |
-| **设备发现** | 支持 mDNS 自动发现局域网内的 DIY3 设备，同时支持手动输入 IP |
-| **数据获取** | HA 定时轮询 DIY3 主机的 HTTP API，获取主机及全部子设备数据 |
+| **连接方式** | 设备与 HA 通过局域网内的 MQTT Broker 通信，Token 鉴权 |
+| **MQTT Broker** | 用户自行部署（推荐 HA Mosquitto Add-on），Jackery 集成依赖 HA 内置 MQTT 集成与 Broker 通信 |
+| **设备发现** | 支持 mDNS 自动发现局域网内的 DIY3 设备，同时支持手动输入设备 SN |
+| **数据获取** | 设备通过 MQTT 主动上报状态与事件数据；HA 集成定时通过 MQTT 发送数据请求指令（5 秒间隔），获取主机及全部子设备数据 |
 | **云端共存** | DIY3 主机同时保持与 Jackery Cloud 的独立连接，APP 功能不受影响 |
-| **子设备拓扑** | Smart CT 和 Smart Plug 通过主机内部协议连接，HA 仅与主机通信；主机负责聚合子设备数据，统一通过 HTTP API 返回 |
+| **子设备拓扑** | Smart CT 和 Smart Plug 通过主机内部协议连接，HA 仅与主机通信；主机负责聚合子设备数据，统一通过 MQTT 上报 |
 | **安全策略** | 本版本严格只读，仅提供 Sensor 与 Binary Sensor，不包含任何控制类实体 |
 
-### 2.3 授权流程
+### 2.4 授权流程
 
-以下描述用户从零开始完成授权的完整流程：
+> **前提**：用户已完成 §2.2 中的前置条件（MQTT Broker 已部署、HA MQTT 集成已配置）。
 
-```
-┌─────────┐          ┌─────────────┐          ┌──────────────┐
-│  用户    │          │ Jackery APP │          │ Home Assistant│
-└────┬────┘          └──────┬──────┘          └──────┬───────┘
-     │                      │                        │
-     │  1. 打开 APP 设备页  │                        │
-     │─────────────────────>│                        │
-     │                      │                        │
-     │  2. 进入"HA 集成"    │                        │
-     │     设置页面         │                        │
-     │─────────────────────>│                        │
-     │                      │                        │
-     │  3. 开启 "MQTT/本地  │                        │
-     │     访问" 开关       │                        │
-     │─────────────────────>│                        │
-     │                      │                        │
-     │                      │  4. APP 生成一次性     │
-     │                      │     Local Access Token │
-     │                      │  5. 设备固件启用       │
-     │                      │     HTTP API 服务      │
-     │                      │──────────────────────> │
-     │                      │                (设备端) │
-     │  6. APP 展示 Token   │                        │
-     │     供用户复制       │                        │
-     │<─────────────────────│                        │
-     │                      │                        │
-     │  7. 打开 HA，添加    │                        │
-     │     Jackery 集成     │                        │
-     │─────────────────────────────────────────────>│
-     │                      │                        │
-     │  8. HA 通过 mDNS     │                        │
-     │     发现设备（或手   │                        │
-     │     动输入 IP）      │                        │
-     │─────────────────────────────────────────────>│
-     │                      │                        │
-     │  9. 输入 Token       │                        │
-     │─────────────────────────────────────────────>│
-     │                      │                        │
-     │                      │       10. HA 以 Token  │
-     │                      │       调用设备 HTTP    │
-     │                      │       API 验证连通性   │
-     │                      │<───────────────────────│
-     │                      │                        │
-     │  11. 验证成功，自动  │                        │
-     │      创建设备与实体  │                        │
-     │<─────────────────────────────────────────────│
-     │                      │                        │
-     │  ✅ 完成配置          │                        │
+以下描述用户从零开始完成设备授权与集成配置的完整流程：
+
+```mermaid
+sequenceDiagram
+    actor User as 用户
+    participant APP as Jackery APP
+    participant Device as DIY3 设备
+    participant HA as Home Assistant
+
+    rect rgb(240, 248, 255)
+        Note over User, APP: 阶段一：APP 端授权
+        User->>APP: 1. 打开 APP，进入设备页
+        User->>APP: 2. 进入「HA 集成 / 本地访问」设置页
+        User->>APP: 3. 开启「MQTT / 本地访问」开关
+        User->>APP: 4. 输入 MQTT Broker 地址与端口
+        APP->>Device: 5. 下发指令：生成 Token，启用 MQTT
+        Device-->>APP: 确认：MQTT 已连接 Broker
+        APP-->>User: 6. 展示 Token 与设备 SN（支持复制）
+    end
+
+    rect rgb(232, 245, 233)
+        Note over User, HA: 阶段二：HA 端配置
+        User->>HA: 7. 添加 Jackery 集成
+        User->>HA: 8. 选择已发现设备（mDNS）或手动输入 SN
+        User->>HA: 9. 粘贴 Token
+        HA->>Device: 10. 通过 MQTT 订阅设备主题，验证连通性
+        Device-->>HA: 返回设备状态数据
+        HA-->>User: 11. 验证成功，自动创建设备与实体
+    end
+
+    Note over User, HA: ✅ 配置完成，数据开始流入 HA
 ```
 
 **授权流程分步说明：**
 
 | 步骤 | 执行方 | 动作 |
 |------|--------|------|
-| 1–3 | 用户 → APP | 在 Jackery APP 中找到目标设备，进入「Home Assistant / 本地访问」设置页，打开本地访问开关 |
-| 4–5 | APP → 设备 | APP 向设备下发指令，生成一次性 Local Access Token 并启用设备端 HTTP API 服务 |
-| 6 | APP → 用户 | APP 界面展示 Token（支持复制），同时显示设备 IP 地址 |
-| 7–9 | 用户 → HA | 在 HA 中添加 Jackery 集成，选择已发现设备（或手动输入 IP），粘贴 Token |
-| 10 | HA → 设备 | HA 使用 Token 调用设备 HTTP API 进行连通性与鉴权验证 |
-| 11 | HA | 验证通过后自动识别设备型号，创建 Device 及全部 Sensor 实体 |
+| 1–3 | 用户 → APP | 在 Jackery APP 中找到目标设备，进入「Home Assistant / 本地访问」设置页，打开 MQTT/本地访问开关 |
+| 4 | 用户 → APP | 在 APP 中输入本地 MQTT Broker 地址与端口（即 HA 所在机器的 IP 和 Mosquitto 端口） |
+| 5–6 | APP → 设备 | APP 向设备下发指令，生成一次性 Local Access Token，设备启用 MQTT 功能并连接用户本地 Broker |
+| 7 | APP → 用户 | APP 界面展示 Token 与设备 SN（支持复制） |
+| 8–10 | 用户 → HA | 在 HA 中添加 Jackery 集成，选择已发现设备（或手动输入设备 SN），粘贴 Token |
+| 11 | HA → 设备 | HA 通过 MQTT 订阅设备主题，验证连通性与 Token 鉴权 |
+| 12 | HA | 验证通过后自动识别设备型号，创建 Device 及全部 Sensor 实体 |
 
 > **注意**：当前版本 Token 无过期机制，也不支持续期。后续版本将考虑 Token 生命周期管理（见第 9 节路线图）。
 
@@ -165,7 +178,7 @@ Jackery（华宝新能）最新一代户用储能产品 **DIY3** 面向全球市
 | 编号 | 约束 | 说明 |
 |------|------|------|
 | C-1 | **HACS 分发** | 以 Custom Component 形式通过 HACS 安装，不进入 HA 官方核心库 |
-| C-2 | **Local First** | 优先局域网 HTTP 直连，确保低延迟与断网可用 |
+| C-2 | **Local First** | 通过局域网本地 MQTT Broker 通信，确保低延迟与断网可用 |
 | C-3 | **云端共存** | 本地连接不影响设备与 Jackery Cloud 的通信，APP 功能完整 |
 | C-4 | **严格只读** | 本版本 **禁止任何控制操作**。不得包含 Switch、Number、Button 等可写实体，仅提供 Sensor 与 Binary Sensor |
 | C-5 | **不暴露 EMS** | 能源管理策略（充电优先级、市电互补等）由设备端黑盒处理，HA 仅展示最终状态 |
@@ -179,7 +192,7 @@ Jackery（华宝新能）最新一代户用储能产品 **DIY3** 面向全球市
 
 | 设备 | 类型 | 数量限制 | 连接方式 |
 |------|------|----------|----------|
-| **DIY3 主机** | 储能主机 | 每条集成配置对应 1 台主机；同一 HA 支持添加多台 | 局域网 HTTP 直连 |
+| **DIY3 主机** | 储能主机 | 每条集成配置对应 1 台主机；同一 HA 支持添加多台 | 通过局域网 MQTT Broker 通信 |
 | **Smart CT** | 智能互感器 | 每台主机最多 1 台 | 通过主机内部协议连接，数据由主机聚合上报 |
 | **Smart Plug** | 智能插座 | 每台主机最多 10 个 | 通过主机内部协议连接，数据由主机聚合上报 |
 
@@ -207,28 +220,37 @@ Jackery（华宝新能）最新一代户用储能产品 **DIY3** 面向全球市
 
 #### 5.1.1 流程设计
 
-```
-┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐     ┌──────────────┐
-│  添加集成    │────>│  设备发现        │────>│  输入 Token     │────>│  验证与创建  │
-│              │     │  (mDNS 列表     │     │                 │     │  设备/实体   │
-│              │     │   或手动输入 IP) │     │                 │     │              │
-└──────────────┘     └──────────────────┘     └─────────────────┘     └──────────────┘
+```mermaid
+flowchart LR
+    A["添加集成"] --> B["设备发现\n(mDNS 列表\n或手动输入 SN)"]
+    B --> C["输入 Token\n(可选填主题前缀)"]
+    C --> D{"MQTT\n验证"}
+    D -- "成功" --> E["自动创建\n设备与实体"]
+    D -- "失败" --> F["显示错误提示\n(见 5.1.3)"]
+    F --> B
+
+    style A fill:#e3f2fd,stroke:#1565c0
+    style B fill:#e3f2fd,stroke:#1565c0
+    style C fill:#e3f2fd,stroke:#1565c0
+    style D fill:#fff8e1,stroke:#f9a825
+    style E fill:#e8f5e9,stroke:#43a047
+    style F fill:#fce4ec,stroke:#e53935
 ```
 
 #### 5.1.2 Config Flow 步骤
 
 | 步骤 | 名称 | 说明 |
 |------|------|------|
-| Step 1 | 设备选择 | 展示通过 mDNS 发现的 DIY3 设备列表（显示设备名称 + IP），同时提供「手动输入 IP」选项 |
-| Step 2 | Token 输入 | 用户粘贴从 Jackery APP 获取的 Local Access Token |
-| Step 3 | 连接验证 | 集成以 Token 调用设备 HTTP API 验证连通性与鉴权；失败时显示明确错误信息（见 5.1.3） |
+| Step 1 | 设备选择 | 展示通过 mDNS 发现的 DIY3 设备列表（显示设备名称 + SN），同时提供「手动输入设备 SN」选项 |
+| Step 2 | Token 输入 | 用户粘贴从 Jackery APP 获取的 Local Access Token，可选填 MQTT 主题前缀（默认 `hb`） |
+| Step 3 | 连接验证 | 集成通过 MQTT 订阅设备主题，验证连通性与 Token 鉴权；失败时显示明确错误信息（见 5.1.3） |
 | Step 4 | 设备创建 | 验证成功后自动识别设备型号及已连接的子设备（CT、Plug），创建 Device 与全部 Sensor 实体 |
 
 #### 5.1.3 错误处理
 
 | 错误场景 | 错误码 | 用户提示文案 |
 |----------|--------|-------------|
-| 设备 IP 不可达 | `cannot_connect` | "无法连接到设备，请检查设备是否在线且与 Home Assistant 在同一局域网内" |
+| MQTT 不可用或设备不可达 | `cannot_connect` | "无法连接到设备，请检查：1) MQTT 集成已配置并连接到 Broker；2) 设备已在 APP 中开启本地访问并连接到同一 Broker" |
 | Token 无效 | `invalid_auth` | "Token 验证失败，请检查 Token 是否正确。可在 Jackery APP 中重新生成" |
 | 设备已被添加 | `already_configured` | "该设备已添加到 Home Assistant" |
 | 设备不支持 | `unsupported_device` | "该设备型号暂不支持，请确认固件已更新至最新版本" |
@@ -238,7 +260,7 @@ Jackery（华宝新能）最新一代户用储能产品 **DIY3** 面向全球市
 
 - **不限制实例数量**：用户可重复执行配置流程添加多台 DIY3 主机。
 - 每台主机为独立的 HA Device，其下挂载的 CT 和 Plug 为子设备。
-- 各主机使用独立的 HTTP 连接与轮询任务，互不影响。
+- 各主机使用独立的 MQTT 主题订阅与数据请求任务，互不影响。
 
 ### 5.2 实体映射 (Entity Mapping)
 
@@ -249,7 +271,7 @@ sensor.jackery_{device_sn}_{entity_key}
 binary_sensor.jackery_{device_sn}_{entity_key}
 ```
 
-- `device_sn`：设备序列号，自动从设备 API 获取，全小写，特殊字符替换为下划线。
+- `device_sn`：设备序列号，自动从 MQTT 消息中获取，全小写，特殊字符替换为下划线。
 - `entity_key`：实体标识，采用 `snake_case`，与下方表格中的 Key 列对应。
 - 子设备 Entity ID 格式：`sensor.jackery_{sub_device_sn}_{entity_key}`
 
@@ -265,110 +287,44 @@ binary_sensor.jackery_diy3a12345_online
 
 #### 5.2.2 DIY3 主机实体
 
-**功率传感器 (实时功率)**
+DIY3 主机提供以下四类传感器，覆盖实时监控与长期统计需求：
 
-| Key | 名称 | 单位 | device_class | state_class | 图标 | 说明 |
-|-----|------|------|-------------|-------------|------|------|
-| `solar_power` | Solar Power | W | `power` | `measurement` | `mdi:solar-power` | 光伏总输入功率 |
-| `solar_power_pv1` | Solar Power PV1 | W | `power` | `measurement` | `mdi:solar-panel` | PV1 通道输入功率 |
-| `solar_power_pv2` | Solar Power PV2 | W | `power` | `measurement` | `mdi:solar-panel` | PV2 通道输入功率 |
-| `battery_charge_power` | Battery Charge Power | W | `power` | `measurement` | `mdi:battery-charging` | 电池充电功率 |
-| `battery_discharge_power` | Battery Discharge Power | W | `power` | `measurement` | `mdi:battery-minus` | 电池放电功率 |
-| `grid_import_power` | Grid Import Power | W | `power` | `measurement` | `mdi:transmission-tower-import` | 市电输入（购电）功率 |
-| `grid_export_power` | Grid Export Power | W | `power` | `measurement` | `mdi:transmission-tower-export` | 馈网输出（售电）功率 |
-| `eps_output_power` | EPS Output Power | W | `power` | `measurement` | `mdi:power-plug` | EPS 离网输出功率 |
-| `home_power` | Home Power | W | `power` | `measurement` | `mdi:home-lightning-bolt` | 家庭用电功率（计算值） |
-
-**电池状态**
-
-| Key | 名称 | 单位 | device_class | state_class | 图标 | 说明 |
-|-----|------|------|-------------|-------------|------|------|
-| `battery_soc` | Battery SOC | % | `battery` | `measurement` | `mdi:battery` | 电池剩余电量百分比 |
-| `battery_soh` | Battery SOH | % | — | `measurement` | `mdi:battery-heart-variant` | 电池健康度 |
-| `battery_temperature` | Battery Temperature | °C | `temperature` | `measurement` | `mdi:thermometer` | 电池温度 |
-| `battery_count` | Battery Count | — | — | `measurement` | `mdi:battery-multiple` | 已连接电池包数量 |
-
-**能量统计 (Energy Dashboard 适配)**
-
-| Key | 名称 | 单位 | device_class | state_class | 图标 | 说明 |
-|-----|------|------|-------------|-------------|------|------|
-| `solar_energy` | Solar Energy | kWh | `energy` | `total_increasing` | `mdi:solar-power` | 光伏累计发电量 |
-| `battery_charge_energy` | Battery Charge Energy | kWh | `energy` | `total_increasing` | `mdi:battery-plus` | 电池累计充电量 |
-| `battery_discharge_energy` | Battery Discharge Energy | kWh | `energy` | `total_increasing` | `mdi:battery-minus` | 电池累计放电量 |
-| `grid_import_energy` | Grid Import Energy | kWh | `energy` | `total_increasing` | `mdi:transmission-tower-import` | 累计购电量 |
-| `grid_export_energy` | Grid Export Energy | kWh | `energy` | `total_increasing` | `mdi:transmission-tower-export` | 累计馈网电量 |
-| `eps_output_energy` | EPS Output Energy | kWh | `energy` | `total_increasing` | `mdi:power-plug` | EPS 累计输出电量 |
-
-**运行状态**
-
-| Key | 名称 | 类型 | device_class | 图标 | 说明 |
-|-----|------|------|-------------|------|------|
-| `online` | Online | `binary_sensor` | `connectivity` | `mdi:lan-connect` | 设备在线状态（基于 HTTP 响应） |
-| `error_code` | Error Code | `sensor` | — | `mdi:alert-circle` | 当前错误码，无错误时为 0 |
-| `error_message` | Error Message | `sensor` | — | `mdi:alert-circle-outline` | 错误码对应的可读描述（见 5.2.6） |
+- **实时功率**：光伏总输入及分路功率、电池充/放电功率、市电购电/馈网功率、EPS 离网输出功率、家庭用电功率（计算值）。
+- **电池状态**：SOC（剩余电量百分比）、SOH（健康度）、电池温度、已连接电池包数量。
+- **能量统计**：光伏累计发电量、电池累计充/放电量、累计购电量、累计馈网电量、EPS 累计输出电量。所有能量传感器均适配 HA **Energy Dashboard**。
+- **运行状态**：在线/离线状态（Binary Sensor）、当前错误码及可读描述。
 
 #### 5.2.3 Smart CT 实体
 
-| Key | 名称 | 单位 | device_class | state_class | 图标 | 说明 |
-|-----|------|------|-------------|-------------|------|------|
-| `grid_power` | Grid Power | W | `power` | `measurement` | `mdi:current-ac` | 电网总有功功率（正=购电，负=馈电） |
-| `phase_a_power` | Phase A Power | W | `power` | `measurement` | `mdi:current-ac` | A 相有功功率 |
-| `phase_b_power` | Phase B Power | W | `power` | `measurement` | `mdi:current-ac` | B 相有功功率（三相时） |
-| `phase_c_power` | Phase C Power | W | `power` | `measurement` | `mdi:current-ac` | C 相有功功率（三相时） |
-| `phase_a_voltage` | Phase A Voltage | V | `voltage` | `measurement` | `mdi:flash` | A 相电压 |
-| `phase_b_voltage` | Phase B Voltage | V | `voltage` | `measurement` | `mdi:flash` | B 相电压（三相时） |
-| `phase_c_voltage` | Phase C Voltage | V | `voltage` | `measurement` | `mdi:flash` | C 相电压（三相时） |
-| `phase_a_current` | Phase A Current | A | `current` | `measurement` | `mdi:current-ac` | A 相电流 |
-| `phase_b_current` | Phase B Current | A | `current` | `measurement` | `mdi:current-ac` | B 相电流（三相时） |
-| `phase_c_current` | Phase C Current | A | `current` | `measurement` | `mdi:current-ac` | C 相电流（三相时） |
-| `grid_import_energy` | Grid Import Energy | kWh | `energy` | `total_increasing` | `mdi:transmission-tower-import` | 累计正向（购电）电量 |
-| `grid_export_energy` | Grid Export Energy | kWh | `energy` | `total_increasing` | `mdi:transmission-tower-export` | 累计反向（馈网）电量 |
+Smart CT 提供电网侧的电气监测数据：
 
-> **注意**：单相配置时，B/C 相实体将不被创建；集成根据设备 API 返回的 CT 类型自动判断。
+- **功率**：电网总有功功率，以及各相（A/B/C）有功功率。
+- **电压与电流**：各相电压 (V)、电流 (A)。
+- **能量统计**：累计正向（购电）电量、累计反向（馈网）电量，适配 Energy Dashboard。
+
+> 单相配置时仅创建 A 相实体；三相配置时自动创建 A/B/C 三相实体，由设备 API 返回的 CT 类型决定。
 
 #### 5.2.4 Smart Plug 实体
 
-| Key | 名称 | 单位 | device_class | state_class | 图标 | 说明 |
-|-----|------|------|-------------|-------------|------|------|
-| `load_power` | Load Power | W | `power` | `measurement` | `mdi:power-socket-eu` | 插座负载实时功率 |
-| `load_energy` | Load Energy | kWh | `energy` | `total_increasing` | `mdi:lightning-bolt` | 插座累计用电量 |
-| `switch_state` | Switch State | — | `binary_sensor` / `power` | — | `mdi:toggle-switch` | 插座开关状态（只读展示，1=开/0=关） |
+Smart Plug 提供单一负载的用电监测：
 
-> **注意**：`switch_state` 为 **Binary Sensor**，仅展示当前开关状态，用户 **不可** 在 HA 中操控。
+- **实时功率**：插座负载功率 (W)。
+- **能量统计**：插座累计用电量 (kWh)，适配 Energy Dashboard。
+- **开关状态**：以 Binary Sensor 只读展示当前开关状态（开/关），用户 **不可** 在 HA 中操控。
 
 #### 5.2.5 HA Device 信息
 
-每个设备在 HA 中注册的 Device 信息如下：
+- 每个设备在 HA 中注册为独立 Device，以序列号 (SN) 唯一标识。
+- 设备显示名称格式：`Jackery {型号} {SN 后 4 位}`（如 "Jackery DIY3 2345"）。
+- Smart CT 与 Smart Plug 通过 `via_device` 关联到所属 DIY3 主机，形成设备树。
 
-| 字段 | DIY3 主机 | Smart CT | Smart Plug |
-|------|-----------|----------|------------|
-| `name` | Jackery DIY3 {SN 后 4 位} | Jackery Smart CT {SN 后 4 位} | Jackery Smart Plug {SN 后 4 位} |
-| `manufacturer` | Jackery | Jackery | Jackery |
-| `model` | DIY3 | Smart CT | Smart Plug |
-| `identifiers` | `(DOMAIN, device_sn)` | `(DOMAIN, ct_sn)` | `(DOMAIN, plug_sn)` |
-| `via_device` | — | 所属 DIY3 主机 | 所属 DIY3 主机 |
+#### 5.2.6 错误码
 
-#### 5.2.6 错误码定义
+- 设备端上报数字错误码，集成内置映射表将其翻译为用户可读的描述文案。
+- 错误码分为 Warning（警告）与 Error（故障）两个级别，涵盖电池异常、光伏异常、电网异常、逆变器异常、子设备通讯丢失等类别。
+- 未识别的错误码统一展示为 "Unknown Error ({code})"。
 
-| 错误码 | 级别 | 描述 (error_message) | 说明 |
-|--------|------|---------------------|------|
-| 0 | — | "Normal" | 正常运行 |
-| 1001 | Warning | "Battery Over Temperature" | 电池温度过高 |
-| 1002 | Warning | "Battery Under Temperature" | 电池温度过低 |
-| 1003 | Error | "Battery Over Voltage" | 电池过压保护 |
-| 1004 | Error | "Battery Under Voltage" | 电池欠压保护 |
-| 1005 | Error | "Battery Communication Error" | 电池通讯异常 |
-| 2001 | Warning | "PV Over Voltage" | 光伏过压 |
-| 2002 | Warning | "PV Reverse Connection" | 光伏反接 |
-| 3001 | Error | "Grid Frequency Abnormal" | 电网频率异常 |
-| 3002 | Error | "Grid Voltage Abnormal" | 电网电压异常 |
-| 4001 | Error | "Inverter Over Temperature" | 逆变器过温 |
-| 4002 | Error | "Inverter Overload" | 逆变器过载 |
-| 5001 | Warning | "CT Communication Lost" | CT 通讯丢失 |
-| 5002 | Warning | "Plug Communication Lost" | 插座通讯丢失 |
-| 9999 | Error | "Unknown Error" | 未知错误 |
-
-> 以上错误码为建议定义，实际以设备固件返回的错误码为准。集成内置映射表负责翻译为可读文案；未映射码统一展示为 `Unknown Error ({code})`。
+> 详细的实体字段定义（含 Key、单位、device_class、state_class 等）与错误码映射表见技术设计文档。
 
 ---
 
@@ -382,17 +338,92 @@ binary_sensor.jackery_diy3a12345_online
 - **设备详情**：显示设备型号、SN、固件版本（如有）、在线状态。
 - **实体列表**：该设备下的全部 Sensor 与 Binary Sensor。
 
-### 6.2 Energy Dashboard 适配
+### 6.2 Home Energy Management 适配
 
-以下实体可直接配置到 HA 原生 **Energy Dashboard**：
+HA 内置的 [Home Energy Management](https://www.home-assistant.io/docs/energy/) 是 Jackery 集成的核心展示场景。该模块支持电网、太阳能、电池、独立设备四大能源维度，Jackery 集成需 **全面适配** 以下各项。
 
-| Dashboard 栏位 | 对应实体 |
-|----------------|----------|
-| Solar Production | `sensor.jackery_{sn}_solar_energy` |
-| Battery Systems — Energy going in | `sensor.jackery_{sn}_battery_charge_energy` |
-| Battery Systems — Energy coming out | `sensor.jackery_{sn}_battery_discharge_energy` |
-| Grid — Consumption | `sensor.jackery_{sn}_grid_import_energy` 或 CT 的 `grid_import_energy` |
-| Grid — Return to grid | `sensor.jackery_{sn}_grid_export_energy` 或 CT 的 `grid_export_energy` |
+#### 6.2.1 适配总览
+
+```mermaid
+flowchart TB
+    subgraph HA_ENERGY["HA Home Energy Management"]
+        GRID["Electricity Grid\n电网用电"]
+        SOLAR["Solar Panels\n太阳能"]
+        BATTERY["Home Batteries\n家庭电池"]
+        INDIVIDUAL["Individual Devices\n独立设备"]
+    end
+
+    subgraph JACKERY["Jackery 集成提供的实体"]
+        J_GRID_IN["grid_import_energy\n(购电量)"]
+        J_GRID_OUT["grid_export_energy\n(馈网量)"]
+        J_SOLAR["solar_energy\n(光伏发电量)"]
+        J_BAT_IN["battery_charge_energy\n(充电量)"]
+        J_BAT_OUT["battery_discharge_energy\n(放电量)"]
+        J_PLUG["Smart Plug load_energy\n(插座用电量)"]
+    end
+
+    J_GRID_IN --> GRID
+    J_GRID_OUT --> GRID
+    J_SOLAR --> SOLAR
+    J_BAT_IN --> BATTERY
+    J_BAT_OUT --> BATTERY
+    J_PLUG --> INDIVIDUAL
+
+    style HA_ENERGY fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
+    style JACKERY fill:#fff8e1,stroke:#f9a825,stroke-width:2px
+```
+
+#### 6.2.2 Electricity Grid（电网用电）
+
+HA Energy Dashboard 的电网模块需要区分 **从电网购入的电量** 与 **向电网馈出的电量**。
+
+| Dashboard 配置项 | 对应 Jackery 实体 | 数据来源 | 要求 |
+|-----------------|------------------|----------|------|
+| Grid consumption (购电) | `sensor.jackery_{sn}_grid_import_energy` | DIY3 主机上报 或 Smart CT 正向电量 | `device_class: energy`, `state_class: total_increasing`, 单位 kWh |
+| Return to grid (馈网) | `sensor.jackery_{sn}_grid_export_energy` | DIY3 主机上报 或 Smart CT 反向电量 | 同上 |
+
+> **Smart CT 优先**：当 Smart CT 已连接时，建议用户优先使用 CT 的 `grid_import_energy` / `grid_export_energy`，因为 CT 直接安装在电表侧，数据更准确。
+
+#### 6.2.3 Solar Panels（太阳能）
+
+| Dashboard 配置项 | 对应 Jackery 实体 | 要求 |
+|-----------------|------------------|------|
+| Solar production (发电量) | `sensor.jackery_{sn}_solar_energy` | `device_class: energy`, `state_class: total_increasing`, 单位 kWh |
+
+> 用户也可同时配置 `solar_power`（实时功率 W）用于 Energy Dashboard 的功率展示（HA 2024.x 起支持在 Energy Dashboard 中配置 `state_class: measurement` 的功率传感器）。
+
+#### 6.2.4 Home Batteries（家庭电池）
+
+HA 的电池模块需要 **充电电量** 和 **放电电量** 两个传感器。
+
+| Dashboard 配置项 | 对应 Jackery 实体 | 要求 |
+|-----------------|------------------|------|
+| Energy going in to battery (充电) | `sensor.jackery_{sn}_battery_charge_energy` | `device_class: energy`, `state_class: total_increasing`, 单位 kWh |
+| Energy coming out of battery (放电) | `sensor.jackery_{sn}_battery_discharge_energy` | 同上 |
+
+> **电池 SOC 展示**：虽然 Energy Dashboard 本身不直接使用 SOC，但用户可在 Dashboard 卡片或自动化中使用 `battery_soc` 传感器，了解当前电池状态。
+
+#### 6.2.5 Individual Devices（独立设备）
+
+每个 Smart Plug 的用电量可作为独立设备接入 Energy Dashboard，让用户追踪单一负载的能耗。
+
+| Dashboard 配置项 | 对应 Jackery 实体 | 要求 |
+|-----------------|------------------|------|
+| Individual device (单个插座) | `sensor.jackery_{plug_sn}_load_energy` | `device_class: energy`, `state_class: total_increasing`, 单位 kWh |
+
+> 每个 Smart Plug 可独立添加为一个 Individual Device，最多支持 10 个。
+
+#### 6.2.6 实体技术要求汇总
+
+为确保所有能量传感器均能被 HA Energy Dashboard 自动识别，必须满足以下技术要求：
+
+| 要求 | 说明 |
+|------|------|
+| `device_class` | 必须为 `energy` |
+| `state_class` | 必须为 `total_increasing`（累计递增值，HA 自动处理归零/重置） |
+| `native_unit_of_measurement` | 必须为 `kWh` |
+| 数据连续性 | 设备重启或离线恢复后，累计值应从上次值继续递增而非归零 |
+| 更新频率 | 能量值至少每 **60 秒** 更新一次（推荐随功率数据同步更新，即 5 秒） |
 
 ---
 
@@ -402,36 +433,38 @@ binary_sensor.jackery_diy3a12345_online
 
 | 参数 | 值 | 说明 |
 |------|-----|------|
-| 轮询间隔 | **5 秒** | 通过 HTTP GET 定时拉取设备 API，兼顾实时性与资源占用 |
-| 协议 | HTTP/REST | 局域网直连，请求-响应模式 |
-| 超时设置 | 单次请求超时 **5 秒** | 超时后标记本次请求失败，等待下次轮询 |
+| 数据请求间隔 | **5 秒** | 集成通过 MQTT 定时发送数据请求指令，兼顾实时性与资源占用 |
+| 协议 | MQTT | 通过局域网本地 MQTT Broker，发布/订阅模式 |
+| 离线判定 | **60 秒** 无数据 | 超过 60 秒未收到设备 MQTT 消息，标记设备离线 |
 
 ### 7.2 离线与异常处理
 
 | 场景 | 处理策略 |
 |------|----------|
-| 设备网络不可达 | 连续 **3 次** 轮询失败（约 15 秒）后将该设备及其子设备全部实体标记为 `Unavailable` |
-| 设备恢复在线 | 下一次轮询成功后自动恢复所有实体状态为 `Available` |
-| 子设备离线 | CT 或 Plug 从设备 API 返回中消失时，对应实体标记为 `Unavailable`；重新出现时恢复 |
-| Token 失效 | API 返回 401/403 时，记录日志并在 HA 集成页面显示 **"Reauthentication Required"** 提示 |
-| API 格式异常 | 解析失败时保持上一次有效数据，记录 warning 日志 |
+| 设备无 MQTT 消息 | 超过 **60 秒** 未收到设备上报数据，将该设备及其子设备全部实体标记为 `Unavailable` |
+| 设备恢复在线 | 收到设备 MQTT 消息后自动恢复所有实体状态为 `Available` |
+| 子设备离线 | CT 或 Plug 从设备 MQTT 消息中消失时，对应实体标记为 `Unavailable`；重新出现时恢复 |
+| Token 失效 | 设备拒绝 Token 鉴权时，记录日志并在 HA 集成页面显示 **"Reauthentication Required"** 提示 |
+| MQTT Broker 不可用 | 集成记录 warning 日志，待 Broker 恢复后自动重新订阅 |
+| 消息格式异常 | JSON 解析失败时保持上一次有效数据，记录 warning 日志 |
 
 ### 7.3 性能要求
 
 | 指标 | 目标值 |
 |------|--------|
-| 单次 API 请求耗时 | < 500ms（局域网环境） |
+| MQTT 消息端到端延迟 | < 500ms（局域网环境） |
 | 内存占用 | < 50MB（10 台设备场景） |
-| CPU 影响 | 单台设备轮询对 HA 主进程 CPU 增量 < 1% |
+| CPU 影响 | 单台设备 MQTT 订阅对 HA 主进程 CPU 增量 < 1% |
 
 ### 7.4 兼容性
 
 | 项目 | 要求 |
 |------|------|
-| Home Assistant 最低版本 | **2024.6.0**（需 mDNS 发现与最新 ConfigFlow API 支持） |
+| Home Assistant 最低版本 | **2024.6.0**（需 MQTT 集成与最新 ConfigFlow API 支持） |
+| MQTT 集成 | HA 内置 MQTT 集成需预先配置并连接到本地 Broker |
 | Python 版本 | ≥ 3.12（随 HA 版本要求） |
 | HACS 版本 | ≥ 2.0 |
-| 设备固件 | 需设备端固件支持本地 HTTP API（由 Jackery APP ≥ 2.10.18 触发启用） |
+| 设备固件 | 需设备端固件支持本地 MQTT 功能（由 Jackery APP ≥ 2.10.18 触发启用） |
 
 ---
 
@@ -451,7 +484,7 @@ binary_sensor.jackery_diy3a12345_online
 | 限制 | 说明 | 影响 |
 |------|------|------|
 | Token 无续期 | 当前 Token 一次性生成，无过期与续期机制 | 若 Token 泄露，需用户在 APP 重新生成 |
-| 无 TLS 加密 | 当前本地 HTTP 通信为明文 | 局域网内风险可控，但不适用于跨网段访问 |
+| 无 TLS 加密 | 当前本地 MQTT 通信为明文 | 局域网内风险可控，但不适用于跨网段访问 |
 | 不支持固件升级 | HA 集成不提供 OTA 功能 | 固件升级需通过 Jackery APP 完成 |
 | 无历史数据回填 | 集成仅采集实时与累计数据 | 集成首次安装前的历史数据不可追溯 |
 | 仅支持 DIY3 | 当前版本仅适配 DIY3 系列 | 其他型号需后续版本支持 |
@@ -464,12 +497,11 @@ binary_sensor.jackery_diy3a12345_online
 
 | 优先级 | 阶段 | 功能 | 说明 |
 |--------|------|------|------|
-| P0 | V1.0 | **本版本交付内容** | 只读集成、mDNS 发现、HTTP 轮询、全量 Sensor |
+| P0 | V1.0 | **本版本交付内容** | 只读集成、mDNS 发现、MQTT 订阅与定时请求、全量 Sensor |
 | P1 | V1.1 | **Token 生命周期管理** | Token 过期提醒、APP 端续期/吊销、HA 侧 Reauthentication Flow |
-| P1 | V1.1 | **WebSocket 推送** | 将 HTTP 轮询升级为 WebSocket 长连接，降低延迟与资源消耗 |
-| P1 | V1.1 | **TLS 加密** | 设备端启用 HTTPS（自签证书或 Jackery CA 签发），保护局域网通信 |
+| P1 | V1.1 | **TLS 加密** | MQTT Broker 启用 TLS（自签证书或 Jackery CA 签发），保护局域网通信 |
 | P2 | V1.2 | **诊断与日志** | 在 HA 集成页面提供「诊断」按钮，导出连接日志与设备状态快照 |
-| P2 | V1.2 | **可配置刷新间隔** | 在集成 Options Flow 中允许用户调整轮询频率（1s–30s） |
+| P2 | V1.2 | **可配置请求间隔** | 在集成 Options Flow 中允许用户调整数据请求频率（1s–30s） |
 | P2 | V1.2 | **设备友好命名** | 支持在配置流或 Options 中自定义设备显示名称 |
 | P3 | V2.0 | **有限控制权限** | 开放低风险操作（如设置 SOC 上/下限），需设备端 API 支持指令校验 |
 | P3 | V2.0 | **多型号支持** | 扩展至其他 Jackery 储能产品线 |