# 智能家居模块规划(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](./AI_DEV_GUIDE.md)(模块注册 / IPC / 命令 / 进程范式)、[UI_DESIGN_SYSTEM.md](./UI_DESIGN_SYSTEM.md)(页面框架 / 组件规范 / 四态)、[EDITOR_MODULE_PLAN.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-`),`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}//settings.json` 范式(ai / translate / terminal / editor / monitor 共 5 处先例) | 照抄 | | 文件锁 / 状态管理 | `dsh/mod.rs` 的 `AppState + Mutex` 范式 | 照抄 | | 前端壳 | 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/`(那是伪造状态,且需 admin),所有变更必须经 service 调用。 - **不做多 HA 实例聚合。** 数据结构上支持多连接(`connections[]` + `activeId`,照抄飞牛连接管理),但 UI 一次只显示一个激活实例,不做跨实例合并视图。 --- ## 3. Home Assistant 接口映射 这是本模块的技术核心。所有参数细节以 [HA 开发者文档](https://developers.home-assistant.io/docs/api/rest/) 与实例实测为准,**实现时逐条核对**。 ### 3.1 认证 - 令牌类型:**长期访问令牌(Long-Lived Access Token,LLAT)**,用户在 HA「个人资料 → 安全 → 长期访问令牌 → 创建令牌」生成,一串 `eyJ...` 的 JWT,**有效期 10 年**,只能删除不能续期。 - REST:请求头 `Authorization: Bearer `。 - 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/` | 控制后的校正 | | **服务调用** | `POST /api/services//` | body:`{"entity_id": "...", ...参数}`;`entity_id` 可为字符串或数组 | | 需要返回值的服务 | `POST /api/services//?return_response=true` | 少数服务(天气预报、日历)才有 | | 服务清单 | `GET /api/services` | 含字段定义;用作"高级参数"兜底,不用它生成主控件 | | 历史 | `GET /api/history/period/?filter_entity_id=&minimal_response` | 可选 P5(图表) | | 日志 | `GET /api/error_log` | 可选:设置页"诊断"入口 | | 模板渲染 | `POST /api/template` `{"template": "..."}` | 可选,不建议 P1 引入(会牵出模板注入面) | ### 3.3 WebSocket 协议(P4) ``` ws://:8123/api/websocket (HTTPS 反代则 wss:// ) S→C {"type":"auth_required","ha_version":"2024.x.x"} C→S {"type":"auth","access_token":""} S→C {"type":"auth_ok","ha_version":"2024.x.x"} // 或 {"type":"auth_invalid","message":"..."} 后关闭 ``` **鉴权通过后所有命令都是"自增 id + type"的请求/响应式**,`id` 由客户端维护: ```jsonc // 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>`),模块 Tab 切走不关连接;只有用户显式关闭实时、或应用退出才断。 - **必须实现断线重连**(指数退避,上限如 30s),并在重连成功后重新拉一次全量状态(断线期间的增量丢了)。 - **心跳双向**:服务端 30s 内未收到响应会断开;客户端也要主动 `ping` 探测半开连接(尤其在路由/NAT 环境下)。 - **鉴权失败不可无限重连**:`auth_invalid` → 置 `authFailed` 状态、通知前端弹"令牌失效,请重新填写",**停止重连**避免刷爆日志。 - **事件必须节流后再送前端**(§6.5):`subscribe_entities` 在设备状态风暴时可能每秒几十条消息,逐条 IPC 会打爆 WebView。 ### 3.4 实体与状态模型 ```jsonc { "entity_id": "light.hall_ceiling", // . "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/`)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- # 每个连接一条明文令牌 ``` `settings.json` 结构(含 `version` + 自愈,范式照抄 `dsh/types.rs` / `editor/types.rs`): ```jsonc { "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>`),不落盘。原因: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//`,`entity_id` + 参数。 - **乐观更新 + 校正**(本模块最重要的交互决策;**P2 落地版见 §9.3-1 / -2**): 1. 点击 → 立即把本地状态按意图改写(`on` → 卡片立刻点亮)。 2. 下发服务(`POST /api/services//`)。 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=`),便于用户去 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)** 规则模型(**线性三段式,不做嵌套树**——这是"简单自动化"的边界所在): ```jsonc { "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` 足够(读多写少、单机场景),不必引入 `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](./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`(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)** - [x] `reqwest` 补 `gzip` feature(P0)。实测 265,973 B → 45,890 B(**5.8×**),耗时 3.96s → 2.30s。 - [x] 实测 HA:`/api/` 200;`/api/config` 显示版本 **2026.10.1**、实例名「我的家」、单位制**美制**;`/api/states` **577 实体 / 266 KB**。 - [x] 反代链路基线:`ping/pong` 往返 **617 ms**;**未挂 Cloudflare Access**(直接返回 JSON,没有登录页)。 - [x] 一次性 WS 脚本实测:握手正常、`subscribe_entities` 支持(首帧 577 实体 / 152 KB / 2.23s;30 秒内 2 个增量事件)、区域 / 实体 / 设备注册表全部可用。 - [x] `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)** - [x] 前端:`src/modules/smarthome/index.ts` + `SmartHomeModule.vue`(三 Tab 壳)+ `DevicePane.vue` / `AutomationPane.vue` / `SettingsPane.vue` / `ConnectionDialog.vue` / `HaStatusBanner.vue`;注册 `src/modules/index.ts` 与 `icons.ts`。 - [x] Rust:`smarthome/{mod,types,client,commands}.rs`;`lib.rs` 注册 `mod` + `setup.rs` 里 `.manage(HaManager)` + **`generate_handler!` 与 `export_bindings()` 的 `collect_commands!` 两处都已登记**。 - [x] `Cargo.toml`:`reqwest` 补 `gzip` feature。 - [x] 连接模型双地址(`localUrl` / `remoteUrl`)+ `endpointMode`;`secrets` 键名 `smarthome-token-`;`settings.json` 读写(version + 自愈,照抄 `dsh/mod.rs`)。 - [x] 端点选择:`local(900ms) → remote(5000ms)`(**修正后的顺序**,见 §3.7-a),会话粘滞(局域网 60s / 反代 300s),请求失败立即重探。 - [x] 连接列表 UI(照抄 `ConnectionsSettings.vue` 的交互)+ **逐地址测试连接**(两跳各自给结果)+ 令牌掩码回显 + 链路诊断区。 - [x] 静态自检:`cargo check` 0 错误 0 警告 · `vue-tsc --noEmit` 0 错误 · `eslint src` 0 问题。 - [ ] 真机验证(需真实 HA + 令牌,见 §9.1 末节):填错令牌报「令牌失效」;凭据管理器里能看到条目;`settings.json` 中 grep 不到令牌明文;两个地址各自测得出结果;故意把局域网地址写错后能自动落到反代。 **P1(已完成,2026-10-16 —— 实施记录见 §9.2)** - [x] `smarthome_list_entities`(内存缓存 60s + 精简 `EntitySummary`;`HaApiError` 分类错误)。 - [x] `src/stores/smartHomeStore.ts` 增实体与筛选状态 + `format.ts`(分组 / domain 图标 / 状态文案 / 可控判定 / 相对时间 / 中文排序)。 - [x] `DevicePane.vue`(split:左筛选栏 + 卡片网格)+ `DeviceCard.vue`(只读态 + 收藏置顶)。 - [x] 四态 + 错误分类(§3.6 / §7.5):`auth` 清空数据、其它错误保留数据并提示。 - [x] `SettingsPane.vue` 增「数据刷新」组(自动刷新间隔;远端链路下停用)。 - [x] 静态自检:`cargo check` 0 错误 0 警告 · `vue-tsc --noEmit` 0 错误 · `eslint src` 0 问题。 - [ ] 真机验证(见 §9.2 末节):实体数量与首屏耗时(尤其远端)、gzip 是否生效、`unavailable` 呈现、分组与卡片文案是否与实际设备对得上。 **P2(已完成,2026-10-19 —— 实施记录见 §9.3)** - [x] `smarthome_call_service` + `smarthome_get_entity`(错误类型继续用 P1 的 `HaApiError`)+ 乐观更新 + 服务响应快速通道 + 分级单实体校正 + 危险操作确认。 - [x] `controls/`:`LightControl`(开关 + 亮度 + 色温)、`SwitchControl`(switch / input_boolean / automation / lock)、`CoverControl`(升降停 + 位置)、`ClimateControl`(模式 + 温度步进)、`FanControl`、`MediaControl`、`ActionControl`(场景 / 脚本)+ `ControlSlider`。 - [x] 乐观更新 + 分级校正(局域网 600ms / 远端 2000ms)+ 失败回滚提示;滑杆松手(`valueCommit`)才下发。 - [x] 危险操作 `AlertDialog`(开锁 / 窗帘全开)+ 设置页「安全」组可关;能力判定降级(判不出来就不出控件)。 - [x] 控制后同步后端实体缓存(`merge_entities`),避免"切页再切回又看到控制前的旧值"。 - [x] 静态自检:`cargo check` 0 错误 0 警告 · `vue-tsc --noEmit` 0 错误 · `eslint src` 0 问题。 - [ ] 真机验证(见 §9.3 末节):四类设备点一遍看"乐观更新 → 校正"是否与设备实际行为一致;小米灯的 `supported_color_modes` 是否匹配;给不支持色温的灯传非法参数看 `400` 文案;远端的控制体感延迟与"状态未变化"提示频率。 **P3(已完成,2026-10-19 —— 实施记录见 §9.4)** - [x] 从 `list_entities` 结果里切出 `automation.*` / `script.*`;`AutomationPane.vue` 完成实现(列表 + 状态点 + 上次触发时间 + 类型徽章)。 - [x] 启停(`automation.turn_on|turn_off`)+ 立即运行(`automation.trigger` / `script.turn_on`)+ 「在 HA 中管理」外链。 - [x] Rust 只加 `lastTriggered` 字段(不需要新命令,验证了 P2 的边界划分)。 - [x] 静态自检:`cargo check` 0 错误 0 警告 · `vue-tsc --noEmit` 0 错误 · `eslint src` 0 问题。 - [ ] 真机验证(见 §9.4 末节):触发是否走条件;启停是否真的生效;`last_triggered` 的可用性;脚本 `state` 语义。 **P3.5 通用域控件(已完成,2026-10-19 —— 实施记录见 §9.6)** - [x] `NumberControl.vue`(上下限/步长取实体自带的;参数不全不渲染)+ `SelectControl.vue`(选项取实体的 `options`)。 - [x] `ActionControl.vue` 扩到 `button`(`press` + 按钮的乐观 state/lastChanged)。 - [x] `format.ts` 增分组「数值 / 下拉 / 按钮」、可控域与图标;`isControllable` 与"能否渲染控件"统一口径。 - [x] Rust:`EntitySummary` += `min` / `max` / `step` / `options`;`ServiceParams` += `value` / `option`。 - [x] 静态自检:`cargo check` 0 错误 0 警告 · `vue-tsc --noEmit` 0 错误 · `eslint src` 0 问题。 - [ ] 真机验证(见 §9.6 末节):大步长滑杆的体验、`select` 当前值不在选项里时的显示、按钮按下后相对时间是否立刻更新。 **P4(已完成,2026-10-19 —— 实施记录见 §9.7)** - [x] `Cargo.toml`:`tokio-tungstenite` 补 `connect` + `rustls-tls-webpki-roots`(D5:要支持 `wss://`);`futures-util` 显式开 `sink`。 - [x] `ws.rs`:握手 / 心跳 / 重连退避 / `auth_invalid` 停止重连 / 200ms 聚合;`smarthome_ws_start|stop|status`;**端点选择复用 P0 的逻辑**(`ws://` / `wss://` 均按所选端点)。 - [x] `registry.rs`:注册表拉取 + 房间分组接入左栏(含"未分配房间"分组;**三级回退**见 §9.5-1)。 - [x] `automation.rs`:规则模型 / 加载保存(`spawn_blocking`)/ 求值 / 执行 / 冷却 / 循环保护 / 运行记录。 - [x] `RuleEditorDialog.vue` + `EntityPicker.vue`;设置页实时推送开关(`smarthome_set_realtime_enabled`)与「实时连接」诊断行。 - [x] 设备数据从"拉取"切到"推送 + 校正"(卡片更新不再依赖手动刷新;实时连接建立后跳过单实体校正)。 - [x] 静态自检:`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)** - [x] 真机普查(只读):604/606 实体有 device_id、每设备实体中位 9/max 110、`friendly_name` 三段结构、`* ` 扩展标记、12 个系统类设备。 - [x] Rust:`RegistryResult` += 实体注册表(device_id / name / entity_category);`HaDevice` += 用户命名 / 厂商 / 型号。 - [x] 表现层:`buildRegistryIndex` / `buildDevices` / `splitDevice` + 主实体与关键读数的选取规则(真机验证三轮)。 - [x] UI:一级设备卡(名字 + 主控 + ≤2 读数)→ 二级设备详情(主控 + 常用功能组,可折叠)→ 三级「高级设置」折叠区。 - [x] 左栏改为设备维度:房间 / 类型 / 收藏 / 搜索 / 只显示可控 / 隐藏离线 / **显示系统设备**(默认隐藏 12 个系统设备)。 - [x] 静态自检:`cargo check` 0 错误 0 警告 · `vue-tsc --noEmit` 0 错误 · `eslint src` 0 问题。 - [ ] 真机验证(见 §9.9 末节):一级网格一眼可用;插座卡片 = 名字 + 开关 + 功率;常用组折叠顺手;三级能查到高级项。 **P5(按需)** - [ ] 历史曲线 / camera 缩略图 / 通知动作 / quickpanel provider / 实体隐藏与重命名的 HA 侧写回。