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

1202 lines
109 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 智能家居模块规划(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-<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 开发者文档](https://developers.home-assistant.io/docs/api/rest/) 与实例实测为准,**实现时逐条核对**。
### 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` 由客户端维护:
```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<Option<Handle>>`),模块 Tab 切走不关连接;只有用户显式关闭实时、或应用退出才断。
- **必须实现断线重连**(指数退避,上限如 30s),并在重连成功后重新拉一次全量状态(断线期间的增量丢了)。
- **心跳双向**:服务端 30s 内未收到响应会断开;客户端也要主动 `ping` 探测半开连接(尤其在路由/NAT 环境下)。
- **鉴权失败不可无限重连**:`auth_invalid` → 置 `authFailed` 状态、通知前端弹"令牌失效,请重新填写",**停止重连**避免刷爆日志。
- **事件必须节流后再送前端**(§6.5):`subscribe_entities` 在设备状态风暴时可能每秒几十条消息,逐条 IPC 会打爆 WebView。
### 3.4 实体与状态模型
```jsonc
{
"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`):
```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<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)**
规则模型(**线性三段式,不做嵌套树**——这是"简单自动化"的边界所在):
```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<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](./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)**
- [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-<connId>`;`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 侧写回。