企业官网建设流程全解析

WashData 是一款运行在 Home Assistant 中的家电功率监测集成：它通过智能插座识别洗衣机、烘干机、洗碗机的运行程序，学习功率曲线并预测剩余时间。而 WashData 全屏管理面板与后端之间的每一次交互——从查看实时状态到修剪周期、触发 ML 训练——全部由 111 条以上ha_washdata/命名空间的 WebSocket 命令驱动。本文为你完整梳理这套 WS API 的架构、消息格式、命令分组与权限模型，无需通读源码也能看懂面板背后发生了什么。

面板与后端如何通信？三层架构一图看懂

WashData 的交互链路分三层，自上而下依次是：

1. 面板（Panel）：侧边栏的 WashData 全屏页面，由 ha-washdata-panel.js 驱动，负责渲染 UI；
2. WebSocket 层：Home Assistant 原生的websocket_api组件，负责消息路由与鉴权；
3. 命令处理器：ws_api.py 中的 114 个ws_*处理函数，每个负责一条命令，内部调用 manager.py 等核心模块完成业务逻辑。

面板注册、静态资源与 Lovelace 卡片的路径都在 frontend.py 中完成；而所有命令的统一注册入口是 async_register_commands——它在每次集成加载/重载时执行，因此新增命令只需重载集成，无需重启整个 Home Assistant。

💡 每个命令都用ha_washdata/前缀标识，例如ha_washdata/get_devices。前缀避免了与其他集成命令冲突，也让权限控制可以在一个入口处统一生效。

一次完整的请求-响应：从 get_devices 开始

所有请求都是 JSON 消息，结构固定：

{ "id": 1, "type": "ha_washdata/get_devices" }

响应分三种形态：

以get_devices为例，它是整个面板的起点，返回所有已接入设备的实时状态（功耗、进度、当前程序）。响应中的entry_id字段尤其重要——绝大多数命令都需要它来指定操作哪台设备：

{ "id": 1, "type": "ha_washdata/get_device_cycles", "entry_id": "abc123", "limit": 50 }

get_device_cycles支持limit/offset分页，按时间倒序返回周期列表。值得注意的是，传输前每个周期都会自动剥离power_data、power_trace等大字段（见 ws_api.py#L202-L203），防止撞上 HA 的 32 KB 消息上限。

111+ 条命令全景：按功能域分组速查

完整命令表已由源码自动生成，见 docs/WS_API.md。这里按功能域速览最核心的几组：

所有修改类命令（如import_config、trim_cycle、apply_merge）都会经过每设备写锁串行化，防止并发写入破坏存储数据；参数校验则由 voluptuous schema 在入口处完成，非法参数在业务逻辑执行前就会被拒绝。

长任务不卡面板：后台任务注册表机制

重操作（如reprocess_history重新处理全部历史、trigger_ml_training训练模型、apply_split拆分周期）不会同步等待，而是立即返回一个task_id，真正的计算交给 task_registry.py 管理的后台任务：

• 查询：list_tasks返回所有运行中/最近完成的任务快照；get_task_result按task_id取回结果；
• 订阅：subscribe_tasks建立推送通道，任务每完成一小块进度，服务端就主动发送一条事件消息，面板据此渲染进度条；
• 取消：cancel_task设置取消标志，任务在分块之间检查该标志后优雅退出。

任务支持 9 种类型（reprocess、rebuild、trim、split、merge、ml_training、pg_history、pg_sweep、pg_detail），每个任务都携带total/done进度字段和估算的eta_s剩余秒数。即使 WebSocket 断开重连，最近完成的 30 个任务结果依然可以从服务端重新拉取——这正是注册表存在的意义。

权限与安全的四道关卡

WashData 对每条命令都强制执行 RBAC（基于角色的访问控制），注册时由 ws_api.py#L1415-L1416 的_guard包装器统一注入，没有"漏网"的命令：

1. none / read / edit / full 四级权限：get_*查询类命令只需read级别；修改类命令需要edit；而wipe_history、export_config、trigger_ml_training等危险操作要求full级别；
2. 管理员豁免：HA 管理员始终解析为full；RBAC 默认关闭时，所有已认证用户均为full；
3. 大载荷剥离与降采样：周期数据在传输前自动剥离大字段，曲线数据降采样到 240 点以内；
4. 契约校验（可选）：设置环境变量HA_WASHDATA_WS_CONTRACT=1后，每条响应的字段都会对照 ws_schema.py 中的 TypedDict 定义进行校验并记录日志，生产环境默认零开销关闭。

权限不足的命令不会报错执行，而是直接返回unauthorized/forbidden错误。面板配置与用户偏好则通过set_panel_config（管理员）和set_user_prefs（每用户）两个命令分别管理。

不用改代码，也能实测每一条命令

由于 WashData 完全基于 HA 原生 WebSocket API，你可以直接在开发者工具 → 信息服务（WebSocket）中手动发送命令实测，无需写任何代码：

{ "id": 7, "type": "ha_washdata/get_suggestions" }

配合get_constants（返回设备类型、状态色、ML 功能开关等全局常量）和get_logs（返回内存环形缓冲区中最近 500 条日志），就能在面板外快速定位问题。

文档与类型如何保持同步？生成机制揭秘

这套 API 的"单一事实来源"是 ws_schema.py：WS_COMMANDS字典登记每条命令的请求参数，WS_RESPONSE_TYPES则为每条命令定义一个响应 TypedDict。围绕它有一条完整的工具链：

• python3 devtools/generate_ws_types.py一次性生成 docs/WS_API.md（本文参考的完整命令表）和 ws-types.d.ts（前端 TypeScript 类型）；
• tests/test_ws_contract.py 断言ws_api.py实际注册的命令集合与WS_COMMANDS的键完全一致——新增、删除或重命名命令而忘记同步 schema，测试套件会立即失败。

因此文档标注的"114 commands"始终与代码保持同步，docs/WS_API.md顶部也明确写着"请勿手动编辑"。

源码索引：按主题快速定位

掌握以上要点后，你就可以把 WashData 面板理解为"114 条 WebSocket 命令的图形化外壳"——无论是排查面板 bug、编写自定义 Lovelace 卡片，还是扩展新的集成功能，这套 WS API 都是最可靠的切入点。