109 KiB
智能家居模块规划(Smart Home Module Plan)
状态:方案已定稿,P0–P4 已落地并完成一次全链路复审修复(§9 决策已全部拍板;实施记录见 §9.1–§9.7,复审见 §9.8;下一步只剩按需的 P5 与真机验证) 已定决策(2026-10-16,用户拍板):D1 自动化两条路都做(P3 HA 侧 + P4 本地规则)· D2 接受"本地规则仅在 Thing 运行时生效"(UI 常驻声明)· D3 命名按推荐 · D4 独立窗口 / 快速面板入口后续再加 · D5 需要支持
wss://· D6 相机缩略图先不做 补充需求(2026-10-16):一条连接两个地址(局域网 + 反代),创建时同时填写、按可达性自动选择;反代链路为 Cloudflare Tunnel,延迟显著高于局域网 → 链路策略见 §3.7 定位:Thing 工具集的第 15 个模块,id = smarthome,name = 智能家居,category = 'system'对接对象:Home Assistant(REST + WebSocket),不直连米家云 作者:砚 | 日期:2026-10-16 关联文档:AI_DEV_GUIDE.md(模块注册 / IPC / 命令 / 进程范式)、UI_DESIGN_SYSTEM.md(页面框架 / 组件规范 / 四态)、EDITOR_MODULE_PLAN.md(模块规划文档的组织范式)阅读顺序:§0 结论 → §2 可行性 → §3 HA 接口映射 → §5 功能规格 → §7 UI → §8 路线图 → §9 决策点 → §11 开工清单。
0. 结论先行
九条判断。前三条直接回答"可行性 / 实时性 / 自动化归属"三个不确定项。
-
完全可行,且不需要新增任何 Rust 依赖。 项目已具备全部所需基础设施:
reqwest 0.12(REST,已在下载引擎 / 飞牛 / WebDAV 使用)、tokio-tungstenite 0.24(WebSocket 客户端,P4 起实际使用,见smarthome/ws.rs)、keyring 3+src-tauri/src/secrets.rs(系统凭据管理器,DPAPI 保护,已有secret_read / secret_write / secret_delete / mask四个原语)、tokio多线程运行时、chrono。真正要写的只有"协议客户端 + 协议到 UI 的映射"。 -
实时性问题:设备数据不需要实时,自动化需要。 两者要用不同机制:
- 设备数据 = 拉取式。打开模块拉一次全量状态,配手动刷新按钮 + 可选自动刷新(默认关,选 5/10/30s)。HA 的一次
GET /api/states是单请求,几百个实体约几百 KB,本地局域网代价可忽略。 - 自动化 = 事件驱动,必须有实时推送。轮询做自动化有两个致命缺陷:① 延迟下限 = 轮询间隔;② 会漏掉瞬态变化(人体传感器
on → off若发生在两次轮询之间,"有人经过"这个事件就丢了)。所以自动化引入 WebSocket(subscribe_entities/subscribe_events)。 - 因此:P1–P3 只走 REST,P4 才引入 WS。WS 接入顺带把设备数据升级为实时推送(同一份代码同时服务两个功能),但它是 P4 的工作,不是 P1 的前置条件。
- 设备数据 = 拉取式。打开模块拉一次全量状态,配手动刷新按钮 + 可选自动刷新(默认关,选 5/10/30s)。HA 的一次
-
"简单自动化"有两条路,建议分阶段各取一条。 (a) 管理 HA 自身已有的自动化(列出 / 启停 / 手动触发)——纯 REST,零风险,立刻可用;(b) 本地轻量规则引擎("门窗开 → 开灯"这类)——需 WS 事件驱动,可控性强。关键限制必须提前告知用户:本地规则只在 Thing 运行时生效(桌面应用关掉、电脑关机就不跑了)。若用户要的是"24 小时常驻可靠",那正确做法是把规则写回 HA 服务端,本模块只做编辑入口。→ 见 §5.4 与 §9-D1/D2。
-
"按房间分组"在纯 REST 下拿不到(重要缺口)。
GET /api/states的返回里没有 area(房间)信息——房间归属只存在于 HA 的注册表里,而注册表只能通过 WebSocket 的config/entity_registry/list+config/area_registry/list查询。所以 P1(只走 REST)的分组能力只能是:按 domain(灯 / 开关 / 传感器…)+ 按收藏。房间分组要等 P4 引入 WS 后补。这一点直接影响 UI 规划(§7.2 的左栏先不设房间维度),必须在开工前明确,否则会做出"有房间筛选但点进去是空的"。真机修正(2026-10-19,见 §9.5-1):注册表能拿到,但目标实例上实体级
area_id全是空的,房间归属在设备上。因此 P4 必须按实体 → 设备 → 区域三级回退。 -
认证 = 长期访问令牌,落系统凭据管理器。 令牌由用户在 HA 的「个人资料 → 安全 → 长期访问令牌」自行创建后粘贴进来;本模块不代用户登录、不存小米账号。令牌只经
secrets::secret_write进入 Windows 凭据管理器(键名约定smarthome-token-<connId>),settings.json只存baseUrl / 名称 / insecure等非敏感项。前端永远拿不到明文,只拿secrets::mask()处理过的掩码(与翻译模块 API Key、WebDAV 密码同一姿态)。 -
UI 落在主窗口,不新开独立窗口。 智能家居是"常看常点"的模块,与 terminal / diff / editor 那种"需要独占屏幕"的工作台不同。用现有
useModuleTabs注册三个 Tab(设备 / 自动化 / 设置),内容区用split布局(左 280px 筛选栏 + 右侧实体卡片网格)。实体卡片按 domain 映射控件,不追求通用化。 -
安全姿态:令牌在单点暴露,危险操作二次确认。 明文令牌只存在于 Rust 内存与系统凭据库;传输层若走
http://(局域网常见)则在设置页明确提示"令牌经明文网络传输,建议仅局域网使用或启用 HTTPS";lock.unlock/cover全开 /valve/alarm这类操作沿用 P4 原则(视觉降级 + 二次确认),但不做二次口令。 -
不做的事(明确划界):不做 HA Lovelace 前端的替代或内嵌;不做设备配网 / 集成添加(那是 HA 自己的事);不做小米账号登录;不做 HA 自动化 YAML 编辑器 / 模板语法编辑器;不做本机历史曲线存储(HA 自己有 history,需要时按需拉取,不落盘)。
-
一条连接两个地址:局域网优先,反代兜底(P0 就要做,不是优化项)。 用户在家走
http://192.168.x.x:8123(RTT < 5ms),在外面走 Cloudflare Tunnel 反代(RTT 100–400ms 量级,高 1–2 个数量级)。因此连接模型是localUrl+remoteUrl+endpointMode(auto|local|remote):auto 模式按「上次可用 → 局域网(短超时 900ms)→ 反代」顺序探测,探测结果会话内粘住(不让同一屏数据来自两个链路,否则时间戳会错乱),网络变化时失效重探(复用现成的network_monitor.rs)。没有这条策略,在外面每次操作都要先等局域网超时 —— 所以它与"连接管理"同属 P0。
1. 需求解构
| 用户原话 | 解构为 | 落点 |
|---|---|---|
| 「添加一个智能家居管理模块」 | 新模块,走既有 ModuleConfig 注册范式 | §6.6 / §11 |
| 「对接 Home Assistant」 | 协议适配层:REST + WS 客户端,封装为内部 API | §3 / §6.1 |
| 「设备大部分是小米的,装了 xiao home 集成,已扫到设备」 | 不做设备侧任何事——HA 已经把设备变成 entity_id;本模块只看实体 |
§2.3 能力边界 |
| 「登录使用 HA 自己的长期访问令牌」 | 令牌粘贴 + 连通性测试 + 失效重填,不做 OAuth 流程 | §3.1 / §5.1 |
| 「为了安全放入系统的凭据管理」 | secrets.rs(keyring / DPAPI),明文不落 settings.json,前端只见掩码 |
§4 / §5.1 |
| 「设备数据(不一定需要实时更新)」 | 拉取式 + 手动刷新 + 可选自动刷新(默认关) | §5.2 / §8-P1 |
| 「但是自动化是否需要?不确定」 | 需要:事件驱动,P4 接 WS;轮询会漏瞬态变化 | §0.2 / §5.4 / §8-P4 |
| 「设备控制」 | 按 domain 映射服务调用;乐观更新 + 单实体状态校正 | §3.5 / §5.3 |
| 「简单自动化」 | 三段式(触发 / 条件 / 动作)线性规则,不做嵌套树 | §5.4 / §9-D1 |
| 「帮我规划可行性和实现路径、UI」 | 本文档;UI 规范见 §7 | 全文 |
| 「需要两个链接,登录时同时输入本地和反代」 | 连接模型加 localUrl / remoteUrl + 端点选择策略 |
§3.7 / §4 / §5.1 |
| 「反代是 Cloudflare Tunnel,速度可能不快,需要考虑延迟」 | 分级超时 + 端点粘滞 + gzip + 远端不轮询 + UI 明示当前链路 | §3.7 / §5.2 / §5.3 / §7.4 |
2. 可行性
2.1 依赖盘点(仅两项需补 feature)
| 能力 | 现有资产 | 结论 |
|---|---|---|
| HTTP REST 客户端 | reqwest 0.12(json / stream / blocking 已开) |
直接用 async client;P0 补 gzip feature(默认未开,见 §3.7-b) |
| WebSocket 客户端 | tokio-tungstenite 0.24(声明了但没人用) |
P4 补 connect + rustls-tls-webpki-roots(D5 已定支持 wss://) |
| 异步运行时 | tokio 1(rt-multi-thread / sync / time / net 已开) |
Tauri async command 直接可用 |
| 令牌存储 | keyring 3 + src-tauri/src/secrets.rs(secret_read/write/delete、try_store、read_or_empty、mask) |
零成本复用,键名自定 |
| 模块设置持久化 | {app_data_dir}/<module>/settings.json 范式(ai / translate / terminal / editor / monitor 共 5 处先例) |
照抄 |
| 文件锁 / 状态管理 | dsh/mod.rs 的 AppState + Mutex<Settings> 范式 |
照抄 |
| 前端壳 | ModuleConfig + useModuleTabs + shadcn-vue 全套组件 |
照抄 |
| 外部链接打开 | @tauri-apps/plugin-opener 的 openUrl(quickpanel/web.ts、dshStore 已在用),default.json 权限已够 |
无需新权限 |
| 系统通知(规则动作) | tauri-plugin-notification 已在依赖 + 已注册 |
可选 |
| 图标 | @lucide/vue(House / Lightbulb / Blinds / Thermometer / Fan / Lock / Speaker …) |
无需新图标库 |
2.2 待核实项(开工前必须逐条验证,都是"可能会卡住半天"的点)
tokio-tungstenite的 feature 组合(D5 已定:需要wss://)。当前P4 开工前已用Cargo.toml写作tokio-tungstenite = "0.24",未显式开 feature。cargo tree -e features -i tokio-tungstenite核实:connect已随 default 启用(由本项与 axum 的ws共同引入),TLS 未启用。P4 已补connect+rustls-tls-webpki-roots(纯 Rust 无 C 依赖,与项目姿态一致;native-tls会引入系统依赖),并确认复用依赖树里已有的 rustls 0.23(经 russh)不新增编译单元。另:futures-util的sink特性也不在 default 里(此前只是被 tokio-tungstenite 传递打开),已显式声明。reqwest的gzipfeature(P0 就要加)。 默认未开 → 不发Accept-Encoding→ 反代链路上 Cloudflare 回未压缩 JSON,远端首屏流量翻 5–10 倍。详见 §3.7-b 的"必须做的事"。- WS 帧大小上限。
subscribe_entities首次快照(全实体)可能是一条很大的消息。tungstenite 有max_message_size/max_frame_size默认值(通常 64MiB / 16MiB),几百实体不会触发,但 1000+ 实体建议显式配置并在日志里记录实际帧大小。 - HA 版本门槛。
subscribe_entities需要 HA ≥ 2023.11;config/area_registry/list等注册表查询很早就有。实现时用GET /api/config的version做能力探测,不支持就退化为subscribe_events(state_changed)或纯 REST。设置页展示 HA 版本。 opener打开 URL 的 scope。default.json只有opener:default+allow-open-path+allow-reveal-item-in-dir,而实际代码里openUrl能用(quickpanel 已在用),说明opener:default覆盖了 URL。若实施时被 scope 拦(HA 地址是http://192.168.x.x:8123,非https),需补opener:allow-open-url或加 scope 白名单——不要想当然。- 反代是否叠加了 Cloudflare Access。 若 CT 隧道前面挂了 CF Access(Zero Trust),请求还需
CF-Access-Client-Id/CF-Access-Client-Secret两个 Service Token 头,否则会被 CF 的登录页拦下(表现为测试连接拿到 HTML 而非 JSON)。本次按"只用 HA 自己的令牌"设计,不实现该头;若用户环境实际启用了 Access,测试连接会立刻暴露,届时再补两个字段 + 两条凭据即可(成本很低,故不预留)。 - HA 的
unavailable/unknown语义。 小米设备在云连模式下断网会变unavailable,这不是错误,UI 要单独呈现(§7.5),不要当异常弹错误。
2.3 能力边界
- 本模块与设备之间隔着 HA。 小米设备(Xiaomi Home 集成)多数走米家云,控制延迟 200ms ~ 数秒不等,且云端断连时实体为
unavailable。本模块不承诺实时性 SLA,UI 用"命令已下发 ≠ 状态已改变"的措辞(§5.3 乐观更新)。 - 不做设备发现 / 配网 / 集成配置。 这些是 HA 的职责,本模块只消费它的实体与服务,最多提供"在 HA 中打开此设备"的外链。
- 不做状态写回。 不用
POST /api/states/<entity_id>(那是伪造状态,且需 admin),所有变更必须经 service 调用。 - 不做多 HA 实例聚合。 数据结构上支持多连接(
connections[]+activeId,照抄飞牛连接管理),但 UI 一次只显示一个激活实例,不做跨实例合并视图。
3. Home Assistant 接口映射
这是本模块的技术核心。所有参数细节以 HA 开发者文档 与实例实测为准,实现时逐条核对。
3.1 认证
- 令牌类型:长期访问令牌(Long-Lived Access Token,LLAT),用户在 HA「个人资料 → 安全 → 长期访问令牌 → 创建令牌」生成,一串
eyJ...的 JWT,有效期 10 年,只能删除不能续期。 - REST:请求头
Authorization: Bearer <token>。 - WS:连接后走握手协议(§3.3)。
- 令牌有效性探测(最轻量):
GET /api/→ 期望{"message": "API running."};401 表示令牌无效/被吊销。 - 能力探测:
GET /api/config→{ version, location_name, unit_system, time_zone, components[], latitude, longitude, elevation }。用途:设置页展示实例名与版本、按版本决定 WS 命令可用性、读unit_system决定温度单位显示策略。
3.2 REST 端点(P1–P3 的全部依赖)
| 用途 | 端点 | 备注 |
|---|---|---|
| 令牌校验 / 连通性 | GET /api/ |
测试连接按钮 |
| 实例信息 | GET /api/config |
版本 / 实例名 / 单位制 |
| 全量状态 | GET /api/states |
数组,元素见 §3.4 |
| 单实体状态 | GET /api/states/<entity_id> |
控制后的校正 |
| 服务调用 | POST /api/services/<domain>/<service> |
body:{"entity_id": "...", ...参数};entity_id 可为字符串或数组 |
| 需要返回值的服务 | POST /api/services/<domain>/<service>?return_response=true |
少数服务(天气预报、日历)才有 |
| 服务清单 | GET /api/services |
含字段定义;用作"高级参数"兜底,不用它生成主控件 |
| 历史 | GET /api/history/period/<ISO8601>?filter_entity_id=<eid>&minimal_response |
可选 P5(图表) |
| 日志 | GET /api/error_log |
可选:设置页"诊断"入口 |
| 模板渲染 | POST /api/template {"template": "..."} |
可选,不建议 P1 引入(会牵出模板注入面) |
3.3 WebSocket 协议(P4)
ws://<host>:8123/api/websocket (HTTPS 反代则 wss:// )
S→C {"type":"auth_required","ha_version":"2024.x.x"}
C→S {"type":"auth","access_token":"<LLAT>"}
S→C {"type":"auth_ok","ha_version":"2024.x.x"} // 或 {"type":"auth_invalid","message":"..."} 后关闭
鉴权通过后所有命令都是"自增 id + type"的请求/响应式,id 由客户端维护:
// 1) 订阅全实体(推荐,HA ≥ 2023.11;一次订阅,服务端按增量推送)
C→S {"id":1,"type":"subscribe_entities"} // 省略 entity_ids = 全量
S→C {"id":1,"type":"result","success":true,"result":null}
S→C {"id":1,"type":"event","event":{
"a": { "light.hall": {"s":"on","a":{"brightness":180},"c":"...","lc":...,"lu":...} }, // added
"c": { "sensor.temp": {"+" : {"current_temperature": 24.5}} }, // changed(差分)
"r": ["switch.old"] // removed
}}
// 2) 订阅状态变化事件(兼容旧版本;用于自动化触发)
C→S {"id":2,"type":"subscribe_events","event_type":"state_changed"}
S→C {"id":2,"type":"event","event":{"event_type":"state_changed","data":{
"entity_id":"binary_sensor.door","old_state":{"state":"off",...},"new_state":{"state":"on",...}}}}
// 3) 调服务(与 REST 等价,复用同一长连接)
C→S {"id":3,"type":"call_service","domain":"light","service":"turn_on",
"target":{"entity_id":"light.hall"},"service_data":{"brightness_pct":70}}
// 4) 注册表(房间分组的唯一来源)
C→S {"id":4,"type":"config/area_registry/list"}
C→S {"id":5,"type":"config/entity_registry/list"}
C→S {"id":6,"type":"config/device_registry/list"}
// 5) 心跳
C→S {"id":7,"type":"ping"} S→C {"id":7,"type":"pong"}
实现要点(踩坑清单):
- 连接生命周期归属应用而非页面。 WS 由 Rust 侧持有(
tokio::spawn的任务 +Mutex<Option<Handle>>),模块 Tab 切走不关连接;只有用户显式关闭实时、或应用退出才断。 - 必须实现断线重连(指数退避,上限如 30s),并在重连成功后重新拉一次全量状态(断线期间的增量丢了)。
- 心跳双向:服务端 30s 内未收到响应会断开;客户端也要主动
ping探测半开连接(尤其在路由/NAT 环境下)。 - 鉴权失败不可无限重连:
auth_invalid→ 置authFailed状态、通知前端弹"令牌失效,请重新填写",停止重连避免刷爆日志。 - 事件必须节流后再送前端(§6.5):
subscribe_entities在设备状态风暴时可能每秒几十条消息,逐条 IPC 会打爆 WebView。
3.4 实体与状态模型
{
"entity_id": "light.hall_ceiling", // <domain>.<object_id>
"state": "on", // 字符串,可能是数值 / on / off / unavailable / unknown
"attributes": { // 各 domain 不同,且有隐藏坑
"friendly_name": "门厅吸顶灯",
"supported_color_modes": ["brightness","color_temp"],
"brightness": 180, // 0–255
"color_temp_kelvin": 4000,
"device_class": "temperature",
"unit_of_measurement": "°C",
"supported_features": 4, // 位掩码,表示支持哪些操作
"hvac_modes": ["off","heat","cool"],
"current_temperature": 24.5 // 数值型可能在 state 或 attributes
},
"last_changed": "2026-10-16T12:00:00.123456+00:00",
"last_updated": "2026-10-16T12:00:00.123456+00:00"
}
必须处理的三件事:
state与attributes谁是数值因 domain 而异。sensor的读数在state里(字符串形式的数字);climate的当前温度在attributes.current_temperature。卡片渲染必须按 domain 分别取,不能统一。supported_features/supported_color_modes决定控件形态。 例如灯若无brightness能力就只渲染开关不给滑杆。宁可少给控件,也不要给一个点了没反应的滑杆(这与编辑器模块"避免误报优先于覆盖完整"是同一取舍)。unavailable/unknown是合法状态,不是错误。unavailable= 设备离线(小米云断连常见);unknown= 状态未初始化。
3.5 服务(控制)映射
控制统一走 domain.service + target。下表是 P2 要覆盖的最小集合:
| domain | 常用服务 | 关键参数 | 控件形态 |
|---|---|---|---|
light |
turn_on / turn_off / toggle |
brightness_pct(0–100) 或 brightness(0–255)、color_temp_kelvin、rgb_color、transition |
开关 + 亮度滑杆(点击滑杆即开灯)+ 色温滑杆(按 supported_color_modes) |
switch / input_boolean |
turn_on / turn_off / toggle |
— | 开关 |
cover |
open_cover / close_cover / stop_cover / set_cover_position |
position(0–100) |
三按钮(升/停/降,按 supported_features 位决定)+ 位置滑杆 |
climate |
set_temperature / set_hvac_mode / turn_off |
temperature、hvac_mode、fan_mode |
目标温度步进(±0.5)+ 模式下拉 + 当前温度显示 |
fan |
turn_on / turn_off / set_percentage |
percentage(0–100)、preset_mode |
开关 + 档位滑杆 |
media_player |
turn_on / turn_off / media_play_pause / volume_set / volume_mute |
volume_level(0–1) |
播放/暂停 + 音量滑杆(P2 可只给开关与播放) |
scene / script |
turn_on |
— | 单按钮"执行" |
automation |
turn_on / turn_off / trigger |
— | 启用开关 + "立即运行"按钮(见 §5.4-A) |
lock |
lock / unlock |
可选 code |
单一开关 + 解锁二次确认 |
vacuum |
start / return_to_base / pause |
— | 三按钮(P5) |
number |
set_value |
value(上下限与步长取实体自带的 min / max / step) |
滑杆(复用 ControlSlider) |
select |
select_option |
option(取自实体的 options) |
下拉 |
button |
press |
— | 单按钮「按下」(无乐观状态,但 state 是按下时间,可乐观改) |
notify / persistent_notification |
send_message 等 |
message / title |
不作为设备控件(供自动化动作用) |
不支持控制的实体(sensor / binary_sensor / camera / person / device_tracker / sun / weather)只读展示;其中 camera 的缩略图(/api/camera_proxy/<entity_id>)P5 再议——P1 明确不做,它牵出图片缓存与鉴权头传递。
3.6 错误与状态码
| 现象 | 成因 | UI 呈现 |
|---|---|---|
401 Unauthorized |
令牌无效 / 被吊销 | 「令牌已失效」错误态 + 跳到设置页重填(不重试) |
| 连接超时 / DNS 失败 | 地址错、不在同一局域网、HA 未启动 | 「无法连接」错误态 + 重试按钮 |
404 |
实体或服务不存在(设备被移除、集成重载) | toast「该实体已不存在」+ 标记为失效 |
400 |
参数不被支持(如给不支持彩色的灯传 rgb_color) |
toast 原文错误信息(HA 的 message 通常可读) |
500 |
HA 内部错误 / 集成报错 | toast + 「查看 HA 日志」外链 |
实体 unavailable |
设备离线(不是请求错误) | 卡片灰显 + "离线"标记,不弹错误 |
3.7 链路与延迟(双地址 + Cloudflare Tunnel)
a. 端点模型与选择算法
| 字段 | 说明 |
|---|---|
localUrl |
局域网直连地址,如 http://192.168.1.10:8123。可留空(只配反代的人) |
remoteUrl |
反代地址,如 https://ha.example.com(Cloudflare Tunnel)。可留空 |
endpointMode |
auto(默认)/ local(强制局域网)/ remote(强制反代) |
两者至少填一个。auto 的探测顺序与超时(P0 实施时定稿):
1) localUrl(若已配置) 超时 900ms ← 必须短
2) remoteUrl(若已配置) 超时 5000ms
全部失败 → ResolveFailure{kind: "network"},前端「无法连接」+ 重试
实施修正(2026-10-16,P0):原方案把「上次成功的端点(lastOkUrl)」排在探测第一优先级, 落地时改成局域网永远先试。原因是 lastOkUrl 优先会把人困在反代上:回家后反代依然可用, 探测顺序就永远不会回到局域网(代价是出门后每轮冷探测多花 900ms —— 而冷探测每 60s 才发生一次, 且请求失败会立刻重探)。
lastOkUrl因此降级为纯展示字段。 「仅局域网 / 仅反代」强制模式下,该地址的探测超时放宽到 5s:此时失败就是"真的连不上", 不该用 900ms 这种"探测缺失"用的短超时把可用链路判死。
三个关键点:
- 局域网探测超时必须远小于反代(900ms vs 5000ms)。在家里局域网必然 <10ms 命中;在外面局域网会因 ARP / 路由超时而必然耗满这个值——它直接决定"出门后每次首次操作有多卡"。
- 探测命中后会话内粘住,TTL 按链路分档:局域网 60s、反代 300s。不允许同一屏数据来自两个链路,否则"更新于 X 秒前"的时间戳会来自不同链路,用户无法判断新鲜度;分档的理由是缓存在反代上时唯一的提升空间只有"回家切回局域网",不值得每分钟白花 900ms 去探。
- 请求失败立刻重探(不等 TTL)。注意
resolve()命中缓存时不重新探测,因此 P1 的数据请求失败后必须调用clear_endpoint_cache(),否则会一直粘在一个已经不可用的端点上。 - "网络变化触发清缓存"尚未接线(
network_monitor.rs有现成的变化通知,P1 再接):目前靠"失败即重探"覆盖"出门"这一半(在外面反代请求失败 → 切回局域网)。 - WS 连接走同一套选择逻辑,且一旦连上就固定在所选端点(P4)。
b. Cloudflare Tunnel 的延迟特征与对策
链路:本机 → CF 边缘节点 → cloudflared 隧道 → HA。国内访问 CF 边缘常绕行境外/香港,RTT 典型 100–400ms;局域网是 <5ms,相差 1–2 个数量级。
| 影响面 | 量级 | 对策 |
|---|---|---|
首屏全量 GET /api/states |
几百 KB JSON,远端 0.5–3s | ① 开启 reqwest 的 gzip feature(默认未开)② 首屏给明确进度提示,而不是"看起来卡住了" |
WS subscribe_entities 首次快照 |
与全量同级,但只发生一次 | 之后增量仅几十字节~几 KB —— 这是远端优于轮询的核心原因 |
| 单次控制命令 | RTT + HA/米家处理 = 0.3–2s | 乐观更新(§5.3);远端下校正窗口拉长到 2s 或直接等 WS 推送 |
| 自动刷新(若开启) | 每次刷新都是一次全量 | 远端模式不提供自动刷新(开关置灰并说明原因),远端靠 WS 增量 |
| WS 保活 | CF 对空闲 WS 有超时(~100s 量级) | HA 的双向 30s 心跳足以保活,但心跳必须实现(不能只依赖 TCP keepalive);以实测为准 |
必须做的事(极易忽略):reqwest 的压缩 feature 默认关闭。不开 gzip 就不会发送 Accept-Encoding,Cloudflare 会回未压缩的 JSON —— 远端首屏流量直接翻 5–10 倍(也拖长耗时)。→ P0 就把 reqwest = { …, features = [..., "gzip"] } 补上,即使 P0 还没有大响应,也先把这个决策定死,避免 P4 忘掉。
真机实测(2026-10-19,577 实体):明文 265,973 B / gzip 45,890 B(5.8×);耗时 3.96s → 2.30s。 反代链路的
ping/pong往返 617 ms,WS 首帧(152 KB 未压缩)2.23 s, 之后 30 秒内只有 2 个增量事件 / 328 B。← 这组数字就是"P4 用 WS 而不是轮询"的量化依据。
c. 为什么仍然不落盘状态缓存
远端慢时最诱人的做法是"把上次状态落盘、先渲染出来"。本方案明确拒绝:智能家居里"显示灯已关、实际还亮着"是有实际后果的误导,比"多等 1 秒"糟得多。远端慢的场景改为:骨架屏 + 链路提示("正在通过远程连接加载")+ 更宽松的超时。
d. UI 必须暴露链路状态
用户必须能一眼看出"现在走局域网还是反代",否则远端慢会被误判成应用有 bug:
- 诊断区显示「当前链路:局域网 / 远程(反代)」+ 该端点最近一次请求实测耗时;
- 「更新于 X 秒前」必须来自实际成功的那次请求;
- 设置页提供端点强制切换(
local/remote),用于出门前确认反代是否可用。
4. 数据与存储
{app_data_dir}/smarthome/
├── settings.json # 非敏感配置
└── automations.json # 本地规则(P4)
Windows 凭据管理器(service = "Thing")
└── smarthome-token-<connId> # 每个连接一条明文令牌
settings.json 结构(含 version + 自愈,范式照抄 dsh/types.rs / editor/types.rs):
{
"version": 1,
"activeId": "home",
"connections": [
{
"id": "home", "name": "家里",
"localUrl": "http://192.168.1.10:8123", // 可选
"remoteUrl": "https://ha.example.com", // 可选(Cloudflare Tunnel)
"endpointMode": "auto", // auto | local | remote
"insecure": false,
"lastOkUrl": "http://192.168.1.10:8123", // 上次成功端点(决定探测顺序)
"lastOkAt": 1760000000, "haVersion": "2026.9.3", "locationName": "家里"
}
],
"ui": {
"autoRefreshSec": 0, // 0 = 关闭(默认);远端链路下强制为 0
"hiddenDomains": [], // 实体过滤
"hiddenEntityIds": [],
"favoriteEntityIds": ["light.hall_ceiling"],
"confirmDangerous": true // 危险操作二次确认(默认开)
},
"realtime": { "enabled": false, "lastConnectedAt": null } // P4
}
会话内的端点缓存(
CachedEndpoint)不落盘:它是"这次跑在哪个网络环境"的判断,下次启动的网络环境可能完全不同,落盘反而会先走错一次。跨会话只保留lastOkUrl作为探测顺序的第一优先级(它只是一个提示,不是结论)。
约定:
- 令牌绝不落
settings.json/ localStorage。 写入顺序照secrets.rs的注释要求:「先写凭据库成功、再清明文」,写失败保留明文并记日志(logger::log_error("smarthome", ...))。 - 前端只拿掩码:命令返回
tokenMasked(secrets::mask()的产物)+hasToken: boolean,没有返回明文的命令。 - 状态缓存只在内存(
Mutex<HashMap<String, EntityState>>),不落盘。原因:HA 自己就是状态真相源,落盘会引入"离线看到的陈旧状态"这种更坏的问题。可选:把最近一次成功拉取的时间戳落盘,用于 UI 显示"数据来自 X 分钟前"。 - 收藏与隐藏偏好落盘,因为它们表达的是用户意志而非状态。
- 迁移策略:
version不匹配时只补增量,不清空(教训来自主题色那次SETTINGS_VERSION讨论:递增会误清用户配置)。
5. 功能规格
5.1 连接与认证(P0)
- 首次进入模块 → 空态引导:「连接 Home Assistant」按钮 → 对话框填 名称 / 局域网地址 / 反代地址 / 令牌,加
insecure开关(自签证书时勾选,文案同飞牛连接)。- 两个地址至少填一个;只填一个时
endpointMode自动退化为对应模式(不必让用户理解 auto 的含义)。 - 地址规范化:省略协议时补
http://;结尾/去掉;反代地址默认按https://提示。
- 两个地址至少填一个;只填一个时
- 测试连接(对话框内直接测、无需先保存):逐个地址探测(先局域网,再反代),对每个地址都给出独立结果 —— "局域网:连接成功(2026.9.3 · 家里)| 反代:失败(超时)"。这比一个笼统的"成功/失败"有用得多:用户在外面测时,局域网失败是预期内的。
- 保存:令牌 → 凭据库;其余 →
settings.json。多连接列表 + 「设为激活」(照抄ConnectionsSettings.vue的交互与图标语义:编辑 / 激活 / 删除 / 已连接标记)。 - 令牌失效:任何 401 → 顶部持久横幅「访问令牌已失效」+「重新填写」按钮,且不自动重试。
- 链路:诊断区显示当前使用的端点与实测耗时(§3.7-d);提供
auto/local/remote强制切换。 - 安全提示(设置页常驻说明):局域网
http://下令牌明文过网,建议仅在家庭内网使用;反代走 HTTPS 时该问题不存在。
5.2 设备数据(P1)
- 拉取:进入模块拉一次全量(
force=false,若 60s 内有缓存则先用缓存渲染再后台刷新);force=true用于手动刷新按钮。 - 刷新:标题区右侧「刷新」按钮(带 loading)+ 最近的更新时间 + 当前链路徽章(局域网 / 远程);可选自动刷新间隔(默认关)。规则:远端链路下自动刷新不可用(开关置灰并说明"远程连接下请用实时推送,避免反复拉取全量")——每次自动刷新在反代上都是一次几百 KB 的全量拉取(§3.7-b)。P4 后自动刷新被实时推送取代,此开关保留为"实时不可用时的降级"。
- 分组与筛选(P1 能力上限,见 §0.4):
全部 / 收藏 / 按类型(灯·开关·窗帘·空调·传感器·其它);顶部搜索框按friendly_name与entity_id做不区分大小写子串匹配;过滤"只显示可控设备"与"隐藏离线设备"两个开关。房间维度留待 P4。 - 卡片展示:见 §7.2;只读实体(传感器)显示数值 + 单位 + 相对时间。
- 排序:收藏置顶 → 同组内按
friendly_name本地化排序(不用localeCompare的默认行为,中文需Intl.Collator('zh'))。
5.3 设备控制(P2)
- 下发:
POST /api/services/<domain>/<service>,entity_id+ 参数。 - 乐观更新 + 校正(本模块最重要的交互决策;P2 落地版见 §9.3-1 / -2):
- 点击 → 立即把本地状态按意图改写(
on→ 卡片立刻点亮)。 - 下发服务(
POST /api/services/<domain>/<service>)。 - 快速通道:HA 的响应体就是受影响实体的最新状态 —— 若它确实与下发前不同,直接采用并结束(省一次往返;远端链路上约 200–400ms)。
- 否则在分级窗口后拉单实体校正:局域网 600ms、远端(反代)2000ms —— 远端 RTT 再加米家云端处理,600ms 必然被误判成"状态未变化"。
- 校正结果"看起来没变" → 回滚到原状态 + toast「命令已下发,但设备状态未变化」(小米云设备会真的出现这种情况,措辞必须诚实);校正请求本身失败 → 不改 UI(宁可相信意图已生效)。
- 例外:动作本就没有可预期的状态变化时(执行场景 / 脚本、停止窗帘),既不走快速通道也不做校正 —— 否则会拿"状态没变"去冤枉一次成功执行。
- P4 之后改为:乐观更新 + 等 WS 推送校正(1.5s 超时兜底),不再单独拉单实体。
- 点击 → 立即把本地状态按意图改写(
- 参数型控件(亮度/位置/温度滑杆):拖动时本地即时反馈,松手才下发(
@change而非@input),避免拖动过程刷出几十条命令。 - 危险操作二次确认:
lock.unlock、cover.open_cover(全开)、valve、alarm_control_panel、vacuum启动。用AlertDialog,确认按钮destructive变体。 - 不可用实体:控件禁用并给 tooltip 说明("设备离线" / "该集成不支持此能力")。
- 外链:卡片的溢出菜单里「在 Home Assistant 中打开」(
openUrl→{baseUrl}/history?entity_id=<eid>),便于用户去 HA 侧排查。
5.4 简单自动化(P3 / P4)
A. HA 已有自动化(P3,纯 REST,零风险)
- 数据源:
automation.*(自动化)+script.*(脚本)实体(来自同一个GET /api/states)。 - 能力:列出(名称 + 最后触发时间
attributes.last_triggered+ 状态)+ 启用/停用(automation.turn_on|turn_off)+ 立即运行(automation.trigger,默认skip_condition: false)。 - 不做编辑(HA 自己的 UI 更强,在本地重做一遍是重复劳动)。
B. 本地轻量规则引擎(P4,需 WS)
规则模型(线性三段式,不做嵌套树——这是"简单自动化"的边界所在):
{
"id": "r_1",
"name": "回家开灯",
"enabled": true,
"trigger": { // 触发:只支持"实体状态变化"与"定时"
"type": "state", // state | time
"entity_id": "binary_sensor.door_contact",
"to": ["on"], // 省略 = 任意变化
"from": ["off"], // 可选
"for": 0, // 可选:持续 N 秒才触发(去抖)
"numeric": null // 可选:{ "op": ">", "value": 28 }(数值型实体)
},
"conditions": [ // 条件:全部 AND(验收时全过才执行)
{ "type": "time", "from": "18:00", "to": "23:59", "weekdays": [1,2,3,4,5,6,7] },
{ "type": "state", "entity_id": "person.me", "state": "home" }
],
"actions": [ // 动作:顺序执行
{ "type": "service", "domain": "light", "service": "turn_on",
"entity_id": "light.hall_ceiling", "data": { "brightness_pct": 70 } },
{ "type": "delay", "seconds": 60 },
{ "type": "notify", "title": "到家", "message": "门厅灯已开" }
],
"cooldownSec": 30, // 冷却:防止同一规则被抖动反复触发
"lastFiredAt": 1760000000,
"fireCount": 12
}
- 求值在 Rust 侧(WS 事件到达即匹配),不依赖前端页面是否打开——但整体仍依赖应用进程存活。
- UI 必须显式标注限制:规则卡 / 规则编辑器顶部放一条常驻说明:「本地规则仅在 Thing 运行时生效;需要 7×24 可靠请改用 HA 自身的自动化」。
- 三条必须实现的护栏:
- 冷却时间:
cooldownSec(默认 30s)内的重复触发直接丢弃。 - 动作失败不中断:某动作 4xx/5xx 时记
lastError并继续下一动作(否则一条失败会吞掉后续所有动作)。 - 循环保护:规则动作导致的实体变化若能再次触发同一规则(A 开 B、B 关 A),冷却时间不足以阻断时要有执行链深度上限(如单次事件链最多 3 层)。
- 冷却时间:
- 运行记录:内存里保留最近 50 条触发记录(时间 / 规则 / 结果),存
automations.json的lastFiredAt/fireCount,供列表展示。
5.5 设置(各阶段累积)
- 连接:多连接管理(§5.1)。
- 刷新:自动刷新间隔(关 / 5 / 10 / 30s);实时推送开关(P4,默认关,开启后走 WS)。
- 显示:隐藏的 domain、隐藏的实体、"只显示可控设备"、"隐藏离线设备"。
- 安全:危险操作二次确认开关(默认开)、"忽略 HTTPS 证书校验"(跟随连接项)。
- 诊断:HA 版本 / 实例名 / 最后成功请求时间 / WS 状态(P4)/ 「在 HA 中打开」/ 「打开 HA 日志」(
openUrl {baseUrl}/config/logs)。 - 关于限制的说明(常驻文案):本地自动化的生效前提。
6. 架构设计
6.1 Rust 目录
src-tauri/src/smarthome/
├── mod.rs # AppState(app_data_dir / module_dir / 内存状态缓存 / WS 句柄)
│ # + settings 读写(version + 自愈)+ secrets 键名约定
├── types.rs # 序列化结构:HaSettings / HaConnection / EntityState /
│ # EntitySummary(发给前端的精简结构)/ ServiceCall / Rule…
├── client.rs # reqwest 客户端:token 注入、超时、insecure、错误归一化(HaError)
├── ws.rs # tokio-tungstenite:握手鉴权 / 心跳 / 订阅 / 重连退避 / 事件分发(P4)
├── registry.rs # 实体/设备/区域注册表缓存(P4,房间分组的唯一来源)
├── automation.rs # 本地规则引擎:加载/保存/求值/执行/冷却/运行记录(P4)
└── commands.rs # 所有 #[tauri::command]
设计要点:
HaError归一化:把reqwest::Error/ 状态码 / WS 断开统一成{ kind, status, message },kind ∈ {auth | notFound | badRequest | network | server | unsupported},前端据此映射到 §3.6 的呈现。不要在命令里抛裸字符串(会丢掉分类信息,前端只能猜)。- 命令参数不要用
serde_json::Value:specta 无法为它生成类型(lib.rs 里本就有那份豁免清单)。控制参数用固定的ServiceParams结构 —— 顺带把"能传什么"限死了,前端不可能往 HA 的service_data里塞任意键。 - 命令一律
async,符合AI_DEV_GUIDE的"避免阻塞主线程";secrets调用是同步的短操作,可留在异步命令里(微秒级),但automations.json读写要spawn_blocking(沿用编辑器模块的教训)。 - 状态缓存加锁粒度:
Mutex<HashMap>足够(读多写少、单机场景),不必引入dashmap(终端模块用它是因为每会话高频 I/O)。 - 实体发给前端时做精简:只传
entity_id / domain / friendly_name / state / unit / device_class / 白名单 attributes / last_changed。全量attributes动辄几百 KB,IPC 序列化会明显卡(这是终端模块"大文件不要全读进内存"的同类教训)。
6.2 命令清单
| 命令 | 参数 | 返回 | 阶段 |
|---|---|---|---|
smarthome_get_settings |
— | HaSettingsView(含 tokenMasked / hasToken / 当前链路 endpointKind + endpointLatencyMs) |
P0 |
smarthome_save_connection |
HaConnectionInput(含 localUrl / remoteUrl / endpointMode) |
HaSaveConnectionResult { id, settings }——回传 id(新建后前端要靠它接着写令牌,按名称/地址反查不可靠) |
P0 |
smarthome_set_token |
connId, token |
HaSettingsView |
P0 |
smarthome_clear_token |
connId |
HaSettingsView |
P0 |
smarthome_delete_connection |
connId |
HaSettingsView(连带清除该连接的令牌) |
P0 |
smarthome_activate_connection |
connId |
HaSettingsView |
P0 |
smarthome_set_endpoint_mode |
connId, mode |
HaSettingsView |
P0 |
smarthome_test_connection |
HaConnectionInput(草案也可测)+ token(留空回落已存令牌) |
EndpointProbe[]:每个地址一条 { url, kind, ok, haVersion, locationName, elapsedMs, error, errorKind }。不返回实体数——那要拉 /api/states,在反代上会把"测试连接"拖慢数秒,实体列表 P1 本来就会拉 |
P0 |
smarthome_check_link |
connId |
LinkInfo { url?, kind?, ok, latencyMs, error?, errorKind? }——按端点策略强制新探测一次 |
P0 |
smarthome_list_entities |
connId, force: bool |
EntityListResult { entities, fetchedAt, fromCache };错误类型是 HaApiError { kind, message }(前端按 kind 分支,见 §9.2-2);force=false 且命中 60s 缓存时直接返回 |
P1 |
smarthome_save_ui_settings |
ui: HaUiSettings |
HaSettingsView(整体覆盖写入;非法 autoRefreshSec 由 heal 收敛) |
P1 |
smarthome_get_entity |
connId, entityId |
EntitySummary(在分级窗口后调用,不是常规路径);错误类型同为 HaApiError |
P2 |
smarthome_call_service |
connId, domain, service, entityId, params: ServiceParams |
ServiceCallResult { entities } —— HA 响应体里受影响实体的新状态(可能为空);错误类型 HaApiError(badRequest 时带上 HA 的原文 message) |
P2 |
smarthome_open_url |
— | — | 前端直接 openUrl,不需要命令 |
smarthome_ws_start / _stop / _status |
connId(start) |
WsStatus |
P4 |
smarthome_set_realtime_enabled |
enabled |
HaSettingsView——实时推送开关(持久化;与 ui 分开,收藏这类改动不该重连) |
P4 |
smarthome_list_registry |
connId, force |
{ areas, devices, entityAreas }(entityAreas 已按三级回退算好) |
P4 |
smarthome_list_rules / _save_rule / _delete_rule / _set_rules_enabled |
— / rule / ruleId / enabled |
RuleListResult { enabled, rules, records }——把"总开关 + 最近记录"并进同一返回,省两次往返 |
P4 |
6.3 事件清单(Rust → 前端)
| 事件名 | 载荷 | 触发时机 |
|---|---|---|
smarthome-connection-status |
{ connId, state: 'idle'|'connecting'|'connected'|'authFailed'|'disconnected', detail? } |
连接状态变化(含 WS) |
smarthome-state-batch |
{ connId, added: [], changed: [], removed: [] } |
WS 增量推送(节流后) |
smarthome-rule-fired |
{ ruleId, ruleName, at, ok, detail? } |
规则触发(P4) |
6.4 前端目录与 store
src/modules/smarthome/
├── index.ts # ModuleConfig(id: 'smarthome', icon: 'smarthome', order: 85)
├── SmartHomeModule.vue # 外壳 + useModuleTabs('smarthome', …) + 三 Tab
├── components/
│ ├── DevicePane.vue # 设备页:左筛选栏 + 右卡片网格
│ ├── DeviceCard.vue # 卡片骨架(按 domain 分发控件)
│ ├── controls/ # 每 domain 一个控件组件(LightControl.vue / CoverControl.vue …)
│ ├── EntityPicker.vue # 选择实体的可搜索下拉(规则编辑器复用)
│ ├── AutomationPane.vue # 自动化页:HA 自动化区 + 本地规则区
│ ├── RuleEditorDialog.vue # 规则三段式编辑器(P4)
│ ├── SettingsPane.vue # 设置页(连接管理 + 偏好 + 诊断)
│ ├── ConnectionDialog.vue # 新建/编辑连接 + 测试
│ └── HaStatusBanner.vue # 顶部状态/错误横幅(含"仅运行时生效"提示位)
└── format.ts # domain 图标映射 / 状态文案 / 相对时间 / 单位换算
src/stores/smartHomeStore.ts # 实体列表 · 连接状态 · 筛选条件 · 偏好 · IPC 封装
- P1 用
EntitySummary[]整份替换,不是原计划的Map + stateVersion。 P1 每次刷新都是"全量替换",换一次数组引用就触发一次更新;Map + 增量合并 + stateVersion是 P4 增量推送才需要的东西,届时再换(筛选与卡片的计算不用动,只改数据层)。 - 筛选条件(分组 / 搜索 / 只显示可控 / 隐藏离线)放 store 的会话状态里:
TabsContent会卸载非活动面板,只放在组件里的 ref 会在切走再切回时丢(§9.2-5)。 - 不新增独立窗口,因此不需要新的 capabilities 文件(只用
invoke+listen,core:default已覆盖)。
6.5 数据流与节流
P1/P2(REST)
用户操作 ──invoke──▶ Rust client ──HTTP──▶ HA
模块打开 ──invoke(list_entities)──▶ 内存缓存 ──▶ EntitySummary[] ──▶ store
P4(WS)
HA ──ws──▶ Rust ws task ──解析──▶ 内存缓存更新
│
├─ 规则引擎求值(Rust 内,零 IPC)
└─ 200ms 聚合窗口 ──▶ smarthome-state-batch ──▶ store 合并 ──▶ UI
- 200ms 聚合窗口是硬要求:一次全屋状态变化(如 HA 重启恢复、场景切换)会造成数十条消息;逐条 IPC 会让 WebView 卡住。
- 聚合窗口内的多次变更按
entity_id合并,只发最终值 + 一个changed集合。
6.6 注册清单(4 处机械改动)
src/modules/smarthome/index.ts——ModuleConfig,searchItems带上「设备 / 自动化 / 设置」三页 + 常见设备文案(便于全局搜索跳转,范式见monitor/index.ts)。src/modules/index.ts—— import + 入allModules。src/modules/icons.ts——smarthome: House(lucide)。src-tauri/src/lib.rs——mod smarthome;+.manage(...)+generate_handler!追加命令。
无需改
capabilities、tauri.conf.json、Cargo.toml(除 §2.2-1 的 feature 核实结果可能需要在tokio-tungstenite上加 feature)。
7. UI 设计
遵循 UI_DESIGN_SYSTEM.md:Tab 并入模块体系、内容区唯一滚动容器、卡片统一 Card + shadow-sm、颜色只来自 token、四态齐全。
7.1 外壳与分栏
SmartHomeModule (内容区,随外层 ScrollArea 滚动)
├ HaStatusBanner 全宽 · 仅异常/提示时占位(未连接 / 令牌失效 / 本地规则限制说明)
└ 三 Tab(设备 / 自动化 / 设置),由 useModuleTabs 注册进 TitleBar 浮动切换器
设备页 = split:左 280px 筛选栏(shrink-0,1px --border 分割)+ 右卡片网格(fill)
自动化页 = plain:纵向堆叠 gap-12(HA 自动化区 / 本地规则区)
设置页 = settings:纵向堆叠 gap-24,复用 SettingGroup + SettingRow
7.2 设备页(核心页面)
左栏(280px):搜索框(胶囊 --subtle 底)→ 分组列表(全部 / 收藏 / 灯 / 开关 / 窗帘 / 空调 / 传感器 / 其它,右侧带计数徽章)→ 两个过滤开关(只显示可控 / 隐藏离线)。P4 后在分组上方插入房间分段(数据来自注册表)。
右栏:grid-cols-1 md:grid-cols-2 xl:grid-cols-3、gap-4、items-start(各卡片高度自洽)。
实体卡片骨架(Card + shadow-sm,p-4):
┌────────────────────────────────────────────┐
│ ● 门厅吸顶灯 收藏★ ⋯ │ 状态点 + friendly_name(13/600, 截断) + 溢出菜单
│ 客厅 · 灯 │ caption(12) 房间(P4) · domain 中文名
├────────────────────────────────────────────┤
│ 开 · 亮度 70% │ 状态行:状态文字(13) 或 数值(22/600 tabular-nums)+单位(11)
├────────────────────────────────────────────┤
│ [ 开关 ] ──────○────── 2700K ──○── │ 控件区(按 domain 分发)
└────────────────────────────────────────────┘
last_changed 相对时间(12/muted) 放右上或底部
状态色语义(严格遵守 P1「状态色不用于可点击元素」;不用 --primary 表示"开"):
| 状态 | 点 / 强调 | 文案 |
|---|---|---|
on / 活动 |
--success |
开 / 运行中 |
off |
--neutral |
关 |
unavailable |
--warning |
离线(卡片整体降至 opacity 弱化,控件禁用) |
unknown |
--neutral |
未知 |
告警类 binary_sensor(烟感/水浸/门磁开) |
--danger |
触发 |
domain → lucide 图标(全部取自 @lucide/vue,--fg-secondary 色,尺寸 16 或卡片标题 20,不做装饰性 text-primary):
| domain | 图标 | domain | 图标 |
|---|---|---|---|
light |
Lightbulb |
cover |
Blinds |
switch / input_boolean |
ToggleRight |
climate |
Thermometer |
sensor |
Gauge |
fan |
Fan |
binary_sensor |
CircleDot / 按 device_class 细分(DoorOpen / Droplets / Flame) |
media_player |
Speaker |
lock |
Lock / Unlock |
vacuum |
Bot |
scene / script |
Sparkles / FilePlay |
camera |
Camera |
automation |
Workflow |
person / device_tracker |
User / MapPin |
7.3 自动化页
上半区 · HA 自动化(P3):列表行(Workflow 图标 + 名称 + 「最后触发:3 小时前」+ 状态徽章)右侧一组控件:启用 Switch / 「运行」Button(outline)/ 溢出菜单(在 HA 中打开)。
下半区 · 本地规则(P4):规则卡列表(名称 + 一句话摘要「门厅门磁 开 → 开 门厅灯」+ 启用开关 + 最近触发)+ 「新建规则」。顶部常驻警示条:--warning-soft 底 + --warning-text 文字:「本地规则仅在 Thing 运行时生效」。
规则编辑器对话框(DialogContent,三段式纵向堆叠,每段一个 SettingGroup):
触发 [实体选择器] [变化为 ▾ on/off/任意] [持续 __ 秒] | 或 [数值条件 > __]
条件 [+ 添加条件] 行式列表(时间窗口 / 实体状态),可删
动作 [+ 添加动作] 行式列表(调服务【domain+service+实体+参数】/ 延时 / 通知),可上下移、可删
───────
冷却时间 __ 秒 · 启用开关
- 实体选择器 = 可搜索下拉(复用设备页的分组能力),选中后按 domain 动态给出可选服务与参数(参数控件复用 §7.2 的 controls/)。
- 校验:动作至少 1 条、服务必填、
delay上限(如 600s,防止用户写出"睡 1 小时"的怪规则)。 - 保存前用
AlertDialog归纳"这个规则会做什么"(一句话预览),避免用户配错灯。
7.4 设置页
SettingGroup 组织,卡片式连接列表(形状与交互照抄 music/components/settings/ConnectionsSettings.vue:名称 + 类型徽章 + 地址次要行 + 编辑/激活/删除的 ghost 图标按钮 + 已连接时显示 Check 标记)。
- 组1 连接:连接列表 + 新建;对话框内
测试/保存双按钮(顺序与观感同飞牛:先关窗再异步登录,避免"已保存但卡住")。 - 组2 数据刷新:自动刷新间隔
Select(关/5/10/30s,远端链路下置灰);实时推送Switch(P4,附说明"开启后使用 WebSocket,可实时反映设备状态")。 - 组3 显示:隐藏 domain(多选)/ 隐藏实体(列表)/ 两个过滤开关。
- 组4 安全:危险操作二次确认
Switch(默认开);明文传输提示(--warning-soft条)。 - 组5 链路与诊断:当前链路(局域网 / 远程反代)徽章 + 端点强制切换
Select(auto / local / remote)+ 该端点最近一次请求耗时 / HA 版本 / 实例名 / 激活连接 / 最后成功请求时间 / WS 状态(P4)/ 「打开 HA 日志」。
7.5 四态映射(P3 原则,最易漏)
| 态 | 设备页 | 自动化页 |
|---|---|---|
| 加载 | 首次拉取的骨架卡(灰块,不用 spinner 占满屏) | 列表骨架行 |
| 空 | 未配置连接:引导卡「连接 Home Assistant」+ 主按钮(与"已连接但无实体"用不同文案——后者提示"HA 中没有可用实体,请检查集成") | 无规则:引导卡 + 新建按钮 |
| 错误 | 按 §3.6 分类:令牌失效(含"重新填写"按钮)/ 无法连接(重试按钮)/ 服务错误 | 同左(错误横幅可跨页共用) |
| 成功 | 卡片网格;顶部显示"更新于 12:03" | 列表 + 触发记录 |
7.6 视觉规范落地要点
- 数值(亮度 %、温度、功率)统一
tabular-nums,避免刷新跳动。 - 滑杆用现有
Slider(shadcn-vue)+ 右侧数值标签(label11px)。 - 相对时间由
format.ts统一输出("刚刚 / 3 分钟前 / 昨天 21:04"),避免各组件各写一套。 - 过渡:只对
opacity/transform,Tab 切换复用全局.tab-animate;卡片状态变化用--duration-fast的颜色过渡,不加位移动画(高频刷新时位移动画会很吵)。 - 图标
stroke-width已全局 1.75,无需逐个设置。 - 状态点旁必须有文字(图标不单独承载语义)。
- 中文
letter-spacing: 0。
8. 路线图
| 阶段 | 内容 | 依赖 | 交付判据 |
|---|---|---|---|
| P0 骨架 + 连接(已落地 2026-10-16,见 §9.1) | 模块注册(4 处)+ Rust smarthome/(mod/types/client/commands)+ 双地址连接管理 + 端点选择(auto/local/remote:短超时探测 + 会话粘滞 + 网络变化重探) + 令牌入凭据库 + 逐地址测试连接 + reqwest 补 gzip feature + 设置页骨架 + 链路诊断区 |
§2.2-5、-6 核实完成 | 填两个地址 + 令牌后能分别测出两跳的连通性 / HA 版本 / 实例名;令牌在凭据管理器里可见、settings.json 里没有;诊断区能显示当前链路 |
| P1 设备数据(已落地 2026-10-16,见 §9.2) | list_entities + 内存缓存 + 精简结构 + 左筛选栏(分组 / 收藏 / 搜索 / 两个过滤开关)+ 卡片只读展示 + 手动刷新 + 自动刷新偏好 + 四态 + 错误分类 |
P0 | 全屋实体正确分类展示;断网/令牌失效/未配置三种态可区分;传感器数值与单位正确 |
| P2 设备控制(已落地 2026-10-19,见 §9.3) | 按 domain 的 controls/(8 个组件)+ call_service + 乐观更新与校正(含服务响应快速通道)+ 危险操作确认 + 能力判定降级 + 后端缓存同步 |
P1 | 灯/开关/窗帘/空调四类可控;点灯即时反馈、校正失败会回滚并提示 |
| P3 HA 自动化(已落地 2026-10-19,见 §9.4) | automation.* / script.* 列表(含上次触发时间)+ 启停 + 立即运行 + 「在 HA 中管理」外链 |
P2 | 能启停并手动触发 HA 已有自动化 |
| P4 实时 + 本地规则(已落地 2026-10-19,见 §9.7) | WS 客户端(鉴权/心跳/重连/聚合,wss:// 支持)+ subscribe_entities + 注册表(房间分组)+ 规则引擎 + 规则编辑器 + 设备数据升级为实时(顺带取消远端下的单实体校正) |
P3 + §2.2-1、-3、-4 | 开关灯后 UI 在 1s 内自行更新(无需手动刷新);房间分组可用;规则能触发并留记录 |
| P5 打磨(可选) | 历史曲线(/api/history/period)、camera 缩略图、通知动作、快速面板 provider("开某盏灯"直达)、实体重命名/隐藏的 HA 侧写回 |
P4 | 按需取舍 |
工量分布(相对量级,非时间承诺):P0 与 P1 合计约占一半工作量(协议客户端 + 连接/凭据 + 列表页是地基);P2 是 domain 控件逐个铺开(机械但量大);P4 的 WS 与规则引擎是第二个技术高峰(仅次于 P1)。建议按 P0→P1 先做出"能看"的最小可用版本给用户试用,再决定 P2/P3/P4 的优先级(很可能用户看到设备列表后立刻要求控制,自动化反而往后退)。
9. 决策记录(2026-10-16 全部拍板)
| # | 问题 | 结论 | 影响 |
|---|---|---|---|
| D1 | 自动化走「管理 HA 已有自动化」还是「本地规则引擎」? | 两条都做:P3 先做前者(REST,成本极低),P4 再做后者 | P4 必然需要 WebSocket |
| D2 | 是否接受「本地规则仅在 Thing 运行时生效」? | 接受;UI 常驻声明该限制,长期可靠规则引导用户去 HA 侧建 | 规则引擎定位为「快捷 / 本地联动」,不承诺 7×24 |
| D3 | 模块 id / 显示名 |
按推荐:id = smarthome,name = 智能家居,icon = House,order = 85 |
只影响命名一致性 |
| D4 | 独立悬浮窗 / 快速面板入口 | 保留到后续(P5 用 quickpanel provider 提供"开某盏灯"直达),P0–P4 不做 | §6.4 暂不新增窗口与 capabilities |
| D5 | 是否需要 wss:// |
需要(Cloudflare Tunnel + HTTPS 反代场景必须)→ P4 补 connect + rustls-tls-webpki-roots |
§2.2-1 的 Cargo feature 已定 |
| D6 | 相机缩略图 | 先不做,P5 再议 | P1 范围不膨胀 |
| D7 | 一条连接两个地址 + 反代延迟 | P0 就做(§3.7):localUrl / remoteUrl + auto/local/remote,短超时探测 + 会话粘滞 + 网络变化重探 |
P0 范围变大,但这是"在外面也能用"的前提 |
9.1 P0 实施记录(2026-10-16:已完成,静态自检通过)
落地文件
| 层 | 文件 |
|---|---|
| Rust | src-tauri/src/smarthome/{mod,types,client,commands}.rs;setup.rs(.manage(HaManager));lib.rs(mod smarthome + 命令导入 + 两处登记);Cargo.toml(reqwest 补 gzip feature) |
| 前端 | src/modules/smarthome/{index.ts, SmartHomeModule.vue};components/{DevicePane, AutomationPane, SettingsPane, ConnectionDialog, HaStatusBanner}.vue;src/stores/smartHomeStore.ts;src/modules/{index.ts, icons.ts} 注册(icon = House, order = 85) |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
实施中定下的 7 件事(均已回写进上文)
- 探测顺序改为"局域网永远先试"(§3.7-a):原方案的 lastOkUrl 优先会把人困在反代上。
- 端点缓存 TTL 分档:局域网 60s / 反代 300s。
- 「测试连接」不拉
/api/states:EndpointProbe里去掉实体数。那是几百 KB 的响应,在反代上会把一次 1 秒的测试拖到 3 秒以上,而实体列表 P1 本来就要拉一次。 smarthome_save_connection回传id:新建后前端要立刻写令牌,按「名称 + 地址」反查不可靠(用户可能建两条同名连接)。LinkInfo/EndpointProbe都带errorKind:前端据此区分"重填令牌"(auth,重试无意义)与"重试 / 检查地址"(network/config)。分类判定留在 Rust 侧,不让前端靠匹配错误文案猜。- 可达性检查要校验响应体,不能只看状态码:反代前面若挂了访问网关(Cloudflare Access),未携带 Service Token 时会被重定向到一个 200 的 HTML 登录页——只看状态码会把它判成"链路正常",直到后续真实请求才莫名失败。因此
GET /api/必须能解析出 HA 的 JSON 响应。 - 强制模式与地址在保存时就要自洽:「仅局域网」却没填局域网地址 → 保存即报错,而不是等"检测链路"时才报(错误信息要贴着用户输入)。
踩到的两个坑
lib.rs的命令必须登记两处:export_bindings()的collect_commands!与run()的generate_handler!。只登记一处不会报错 —— 漏前者bindings.ts缺类型,漏后者"有类型但调用失败"(文件里本就有这条注释警告,这次直接按它做)。- 前端一律用裸
invoke(同 monitorStore),不引用src/lib/bindings.ts:那份文件由 debug 构建时覆盖生成,若依赖它,"还没跑过一次 debug 构建"的开发态会直接编译不过。
P0 刻意未做
- 设置页的「自动刷新 / 显示偏好 / 危险操作确认」开关分属 P1 / P1 / P2 —— 不放还不能生效的开关(放了就是骗用户)。
- 「网络变化触发清缓存」未接线(§3.7-a 最后一条),目前靠"失败即重探"覆盖一半场景。
P0 尚需真机验证(代码侧无法自证)
- 真实 HA 地址 + 令牌下,两个地址各自的连通性与耗时(在家局域网应 <20ms)。
- 令牌确实进了 Windows 凭据管理器;
{app_data}/smarthome/settings.json里 grep 不到明文。 - 「只填反代」「只填局域网」两种配置下端点策略自动收敛是否正确。
- 反代未被 Cloudflare Access 拦下(被拦会拿到 HTML 登录页 → §2.2-6)。
9.2 P1 实施记录(2026-10-16:已完成,静态自检通过)
落地范围
| 层 | 内容 |
|---|---|
| Rust | client.rs 增 fetch_entities / fetch_meta / 属性白名单提取;types.rs 增 EntitySummary / EntityListResult / HaApiError;mod.rs 增实体缓存(60s TTL);commands.rs 增 smarthome_list_entities / smarthome_save_ui_settings,并让 check_link 顺带取 HA 实例信息 |
| 前端 | format.ts(新建:分组 / 图标 / 状态文案 / 可控判定 / 相对时间 / 中文排序);DevicePane.vue 重写为 split 布局;DeviceCard.vue(新建);SettingsPane.vue 增「数据刷新」组;smartHomeStore.ts 增实体与筛选状态 |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
实施中定下的 5 件事(均已回写进上文)
- Rust 只搬运数据,表现层语义全在前端(
format.ts):分组 / 图标 / 状态文案 / 是否可控都由前端决定。HA 新增一个 domain 时只改这一个文件 —— Rust 侧不做任何"这个实体能不能控制"的判断。 - 本模块是第一个不用
String作错误类型的命令模块:smarthome_list_entities返回Result<_, HaApiError { kind, message }>,前端按kind分支(auth→ 重填令牌;其它 → 重试),不再靠匹配错误文案猜。已实测cargo check通过,说明 tauri-specta 能吃下自定义错误类型。 - 失败处理分叉:
auth→ 清空实体列表(旧数据可能是上一个有效令牌留下的,留着会误导);其它(网络抖动 / 隧道瞬断)→ 保留已有数据 + 一条提示条。远端链路上瞬时失败很常见,把整屏清空比"略旧的数据 + 明确的更新时间"更糟。 - 自动刷新在远端链路下直接不启动(不只是把开关置灰):见 §5.2。
- 筛选条件是会话状态、放 store:
TabsContent会卸载非活动面板,只存在组件里的 ref 会被重置(表现为"切去设置再切回来,搜索词没了")。
P1 刻意未做
- 「隐藏 domain / 隐藏实体」的 UI:
ui.hiddenDomains/hiddenEntityIds字段保留但暂无入口 —— 它需要每条实体的菜单,属于 P5 的「实体隐藏」范围,此刻加等于给一个没有出口的设置。 - 房间分组:要等 P4 的 WS 注册表查询(§0.4)。
P1 尚需真机验证
- 实体数量与首屏耗时(尤其远端链路),以及
/api/states的 gzip 是否真的生效。 - 小米设备经米家云时
unavailable的出现频率与呈现是否合理。 - 分组归类与卡片文案是否与实际设备对得上(
binary_sensor的device_class→ 中文映射最容易出偏差)。
真机测试发现并修复(2026-10-19):首屏不自动加载实体,切一下标签页才开始(远端约 4–5s)。 根因是
refresh()是异步的:DevicePane挂载时store.ready还是 false、activeId还是空串,loadEntities()命中「没有激活连接就直接返回」的守卫静默返回;切标签页会让面板组件 重新挂载,此时设置已就绪才真正开始拉取。 改为监听「设置就绪 / 激活连接变化」触发首次拉取(immediate: true),并给loadEntities()加了并发守卫。教训:凡是"要等异步状态就绪才能跑"的首次加载,都不能直接写在onMounted里。 (P3 时把这个触发器从 DevicePane 挪进了 store —— 自动化页有同样的需求,两处各写一遍是重复。)
9.3 P2 实施记录(2026-10-19:已完成,静态自检通过)
落地范围
| 层 | 内容 |
|---|---|
| Rust | EntitySummary 增控制所需的能力位与参数(supportedFeatures / supportedColorModes / 色温范围与当前值 / hvacModes / targetTempStep / volumeLevel / percentage,共 9 个字段,同一次拉取里拿到);新增 ServiceParams / ServiceCallResult;client.rs 增 call_service / fetch_entity;mod.rs 增 merge_entities(控制后同步缓存);commands.rs 增 smarthome_call_service / smarthome_get_entity |
| 前端 | components/controls/(8 个组件:SwitchControl / LightControl / CoverControl / ClimateControl / FanControl / MediaControl / ActionControl / ControlSlider + index.ts 映射);DeviceCard.vue 插入控件区;store 增 control()(乐观更新 + 快速通道 + 分级校正);SettingsPane.vue 增「安全」组(危险操作二次确认) |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
实施中定下的 6 件事(均已回写进上文)
- 服务响应当"快速通道"用:HA 的
POST /api/services/...响应体就是受影响实体的最新状态。因此校正顺序改为:乐观更新 → 下发 → 若响应带回的新状态确实与下发前不同就直接采用(远端链路上省一次往返,约 200–400ms)→ 否则才走分级窗口的单实体重拉。计划里只有后者(§5.3),这是纯增量的改进。 optimistic为空 = 不做校正(执行场景 / 脚本、停止窗帘):这类动作本就没有可预期的状态变化,硬做"状态没变就回滚"会冤枉一次成功执行。判据写在control()里而不是各控件里 —— 控件只声明意图,不关心校正策略。ServiceParams用固定字段而不是serde_json::Value:specta 无法为Value生成类型(lib.rs 里本就有这份豁免清单);顺带把"能传什么参数"限死了,前端不可能把任意键塞进service_data。- 控制后必须同步后端缓存(
merge_entities):否则会出现"开灯 → 切到设置页 → 切回设备页(60s 内命中缓存)→ 又显示灯是关的"这种误导。响应没带回状态时(部分云端集成)改为清缓存,宁可多拉一次也不显示控制前的旧值。 - 能力判定集中在前端
format.ts:灯的亮度/色温看supported_color_modes(而不是supported_features的旧位约定,老集成没这个属性时才回退);窗帘看supported_features的 OPEN/CLOSE/STOP/SET_POSITION 位。"宁可少给控件"由此落到实处:能力判不出来就不渲染控件。 - 滑杆的
commit与update分开:拖动走update:modelValue(只改本地值),松手走valueCommit才下发 —— 远端链路上不这样会刷出几十条命令。
踩到的一个坑
format.ts里那份本地EntitySummary接口与 store 的那份字段漂移了:P2 加能力位时只改了 store,format.ts仍用旧接口 →lightHasBrightness等函数全部报"属性不存在"。已改为从 storeimport type再 re-export,唯一来源。
P2 刻意未做
valve/alarm_control_panel/vacuum:计划把它们列进了"危险操作",但 P2 的控件覆盖范围是 §3.5 的表;这三个 domain 既没有控件也没有乐观语义,现在只做确认逻辑等于给一个不存在的按钮加锁。- 参数型控件的并发合并:快速连点 + 会连发多条
set_temperature。每按一次都是一次明确操作,暂不做防抖(P4 有 WS 之后可再评估)。
P2 尚需真机验证
- 四类设备(灯 / 开关 / 窗帘 / 空调)真机点一遍,重点看乐观更新 → 校正这一段是否与设备实际行为一致。
- 小米设备的
supported_color_modes是否符合预期(会不会出现"给了亮度滑杆但调不动")。 - 给不支持色温的灯传
color_temp_kelvin,确认400的错误文案能读(验证extract_message)。 - 远端链路上单次控制的体感延迟与"命令已下发但状态未变化"的触发频率。
9.4 P3 实施记录(2026-10-19:已完成,静态自检通过)
落地范围
| 层 | 内容 |
|---|---|
| Rust | 只加了 1 个字段:lastTriggered(attributes.last_triggered,自动化 / 脚本的"上次触发时间")。没有新增任何命令 |
| 前端 | AutomationPane.vue 从占位改为完整实现(列表 + 启停 + 立即运行 + 「在 HA 中管理」外链);store 增 openHaPage()(与设置页共用的"打开 HA 前端"出口);首次拉取触发器从 DevicePane 挪进 store |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
实施中定下的 4 件事
- P3 几乎不需要新的 Rust 代码:
automation.turn_on|turn_off与automation.trigger/script.turn_on全部走 P2 的smarthome_call_service;列表数据来自 P1 的实体列表。这验证了前面把"服务调用"做成通用命令、把"能力与语义"留给前端的边界划分是对的。 - 「运行」传空乐观状态:触发不会让这条实体自身产生可预期的状态变化 —— 空乐观状态会跳过"状态没变就回滚"的校正,否则一次成功的触发会被提示成"命令已下发,但设备状态未变化"(与
ActionControl同一条规则,§5.3 的例外分支)。 - 脚本只有「运行」,没有启停开关:
script.turn_off的语义是"停止正在运行的脚本"而不是"禁用脚本",摆一个开关会误导(HA 侧禁用脚本要在设置里改)。自动化才有turn_on|turn_off的启用语义。 - 首次拉取触发器进 store:设备页与自动化页都要"等设置就绪再拉实体",两处各写一遍 watch 是重复;放进 store 后两页都不必关心,且天然带并发守卫。
P3 刻意未做
- 不做自动化编辑(§5.4-A):HA 自己的自动化编辑器更强,在本地重做一遍是重复劳动。列表里给一个「在 HA 中管理」外链(
/config/automation),要改就去 HA 改。 - 不做「跳过条件强制执行」(
skip_condition):默认 false 就是"照常走条件"的语义,多一个开关只会让人误点。
P3 尚需真机验证
- 「运行」是否照常走条件判断(
automation.trigger的skip_condition默认 false)。 - 启用 / 停用开关是否真的让自动化不再触发(去 HA 侧看状态是否同步)。
last_triggered是否在有automation.*实体上都有值(部分集成可能不带该属性,届时显示"尚未触发过"是正常的)。- 脚本实体的
state语义是否与展示一致(on表示正在运行 /off表示空闲)。
9.5 P4 前置验证(真机,2026-10-19)
用用户的实例(https://ha.lfeng.me,HA 2026.10.1,577 实体)把 P4 的前置假设全部实测了一遍。
| 项 | 实测 | 对 P4 的含义 |
|---|---|---|
| 握手 | auth_required(ha_version 2026.10.1) → auth → auth_ok |
协议与预期一致 |
subscribe_entities |
支持;首帧 577 实体 / 152 KB / 2.23 s | HA ≥ 2023.11 无虞;首帧是一条大消息(tungstenite 默认 64 MiB 上限够用) |
| 30 秒增量 | 2 个事件 / 328 B / 最大单帧 165 B | 空闲期几乎无流量 —— 这正是远端链路下 WS 优于轮询的根本原因 |
ping / pong |
617 ms | 反代链路的真实往返;心跳与聚合窗口按它设计 |
| 区域注册表 | 可用(客厅 ke_ting 等) |
房间分组可行 |
| 实体注册表 | 606 条,带 area_id 的 0 条 |
计划假设错误,见修正 1 |
| 设备注册表 | 36 条,带 area_id 的 27 条 |
房间归属在设备上 |
tokio-tungstenite |
connect 已随 default 启用;TLS 未启用 |
要支持 wss:// 必须补 rustls-tls-webpki-roots(复用依赖树里已存在的 rustls 0.23,不新增编译单元) |
修正 1:房间分组必须走「实体 → 设备 → 区域」三级回退。
entity_registry 的 area_id 在这台实例上全空;36 个设备里 27 个有 area。计划 §3.3 原本只写了实体的 area_id,照做会得到一间房都没有。
实现时:entity.area_id → 有则用;否则 entity.device_id → device.area_id;仍无 → 归入「未分配房间」分组(36 个设备里 9 个没有 area,这个分组是必需的不是兜底)。
修正 2:climate 的温度单位与上下限不能写死(真机 bug,已修)。
这台实例是美制单位制:min_temp 61 / max_temp 86 / target_temp_step 1 / temperature 77。而 P2 的控件写死了 5..35 钳制 + °C 显示 —— 77 会被钳成 35。
已修:EntitySummary 增 minTemp / maxTemp(用实体自带的);温度单位改从 /api/config 的 unit_system.temperature 读,随连接记录(temperatureUnit);首次拉实体时若还不知道实例信息,顺带取一次 /api/config(之后不再请求)。「测试连接」的结果也一并显示单位。
修正 3:灯关着时 HA 不给 brightness / color_temp_kelvin(真机上都是 null)。
原先滑杆按 0 与范围上界摆位,等于宣称"亮度最低、色温最冷"。已改为取范围中点作中性占位(拖动本身会带上明确值并开灯,所以不影响正确性)。
顺带记录:这台实例的实体构成(决定控件覆盖是否够用)
- 577 实体:sensor 122、number 100、event 88、switch 84、button 56、notify 42、text 25、select 25、light 12、binary_sensor 9,其余零散;unavailable 47
- 没有
cover/lock/vacuum/valve/alarm_control_panel—— P2 做的窗帘/门锁控件在这台实例上没有实测对象 - 已有控件的:switch 84 + light 12 + climate 1 + fan 1 + media_player 1 ≈ 99 个
- 能控但还没控件的:
number/button/select/text共 206 个(投影仪音量、摄像机变焦、输入信源、开机/播放/暂停按钮全在这里) - 灯的能力分布:
onoff8(不给滑杆,判断逻辑正确)、color_temp3、rgb1;supported_features是 0(证实了"看supported_color_modes而不是旧位约定"是对的)
待决策(需用户拍板):是否补
number(滑杆 + 数值输入,number.set_value)、button(按下,button.press)、select(下拉,select.select_option)三类通用控件?它们能覆盖这台实例 206 个能控实体(占 1/3 以上),成本是 3 个小组件 —— 收益/成本比明显高于继续铺别的 domain。text(text.set_value)建议暂缓:里面有"移动侦测时间段"这类需要格式约束的语义,输入错格式只能靠 HA 返回 400 兜底。 → 已拍板(2026-10-19,用户选 A):先补这三类,再进 P4。实施记录见 §9.6。
9.6 通用域控件(number / select / button,2026-10-19:已完成,静态自检通过)
背景:真机数据显示 577 个实体里 206 个"能控但没有控件"(number 100 / button 56 / select 25 / text 25)。经用户拍板选 A(先补再进 P4)。
落地范围
| 层 | 内容 |
|---|---|
| Rust | EntitySummary += min / max / step / options;ServiceParams += value(number.set_value)、option(select.select_option) |
| 前端 | NumberControl.vue(滑杆,复用 ControlSlider)、SelectControl.vue(下拉);ActionControl.vue 扩到 button;format.ts 增分组「数值 / 下拉 / 按钮」、可控域、图标与参数完备性判定 |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
定下的 4 件事
- 上下限与步长一律用实体自带的:真机上这批差异极大 —— 0–100 的扬声器音量、10–90 的摄像机变焦倍数、步长 180 的图像翻转角。写死任何一个都会让另一批实体没法用。参数不全(缺 min/max、max ≤ min、步长 ≤ 0)时不渲染控件。
isControllable与"能不能渲染出控件"共用同一个口径:数字实体缺参数、下拉实体没选项时算作只读 —— 否则会出现"在『只显示可控设备』过滤里、卡片却没有控件"的别扭状态。- 按钮归到
ActionControl:它与场景 / 脚本同属"无乐观状态的动作"类(按钮的state是"上次按下时间"而不是状态),共用"不做校正"那条规则;只是服务从turn_on换成press、文案从"执行"换成"按下"。 - 按钮反过来要"有"乐观状态:既然它的
state就是按下时间,按下时就乐观地把state与lastChanged一起改成当前时刻 —— 卡片底部的相对时间立刻跳到"刚刚",否则按一下在界面上毫无痕迹(只有 toast)。带上乐观状态后,它也自然走回"服务端确认就采用、否则分级校正"的常规流程。
未做:text(text.set_value)—— 里面有"移动侦测时间段"这类需要格式约束的语义,输错只能靠 HA 返回 400 兜底,收益低于另外三类。
待真机验证
number滑杆在步长很大时的体验(步长 180 只有两档,滑杆是否显得别扭)。select的当前值不在options里时(HA 的unknown),下拉是否显示异常。- 按钮按下后卡片底部的相对时间是否立刻更新,且校正后与服务端时间一致。
9.7 P4 实施记录(2026-10-19:已完成,静态自检通过)
落地范围
| 层 | 内容 |
|---|---|
| Cargo | tokio-tungstenite 补 connect + rustls-tls-webpki-roots(D5:必须支持 wss://);futures-util 显式开 sink |
| Rust | ws.rs:握手 / 鉴权 / 心跳 25s / 半开检测 / 指数退避重连(上限 30s)/ auth_invalid 停止重连 / 200ms 聚合 / 请求-应答通道;registry.rs:三张注册表 + 实体 → 设备 → 区域三级回退;automation.rs:三段式规则 + 冷却 + 动作失败不中断 + 突发循环保护 + 运行记录 |
| 命令 | smarthome_ws_start / _stop / _status、smarthome_set_realtime_enabled、smarthome_list_registry、smarthome_list_rules / _save_rule / _delete_rule / _set_rules_enabled |
| 事件 | smarthome-connection-status(WsStatus)、smarthome-state-batch(StateBatch)、smarthome-rule-fired(与 RuleRecord 同构) |
| 前端 | store 接三类事件 + 增量合并(applyBatch);设备页房间分段 + 卡片副标题「房间 · 类型」;设置页「实时推送」开关与「实时连接」诊断;自动化页本地规则区 + RuleEditorDialog + EntityPicker |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
定下的 6 件事(含与计划的差异)
- WS 的粒度是"应用",且由 Rust 侧持有(plan §3.3 第一条)。台账在
HaManager.ws,Tab 切走不关连接;smarthome-connection-status只推"状态变化",不推心跳。 - 事件必须"先合并回原始对象再推导摘要",不能整份替换。 真机上
c(changed)里的 attributes 可能是差量({"+": {...}, "-": [...]}),照文档只做浅合并会在下一次事件里把未变化的字段抹掉。因此ws.rs维护一份HashMap<entityId, RawEntity>(state + 完整 attrs + last_changed),差量合并后再走与 REST 同一条client::to_summary,保证两条链路算出的EntitySummary完全一致。 subscribe_entities的首帧就是全量快照,所以"重连后重新拉一次全量"这件事不需要额外请求:reset_state()清空本地状态,重连时会自然收到全量a段。断线期间的增量由此补齐。- 房间映射严格按三级回退(§9.5-1 的真机修正):
entity.area_id→device.area_id→ 前端「未分配房间」。真机 36 个设备里 9 个确实没有区域,所以这一档是必需分组而不是兜底。 - 规则靠 WS 驱动 ⇒ 规则总开关开着就必须有连接。 引入
HaManager::sync_ws(幂等):realtime.enabled || rules.enabled为真时要有一条连接,为假时断开。它在启动、以及每次改连接 / 令牌 / 端点策略 / 实时开关 / 规则之后被调用。代价是"关掉实时推送仍可能保持连接"(当规则开着),这是有意的:规则没连接永远不会触发。 - 控制后的单实体校正:实时推送开着时跳过(plan §5.3 的"P4 之后"分支落地)。推送本身就是服务端真值;只有连接刚断时才退回轮询校正。
与计划的两处差异(有意为之)
smarthome_list_rules返回RuleListResult { enabled, rules, records }而不是裸Rule[]:自动化页进来就要这三样,拆三条命令只是多两次往返。- 实时推送开关不放在
ui里,而走独立的smarthome_set_realtime_enabled:save_ui_settings会被收藏 / 自动刷新这类改动频繁调用,若它带上"重连"语义,点个收藏就会让灯闪一下。
未做 / 已知缺口
- 自签名证书的
wss://:insecure目前只覆盖 REST(tungstenite 的证书校验开关没接)。反代是正式证书,不受影响;局域网是http://,也用不到。 - 规则的
notify动作走系统通知(tauri-plugin-notification),不写 HA 的persistent_notification。 - 运行记录只在内存(最近 50 条,重启清空);持久化的只有每条规则的
lastFiredAt/fireCount/lastError。 - 条件之间只有 AND(要 OR 就建两条规则);动作不支持嵌套与分支。
待真机验证
- 开关灯 → UI 在 1s 内自行更新(无需手动刷新)。
- 断网 / 挂断隧道 → 自动重连成功并恢复全量(
auth_invalid除外:那种情况停止重连并弹横幅)。 - 房间分段与真实房间对得上,尤其「未分配房间」这一档的数量。
- 规则能触发并留记录;A↔B 互触规则不无限循环(冷却 + 10s/5 次的突发护栏)。
- 反代链路上
wss://能否建连(本次只补了 TLS feature,尚未在真机连过 WS over TLS)。 - 半开连接的判定是否合适(25s 心跳 / 75s 无入站即断开重连)——在反代
ping/pong617ms 的基线上应留有余量。
9.8 全链路复审与修复(2026-10-19)
对 P0–P4 全部代码做了一次从头重读的复审(不再依赖之前的实施印象),修掉 10 项。
| # | 问题 | 根因 | 修复 |
|---|---|---|---|
| 1 | 重连/首帧会让规则凭空触发 | subscribe_entities 首帧就是全量快照,而 commit() 对"首次见到"也走了规则求值 → 只配「变化为 on」的边沿触发规则在每次连接/重连各执行一次 |
ws.rs:新增实体只计入批次,不求值规则(快照不是"变化") |
| 2 | 同一规则可在同一瞬间重复执行 | 冷却是"先读后写",动作是 async(可能几秒),同窗口两条事件各自起 fire → 都读到旧时间戳通过冷却 |
automation.rs:抽出 claim(),在同一把锁里判冷却并写下占位,后到的被挡掉 |
| 3 | 切换连接后房间是上一实例的 | cached_registry() 只判 TTL,不看 connId |
缓存条目带 connId + clear_registry_cache();activate / delete_connection 显式失效 |
| 4 | 切连接后卡片网格空白且无解释 | 前端只清了实体,没清 filterRoom / registry |
store.resetConnectionScope() 统一清理连接作用域状态 |
| 5 | 实时推送下控制没有兜底,UI 可能永远停在乐观值 | if (wsConnected) return 把 plan §5.3 要求的"1.5s 超时兜底"丢了 |
store.scheduleWsFallback():1.5s 内该实体没被推送改过 → 回滚 + 诚实提示 |
| 6 | 每触发一次就整份序列化 + 写盘 | 统计字段随触发频率线性写盘(传感器抖动场景很常见) | maybe_persist() 去抖(内存立即更新,磁盘最多每 3s 一次);命令层的显式保存仍立即写盘 |
| 7 | for(持续 N 秒)触发按事件起定时任务 |
1Hz 实体 + for=300 → 常驻几百个任务,且不受连接切换影响(会用旧端点/旧令牌执行动作) |
改为槽位表(pending)+ 巡检任务 spawn_sweeper(与 WS 连接同生命周期);语义仍是"持续满足 N 秒" |
| 8 | 实时已连上仍在按 5s 拉全量 | 只按"是否反代"置灰 | 自动刷新在实时连接就绪时同样置灰,并写明原因(设备页与设置页都改) |
| 9 | 设置页永远显示"已连接(0 个实体)" | flush() 只更新内存里的 entity_count,从未 emit |
数字变化时补一次 smarthome-connection-status;同时首帧/每次入站更新 last_event_at、断开时清零 connected_at;flush() 改为一次锁收集两批 |
| 10 | 交互/一致性 | ① EntityPicker.controllableOnly 是死参数;② 规则列表无加载态(闪"还没有规则");③ 每次触发都弹 toast;④ 没开实时也常驻房间提示;⑤ 注释许诺了不存在的"自定义服务"入口 |
① 真正生效并用于动作实体(限可控);② 加 rulesLoading 骨架;③ 只在失败时弹;④ 房间分段仅在开启实时后出现;⑤ 注释与实现对齐;另补 aria-current / aria-pressed |
复审结论(保留意见,不打算改)
bg-subtle与项目里更常见的bg-muted并存:两者都是style.css里已定义的设计 token(--subtle/--muted取值相同),且本模块 P0 的ConnectionDialog与 diff 模块都在用bg-subtle。保留现状,不做全局替换。last_changed在紧凑事件帧里按c→lc→lu兜底取用:HA 的紧凑形态是c=last_changed、lc=last_updated,个别版本只带lc时"x 分钟前"会有偏差但不影响状态本身。属已知近似,待真机核对。- 未做的一类:
connect_async本身没有独立超时(只有握手阶段 20s 超时)。端点已经过探测才连,实际风险低,记录在案。
自检:cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
9.9 设备视角重构:按设备展示 + 三级分层(2026-10-19,已完成)
触发:用户反馈"设备的显示很混乱,会显示出所有设备的所有项",要求改为
「一级卡片只显示主要信息与主要设置 → 点进二级详情 → 不常用/不可改的项进三级」。
先用真机做了两次只读普查(GET /api/states + config/*_registry/list,无 call_service),
再按数据设计,最后把算法搬到真机数据上验证过才落地。
真机普查结论(决定设计的关键数据)
| 项 | 实测 | 对设计的影响 |
|---|---|---|
| 实体 | REST 577 / 注册表 606(隐藏·禁用的 32 条 REST 不返回) | 只用 REST 就是"一屏 577 项"的根因 |
| 有 device_id 的实体 | 604 / 606(只有 person / todo 没有) |
按设备聚合可行 |
| 设备 | 36 个 + 1 组未归组 | 一级从 577 项降到 37 张卡 |
| 每设备实体数 | min 1 / 中位 9 / max 110(摄像机) | 设备内部必须再分层,否则详情页还是墙 |
entity_category |
只有 30 / 606 条有值(diagnostic 18 / config 12) | 只能当"高级"的判据之一,不能单独用 |
friendly_name |
结构是 "<设备名> <功能组> <项>"(如「厨房插座 功耗参数 电功率」) |
去掉设备名前缀后可解析出功能组 → 详情页按组归拢 |
| 扩展功能标记 | 集成为扩展/实验性功能打 * 前缀(如「* 充电保护 开关」) |
天然的"高级项"判据 |
entity_id 规律 |
_s_2 =本体、_p_2_1 =基础功能点第 1 项 |
用来稳定选出"主实体"(插座的主开关就是 _on_p_2_1) |
| 系统类设备 | 12 个(Sun / Backup / HA 的 Core·Supervisor·OS / HACS安装器 / Shopping list / Forecast …) |
默认隐藏,左栏给开关 → 不淹没真设备 |
三级分层规则(全部落在表现层 modules/smarthome/format.ts)
- 一级
DeviceCard:名字 + 主控 + 最多 2 个关键读数- 插座 = 名字 + 开关 + 功率/耗电(真机验证输出与原话要求一致)
- 灯 = 名字 + 开关(含亮度/色温)+ 读数;温度计 = 名字 + 温度/湿度
- 二级
DeviceDetail:主控 + 「常用」功能组(每组可折叠,默认只展开含主控的组与第一组)- 组内可控项 → 复用
controls/的控件;只读项 → 一行「名称 + 值 + 单位 + 变化时间」(EntityRow)
- 组内可控项 → 复用
- 三级 「高级设置」折叠区:
entity_category ∈ {config, diagnostic}∪ 功能组带*∪domain ∈ {event, notify, text, todo, tts, image, update…};展开后仍按功能组归拢并视觉降级 (还露出原始entity_id,便于去 HA 排查)
主实体 / 关键读数怎么选(primaryScore / readingScore,真机调过三轮)
- 主控:本体(功能组为空)−100、
_s_2/_p_2_1−50、功能组以「开关」「灯」开头 −10,再按 domain 优先级 - 读数:优先
device_class∈ 功率/电量/温度/湿度/光照/电流/电压/电池/人体在场… ; 有单位但离线的也保留(体脂秤离线时应显示"体重 离线"而不是空白);timestamp/date/time/enum明确排除(否则「太阳 下个清晨」「备份 下一次自检」会跑到卡片上); 枚举型(带options)降级到末尾 - 兜底:只有没有任何控件的设备才会拿"高级项"当读数 —— 有主控的设备宁可卡片干净
(真机上「电脑」的读数全是
开机时间提醒 4294967295 min这类垃圾)
落地范围
| 层 | 内容 |
|---|---|
| Rust | registry.rs / types.rs:RegistryResult += entity_registry(entity_id → device_id / name / entity_category);HaDevice += name_by_user / manufacturer / model;save_connection 首次保存时默认打开实时连接(设备聚合依赖 WS) |
| 前端 | format.ts += buildRegistryIndex / buildDevices / splitDevice / readingLabel / readingValue / deviceIcon 等设备级语义;新增 DeviceDetail.vue / EntityRow.vue;DeviceCard.vue 重写为设备卡;DevicePane.vue 重写为设备网格 + 详情切换 + 左栏(房间/类型/收藏/搜索/三个过滤开关);DevicePane 新增「按设备浏览需要实时连接」的降级提示(不做回退平铺,那正是要摆脱的东西) |
| 验证 | 把 format.ts 的算法原样搬进临时脚本跑真机数据,逐台核对卡片预览(37 台),据此修掉了 4 个问题:枚举型被当读数、「有主控也要兜底读数」导致垃圾读数、timestamp 类被当读数、无控件无读数的系统设备占首页 |
| 自检 | cargo check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题 |
已知不足(真机数据决定,非实现缺陷)
- 「米家智能空气炸锅」的设备里没有更"本体"的开关,主控落在「自动保温功能」上;
- 「小米智能摄像机」的实测读数落在「图像翻转 / 报警时间间隔」上(该设备没有更典型的数值型读数);
- 「米家体脂秤」在这台实例上只暴露事件 / 通知 / 按钮(没有体重传感器实体),因此卡片是一个"查询离线数据"按钮;
- 摄像机一个设备仍有 75 个"常用"项 —— 靠功能组折叠收敛,要靠自己再筛得用 HA 的"隐藏实体"。
待真机验证:一级网格是否一眼可用;插座卡片是否就是"名字 + 开关 + 功率"; 点进详情后常用组折叠是否顺手;三级折叠区能否找到某个高级项;系统设备开关是否符合预期。
9.10 设备页重排 + 卡片美化 + 分类与两处识别缺陷修复(2026-10-20,已完成)
触发:用户反馈四条 —— ① 分类太多,要"按识别到有的设备再分类";② 分类要改成顶部横排按钮、去掉侧边栏、
设备卡片平铺;③ 卡片内部上下留白过多、不协调;④ 设备「酷态科10U」是充电器却被识别成按钮。
先用真机(ha.lfeng.me,36 设备 / 606 注册表实体 / 577 REST 实体)复算现有算法定位根因,改完再用同一份数据回归。
缺陷 1:卡片上下留白 38px(不是审美问题,是样式覆盖漏项)
Card 默认 py-6 + gap-6;DeviceCard 只覆盖了 gap-0,漏了 py-6,CardContent 又叠 py-3.5
→ 上下各 24+14=38px。修法:Card 补 !py-0 !gap-0,内距只由 CardContent 的 px-3.5 py-3 决定
(与 DeviceDetail 的写法一致)。构建产物已验证 .\!py-0{padding-block:0!important} 正常生成。
缺陷 2:「酷态科10U」被判成按钮(两个叠加根因)
- a. 单实体设备的前缀解析吃掉
*高级标记:commonNamePrefix对只有一个实体的设备会返回 "整条名字截到最后一个空格"。该设备只有一条酷态科10U * 充电器 恢复默认设置,前缀被算成酷态科10U * 充电器,解析出item=恢复默认设置、starred=false→ 这个"恢复默认设置"按钮被当成主控, 卡片上真的渲染出一个会重置设备的「按下」按钮。 修法:新增deviceNamePrefix,优先用「设备名 + 空格」,commonNamePrefix只作兜底。 真机核对:36 台设备除未归组的LFeng/Shopping list外全部命中(含摄像机那种双空格分隔)。 - b.
hasControl与primary口径不一致:hasControl用"存在任意可控实体"(不排除高级项),primary排除高级项 → 出现"自称可控、卡上却没有控件"的设备。修法:hasControl同样排除高级项, 于是「酷态科10U」落进"无控件设备"(默认隐藏,开关可显)。
分类:12 个 domain 分组 → 9 个设备能力分类
number / select / button 是控件形态不是设备类别 —— 真机上「投影仪」因此落进「数值」、
「米家体脂秤」「酷态科10U」落进「按钮」。新表(DEVICE_GROUPS):
| key | label | domains | 真机命中 |
|---|---|---|---|
light |
灯 | light | 4(电脑挂灯 / 香氛机 / 床头灯 / 厨房灯) |
switch |
插座·开关 | switch、input_boolean | 10 |
climate |
空调 | climate | 1(空调伴侣) |
fan |
风扇 | fan | 1 |
media |
影音 | media_player | 0 → 不渲染 |
cover |
窗帘 | cover | 0 → 不渲染 |
lock |
门锁 | lock | 0 → 不渲染 |
sensor |
传感器 | sensor、binary_sensor、person、device_tracker、weather | 8 |
other |
其它 | 其余 | 1(投影仪) |
配套新增 deviceRoleDomain(主控 domain → 读数 domain → 可见实体多数 domain → other),
让 mostCommonDomain 不再拿 button 兜底;设备 role 逐级回退到 other 才是诚实的。
顶部横排按钮只渲染"确实有设备"的分类(空分类不占位)。
布局重排
去掉左侧 280px 筛选栏,改为自上而下:状态工具条 → 分类 pills(横向可滚动、带计数) →
过滤行(搜索 + 房间 Select + 三个开关)→ 设备网格
grid-cols-1 sm:2 lg:3(lg 以上固定一行 3 个,不再上到 4)+ gap-3 + items-stretch(卡片 h-full + 底部 mt-auto,同行底边对齐)。
房间从 nav 列表改成紧凑下拉,且没有房间时不占位;「显示系统设备」改名为**「显示无控件设备」**
(store 字段名不动)。
卡片美化(只用既有 token):图标包进 size-8 rounded-lg bg-muted 方块;名字 13px/medium +
房间 · 类型 副标题收在图标右侧;读数行更紧凑;底部分隔线 + 项数 + 详情 ›(hover 转 --primary);
hover:border-border-strong hover:shadow-md;离线 opacity-60。
验证:把改后的算法原样搬进临时脚本跑真机数据 —— 酷态科10U / 体脂秤 → role=other、primary=null、systemOnly=true;
投影仪 → other;可见设备分组 switch 10 / light 4 / sensor 8 / fan 1 / climate 1 / other 1,number、button 分组已消失。
vue-tsc --noEmit 0 错误 · eslint src 0 问题 · vite build 成功;并逐类核对构建产出的 CSS,
确认 bg-subtle / bg-muted / border-divider / !px-3.5 等类都真实生成(避免"未定义工具类导致样式缺失"的老问题)。
已知取舍:「小米智能摄像机 4 变焦版」主控是 switch,因此落在「插座·开关」(HA 的设备注册表里没有设备类别字段,
只能按主 domain 判);「智能音箱 Pro」主控是 麦克风 静音 的 switch,也落在「插座·开关」而非「影音」。
10. 风险与不做的事
风险
| 风险 | 级别 | 缓解 |
|---|---|---|
| 小米设备经米家云,控制延迟高、偶发"命令成功但状态不变" | 中高 | 乐观更新 + 校正 + 诚实措辞(§5.3);设置页提示这是云端特性而非本模块缺陷 |
| WS 事件风暴打爆 IPC | 中 | 200ms 聚合 + store 用 stateVersion 标量驱动(§6.5) |
| 令牌失效难以察觉(10 年有效期让人以为永不过期) | 中 | 401 立即横幅 + 不重试 + 诊断区显示最后成功时间 |
| HA 版本差异导致 WS 命令不可用 | 中 | GET /api/config 版本探测 + 能力降级(REST 兜底) |
| 实体数量大(1000+)导致首屏卡 | 中 | 精简结构 + 卡片网格不做全量虚拟滚动,用分组/搜索收敛可见集;必要时 P5 引入虚拟滚动 |
| 危险操作误点(解锁 / 开门) | 中 | 二次确认(默认开)+ 无二次口令(低收益高摩擦) |
明文 http:// 局域网传输令牌 |
低 | 设置页显式提示 + 支持 HTTPS + 建议内网 |
| 本地规则与 HA 自动化互相触发形成循环 | 低 | 冷却时间 + 执行链深度上限(§5.4) |
不做的事
- 不做 HA Lovelace 替代 / iframe 内嵌(WebView 里嵌 HA 前端体验与鉴权都更差)。
- 不做设备配网、集成添加/删除(HA 的职责)。
- 不做小米账号登录、不做米家云直连。
- 不做 HA 自动化 YAML 编辑、不做模板语法编辑。
- 不做多实例聚合视图(数据结构支持多连接,但一次显示一个)。
- 不做状态写回(
POST /api/states)。 - P1 不做 camera 缩略图、不做历史曲线。
11. 开工清单
按顺序执行,每步都可独立验证。
准备(2026-10-19 已基本完成,结论见 §9.5)
reqwest补gzipfeature(P0)。实测 265,973 B → 45,890 B(5.8×),耗时 3.96s → 2.30s。- 实测 HA:
/api/200;/api/config显示版本 2026.10.1、实例名「我的家」、单位制美制;/api/states577 实体 / 266 KB。 - 反代链路基线:
ping/pong往返 617 ms;未挂 Cloudflare Access(直接返回 JSON,没有登录页)。 - 一次性 WS 脚本实测:握手正常、
subscribe_entities支持(首帧 577 实体 / 152 KB / 2.23s;30 秒内 2 个增量事件)、区域 / 实体 / 设备注册表全部可用。 tokio-tungstenite实际 feature(cargo tree -e features -i tokio-tungstenite):connect已随 default 启用,TLS 未启用 → P4 补rustls-tls-webpki-roots(复用树里已有的 rustls 0.23)。- 局域网地址的实测耗时:当前不在局域网,待回家后补测(§9.5 的结论都来自反代链路)。
opener:default打开局域网http://地址:目前只验过https://ha.lfeng.me(可用),http 待回家后确认。
P0(已完成,2026-10-16 —— 实施记录见 §9.1)
- 前端:
src/modules/smarthome/index.ts+SmartHomeModule.vue(三 Tab 壳)+DevicePane.vue/AutomationPane.vue/SettingsPane.vue/ConnectionDialog.vue/HaStatusBanner.vue;注册src/modules/index.ts与icons.ts。 - Rust:
smarthome/{mod,types,client,commands}.rs;lib.rs注册mod+setup.rs里.manage(HaManager)+generate_handler!与export_bindings()的collect_commands!两处都已登记。 Cargo.toml:reqwest补gzipfeature。- 连接模型双地址(
localUrl/remoteUrl)+endpointMode;secrets键名smarthome-token-<connId>;settings.json读写(version + 自愈,照抄dsh/mod.rs)。 - 端点选择:
local(900ms) → remote(5000ms)(修正后的顺序,见 §3.7-a),会话粘滞(局域网 60s / 反代 300s),请求失败立即重探。 - 连接列表 UI(照抄
ConnectionsSettings.vue的交互)+ 逐地址测试连接(两跳各自给结果)+ 令牌掩码回显 + 链路诊断区。 - 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(需真实 HA + 令牌,见 §9.1 末节):填错令牌报「令牌失效」;凭据管理器里能看到条目;
settings.json中 grep 不到令牌明文;两个地址各自测得出结果;故意把局域网地址写错后能自动落到反代。
P1(已完成,2026-10-16 —— 实施记录见 §9.2)
smarthome_list_entities(内存缓存 60s + 精简EntitySummary;HaApiError分类错误)。src/stores/smartHomeStore.ts增实体与筛选状态 +format.ts(分组 / domain 图标 / 状态文案 / 可控判定 / 相对时间 / 中文排序)。DevicePane.vue(split:左筛选栏 + 卡片网格)+DeviceCard.vue(只读态 + 收藏置顶)。- 四态 + 错误分类(§3.6 / §7.5):
auth清空数据、其它错误保留数据并提示。 SettingsPane.vue增「数据刷新」组(自动刷新间隔;远端链路下停用)。- 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(见 §9.2 末节):实体数量与首屏耗时(尤其远端)、gzip 是否生效、
unavailable呈现、分组与卡片文案是否与实际设备对得上。
P2(已完成,2026-10-19 —— 实施记录见 §9.3)
smarthome_call_service+smarthome_get_entity(错误类型继续用 P1 的HaApiError)+ 乐观更新 + 服务响应快速通道 + 分级单实体校正 + 危险操作确认。controls/:LightControl(开关 + 亮度 + 色温)、SwitchControl(switch / input_boolean / automation / lock)、CoverControl(升降停 + 位置)、ClimateControl(模式 + 温度步进)、FanControl、MediaControl、ActionControl(场景 / 脚本)+ControlSlider。- 乐观更新 + 分级校正(局域网 600ms / 远端 2000ms)+ 失败回滚提示;滑杆松手(
valueCommit)才下发。 - 危险操作
AlertDialog(开锁 / 窗帘全开)+ 设置页「安全」组可关;能力判定降级(判不出来就不出控件)。 - 控制后同步后端实体缓存(
merge_entities),避免"切页再切回又看到控制前的旧值"。 - 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(见 §9.3 末节):四类设备点一遍看"乐观更新 → 校正"是否与设备实际行为一致;小米灯的
supported_color_modes是否匹配;给不支持色温的灯传非法参数看400文案;远端的控制体感延迟与"状态未变化"提示频率。
P3(已完成,2026-10-19 —— 实施记录见 §9.4)
- 从
list_entities结果里切出automation.*/script.*;AutomationPane.vue完成实现(列表 + 状态点 + 上次触发时间 + 类型徽章)。 - 启停(
automation.turn_on|turn_off)+ 立即运行(automation.trigger/script.turn_on)+ 「在 HA 中管理」外链。 - Rust 只加
lastTriggered字段(不需要新命令,验证了 P2 的边界划分)。 - 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(见 §9.4 末节):触发是否走条件;启停是否真的生效;
last_triggered的可用性;脚本state语义。
P3.5 通用域控件(已完成,2026-10-19 —— 实施记录见 §9.6)
NumberControl.vue(上下限/步长取实体自带的;参数不全不渲染)+SelectControl.vue(选项取实体的options)。ActionControl.vue扩到button(press+ 按钮的乐观 state/lastChanged)。format.ts增分组「数值 / 下拉 / 按钮」、可控域与图标;isControllable与"能否渲染控件"统一口径。- Rust:
EntitySummary+=min/max/step/options;ServiceParams+=value/option。 - 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(见 §9.6 末节):大步长滑杆的体验、
select当前值不在选项里时的显示、按钮按下后相对时间是否立刻更新。
P4(已完成,2026-10-19 —— 实施记录见 §9.7)
Cargo.toml:tokio-tungstenite补connect+rustls-tls-webpki-roots(D5:要支持wss://);futures-util显式开sink。ws.rs:握手 / 心跳 / 重连退避 /auth_invalid停止重连 / 200ms 聚合;smarthome_ws_start|stop|status;端点选择复用 P0 的逻辑(ws:///wss://均按所选端点)。registry.rs:注册表拉取 + 房间分组接入左栏(含"未分配房间"分组;三级回退见 §9.5-1)。automation.rs:规则模型 / 加载保存(spawn_blocking)/ 求值 / 执行 / 冷却 / 循环保护 / 运行记录。RuleEditorDialog.vue+EntityPicker.vue;设置页实时推送开关(smarthome_set_realtime_enabled)与「实时连接」诊断行。- 设备数据从"拉取"切到"推送 + 校正"(卡片更新不再依赖手动刷新;实时连接建立后跳过单实体校正)。
- 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(见 §9.7 末节):开关灯 → UI 1s 内自行更新;拔网线 → 自动重连成功并恢复全量;房间分段与真实房间对得上;规则触发留记录;A↔B 互触规则不无限循环;反代链路上的
wss://建连。
P4.9 设备视角重构(已完成,2026-10-19 —— 实施记录见 §9.9)
- 真机普查(只读):604/606 实体有 device_id、每设备实体中位 9/max 110、
friendly_name三段结构、*扩展标记、12 个系统类设备。 - Rust:
RegistryResult+= 实体注册表(device_id / name / entity_category);HaDevice+= 用户命名 / 厂商 / 型号。 - 表现层:
buildRegistryIndex/buildDevices/splitDevice+ 主实体与关键读数的选取规则(真机验证三轮)。 - UI:一级设备卡(名字 + 主控 + ≤2 读数)→ 二级设备详情(主控 + 常用功能组,可折叠)→ 三级「高级设置」折叠区。
- 左栏改为设备维度:房间 / 类型 / 收藏 / 搜索 / 只显示可控 / 隐藏离线 / 显示系统设备(默认隐藏 12 个系统设备)。
- 静态自检:
cargo check0 错误 0 警告 ·vue-tsc --noEmit0 错误 ·eslint src0 问题。 - 真机验证(见 §9.9 末节):一级网格一眼可用;插座卡片 = 名字 + 开关 + 功率;常用组折叠顺手;三级能查到高级项。
P5(按需)
- 历史曲线 / camera 缩略图 / 通知动作 / quickpanel provider / 实体隐藏与重命名的 HA 侧写回。