Files
Thing/doc/SMART_HOME_MODULE_PLAN.md
2026-10-23 17:25:17 +08:00

109 KiB
Raw Permalink Blame History

智能家居模块规划(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. 结论先行

九条判断。前三条直接回答"可行性 / 实时性 / 自动化归属"三个不确定项。

  1. 完全可行,且不需要新增任何 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 的映射"。

  2. 实时性问题:设备数据不需要实时,自动化需要。 两者要用不同机制:

    • 设备数据 = 拉取式。打开模块拉一次全量状态,配手动刷新按钮 + 可选自动刷新(默认关,选 5/10/30s)。HA 的一次 GET /api/states 是单请求,几百个实体约几百 KB,本地局域网代价可忽略。
    • 自动化 = 事件驱动,必须有实时推送。轮询做自动化有两个致命缺陷:① 延迟下限 = 轮询间隔;② 会漏掉瞬态变化(人体传感器 on → off 若发生在两次轮询之间,"有人经过"这个事件就丢了)。所以自动化引入 WebSocket(subscribe_entities / subscribe_events)。
    • 因此:P1–P3 只走 REST,P4 才引入 WS。WS 接入顺带把设备数据升级为实时推送(同一份代码同时服务两个功能),但它是 P4 的工作,不是 P1 的前置条件。
  3. "简单自动化"有两条路,建议分阶段各取一条。 (a) 管理 HA 自身已有的自动化(列出 / 启停 / 手动触发)——纯 REST,零风险,立刻可用;(b) 本地轻量规则引擎("门窗开 → 开灯"这类)——需 WS 事件驱动,可控性强。关键限制必须提前告知用户:本地规则只在 Thing 运行时生效(桌面应用关掉、电脑关机就不跑了)。若用户要的是"24 小时常驻可靠",那正确做法是把规则写回 HA 服务端,本模块只做编辑入口。→ 见 §5.4 与 §9-D1/D2。

  4. "按房间分组"在纯 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 必须按 实体 → 设备 → 区域 三级回退。

  5. 认证 = 长期访问令牌,落系统凭据管理器。 令牌由用户在 HA 的「个人资料 → 安全 → 长期访问令牌」自行创建后粘贴进来;本模块不代用户登录、不存小米账号。令牌只经 secrets::secret_write 进入 Windows 凭据管理器(键名约定 smarthome-token-<connId>),settings.json 只存 baseUrl / 名称 / insecure 等非敏感项。前端永远拿不到明文,只拿 secrets::mask() 处理过的掩码(与翻译模块 API Key、WebDAV 密码同一姿态)。

  6. UI 落在主窗口,不新开独立窗口。 智能家居是"常看常点"的模块,与 terminal / diff / editor 那种"需要独占屏幕"的工作台不同。用现有 useModuleTabs 注册三个 Tab(设备 / 自动化 / 设置),内容区用 split 布局(左 280px 筛选栏 + 右侧实体卡片网格)。实体卡片按 domain 映射控件,不追求通用化。

  7. 安全姿态:令牌在单点暴露,危险操作二次确认。 明文令牌只存在于 Rust 内存与系统凭据库;传输层若走 http://(局域网常见)则在设置页明确提示"令牌经明文网络传输,建议仅局域网使用或启用 HTTPS";lock.unlock / cover 全开 / valve / alarm 这类操作沿用 P4 原则(视觉降级 + 二次确认),但不做二次口令。

  8. 不做的事(明确划界):不做 HA Lovelace 前端的替代或内嵌;不做设备配网 / 集成添加(那是 HA 自己的事);不做小米账号登录;不做 HA 自动化 YAML 编辑器 / 模板语法编辑器;不做本机历史曲线存储(HA 自己有 history,需要时按需拉取,不落盘)。

  9. 一条连接两个地址:局域网优先,反代兜底(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 待核实项(开工前必须逐条验证,都是"可能会卡住半天"的点)

  1. tokio-tungstenite 的 feature 组合(D5 已定:需要 wss://)。 当前 Cargo.toml 写作 tokio-tungstenite = "0.24",未显式开 feature。 P4 开工前已用 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 传递打开),已显式声明。
  2. reqwest 的 gzip feature(P0 就要加)。 默认未开 → 不发 Accept-Encoding → 反代链路上 Cloudflare 回未压缩 JSON,远端首屏流量翻 5–10 倍。详见 §3.7-b 的"必须做的事"。
  3. WS 帧大小上限。 subscribe_entities 首次快照(全实体)可能是一条很大的消息。tungstenite 有 max_message_size / max_frame_size 默认值(通常 64MiB / 16MiB),几百实体不会触发,但 1000+ 实体建议显式配置并在日志里记录实际帧大小。
  4. HA 版本门槛。 subscribe_entities 需要 HA ≥ 2023.11;config/area_registry/list 等注册表查询很早就有。实现时用 GET /api/config 的 version 做能力探测,不支持就退化为 subscribe_events(state_changed) 或纯 REST。设置页展示 HA 版本。
  5. 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 白名单——不要想当然。
  6. 反代是否叠加了 Cloudflare Access。 若 CT 隧道前面挂了 CF Access(Zero Trust),请求还需 CF-Access-Client-Id / CF-Access-Client-Secret 两个 Service Token 头,否则会被 CF 的登录页拦下(表现为测试连接拿到 HTML 而非 JSON)。本次按"只用 HA 自己的令牌"设计,不实现该头;若用户环境实际启用了 Access,测试连接会立刻暴露,届时再补两个字段 + 两条凭据即可(成本很低,故不预留)。
  7. 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"
}

必须处理的三件事:

  1. state 与 attributes 谁是数值因 domain 而异。 sensor 的读数在 state 里(字符串形式的数字);climate 的当前温度在 attributes.current_temperature。卡片渲染必须按 domain 分别取,不能统一。
  2. supported_features / supported_color_modes 决定控件形态。 例如灯若无 brightness 能力就只渲染开关不给滑杆。宁可少给控件,也不要给一个点了没反应的滑杆(这与编辑器模块"避免误报优先于覆盖完整"是同一取舍)。
  3. 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):
    1. 点击 → 立即把本地状态按意图改写(on → 卡片立刻点亮)。
    2. 下发服务(POST /api/services/<domain>/<service>)。
    3. 快速通道:HA 的响应体就是受影响实体的最新状态 —— 若它确实与下发前不同,直接采用并结束(省一次往返;远端链路上约 200–400ms)。
    4. 否则在分级窗口后拉单实体校正:局域网 600ms、远端(反代)2000ms —— 远端 RTT 再加米家云端处理,600ms 必然被误判成"状态未变化"。
    5. 校正结果"看起来没变" → 回滚到原状态 + 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 自身的自动化」。
  • 三条必须实现的护栏:
    1. 冷却时间:cooldownSec(默认 30s)内的重复触发直接丢弃。
    2. 动作失败不中断:某动作 4xx/5xx 时记 lastError 并继续下一动作(否则一条失败会吞掉后续所有动作)。
    3. 循环保护:规则动作导致的实体变化若能再次触发同一规则(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 处机械改动)

  1. src/modules/smarthome/index.ts —— ModuleConfig,searchItems 带上「设备 / 自动化 / 设置」三页 + 常见设备文案(便于全局搜索跳转,范式见 monitor/index.ts)。
  2. src/modules/index.ts —— import + 入 allModules。
  3. src/modules/icons.ts —— smarthome: House(lucide)。
  4. 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)+ 右侧数值标签(label 11px)。
  • 相对时间由 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 件事(均已回写进上文)

  1. 探测顺序改为"局域网永远先试"(§3.7-a):原方案的 lastOkUrl 优先会把人困在反代上。
  2. 端点缓存 TTL 分档:局域网 60s / 反代 300s。
  3. 「测试连接」不拉 /api/states:EndpointProbe 里去掉实体数。那是几百 KB 的响应,在反代上会把一次 1 秒的测试拖到 3 秒以上,而实体列表 P1 本来就要拉一次。
  4. smarthome_save_connection 回传 id:新建后前端要立刻写令牌,按「名称 + 地址」反查不可靠(用户可能建两条同名连接)。
  5. LinkInfo / EndpointProbe 都带 errorKind:前端据此区分"重填令牌"(auth,重试无意义)与"重试 / 检查地址"(network / config)。分类判定留在 Rust 侧,不让前端靠匹配错误文案猜。
  6. 可达性检查要校验响应体,不能只看状态码:反代前面若挂了访问网关(Cloudflare Access),未携带 Service Token 时会被重定向到一个 200 的 HTML 登录页——只看状态码会把它判成"链路正常",直到后续真实请求才莫名失败。因此 GET /api/ 必须能解析出 HA 的 JSON 响应。
  7. 强制模式与地址在保存时就要自洽:「仅局域网」却没填局域网地址 → 保存即报错,而不是等"检测链路"时才报(错误信息要贴着用户输入)。

踩到的两个坑

  • 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 尚需真机验证(代码侧无法自证)

  1. 真实 HA 地址 + 令牌下,两个地址各自的连通性与耗时(在家局域网应 <20ms)。
  2. 令牌确实进了 Windows 凭据管理器;{app_data}/smarthome/settings.json 里 grep 不到明文。
  3. 「只填反代」「只填局域网」两种配置下端点策略自动收敛是否正确。
  4. 反代未被 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 件事(均已回写进上文)

  1. Rust 只搬运数据,表现层语义全在前端(format.ts):分组 / 图标 / 状态文案 / 是否可控都由前端决定。HA 新增一个 domain 时只改这一个文件 —— Rust 侧不做任何"这个实体能不能控制"的判断。
  2. 本模块是第一个不用 String 作错误类型的命令模块:smarthome_list_entities 返回 Result<_, HaApiError { kind, message }>,前端按 kind 分支(auth → 重填令牌;其它 → 重试),不再靠匹配错误文案猜。已实测 cargo check 通过,说明 tauri-specta 能吃下自定义错误类型。
  3. 失败处理分叉:auth → 清空实体列表(旧数据可能是上一个有效令牌留下的,留着会误导);其它(网络抖动 / 隧道瞬断)→ 保留已有数据 + 一条提示条。远端链路上瞬时失败很常见,把整屏清空比"略旧的数据 + 明确的更新时间"更糟。
  4. 自动刷新在远端链路下直接不启动(不只是把开关置灰):见 §5.2。
  5. 筛选条件是会话状态、放 store:TabsContent 会卸载非活动面板,只存在组件里的 ref 会被重置(表现为"切去设置再切回来,搜索词没了")。

P1 刻意未做

  • 「隐藏 domain / 隐藏实体」的 UI:ui.hiddenDomains / hiddenEntityIds 字段保留但暂无入口 —— 它需要每条实体的菜单,属于 P5 的「实体隐藏」范围,此刻加等于给一个没有出口的设置。
  • 房间分组:要等 P4 的 WS 注册表查询(§0.4)。

P1 尚需真机验证

  1. 实体数量与首屏耗时(尤其远端链路),以及 /api/states 的 gzip 是否真的生效。
  2. 小米设备经米家云时 unavailable 的出现频率与呈现是否合理。
  3. 分组归类与卡片文案是否与实际设备对得上(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 件事(均已回写进上文)

  1. 服务响应当"快速通道"用:HA 的 POST /api/services/... 响应体就是受影响实体的最新状态。因此校正顺序改为:乐观更新 → 下发 → 若响应带回的新状态确实与下发前不同就直接采用(远端链路上省一次往返,约 200–400ms)→ 否则才走分级窗口的单实体重拉。计划里只有后者(§5.3),这是纯增量的改进。
  2. optimistic 为空 = 不做校正(执行场景 / 脚本、停止窗帘):这类动作本就没有可预期的状态变化,硬做"状态没变就回滚"会冤枉一次成功执行。判据写在 control() 里而不是各控件里 —— 控件只声明意图,不关心校正策略。
  3. ServiceParams 用固定字段而不是 serde_json::Value:specta 无法为 Value 生成类型(lib.rs 里本就有这份豁免清单);顺带把"能传什么参数"限死了,前端不可能把任意键塞进 service_data。
  4. 控制后必须同步后端缓存(merge_entities):否则会出现"开灯 → 切到设置页 → 切回设备页(60s 内命中缓存)→ 又显示灯是关的"这种误导。响应没带回状态时(部分云端集成)改为清缓存,宁可多拉一次也不显示控制前的旧值。
  5. 能力判定集中在前端 format.ts:灯的亮度/色温看 supported_color_modes(而不是 supported_features 的旧位约定,老集成没这个属性时才回退);窗帘看 supported_features 的 OPEN/CLOSE/STOP/SET_POSITION 位。"宁可少给控件"由此落到实处:能力判不出来就不渲染控件。
  6. 滑杆的 commit 与 update 分开:拖动走 update:modelValue(只改本地值),松手走 valueCommit 才下发 —— 远端链路上不这样会刷出几十条命令。

踩到的一个坑

  • format.ts 里那份本地 EntitySummary 接口与 store 的那份字段漂移了:P2 加能力位时只改了 store,format.ts 仍用旧接口 → lightHasBrightness 等函数全部报"属性不存在"。已改为从 store import type 再 re-export,唯一来源。

P2 刻意未做

  • valve / alarm_control_panel / vacuum:计划把它们列进了"危险操作",但 P2 的控件覆盖范围是 §3.5 的表;这三个 domain 既没有控件也没有乐观语义,现在只做确认逻辑等于给一个不存在的按钮加锁。
  • 参数型控件的并发合并:快速连点 + 会连发多条 set_temperature。每按一次都是一次明确操作,暂不做防抖(P4 有 WS 之后可再评估)。

P2 尚需真机验证

  1. 四类设备(灯 / 开关 / 窗帘 / 空调)真机点一遍,重点看乐观更新 → 校正这一段是否与设备实际行为一致。
  2. 小米设备的 supported_color_modes 是否符合预期(会不会出现"给了亮度滑杆但调不动")。
  3. 给不支持色温的灯传 color_temp_kelvin,确认 400 的错误文案能读(验证 extract_message)。
  4. 远端链路上单次控制的体感延迟与"命令已下发但状态未变化"的触发频率。

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 件事

  1. P3 几乎不需要新的 Rust 代码:automation.turn_on|turn_off 与 automation.trigger / script.turn_on 全部走 P2 的 smarthome_call_service;列表数据来自 P1 的实体列表。这验证了前面把"服务调用"做成通用命令、把"能力与语义"留给前端的边界划分是对的。
  2. 「运行」传空乐观状态:触发不会让这条实体自身产生可预期的状态变化 —— 空乐观状态会跳过"状态没变就回滚"的校正,否则一次成功的触发会被提示成"命令已下发,但设备状态未变化"(与 ActionControl 同一条规则,§5.3 的例外分支)。
  3. 脚本只有「运行」,没有启停开关:script.turn_off 的语义是"停止正在运行的脚本"而不是"禁用脚本",摆一个开关会误导(HA 侧禁用脚本要在设置里改)。自动化才有 turn_on|turn_off 的启用语义。
  4. 首次拉取触发器进 store:设备页与自动化页都要"等设置就绪再拉实体",两处各写一遍 watch 是重复;放进 store 后两页都不必关心,且天然带并发守卫。

P3 刻意未做

  • 不做自动化编辑(§5.4-A):HA 自己的自动化编辑器更强,在本地重做一遍是重复劳动。列表里给一个「在 HA 中管理」外链(/config/automation),要改就去 HA 改。
  • 不做「跳过条件强制执行」(skip_condition):默认 false 就是"照常走条件"的语义,多一个开关只会让人误点。

P3 尚需真机验证

  1. 「运行」是否照常走条件判断(automation.trigger 的 skip_condition 默认 false)。
  2. 启用 / 停用开关是否真的让自动化不再触发(去 HA 侧看状态是否同步)。
  3. last_triggered 是否在有 automation.* 实体上都有值(部分集成可能不带该属性,届时显示"尚未触发过"是正常的)。
  4. 脚本实体的 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 个(投影仪音量、摄像机变焦、输入信源、开机/播放/暂停按钮全在这里)
  • 灯的能力分布:onoff 8(不给滑杆,判断逻辑正确)、color_temp 3、rgb 1;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 件事

  1. 上下限与步长一律用实体自带的:真机上这批差异极大 —— 0–100 的扬声器音量、10–90 的摄像机变焦倍数、步长 180 的图像翻转角。写死任何一个都会让另一批实体没法用。参数不全(缺 min/max、max ≤ min、步长 ≤ 0)时不渲染控件。
  2. isControllable 与"能不能渲染出控件"共用同一个口径:数字实体缺参数、下拉实体没选项时算作只读 —— 否则会出现"在『只显示可控设备』过滤里、卡片却没有控件"的别扭状态。
  3. 按钮归到 ActionControl:它与场景 / 脚本同属"无乐观状态的动作"类(按钮的 state 是"上次按下时间"而不是状态),共用"不做校正"那条规则;只是服务从 turn_on 换成 press、文案从"执行"换成"按下"。
  4. 按钮反过来要"有"乐观状态:既然它的 state 就是按下时间,按下时就乐观地把 state 与 lastChanged 一起改成当前时刻 —— 卡片底部的相对时间立刻跳到"刚刚",否则按一下在界面上毫无痕迹(只有 toast)。带上乐观状态后,它也自然走回"服务端确认就采用、否则分级校正"的常规流程。

未做:text(text.set_value)—— 里面有"移动侦测时间段"这类需要格式约束的语义,输错只能靠 HA 返回 400 兜底,收益低于另外三类。

待真机验证

  1. number 滑杆在步长很大时的体验(步长 180 只有两档,滑杆是否显得别扭)。
  2. select 的当前值不在 options 里时(HA 的 unknown),下拉是否显示异常。
  3. 按钮按下后卡片底部的相对时间是否立刻更新,且校正后与服务端时间一致。

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 件事(含与计划的差异)

  1. WS 的粒度是"应用",且由 Rust 侧持有(plan §3.3 第一条)。台账在 HaManager.ws,Tab 切走不关连接;smarthome-connection-status 只推"状态变化",不推心跳。
  2. 事件必须"先合并回原始对象再推导摘要",不能整份替换。 真机上 c(changed)里的 attributes 可能是差量({"+": {...}, "-": [...]}),照文档只做浅合并会在下一次事件里把未变化的字段抹掉。因此 ws.rs 维护一份 HashMap<entityId, RawEntity>(state + 完整 attrs + last_changed),差量合并后再走与 REST 同一条 client::to_summary,保证两条链路算出的 EntitySummary 完全一致。
  3. subscribe_entities 的首帧就是全量快照,所以"重连后重新拉一次全量"这件事不需要额外请求:reset_state() 清空本地状态,重连时会自然收到全量 a 段。断线期间的增量由此补齐。
  4. 房间映射严格按三级回退(§9.5-1 的真机修正):entity.area_id → device.area_id → 前端「未分配房间」。真机 36 个设备里 9 个确实没有区域,所以这一档是必需分组而不是兜底。
  5. 规则靠 WS 驱动 ⇒ 规则总开关开着就必须有连接。 引入 HaManager::sync_ws(幂等):realtime.enabled || rules.enabled 为真时要有一条连接,为假时断开。它在启动、以及每次改连接 / 令牌 / 端点策略 / 实时开关 / 规则之后被调用。代价是"关掉实时推送仍可能保持连接"(当规则开着),这是有意的:规则没连接永远不会触发。
  6. 控制后的单实体校正:实时推送开着时跳过(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 就建两条规则);动作不支持嵌套与分支。

待真机验证

  1. 开关灯 → UI 在 1s 内自行更新(无需手动刷新)。
  2. 断网 / 挂断隧道 → 自动重连成功并恢复全量(auth_invalid 除外:那种情况停止重连并弹横幅)。
  3. 房间分段与真实房间对得上,尤其「未分配房间」这一档的数量。
  4. 规则能触发并留记录;A↔B 互触规则不无限循环(冷却 + 10s/5 次的突发护栏)。
  5. 反代链路上 wss:// 能否建连(本次只补了 TLS feature,尚未在真机连过 WS over TLS)。
  6. 半开连接的判定是否合适(25s 心跳 / 75s 无入站即断开重连)——在反代 ping/pong 617ms 的基线上应留有余量。

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 补 gzip feature(P0)。实测 265,973 B → 45,890 B(5.8×),耗时 3.96s → 2.30s。
  • 实测 HA:/api/ 200;/api/config 显示版本 2026.10.1、实例名「我的家」、单位制美制;/api/states 577 实体 / 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 补 gzip feature。
  • 连接模型双地址(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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(需真实 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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(见 §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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(见 §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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(见 §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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(见 §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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(见 §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 check 0 错误 0 警告 · vue-tsc --noEmit 0 错误 · eslint src 0 问题。
  • 真机验证(见 §9.9 末节):一级网格一眼可用;插座卡片 = 名字 + 开关 + 功率;常用组折叠顺手;三级能查到高级项。

P5(按需)

  • 历史曲线 / camera 缩略图 / 通知动作 / quickpanel provider / 实体隐藏与重命名的 HA 侧写回。