diff --git a/doc/EDITOR_MODULE_PLAN.md b/doc/EDITOR_MODULE_PLAN.md index d013fce..14d521c 100644 --- a/doc/EDITOR_MODULE_PLAN.md +++ b/doc/EDITOR_MODULE_PLAN.md @@ -214,8 +214,8 @@ Tab 收敛为 **概览 / 库 / 编辑器 / 集成**(把 v1 的「同步」并 ┌─ 标题栏(自绘:文档名 + 未保存点 + 窗口按钮)────────────────────────┐ ├─ 工具栏:保存 另存 打开 快速打开 | 格式化(.md 时) | 编码 换行 主题 ─┤ ├────────────┬──────────────────────────────────────────┬─────────────┤ -│ 侧栏 │ 标签页条:doc1 × | doc2 × | … │ 抽屉(可选) │ -│ [库|目录| │ │ 大纲 / 双链 │ +│ 侧栏 │ 标签栏:doc1 × | doc2 × | … │ 抽屉(可选) │ +│ [库|目录| ├──────────────────────────────────────────┤ 大纲 / 双链 │ │ 检索|最近] │ 编辑器(CM6) │ │ │ │ │ │ │ 树 / 结果 │ │ │ @@ -224,6 +224,20 @@ Tab 收敛为 **概览 / 库 / 编辑器 / 集成**(把 v1 的「同步」并 └─────────────────────────────────────────────────────────────────────┘ ``` +**并排分屏**(标签右键 → 并排分屏)把编辑页平分为左右两列,各占一半宽: + +``` +├─ 工具栏(整行,不参与分屏)──────────────────────────────────────────┤ +│ 标签栏:doc1 × | doc2 × │ 副文档名 × │ +├──────────────────────────────┼──────────────────────────────────────┤ +│ 编辑器(CM6)· 主文档 │ 编辑器(CM6)· 副文档 │ +└──────────────────────────────┴──────────────────────────────────────┘ +``` + +- 「标签栏 + 编辑栏」整体是**左半列**,副文档是**右半列**(自带 8px 标题行与关闭按钮), + 两列等宽、各自独立滚动 —— 副文档是并排的一列,**不是嵌在编辑栏内部的一块**。 + 从前的做法把副面板塞在编辑栏(标签栏下方)内部,看起来像"同一栏里又开了个窗口"。 +- 不分屏时标签栏回到顶部、横跨整列宽度(即左半列占满),行为与基础形态一致。 - 侧栏可整体折叠(腾出宽度给长行代码)。 - 抽屉默认关闭,`Ctrl+Shift+O` 切大纲、`Ctrl+Shift+B` 切双链。**这两个键位在实现时由 `keymap.ts` 统一声明并做冲突检测**:若与 CM6 默认键位冲突,以 CM6 默认键位优先,本功能改用 `Alt+O` / `Alt+B`(冲突检测方式沿用 v1 的 `shortcut.rs` 思路,编辑器内用 CM6 的 keymap 优先级)。 diff --git a/doc/SMART_HOME_MODULE_PLAN.md b/doc/SMART_HOME_MODULE_PLAN.md new file mode 100644 index 0000000..a134125 --- /dev/null +++ b/doc/SMART_HOME_MODULE_PLAN.md @@ -0,0 +1,1201 @@ +# 智能家居模块规划(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 侧写回。 diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock index 5b5886e..7d467b3 100644 --- a/src-tauri/Cargo.lock +++ b/src-tauri/Cargo.lock @@ -7895,8 +7895,12 @@ checksum = "edc5f74e248dc973e0dbb7b74c7e0d6fcc301c694ff50049504004ef4d0cdcd9" dependencies = [ "futures-util", "log", + "rustls", + "rustls-pki-types", "tokio", + "tokio-rustls", "tungstenite", + "webpki-roots 0.26.11", ] [[package]] @@ -8032,12 +8036,17 @@ version = "0.6.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840" dependencies = [ + "async-compression", "bitflags 2.13.2", "bytes", + "futures-core", "futures-util", "http", "http-body", + "http-body-util", "pin-project-lite", + "tokio", + "tokio-util", "tower", "tower-layer", "tower-service", @@ -8139,6 +8148,8 @@ dependencies = [ "httparse", "log", "rand 0.8.8", + "rustls", + "rustls-pki-types", "sha1 0.10.7", "thiserror 1.0.69", "utf-8", @@ -8512,6 +8523,24 @@ dependencies = [ "rustls-pki-types", ] +[[package]] +name = "webpki-roots" +version = "0.26.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9" +dependencies = [ + "webpki-roots 1.0.9", +] + +[[package]] +name = "webpki-roots" +version = "1.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a" +dependencies = [ + "rustls-pki-types", +] + [[package]] name = "webview2-com" version = "0.39.1" diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index 1e20831..7b3de5e 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -42,8 +42,14 @@ chrono = "0.4" # blocking:音乐播放引擎在**独立 std 线程**上解码(symphonia 的 MediaSource 是同步 # Read+Seek),需要同步 HTTP 客户端去按 Range 拉 NAS 音频流。放在 std 线程上用 # blocking 是安全的(在 tokio 运行时线程里用才会 panic)。 -reqwest = { version = "0.12", features = ["json", "stream", "multipart", "blocking"] } -futures-util = "0.3" +# gzip:智能家居模块走反代(Cloudflare Tunnel)链路时,`/api/states` 是几百 KB JSON。 +# **默认不开压缩就不会发 Accept-Encoding**,CF 会回未压缩响应,远端首屏流量翻 5–10 倍 +# (见 doc/SMART_HOME_MODULE_PLAN.md §3.7-b)。 +reqwest = { version = "0.12", features = ["json", "stream", "multipart", "blocking", "gzip"] } +# `sink`:WebSocket 客户端要把流拆成读/写两半(`SinkExt` / `StreamExt`)。 +# default 特性里**不含** `sink`(已核对 0.3.32 的 Cargo.toml),目前只是因为 +# tokio-tungstenite 自己开了它才传递可用 —— 依赖传递特性不该被当成前提,故显式打开。 +futures-util = { version = "0.3", features = ["sink"] } tokio = { version = "1", features = ["io-util", "time", "rt-multi-thread", "macros", "sync", "fs", "net"] } axum = { version = "0.7", features = ["ws"] } url = "2" @@ -104,7 +110,14 @@ aes = "0.8" cbc = "0.1" rsa = { version = "0.9", features = ["pem"] } rand = "0.8" -tokio-tungstenite = "0.24" +# WebSocket 客户端(智能家居模块 P4 的实时推送 / 规则引擎)。 +# `connect` 已随 default 启用(`cargo tree -e features -i tokio-tungstenite` 复核过: +# 它由本项 + axum 的 `ws` 共同引入),这里显式写出来是为了让"要连"这件事在清单里可见。 +# **TLS 默认未启用** —— 反代是 HTTPS(`wss://`,D5 已定必须支持),故补 +# `rustls-tls-webpki-roots`:纯 Rust、无 C 依赖,与项目姿态一致(`native-tls` 会引入系统依赖), +# 且复用依赖树里已存在的 rustls 0.23(经 russh),不新增编译单元。 +# 注意:自签证书的 `wss://` 仍是缺口 —— `insecure`(危险开关)目前只覆盖 REST。 +tokio-tungstenite = { version = "0.24", features = ["connect", "rustls-tls-webpki-roots"] } image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp"] } walkdir = "2" notify = { version = "6", features = [] } @@ -178,6 +191,9 @@ windows = { version = "0.52", features = [ "Win32_System_Ole", "Win32_System_Variant", "Win32_UI_Shell", + # 快速面板「保存截图后定位并进入重命名」:SHParseDisplayName / SHOpenFolderAndSelectItems + # 与 ITEMIDLIST 都被 Win32_UI_Shell_Common 门控(windows 0.52 源码 cfg) + "Win32_UI_Shell_Common", "Win32_UI_WindowsAndMessaging", # 翻译模块:Windows.Media.Ocr 本地识别(WinRT) # Foundation_Collections:OcrResult.Lines / OcrEngine.AvailableRecognizerLanguages 返回 IVectorView diff --git a/src-tauri/src/constants.rs b/src-tauri/src/constants.rs index 0ae55e8..49449c8 100644 --- a/src-tauri/src/constants.rs +++ b/src-tauri/src/constants.rs @@ -178,4 +178,12 @@ pub mod events { // 进度在**发送端**按时间节流(见 diff::commands::diff_compare_dirs):整棵树可能有 // 上万个条目、上千次读盘,逐条 emit 会把 IPC 打满;前端只负责显示。 pub const DIFF_SCAN_PROGRESS: &str = "diff-scan-progress"; + // ===== 智能家居(Home Assistant)实时推送与本地规则(P4)===== + // 连接状态变化(含 WS):负载 `WsStatus`。前端据此显示顶部横幅与设置页诊断。 + pub const SMARTHOME_CONNECTION_STATUS: &str = "smarthome-connection-status"; + // 状态增量批次(**200ms 聚合后**):负载 `StateBatch`。 + // 逐条 emit 会把 WebView 打爆(一次全屋变化可能几十条),聚合是硬要求。 + pub const SMARTHOME_STATE_BATCH: &str = "smarthome-state-batch"; + // 本地规则触发:负载 `RuleFiredEvent`。 + pub const SMARTHOME_RULE_FIRED: &str = "smarthome-rule-fired"; } diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index 7b9f50d..5723eb7 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -20,6 +20,7 @@ mod screenshot; mod secrets; mod setup; mod shortcut; +mod smarthome; mod snap_fix; mod taskbar_identity; mod terminal; @@ -145,7 +146,8 @@ use quickpanel::{ quickpanel_get_special_locations, quickpanel_hide_popup, quickpanel_init_file_index, quickpanel_list_archives, quickpanel_list_dir, quickpanel_lock_screen, quickpanel_open_file, quickpanel_open_special, quickpanel_preview_rename, quickpanel_register_shortcut, - quickpanel_reveal_in_explorer, quickpanel_run_custom_command, quickpanel_run_system_command, + quickpanel_reveal_in_explorer, quickpanel_reveal_in_explorer_rename, + quickpanel_run_custom_command, quickpanel_run_system_command, quickpanel_save_settings, quickpanel_scan_apps, quickpanel_search_files, quickpanel_show_popup, quickpanel_show_window, quickpanel_unregister_shortcut, quickpanel_focus_main_window, }; @@ -194,6 +196,15 @@ use terminal::commands::{ }; use terminal::TerminalManager; use taskbar_identity::window_set_taskbar_identity; +use smarthome::{ + smarthome_activate_connection, smarthome_call_service, smarthome_check_link, + smarthome_clear_token, smarthome_delete_connection, smarthome_delete_rule, + smarthome_get_entity, smarthome_get_settings, smarthome_list_entities, smarthome_list_registry, + smarthome_list_rules, smarthome_save_connection, smarthome_save_rule, + smarthome_save_ui_settings, smarthome_set_endpoint_mode, smarthome_set_realtime_enabled, + smarthome_set_rules_enabled, smarthome_set_token, smarthome_test_connection, + smarthome_ws_start, smarthome_ws_status, smarthome_ws_stop, +}; use win32_util::window_focus_window; use translate::{ translate_abort, translate_ai_engine_remove, translate_ai_params_save, translate_apply_shortcuts, @@ -255,7 +266,8 @@ fn export_bindings() { quickpanel_show_window, quickpanel_lock_screen, quickpanel_init_file_index, quickpanel_build_file_index, quickpanel_search_files, quickpanel_file_index_stats, quickpanel_scan_apps, quickpanel_get_app_icon, quickpanel_clear_app_icon_cache, - quickpanel_reveal_in_explorer, quickpanel_open_file, quickpanel_get_special_locations, + quickpanel_reveal_in_explorer, quickpanel_reveal_in_explorer_rename, + quickpanel_open_file, quickpanel_get_special_locations, quickpanel_open_special, quickpanel_delete_file, quickpanel_run_custom_command, quickpanel_run_system_command, quickpanel_list_archives, quickpanel_list_dir, quickpanel_batch_extract, quickpanel_preview_rename, quickpanel_apply_rename, @@ -381,6 +393,30 @@ fn export_bindings() { diff_compare_dirs, diff_get_settings, diff_save_settings, + // 智能家居(Home Assistant):连接 / 令牌 / 端点策略 / 测试 —— 与 run() 里那份保持一致,否则 bindings.ts 缺类型 + smarthome_get_settings, + smarthome_save_connection, + smarthome_set_token, + smarthome_clear_token, + smarthome_delete_connection, + smarthome_activate_connection, + smarthome_set_endpoint_mode, + smarthome_test_connection, + smarthome_check_link, + smarthome_list_entities, + smarthome_save_ui_settings, + smarthome_call_service, + smarthome_get_entity, + // 智能家居 P4:实时推送 / 注册表(房间分组)/ 本地规则 + smarthome_set_realtime_enabled, + smarthome_ws_start, + smarthome_ws_stop, + smarthome_ws_status, + smarthome_list_registry, + smarthome_list_rules, + smarthome_save_rule, + smarthome_delete_rule, + smarthome_set_rules_enabled, // 子窗口任务栏身份(独立 AUMID + 组合图标) window_set_taskbar_identity, // 通用「显示 + 取消最小化 + 强制置前」(绕过 Windows 前台锁定) @@ -639,6 +675,7 @@ pub fn run() { quickpanel_get_app_icon, quickpanel_clear_app_icon_cache, quickpanel_reveal_in_explorer, + quickpanel_reveal_in_explorer_rename, quickpanel_open_file, quickpanel_delete_file, quickpanel_delete_files, @@ -916,6 +953,30 @@ pub fn run() { diff_compare_dirs, diff_get_settings, diff_save_settings, + // 智能家居(Home Assistant):连接 / 令牌 / 端点策略 / 测试 + smarthome_get_settings, + smarthome_save_connection, + smarthome_set_token, + smarthome_clear_token, + smarthome_delete_connection, + smarthome_activate_connection, + smarthome_set_endpoint_mode, + smarthome_test_connection, + smarthome_check_link, + smarthome_list_entities, + smarthome_save_ui_settings, + smarthome_call_service, + smarthome_get_entity, + // 智能家居 P4:实时推送 / 注册表(房间分组)/ 本地规则 + smarthome_set_realtime_enabled, + smarthome_ws_start, + smarthome_ws_stop, + smarthome_ws_status, + smarthome_list_registry, + smarthome_list_rules, + smarthome_save_rule, + smarthome_delete_rule, + smarthome_set_rules_enabled, // 子窗口任务栏身份(独立 AUMID + 组合图标) window_set_taskbar_identity, // 通用「显示 + 取消最小化 + 强制置前」 diff --git a/src-tauri/src/quickpanel/commands.rs b/src-tauri/src/quickpanel/commands.rs index 6870fa0..3c32190 100644 --- a/src-tauri/src/quickpanel/commands.rs +++ b/src-tauri/src/quickpanel/commands.rs @@ -337,6 +337,147 @@ pub fn quickpanel_reveal_in_explorer(path: String) -> Result<(), String> { Ok(()) } +/// 等 Explorer 完成「定位 + 选中」再送 F2 的等待时长。 +/// +/// 这是纯 UI 时序:定位调用只是把一个请求交给已在运行的 Explorer 进程, +/// 它要等窗口到前台、切到目标目录、滚到条目并选中,然后才会响应 F2。 +/// 给得太短会把 F2 送到当时还在前台的那个窗口上(而不是 Explorer)。 +const RENAME_KEY_DELAY_MS: u64 = 450; + +/// 在资源管理器中定位文件(选中)并**进入重命名编辑状态**。 +/// +/// # 为什么不用 `explorer.exe /select,` +/// +/// 本仓原先的定位做法是 `ShellExecuteW("explorer.exe", "/select,\"path\"")`。 +/// 那条命令行在 Win10/11 上**经常新开一个窗口**而不是复用用户已经打开的那个 +/// (尤其目标文件夹已通过标签页 / 其他窗口打开时)—— 表现就是"点保存后又弹出 +/// 一个资源管理器打开了这个文件夹"。`SHOpenFolderAndSelectItems` 才是 shell 为此 +/// 提供的 API:复用已有窗口、滚到条目并选中,随后该窗口即为前台窗口。 +/// +/// 重命名仍然只能借 Explorer 自己的快捷键 F2 —— shell 没有"开始重命名"的 API。 +/// +/// `spawn_blocking`:命令里有 sleep;同时 shell 调用要求 **STA** 线程,而 async 命令 +/// 跑在 tokio 工作线程(MTA)上 —— 所以在工作线程里自己 +/// `CoInitializeEx(APARTMENTTHREADED)`(与 `quickpanel::explorer` 同一做法), +/// 既不占 IPC 线程,也不依赖命令所在线程的既有套间模型。 +#[tauri::command] +#[specta::specta] +pub async fn quickpanel_reveal_in_explorer_rename(path: String) -> Result<(), String> { + tauri::async_runtime::spawn_blocking(move || -> Result<(), String> { + select_in_explorer(&path)?; + std::thread::sleep(std::time::Duration::from_millis(RENAME_KEY_DELAY_MS)); + send_rename_key(); + Ok(()) + }) + .await + .map_err(|e| format!("定位 / 重命名任务失败: {}", e))? +} + +/// 用 shell 的「打开文件夹并选中」定位文件(复用已有窗口,不新开一个)。 +#[cfg(windows)] +fn select_in_explorer(path: &str) -> Result<(), String> { + use std::ffi::OsStr; + use std::os::windows::ffi::OsStrExt; + use windows::core::PCWSTR; + use windows::Win32::System::Com::{ + CoInitializeEx, CoTaskMemFree, CoUninitialize, COINIT_APARTMENTTHREADED, + }; + use windows::Win32::UI::Shell::Common::ITEMIDLIST; + use windows::Win32::UI::Shell::{SHOpenFolderAndSelectItems, SHParseDisplayName}; + + let normalized = path.replace('/', "\\"); + let dir = match normalized.rfind('\\') { + Some(i) if i > 0 => &normalized[..i], + _ => return Err("路径缺少目录部分".into()), + }; + + let wide = |s: &str| -> Vec { + OsStr::new(s).encode_wide().chain(std::iter::once(0)).collect() + }; + let dir_w = wide(dir); + let file_w = wide(&normalized); + + // 首次 COM 初始化失败(例如线程已在 MTA)时,后续 shell 调用一般仍可用,忽略错误继续 + let _ = unsafe { CoInitializeEx(None, COINIT_APARTMENTTHREADED) }; + + let result = unsafe { + let mut folder_pidl: *mut ITEMIDLIST = std::ptr::null_mut(); + let mut file_pidl: *mut ITEMIDLIST = std::ptr::null_mut(); + let attempt = (|| -> Result<(), String> { + SHParseDisplayName(PCWSTR(dir_w.as_ptr()), None, &mut folder_pidl, 0, None) + .map_err(|e| format!("解析目录失败: {}", e))?; + SHParseDisplayName(PCWSTR(file_w.as_ptr()), None, &mut file_pidl, 0, None) + .map_err(|e| format!("解析文件失败: {}", e))?; + // `apidl` 要的是**相对父目录的子 PIDL**,正是绝对 PIDL 的最后一个 ITEMID + let child = il_find_last_id(file_pidl); + SHOpenFolderAndSelectItems(folder_pidl, Some(&[child]), 0) + .map_err(|e| format!("定位文件失败: {}", e)) + })(); + if !folder_pidl.is_null() { + CoTaskMemFree(Some(folder_pidl as *const core::ffi::c_void)); + } + if !file_pidl.is_null() { + CoTaskMemFree(Some(file_pidl as *const core::ffi::c_void)); + } + attempt + }; + + unsafe { CoUninitialize() }; + result +} + +#[cfg(not(windows))] +fn select_in_explorer(_path: &str) -> Result<(), String> { + Err("当前平台不支持".into()) +} + +/// `ITEMIDLIST` 是一条「ITEMID 链」:每个 ITEMID 以 2 字节的 `cb` 开头,`cb == 0` 表示链结束。 +/// 返回最后一个 ITEMID 的指针(即相对父目录的子 PIDL)。 +/// +/// `ILFindLastID` 在 `shlobj_core.h` 里是**内联函数**,`windows` crate 不导出,所以这里自己走一遍 +/// (windows-sys 把它声明成了 shell32 导入,但本项目统一用 `windows` crate 做 shell/COM)。 +#[cfg(windows)] +unsafe fn il_find_last_id(pidl: *const windows::Win32::UI::Shell::Common::ITEMIDLIST) -> *const windows::Win32::UI::Shell::Common::ITEMIDLIST { + use windows::Win32::UI::Shell::Common::ITEMIDLIST; + let mut p: *const ITEMIDLIST = pidl; + loop { + let next = p.cast::().add((*p).mkid.cb as usize).cast::(); + if (*next).mkid.cb == 0 { + return p; + } + p = next; + } +} + +/// 向前台窗口发一次 F2(Explorer 的重命名快捷键)。 +/// +/// 用 SendInput 而不是 PostMessage:F2 要经过 Explorer 的消息泵与输入法状态, +/// 与 `clipboard::popup::simulate_paste` 同一套做法(也是同一条已知限制: +/// 目标窗口若以管理员权限运行,非提权进程的 SendInput 会被 UIPI 挡掉)。 +#[cfg(windows)] +fn send_rename_key() { + use windows_sys::Win32::UI::Input::KeyboardAndMouse::{ + SendInput, INPUT, INPUT_KEYBOARD, KEYBDINPUT, KEYEVENTF_KEYUP, VK_F2, + }; + + // 安全初始化为零值,避免未定义字段 + let mut inputs: [INPUT; 2] = unsafe { std::mem::zeroed() }; + + inputs[0].r#type = INPUT_KEYBOARD; + inputs[0].Anonymous.ki = KEYBDINPUT { wVk: VK_F2, wScan: 0, dwFlags: 0, time: 0, dwExtraInfo: 0 }; + + inputs[1].r#type = INPUT_KEYBOARD; + inputs[1].Anonymous.ki = + KEYBDINPUT { wVk: VK_F2, wScan: 0, dwFlags: KEYEVENTF_KEYUP, time: 0, dwExtraInfo: 0 }; + + unsafe { + SendInput(2, inputs.as_ptr(), std::mem::size_of::() as i32); + } +} + +#[cfg(not(windows))] +fn send_rename_key() {} + /// 用系统默认程序打开文件/文件夹。 /// - 目录:explorer.exe 直接打开(修复索引目录点击后未打开的问题) /// - 文件:ShellExecuteW open,无关联应用时自动 fallback 到「打开方式」对话框(verb: openas) diff --git a/src-tauri/src/quickpanel/mod.rs b/src-tauri/src/quickpanel/mod.rs index 54d86f9..8af8e0c 100644 --- a/src-tauri/src/quickpanel/mod.rs +++ b/src-tauri/src/quickpanel/mod.rs @@ -23,7 +23,8 @@ pub use commands::{ quickpanel_get_app_icon, quickpanel_get_settings, quickpanel_get_special_locations, quickpanel_hide_popup, quickpanel_init_file_index, quickpanel_lock_screen, quickpanel_open_file, quickpanel_open_special, quickpanel_register_shortcut, - quickpanel_reveal_in_explorer, quickpanel_run_custom_command, quickpanel_run_system_command, + quickpanel_reveal_in_explorer, quickpanel_reveal_in_explorer_rename, + quickpanel_run_custom_command, quickpanel_run_system_command, quickpanel_save_settings, quickpanel_scan_apps, quickpanel_search_files, quickpanel_show_popup, quickpanel_show_window, quickpanel_unregister_shortcut, }; diff --git a/src-tauri/src/setup.rs b/src-tauri/src/setup.rs index 63c9a67..d401395 100644 --- a/src-tauri/src/setup.rs +++ b/src-tauri/src/setup.rs @@ -22,6 +22,7 @@ use crate::monitor_kernel::MonitorKernel; use crate::music::MusicManager; use crate::network_monitor::NetworkMonitor; use crate::editor::EditorManager; +use crate::smarthome::HaManager; use crate::process_manager::{ProcessManager, start_monitoring_thread}; use crate::terminal::TerminalManager; use crate::translate::TranslateManager; @@ -101,6 +102,21 @@ pub fn init(app: &mut App) -> Result<(), Box> { diff.init_on_launch(app.handle()); app.manage(diff); + // ===== 智能家居模块:HaManager(Home Assistant 对接) ===== + // 仅注册状态:连接与令牌都在命令调用时按需读取,**启动阶段不发任何网络请求**。 + // 端点探测(局域网 900ms / 反代 5s)发生在首次需要发请求时,不占启动时间。 + let smarthome = HaManager::new(app_data_dir.clone()); + app.manage(smarthome); + // P4:用户上次开着「实时推送」或「本地规则总开关」时,启动后恢复 WS 连接。 + // 放在后台任务里(不阻塞启动),且**只有用户显式开过才会连** —— 与"启动不发请求"一致。 + { + let handle = app.handle().clone(); + tauri::async_runtime::spawn(async move { + let manager = handle.state::(); + manager.sync_ws(&handle).await; + }); + } + // ===== 翻译模块:TranslateManager ===== // 仅注册状态:设置与密钥都在命令调用时按需读取,启动阶段不发任何网络请求 // (模型可用性校验因此改为懒校验:首次翻译失败时解释原因 + 设置页手动拉取模型列表)。 diff --git a/src-tauri/src/smarthome/automation.rs b/src-tauri/src/smarthome/automation.rs new file mode 100644 index 0000000..626f8e2 --- /dev/null +++ b/src-tauri/src/smarthome/automation.rs @@ -0,0 +1,549 @@ +//! 本地轻量规则引擎(P4)。 +//! +//! 三段式(触发 / 条件 / 动作)线性规则,**不做嵌套树** —— 这是"简单自动化"的边界所在 +//! (plan §5.4-B)。求值在 Rust 侧:WS 事件一到就匹配,不依赖前端页面是否打开。 +//! +//! **必须显式告知用户的前提**(D2 已拍板):本地规则只在 Thing 运行时生效。 +//! 应用退出、电脑关机后就不再触发;要 7×24 可靠就得把规则建在 HA 里。UI 有常驻警示条。 +//! +//! 三条护栏(plan §5.4-B 明确要求,一条都不能省): +//! 1. **冷却时间**:`cooldownSec` 内的重复触发直接丢弃; +//! 2. **动作失败不中断**:某个动作 4xx/5xx 时记 `lastError` 并继续下一个, +//! 否则一条失败会吞掉后续所有动作; +//! 3. **循环保护**:规则动作引起的状态变化可能再次触发同一规则(A 开 B、B 关 A), +//! 冷却不足以阻断时用"突发计数"兜底(同规则 10s 内最多 5 次)。 + +use std::collections::{HashMap, VecDeque}; +use std::path::Path; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use chrono::{Datelike, Local, Timelike}; +use tauri::{AppHandle, Emitter}; +use tauri_plugin_notification::NotificationExt; +use tokio::sync::watch; + +use super::client; +use super::types::{ + EndpointKind, EntitySummary, Rule, RuleAction, RuleCondition, RuleFiredEvent, RuleRecord, + RuleTrigger, RulesFile, RULES_VERSION, +}; +use crate::constants::events; + +/// 内存里保留的运行记录条数。 +pub const MAX_RECORDS: usize = 50; +/// 单个 `delay` 动作的上限(秒)。 +/// +/// 防的是"睡 1 小时"这种怪规则:本地规则只在 Thing 运行时生效, +/// 一条要睡一小时的动作在应用重启后就永远跑不完了。 +pub const MAX_DELAY_SEC: u32 = 600; +/// 突发护栏窗口与上限(循环保护,护栏 3)。 +const BURST_WINDOW: Duration = Duration::from_secs(10); +const BURST_MAX: usize = 5; +/// 触发统计落盘的最小间隔(秒)—— 去抖,见 `maybe_persist`。 +const PERSIST_MIN_INTERVAL_SECS: u64 = 3; +/// `for`(持续 N 秒)触发器的巡检间隔(毫秒)。 +const SWEEP_INTERVAL_MS: u64 = 500; + +/// 规则求值 / 执行所需的环境(`Clone` 以便丢进后台任务)。 +#[derive(Clone)] +pub struct RuleEnv { + pub app: AppHandle, + /// REST 端点:动作里的服务调用走 REST(与 P2 的控制同一条路径,不另造一套) + pub base_url: String, + pub token: String, + pub insecure: bool, + pub kind: EndpointKind, + pub rules: Arc>, + pub records: Arc>>, + /// 当前实体摘要(`entity_id` → 摘要),条件判断读它 + pub summaries: Arc>>, + /// 最近触发时刻(内存态,只服务突发护栏) + pub recent: Arc>>, + /// `for`(持续 N 秒)触发器的槽位表:`rule_id` → 到点时刻。 + /// + /// 用槽位表而不是"每次事件起一个 sleep 任务":1Hz 的实体配 `for=300` + /// 会常驻几百个任务,而且那些任务不受连接切换影响(会用旧端点执行动作)。 + pub pending: Arc>>, + /// 触发统计上次落盘时刻(去抖用,见 `maybe_persist`) + pub last_persist: Arc>, + /// `automations.json` 路径 + pub rules_path: std::path::PathBuf, +} + +// ============================== 文件读写 ============================== + +/// 读取规则文件(不存在 / 损坏时退化为默认值,**不报错**:规则是可选功能, +/// 不该因为它坏了导致模块打不开)。 +pub fn load(path: &Path) -> RulesFile { + let mut file: RulesFile = std::fs::read_to_string(path) + .ok() + .and_then(|t| serde_json::from_str(&t).ok()) + .unwrap_or_default(); + if file.version != RULES_VERSION { + file.version = RULES_VERSION; + } + file +} + +/// 写入规则文件(调用方负责放到 `spawn_blocking` 里)。 +pub fn save(path: &Path, file: &RulesFile) -> Result<(), String> { + let json = serde_json::to_string_pretty(file).map_err(|e| format!("序列化规则失败:{e}"))?; + std::fs::write(path, json).map_err(|e| format!("写入规则文件失败:{e}")) +} + +/// 保存前的校验(**留在这里而不是组件里**:规则模型的知识只有一份)。 +pub fn validate(rule: &Rule) -> Result<(), String> { + if rule.name.trim().is_empty() { + return Err("请填写规则名称".to_string()); + } + if rule.trigger.entity_id.trim().is_empty() { + return Err("请选择触发实体".to_string()); + } + if rule.actions.is_empty() { + return Err("至少需要一个动作".to_string()); + } + for action in &rule.actions { + match action.kind.as_str() { + "service" => { + if action.domain.trim().is_empty() + || action.service.trim().is_empty() + || action.entity_id.trim().is_empty() + { + return Err("动作里的 domain / 服务 / 实体都不能为空".to_string()); + } + } + "delay" => { + if action.seconds == 0 { + return Err("延时的秒数必须大于 0".to_string()); + } + if action.seconds > MAX_DELAY_SEC { + return Err(format!("延时最长 {MAX_DELAY_SEC} 秒")); + } + } + _ => {} + } + } + Ok(()) +} + +// ============================== 求值 ============================== + +/// 触发条件是否成立(`old` 为 `None` 表示"首次见到该实体"或"延时复查")。 +pub fn trigger_matches( + trigger: &RuleTrigger, + old: Option<&EntitySummary>, + new: &EntitySummary, +) -> bool { + if trigger.entity_id.is_empty() { + return false; + } + if !trigger.to.is_empty() && !trigger.to.contains(&new.state) { + return false; + } + if !trigger.from.is_empty() { + match old { + Some(o) if trigger.from.contains(&o.state) => {} + // from 非空但拿不到旧状态:不判定为命中(宁可漏一次,也不要误触) + _ => return false, + } + } + if !trigger.numeric_op.is_empty() { + let (Some(value), Some(threshold)) = (new.numeric, trigger.numeric_value) else { + return false; + }; + let ok = match trigger.numeric_op.as_str() { + ">" => value > threshold, + ">=" => value >= threshold, + "<" => value < threshold, + "<=" => value <= threshold, + "==" => (value - threshold).abs() < f64::EPSILON, + "!=" => (value - threshold).abs() >= f64::EPSILON, + _ => true, + }; + if !ok { + return false; + } + } + true +} + +/// 实体状态变化时的入口(由 `ws.rs` 的聚合任务调用,**必须是同步的**: +/// 它跑在 WS 读循环里,耗时工作都丢给后台任务)。 +pub fn on_entity_changed( + env: &RuleEnv, + entity_id: &str, + old: Option<&EntitySummary>, + new: &EntitySummary, +) { + let candidates: Vec<(String, RuleTrigger)> = { + let Ok(file) = env.rules.lock() else { + return; + }; + if !file.enabled { + return; + } + file.rules + .iter() + .filter(|r| r.enabled && r.trigger.entity_id == entity_id) + .map(|r| (r.id.clone(), r.trigger.clone())) + .collect() + }; + + for (rule_id, trigger) in candidates { + if trigger.for_sec == 0 { + if !trigger_matches(&trigger, old, new) { + continue; + } + let env = env.clone(); + tauri::async_runtime::spawn(async move { + fire(&env, &rule_id).await; + }); + continue; + } + // 持续 N 秒:只维护"首次满足的时刻",到点由巡检任务(`spawn_sweeper`)复查; + // 状态一旦离开满足态就把槽位撤掉。**不重置**已存在的槽位 —— 那才是 + // "持续 N 秒满足"的语义(每次事件都重置会变成"静默 N 秒才触发")。 + let matches = trigger_matches(&trigger, old, new); + if let Ok(mut pending) = env.pending.lock() { + if matches { + pending + .entry(rule_id) + .or_insert_with(|| Instant::now() + Duration::from_secs(trigger.for_sec as u64)); + } else { + pending.remove(&rule_id); + } + } + } +} + +/// `for` 触发器的巡检任务:每 `SWEEP_INTERVAL_MS` 看一次槽位表,到点的复查后执行。 +/// +/// **与 WS 连接同生命周期**(收到 stop 就退出):连接换了/停了,就不会有旧定时器 +/// 残留下来用旧端点、旧令牌继续执行动作。 +pub fn spawn_sweeper(env: &RuleEnv, mut stop: watch::Receiver) { + let env = env.clone(); + tauri::async_runtime::spawn(async move { + let mut tick = tokio::time::interval(Duration::from_millis(SWEEP_INTERVAL_MS)); + loop { + tokio::select! { + _ = stop.changed() => break, + _ = tick.tick() => sweep_pending(&env), + } + } + }); +} + +fn sweep_pending(env: &RuleEnv) { + let due: Vec = match env.pending.lock() { + Ok(mut pending) => { + let now = Instant::now(); + let ready: Vec = pending + .iter() + .filter(|entry| *entry.1 <= now) + .map(|entry| entry.0.clone()) + .collect(); + for id in &ready { + pending.remove(id); + } + ready + } + Err(_) => return, + }; + + for rule_id in due { + let (trigger, entity_id) = match env.rules.lock() { + Ok(file) if file.enabled => { + match file.rules.iter().find(|r| r.id == rule_id && r.enabled) { + Some(r) => (r.trigger.clone(), r.trigger.entity_id.clone()), + None => continue, + } + } + _ => continue, + }; + // 复查:到点时**当前**状态仍需满足触发条件(去抖的真正含义) + let current = env + .summaries + .lock() + .ok() + .and_then(|g| g.get(&entity_id).cloned()); + let Some(current) = current else { + continue; + }; + if !trigger_matches(&trigger, None, ¤t) { + continue; + } + let env = env.clone(); + tauri::async_runtime::spawn(async move { + fire(&env, &rule_id).await; + }); + } +} + +/// 原子认领一次触发权:**在同一把锁里**判冷却并写下占位时间。 +/// +/// 为什么必须"认领"而不是"先读后写":`fire` 里的动作是 async(服务调用可能几秒), +/// 同一聚合窗口内的两条事件会各自起一个 `fire`,两个都读到同一份旧 `last_fired_at` +/// → 都通过冷却 → **同一条规则被重复执行**。占位把判定与写入收进一个临界区后, +/// 后到的那次会读到新时间戳并被冷却挡掉。 +/// +/// 返回 `(规则快照, 认领时刻)`。 +fn claim(env: &RuleEnv, rule_id: &str) -> Option<(Rule, i64)> { + let mut file = env.rules.lock().ok()?; + if !file.enabled { + return None; + } + let idx = file.rules.iter().position(|r| r.id == rule_id)?; + if !file.rules[idx].enabled { + return None; + } + let now = chrono::Utc::now().timestamp(); + let (cooldown, last) = (file.rules[idx].cooldown_sec, file.rules[idx].last_fired_at); + if cooldown > 0 && last > 0 && now - last < cooldown as i64 { + return None; + } + file.rules[idx].last_fired_at = now; + Some((file.rules[idx].clone(), now)) +} + +/// 执行一条规则(认领 → 突发护栏 → 条件 → 动作)。 +async fn fire(env: &RuleEnv, rule_id: &str) { + let Some((rule, now)) = claim(env, rule_id) else { + return; + }; + + // 护栏 3:突发计数(冷却不足以阻断的 A→B→A 互触) + if !burst_allow(env, &rule.id) { + crate::logger::log_warn( + "smarthome", + &format!( + "规则「{}」在 {} 秒内触发超过 {} 次,已跳过(循环保护)", + rule.name, + BURST_WINDOW.as_secs(), + BURST_MAX + ), + ); + return; + } + if !conditions_ok(env, &rule) { + // 触发器确实命中了,是条件没放行:本次不执行、不计次数, + // 但冷却槽已被占用(没有动作就不该反复重试) + maybe_persist(env); + return; + } + + let mut failures: Vec = Vec::new(); + for action in &rule.actions { + // 护栏 2:单个动作失败**不中断**后续动作 + if let Err(e) = run_action(env, action).await { + failures.push(e); + } + } + let ok = failures.is_empty(); + let detail = if ok { + format!("已执行 {} 个动作", rule.actions.len()) + } else { + failures.join(";") + }; + + if let Ok(mut file) = env.rules.lock() { + if let Some(slot) = file.rules.iter_mut().find(|r| r.id == rule_id) { + if ok { + slot.fire_count = slot.fire_count.saturating_add(1); + } + slot.last_error = if ok { String::new() } else { detail.clone() }; + } + } + maybe_persist(env); + + crate::logger::log_info( + "smarthome", + &format!("本地规则「{}」触发:{}", rule.name, detail), + ); + push_record( + env, + RuleRecord { + rule_id: rule.id.clone(), + rule_name: rule.name.clone(), + at: now, + ok, + detail, + }, + ); +} + +/// 触发统计的落盘去抖:内存立即更新,磁盘最多每 `PERSIST_MIN_INTERVAL_SECS` 写一次。 +/// +/// 规则很容易被传感器刷得勤(功率反复跳),每触发一次就整份序列化 + 写盘是纯浪费; +/// 统计字段(`lastFiredAt` / `fireCount` / `lastError`)晚几秒落盘不影响任何判断。 +/// 命令层的**显式**保存(存规则 / 删规则 / 总开关)仍立即写盘 —— 那是用户动作。 +fn maybe_persist(env: &RuleEnv) { + let due = match env.last_persist.lock() { + Ok(mut at) => { + if at.elapsed() >= Duration::from_secs(PERSIST_MIN_INTERVAL_SECS) { + *at = Instant::now(); + true + } else { + false + } + } + Err(_) => true, + }; + if !due { + return; + } + let Ok(file) = env.rules.lock().map(|g| g.clone()) else { + return; + }; + let path = env.rules_path.clone(); + tauri::async_runtime::spawn_blocking(move || { + if let Err(e) = save(&path, &file) { + crate::logger::log_warn("smarthome", &format!("保存规则触发统计失败:{e}")); + } + }); +} + +/// 执行单个动作。 +async fn run_action(env: &RuleEnv, action: &RuleAction) -> Result<(), String> { + match action.kind.as_str() { + "delay" => { + let secs = action.seconds.min(MAX_DELAY_SEC) as u64; + if secs > 0 { + tokio::time::sleep(Duration::from_secs(secs)).await; + } + Ok(()) + } + "notify" => { + let title = if action.title.trim().is_empty() { + "Thing 智能家居".to_string() + } else { + action.title.clone() + }; + env.app + .notification() + .builder() + .title(title) + .body(action.message.clone()) + .show() + .map_err(|e| format!("系统通知发送失败:{e}")) + } + // 默认按 service 处理(前端只给这三种 kind) + _ => { + if action.domain.trim().is_empty() + || action.service.trim().is_empty() + || action.entity_id.trim().is_empty() + { + return Err("动作缺少 domain / 服务 / 实体".to_string()); + } + client::call_service( + &env.base_url, + &env.token, + env.insecure, + env.kind, + &action.domain, + &action.service, + &action.entity_id, + &action.params, + ) + .await + .map(|_| ()) + .map_err(|f| format!("{}:{}", action.entity_id, f.message)) + } + } +} + +/// 条件全部 AND(plan §5.4-B)。 +fn conditions_ok(env: &RuleEnv, rule: &Rule) -> bool { + rule.conditions.iter().all(|c| match c.kind.as_str() { + "time" => time_ok(c), + _ => state_ok(env, c), + }) +} + +fn state_ok(env: &RuleEnv, condition: &RuleCondition) -> bool { + if condition.entity_id.is_empty() || condition.state.is_empty() { + return true; + } + env.summaries + .lock() + .ok() + .and_then(|g| g.get(&condition.entity_id).map(|e| e.state == condition.state)) + .unwrap_or(false) +} + +/// 时间窗口条件:`weekdays`(1=周一 … 7=周日,空 = 每天)+ `HH:MM` 区间。 +/// 跨零点(`to < from`)视为跨天窗口,例如 `23:00 – 06:00`。 +fn time_ok(condition: &RuleCondition) -> bool { + if condition.from_time.is_empty() || condition.to_time.is_empty() { + return true; + } + let (Some((fh, fm)), Some((th, tm))) = ( + parse_hhmm(&condition.from_time), + parse_hhmm(&condition.to_time), + ) else { + return true; + }; + let now = Local::now(); + if !condition.weekdays.is_empty() { + let weekday = now.weekday().number_from_monday(); + if !condition.weekdays.contains(&weekday) { + return false; + } + } + let current = now.hour() * 60 + now.minute(); + let from = fh * 60 + fm; + let to = th * 60 + tm; + if from <= to { + current >= from && current <= to + } else { + current >= from || current <= to + } +} + +fn parse_hhmm(text: &str) -> Option<(u32, u32)> { + let (h, m) = text.trim().split_once(':')?; + let hour: u32 = h.trim().parse().ok()?; + let minute: u32 = m.trim().parse().ok()?; + if hour > 23 || minute > 59 { + return None; + } + Some((hour, minute)) +} + +/// 突发护栏:同规则在窗口内的触发次数上限。 +/// +/// 顺带把过期记录从队首清掉(队列按时间推进,天然有序)。 +fn burst_allow(env: &RuleEnv, rule_id: &str) -> bool { + let Ok(mut g) = env.recent.lock() else { + return true; + }; + let cutoff = Instant::now() - BURST_WINDOW; + while g.front().map(|(_, at)| *at < cutoff).unwrap_or(false) { + g.pop_front(); + } + if g.iter().filter(|(id, _)| id == rule_id).count() >= BURST_MAX { + return false; + } + g.push_back((rule_id.to_string(), Instant::now())); + true +} + +/// 记一条运行记录(内存环形)+ 推事件给前端。 +fn push_record(env: &RuleEnv, record: RuleRecord) { + if let Ok(mut g) = env.records.lock() { + g.push_front(record.clone()); + while g.len() > MAX_RECORDS { + g.pop_back(); + } + } + let _ = env.app.emit( + events::SMARTHOME_RULE_FIRED, + RuleFiredEvent { + rule_id: record.rule_id, + rule_name: record.rule_name, + at: record.at, + ok: record.ok, + detail: record.detail, + }, + ); +} diff --git a/src-tauri/src/smarthome/client.rs b/src-tauri/src/smarthome/client.rs new file mode 100644 index 0000000..c3727a4 --- /dev/null +++ b/src-tauri/src/smarthome/client.rs @@ -0,0 +1,735 @@ +//! Home Assistant HTTP 客户端与**端点选择**。 +//! +//! P0 只用到两件事:探测(`GET /api/` + `GET /api/config`)与端点选择 +//! (`auto` / `local` / `remote` 三档)。设备数据与控制命令在 P1/P2 才接上来, +//! 但它们**必须复用这里的 `resolve_endpoint`**,否则在外面的每次请求都会先等 +//! 局域网超时。 +//! +//! 超时策略见 `SMART_HOME_MODULE_PLAN.md` §3.7:局域网探测必须短(在外会必然耗满), +//! 反代探测可以宽松(Cloudflare Tunnel 的 RTT 常在 100–400ms)。 + +use std::time::Instant; + +use serde::Deserialize; +use serde_json::json; + +use crate::smarthome::types::{ + EndpointKind, EndpointMode, EndpointProbe, EntitySummary, HaConnection, ServiceParams, +}; + +/// 局域网探测超时(**必须短**)。 +/// +/// 在家里局域网必然 <10ms 命中;在外面,这个地址会因为 ARP / 路由不可达而 +/// **必然耗满超时**。它直接决定"出门后每次冷探测有多卡"。 +pub const LOCAL_PROBE_TIMEOUT_MS: u64 = 900; +/// 反代探测超时(Cloudflare Tunnel 首包可能较慢,给足余量)。 +pub const REMOTE_PROBE_TIMEOUT_MS: u64 = 5000; +/// 强制模式(`local` / `remote`)下的超时:此时失败就是"真的连不上", +/// 不该因为 900ms 这种"用于探测缺失"的短超时把可用链路判死。 +pub const FORCED_PROBE_TIMEOUT_MS: u64 = 5000; +/// 「测试连接」在单个地址上的总超时(要跑两个请求,给比探测更宽的预算)。 +pub const TEST_LOCAL_TIMEOUT_MS: u64 = 8000; +pub const TEST_REMOTE_TIMEOUT_MS: u64 = 20000; + +/// 普通数据请求的超时:局域网 8s / 反代 30s。 +/// +/// 反代上 `/api/states` 是几百 KB(gzip 后几十 KB),这里给的是"能成功但慢"的余量, +/// 不是"期望 30s" —— 实际体验主要由 §3.7 的链路选择与 gzip 决定。 +pub const REQUEST_TIMEOUT_LOCAL_MS: u64 = 8000; +pub const REQUEST_TIMEOUT_REMOTE_MS: u64 = 30000; + +/// 按链路取数据请求超时。 +pub fn request_timeout(kind: EndpointKind) -> u64 { + match kind { + EndpointKind::Local => REQUEST_TIMEOUT_LOCAL_MS, + EndpointKind::Remote => REQUEST_TIMEOUT_REMOTE_MS, + } +} + +/// 一次 HTTP 交互失败的分类结果(探测与数据/控制请求共用)。 +#[derive(Debug, Clone)] +pub struct ProbeFailure { + /// auth | network | notFound | badRequest | server | other + pub kind: &'static str, + pub message: String, + /// 是否属于"令牌本身无效"。 + /// + /// 这类失败**必须立刻放弃换端点重试**:同一个令牌在所有地址上都无效, + /// 继续试反代只会让用户多等一个超时,并把真正的原因(令牌失效)淹没在 + /// "都无法连接"里。 + pub fatal_auth: bool, +} + +impl ProbeFailure { + fn auth(message: impl Into) -> Self { + Self { + kind: "auth", + message: message.into(), + fatal_auth: true, + } + } + fn network(message: impl Into) -> Self { + Self { + kind: "network", + message: message.into(), + fatal_auth: false, + } + } + fn server(message: impl Into) -> Self { + Self { + kind: "server", + message: message.into(), + fatal_auth: false, + } + } + /// 实体 / 服务不存在(设备被移除、集成重载) + fn not_found(message: impl Into) -> Self { + Self { + kind: "notFound", + message: message.into(), + fatal_auth: false, + } + } + /// 参数不被该服务接受(如给不支持色温的灯传 `color_temp_kelvin`) + fn bad_request(message: impl Into) -> Self { + Self { + kind: "badRequest", + message: message.into(), + fatal_auth: false, + } + } +} + +/// 端点选择结果。 +pub struct ResolvedEndpoint { + pub url: String, + pub kind: EndpointKind, + pub latency_ms: u64, +} + +/// 端点选择失败:带分类,前端据此决定是"重填令牌"还是"重试/切换地址"(§3.6)。 +#[derive(Debug, Clone)] +pub struct ResolveFailure { + /// auth | network | config + pub kind: &'static str, + pub message: String, +} + +impl ResolveFailure { + fn new(kind: &'static str, message: impl Into) -> Self { + Self { + kind, + message: message.into(), + } + } +} + +/// 地址规范化:补协议(局域网默认 `http`、反代默认 `https`)、去掉结尾斜杠。 +pub fn normalize_url(input: &str, prefer_https: bool) -> String { + let mut u = input.trim().to_string(); + if u.is_empty() { + return u; + } + let lower = u.to_lowercase(); + if !lower.starts_with("http://") && !lower.starts_with("https://") { + u = if prefer_https { + format!("https://{u}") + } else { + format!("http://{u}") + }; + } + while u.ends_with('/') { + u.pop(); + } + u +} + +/// REST 端点 → WebSocket 端点:`http` → `ws`、`https` → `wss`,路径固定 `/api/websocket`。 +/// +/// **复用同一份端点选择结果**(plan §3.7-a 最后一条):WS 一旦连上就固定在所选端点, +/// 不允许同一屏数据来自两条链路(否则"更新于 x 秒前"的时间戳会来自不同链路)。 +pub fn ws_url(base: &str) -> Result { + let mut u = url::Url::parse(base).map_err(|e| format!("HA 地址不合法:{e}"))?; + let ok = match u.scheme() { + "https" => u.set_scheme("wss").is_ok(), + "http" => u.set_scheme("ws").is_ok(), + "ws" | "wss" => true, + other => return Err(format!("不支持用 {other} 建立 WebSocket 连接")), + }; + if !ok { + return Err("无法把该地址转换成 WebSocket 协议".to_string()); + } + u.set_path("/api/websocket"); + u.set_query(None); + Ok(u.to_string()) +} + +/// 校验地址合法性(保存时做,**不要在请求时才失败**——那时错误信息已经离用户输入很远了)。 +pub fn validate_url(url: &str, label: &str) -> Result<(), String> { + if url.trim().is_empty() { + return Ok(()); + } + let parsed = url::Url::parse(url).map_err(|e| format!("{label}不是合法的地址:{e}"))?; + if parsed.host_str().unwrap_or("").is_empty() { + return Err(format!("{label}缺少主机名")); + } + Ok(()) +} + +fn build_client(insecure: bool, timeout_ms: u64) -> Result { + reqwest::Client::builder() + // 自签证书:与飞牛连接同款开关。局域网 IP 的 HA 通常是 http,用不到它; + // 反代若用 IP 直连 + 自签证书才需要。 + .danger_accept_invalid_certs(insecure) + .timeout(std::time::Duration::from_millis(timeout_ms)) + // 压缩交给 reqwest 自动协商(Cargo.toml 已开 `gzip` feature): + // 反代链路上 `/api/states` 是几百 KB JSON,不压缩就是白送 5–10 倍流量。 + .build() + .map_err(|e| format!("构建 HTTP 客户端失败:{e}")) +} + +#[derive(Deserialize)] +struct ApiRoot { + #[serde(default)] + message: String, +} + +#[derive(Deserialize)] +struct HaConfig { + #[serde(default)] + version: String, + #[serde(default)] + location_name: String, + #[serde(default)] + unit_system: UnitSystem, +} + +/// HA 的系统单位制(`/api/config`)。只有温度是本模块需要的 —— +/// climate 的 `temperature` / `min_temp` / `max_temp` 都按它给值。 +#[derive(Deserialize, Default)] +struct UnitSystem { + #[serde(default)] + temperature: String, +} + +fn describe_request_error(e: &reqwest::Error) -> String { + if e.is_timeout() { + "连接超时".to_string() + } else if e.is_connect() { + "无法建立连接".to_string() + } else { + format!("请求失败:{e}") + } +} + +/// 轻量可达性检查:`GET /api/`(地址可达 + 令牌有效 + **确实是 HA 的 API**)。 +/// 返回耗时(毫秒)。 +/// +/// 为什么要校验响应体而不仅是状态码:反代前面若挂了访问网关(如 Cloudflare Access), +/// 未携带 Service Token 时会被重定向到一个 **200 的 HTML 登录页** —— 只看状态码会把它 +/// 判成"链路正常",随后的真实请求才会莫名其妙地失败(§2.2-6)。 +async fn check_reachable( + base: &str, + token: &str, + insecure: bool, + timeout_ms: u64, +) -> Result { + let client = build_client(insecure, timeout_ms).map_err(ProbeFailure::network)?; + let started = Instant::now(); + let resp = client + .get(format!("{base}/api/")) + .bearer_auth(token) + .send() + .await + .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; + + let status = resp.status(); + if status.as_u16() == 401 || status.as_u16() == 403 { + return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); + } + if !status.is_success() { + return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); + } + let root = resp.json::().await.map_err(|_| { + ProbeFailure::server("响应不是 Home Assistant 的 API(可能被反向代理或访问网关拦截)") + })?; + if root.message.is_empty() { + return Err(ProbeFailure::server("Home Assistant 返回了空响应")); + } + Ok(started.elapsed().as_millis() as u64) +} + +/// 探测单个地址(「测试连接」用):`GET /api/` + `GET /api/config`。 +/// +/// 不拉 `/api/states` 统计实体数:那是几百 KB 的响应,在反代链路上会把 +/// "测试连接"从 1 秒拖到 3 秒以上,而实体列表在 P1 本来就会拉一次。 +pub async fn probe_url( + url: &str, + token: &str, + insecure: bool, + kind: EndpointKind, +) -> EndpointProbe { + let timeout_ms = match kind { + EndpointKind::Local => TEST_LOCAL_TIMEOUT_MS, + EndpointKind::Remote => TEST_REMOTE_TIMEOUT_MS, + }; + let mut failure: Option = None; + let started = Instant::now(); + + let mut ha_version = String::new(); + let mut location_name = String::new(); + let mut temperature_unit = String::new(); + let mut ok = false; + + match check_reachable(url, token, insecure, timeout_ms).await { + Ok(_) => match fetch_config(url, token, insecure, timeout_ms).await { + Ok(cfg) => { + ha_version = cfg.version; + location_name = cfg.location_name; + temperature_unit = cfg.unit_system.temperature; + ok = true; + } + Err(e) => failure = Some(e), + }, + Err(e) => failure = Some(e), + } + + EndpointProbe { + url: url.to_string(), + kind, + ok, + ha_version, + location_name, + temperature_unit, + elapsed_ms: started.elapsed().as_millis() as u64, + error: failure.as_ref().map(|f| f.message.clone()), + error_kind: failure.as_ref().map(|f| f.kind.to_string()), + } +} + +async fn fetch_config( + base: &str, + token: &str, + insecure: bool, + timeout_ms: u64, +) -> Result { + let client = build_client(insecure, timeout_ms).map_err(ProbeFailure::network)?; + let resp = client + .get(format!("{base}/api/config")) + .bearer_auth(token) + .send() + .await + .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; + let status = resp.status(); + if !status.is_success() { + if status.as_u16() == 401 || status.as_u16() == 403 { + return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); + } + return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); + } + resp.json::() + .await + .map_err(|e| ProbeFailure::server(format!("响应解析失败:{e}"))) +} + +/// 逐个地址探测(顺序:局域网 → 反代),供「测试连接」使用。 +pub async fn probe_all( + local_url: &str, + remote_url: &str, + token: &str, + insecure: bool, +) -> Vec { + let mut out = Vec::new(); + if !local_url.trim().is_empty() { + out.push(probe_url(local_url.trim(), token, insecure, EndpointKind::Local).await); + } + if !remote_url.trim().is_empty() { + out.push(probe_url(remote_url.trim(), token, insecure, EndpointKind::Remote).await); + } + out +} + +/// 候选端点列表:(地址, 类型, 探测超时),按尝试顺序排列。 +fn candidates(conn: &HaConnection) -> Result, ResolveFailure> { + let local = conn.local_candidate(); + let remote = conn.remote_candidate(); + match conn.endpoint_mode { + EndpointMode::Local => match local { + Some((u, _)) => Ok(vec![(u, EndpointKind::Local, FORCED_PROBE_TIMEOUT_MS)]), + None => Err(ResolveFailure::new( + "config", + "当前连接未配置局域网地址(端点策略为「仅局域网」)", + )), + }, + EndpointMode::Remote => match remote { + Some((u, _)) => Ok(vec![(u, EndpointKind::Remote, FORCED_PROBE_TIMEOUT_MS)]), + None => Err(ResolveFailure::new( + "config", + "当前连接未配置反代地址(端点策略为「仅反代」)", + )), + }, + EndpointMode::Auto => { + let mut v = Vec::new(); + // 局域网优先:回家时能自动切回,代价是出门后每轮冷探测多花 900ms + // (见 types::EndpointMode 的注释,这里刻意**不**把 lastOkUrl 排在最前)。 + if let Some((u, k)) = local { + v.push((u, k, LOCAL_PROBE_TIMEOUT_MS)); + } + if let Some((u, k)) = remote { + v.push((u, k, REMOTE_PROBE_TIMEOUT_MS)); + } + if v.is_empty() { + return Err(ResolveFailure::new("config", "该连接没有配置任何地址")); + } + Ok(v) + } + } +} + +/// 按 `endpoint_mode` 顺序探测,返回第一个可用端点。 +/// +/// 失败时的错误信息**包含每个地址的尝试结果** —— 用户需要知道"是局域网不可达、 +/// 还是反代也挂了",一个笼统的"连接失败"无法排障。 +pub async fn resolve_endpoint( + conn: &HaConnection, + token: &str, +) -> Result { + let list = candidates(conn)?; + let mut failures: Vec = Vec::new(); + + for (url, kind, timeout_ms) in list { + match check_reachable(url, token, conn.insecure, timeout_ms).await { + Ok(latency_ms) => { + return Ok(ResolvedEndpoint { + url: url.to_string(), + kind, + latency_ms, + }); + } + Err(f) => { + // 令牌无效:换任何地址都是同一个结果,立即停止 + if f.fatal_auth { + return Err(ResolveFailure::new("auth", f.message)); + } + failures.push(format!("{}:{}", kind_label(kind), f.message)); + crate::logger::log_warn( + "smarthome", + &format!("端点探测失败({} {}):{}", kind_label(kind), url, f.message), + ); + } + } + } + + Err(ResolveFailure::new( + "network", + format!("所有地址均不可达 —— {}", failures.join(";")), + )) +} + +pub fn kind_label(kind: EndpointKind) -> &'static str { + match kind { + EndpointKind::Local => "局域网", + EndpointKind::Remote => "反代", + } +} + +/// 取 HA 元信息(版本 / 实例名 / 温度单位)。 +/// +/// 「检测链路」与"首次拉实体时还不知道实例信息"两个场景会用到它 —— +/// 只是一个很小的 `/api/config` 请求,因此不塞进每次数据拉取里。 +pub async fn fetch_meta( + base: &str, + token: &str, + insecure: bool, + kind: EndpointKind, +) -> Result<(String, String, String), ProbeFailure> { + let cfg = fetch_config(base, token, insecure, request_timeout(kind)).await?; + Ok((cfg.version, cfg.location_name, cfg.unit_system.temperature)) +} + +// ============ 实体状态(P1) ============ + +/// HA 的原始状态对象(`/api/states` 的元素,也是 WS 里 `subscribe_entities` 的形态)。 +/// +/// P4 起 `ws.rs` 也要用:WS 的增量是**差量更新**,必须先把 attributes 合并回一份 +/// 完整的原始对象,再转 `EntitySummary` —— 所以这里不再是 P1 的私有实现细节。 +#[derive(Deserialize, Default, Clone)] +pub struct RawState { + #[serde(default)] + pub entity_id: String, + #[serde(default)] + pub state: String, + /// **故意不建结构体**:attributes 的字段集合随 domain 差异极大 + /// (灯 / 窗帘 / 气候 / 媒体播放器各不相同),按需白名单取用才稳。 + #[serde(default)] + pub attributes: serde_json::Value, + #[serde(default)] + pub last_changed: String, +} + +/// 拉取全量实体状态并转成精简结构。 +/// +/// 调用方必须先 `resolve_endpoint` 拿到可用的 `base` 与 `kind` —— 这里不做链路选择。 +pub async fn fetch_entities( + base: &str, + token: &str, + insecure: bool, + kind: EndpointKind, +) -> Result, ProbeFailure> { + let client = build_client(insecure, request_timeout(kind)).map_err(ProbeFailure::network)?; + let resp = client + .get(format!("{base}/api/states")) + .bearer_auth(token) + .send() + .await + .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; + + let status = resp.status(); + if status.as_u16() == 401 || status.as_u16() == 403 { + return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); + } + if !status.is_success() { + return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); + } + let raw = resp + .json::>() + .await + .map_err(|e| ProbeFailure::server(format!("状态响应解析失败:{e}")))?; + Ok(raw.into_iter().map(to_summary).collect()) +} + +fn attr_str(attrs: &serde_json::Value, key: &str) -> String { + attrs + .get(key) + .and_then(|v| v.as_str()) + .unwrap_or_default() + .to_string() +} + +fn attr_f64(attrs: &serde_json::Value, key: &str) -> Option { + attrs.get(key).and_then(|v| v.as_f64()) +} + +/// 0–255 的整数属性(亮度)。上界夹紧,避免异常集成给出超范围值反倒转换失败。 +fn attr_u8(attrs: &serde_json::Value, key: &str) -> Option { + attrs + .get(key) + .and_then(|v| v.as_u64()) + .map(|n| n.min(255) as u8) +} + +/// 0–100 的整数属性(窗帘位置 / 风扇档位)。 +fn attr_pct(attrs: &serde_json::Value, key: &str) -> Option { + attrs + .get(key) + .and_then(|v| v.as_u64()) + .map(|n| n.min(100) as u8) +} + +fn attr_u32(attrs: &serde_json::Value, key: &str) -> Option { + attrs.get(key).and_then(|v| v.as_u64()).map(|n| n as u32) +} + +/// 字符串数组属性(`supported_color_modes` / `hvac_modes`) +fn attr_str_list(attrs: &serde_json::Value, key: &str) -> Vec { + attrs + .get(key) + .and_then(|v| v.as_array()) + .map(|a| { + a.iter() + .filter_map(|x| x.as_str().map(|s| s.to_string())) + .collect() + }) + .unwrap_or_default() +} + +/// HA 状态对象 → 精简结构。控制类命令(服务响应里带回的变化实体)也复用它, +/// P4 的 WS 增量合并后同样走这里。 +pub fn to_summary(raw: RawState) -> EntitySummary { + let attrs = &raw.attributes; + let domain = raw + .entity_id + .split('.') + .next() + .unwrap_or_default() + .to_string(); + let name = { + let n = attr_str(attrs, "friendly_name"); + if n.is_empty() { + raw.entity_id.clone() + } else { + n + } + }; + // sensor 的读数在 state 里(字符串形式的数字):能解析就顺手给前端一个数值 + let numeric = raw.state.parse::().ok(); + EntitySummary { + entity_id: raw.entity_id, + domain, + name, + state: raw.state, + numeric, + unit: attr_str(attrs, "unit_of_measurement"), + device_class: attr_str(attrs, "device_class"), + brightness: attr_u8(attrs, "brightness"), + // 窗帘:HA 官方集成给 `current_position`,个别集成给 `position`,两个都认 + position: attr_pct(attrs, "current_position").or_else(|| attr_pct(attrs, "position")), + target_temp: attr_f64(attrs, "temperature"), + min_temp: attr_f64(attrs, "min_temp"), + max_temp: attr_f64(attrs, "max_temp"), + current_temp: attr_f64(attrs, "current_temperature"), + last_changed: raw.last_changed, + last_triggered: attr_str(attrs, "last_triggered"), + supported_features: attr_u32(attrs, "supported_features").unwrap_or(0), + supported_color_modes: attr_str_list(attrs, "supported_color_modes"), + min_color_temp_kelvin: attr_u32(attrs, "min_color_temp_kelvin"), + max_color_temp_kelvin: attr_u32(attrs, "max_color_temp_kelvin"), + color_temp_kelvin: attr_u32(attrs, "color_temp_kelvin"), + hvac_modes: attr_str_list(attrs, "hvac_modes"), + target_temp_step: attr_f64(attrs, "target_temp_step"), + volume_level: attr_f64(attrs, "volume_level"), + percentage: attr_pct(attrs, "percentage"), + min: attr_f64(attrs, "min"), + max: attr_f64(attrs, "max"), + step: attr_f64(attrs, "step"), + options: attr_str_list(attrs, "options"), + } +} + +// ============ 设备控制(P2) ============ + +/// 调用服务(控制设备)。 +/// +/// 返回 HA 在响应体里带回的**已变化实体**新状态(`200` 响应就是这些状态对象, +/// 与 `/api/states` 同构)。解析失败时返回空列表而**不是报错**:命令本身已经成功, +/// 状态只是"还没反映出来",不该因此告诉用户"控制失败"。 +pub async fn call_service( + base: &str, + token: &str, + insecure: bool, + kind: EndpointKind, + domain: &str, + service: &str, + entity_id: &str, + params: &ServiceParams, +) -> Result, ProbeFailure> { + let client = build_client(insecure, request_timeout(kind)).map_err(ProbeFailure::network)?; + + let mut body = serde_json::Map::new(); + body.insert( + "entity_id".to_string(), + serde_json::Value::String(entity_id.to_string()), + ); + // 只带真正有值的参数:HA 各服务对 `null` 的处理并不统一 + if let Some(v) = params.brightness_pct { + body.insert("brightness_pct".into(), json!(v)); + } + if let Some(v) = params.color_temp_kelvin { + body.insert("color_temp_kelvin".into(), json!(v)); + } + if let Some(v) = params.position { + body.insert("position".into(), json!(v)); + } + if let Some(v) = params.temperature { + body.insert("temperature".into(), json!(v)); + } + if let Some(v) = ¶ms.hvac_mode { + body.insert("hvac_mode".into(), json!(v)); + } + if let Some(v) = params.percentage { + body.insert("percentage".into(), json!(v)); + } + if let Some(v) = params.volume_level { + body.insert("volume_level".into(), json!(v)); + } + if let Some(v) = params.value { + body.insert("value".into(), json!(v)); + } + if let Some(v) = ¶ms.option { + body.insert("option".into(), json!(v)); + } + + let resp = client + .post(format!("{base}/api/services/{domain}/{service}")) + .bearer_auth(token) + .json(&serde_json::Value::Object(body)) + .send() + .await + .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; + + let status = resp.status(); + if status.as_u16() == 401 || status.as_u16() == 403 { + return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); + } + if status.as_u16() == 404 { + return Err(ProbeFailure::not_found("实体或服务不存在(设备可能已被移除)")); + } + if status.as_u16() == 400 { + // HA 对参数不支持会返回可读的中文/英文 message,原样带给用户最有用 + let text = resp.text().await.unwrap_or_default(); + return Err(ProbeFailure::bad_request(extract_message(&text))); + } + if !status.is_success() { + return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); + } + Ok(resp + .json::>() + .await + .unwrap_or_default() + .into_iter() + .map(to_summary) + .collect()) +} + +/// 取单个实体状态(控制后的校正用)。 +/// +/// 只在校正窗口到期时才调用 —— 它不是常规路径,所以单独一个命令而不是重拉全量。 +pub async fn fetch_entity( + base: &str, + token: &str, + insecure: bool, + kind: EndpointKind, + entity_id: &str, +) -> Result { + let client = build_client(insecure, request_timeout(kind)).map_err(ProbeFailure::network)?; + let resp = client + .get(format!("{base}/api/states/{entity_id}")) + .bearer_auth(token) + .send() + .await + .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; + + let status = resp.status(); + if status.as_u16() == 401 || status.as_u16() == 403 { + return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); + } + if status.as_u16() == 404 { + return Err(ProbeFailure::not_found("该实体已不存在")); + } + if !status.is_success() { + return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); + } + let raw = resp + .json::() + .await + .map_err(|e| ProbeFailure::server(format!("实体响应解析失败:{e}")))?; + Ok(to_summary(raw)) +} + +/// 从 HA 的错误响应里抠出可读的 `message`(响应不是 JSON 时退化为原文截断)。 +fn extract_message(text: &str) -> String { + let parsed = serde_json::from_str::(text) + .ok() + .and_then(|v| v.get("message").and_then(|m| m.as_str()).map(|s| s.to_string())); + match parsed { + Some(m) if !m.is_empty() => m, + _ => { + let short: String = text.chars().take(200).collect(); + if short.is_empty() { + "该服务不接受这些参数".to_string() + } else { + short + } + } + } +} diff --git a/src-tauri/src/smarthome/commands.rs b/src-tauri/src/smarthome/commands.rs new file mode 100644 index 0000000..37b3859 --- /dev/null +++ b/src-tauri/src/smarthome/commands.rs @@ -0,0 +1,734 @@ +//! 智能家居模块的 Tauri 命令。 +//! +//! 约定(同项目其它模块):命令名以模块前缀开头,错误用 `Result<_, String>`; +//! **没有任何命令会向前端返回明文令牌** —— 只有 `tokenMasked` 与 `hasToken`。 + +use std::time::{SystemTime, UNIX_EPOCH}; + +use tauri::{AppHandle, State}; + +use super::client; +use super::types::{ + EndpointMode, EndpointProbe, EntityListResult, EntitySummary, HaApiError, HaConnection, + HaConnectionInput, HaSaveConnectionResult, HaSettingsView, HaUiSettings, LinkInfo, + RegistryResult, Rule, RuleListResult, RulesFile, ServiceCallResult, ServiceParams, WsStatus, +}; +use super::{automation, registry, HaManager, InstanceMeta}; + +/// 读取模块设置视图(连接列表 + 偏好;令牌只有掩码)。 +#[tauri::command] +#[specta::specta] +pub fn smarthome_get_settings(state: State<'_, HaManager>) -> Result { + Ok(state.settings_view()) +} + +/// 新建或更新一条连接(令牌**不在**此命令里,见 `smarthome_set_token`)。 +/// +/// 地址可能刚被改动,已建立的实时连接仍粘在旧端点上 → 重连一次(P4)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_save_connection( + app: AppHandle, + state: State<'_, HaManager>, + input: HaConnectionInput, +) -> Result { + let name = input.name.trim().to_string(); + if name.is_empty() { + return Err("请填写名称".to_string()); + } + // 局域网默认补 http(HA 的默认端口 8123 无 TLS);反代默认补 https + let local_url = client::normalize_url(&input.local_url, false); + let remote_url = client::normalize_url(&input.remote_url, true); + if local_url.is_empty() && remote_url.is_empty() { + return Err("请至少填写一个地址(局域网或反代)".to_string()); + } + // 保存时就校验地址:等到请求时才失败,错误信息已经离用户输入很远了 + client::validate_url(&local_url, "局域网地址")?; + client::validate_url(&remote_url, "反代地址")?; + + let mut settings = state.load_settings(); + let mut conn = HaConnection { + id: input.id.trim().to_string(), + name, + local_url, + remote_url, + endpoint_mode: input.endpoint_mode, + insecure: input.insecure, + ..Default::default() + }; + + // 只配了一个地址时把策略收敛到对应模式:不必让用户理解 auto 的含义 + if conn.endpoint_mode == EndpointMode::Auto { + match (conn.local_url.is_empty(), conn.remote_url.is_empty()) { + (true, false) => conn.endpoint_mode = EndpointMode::Remote, + (false, true) => conn.endpoint_mode = EndpointMode::Local, + _ => {} + } + } + // 强制模式与地址必须自洽:否则要到"检测链路"时才报"未配置该地址",错误离用户输入太远 + if conn.endpoint_mode == EndpointMode::Local && conn.local_url.is_empty() { + return Err("端点策略选了「仅局域网」,但没填局域网地址".to_string()); + } + if conn.endpoint_mode == EndpointMode::Remote && conn.remote_url.is_empty() { + return Err("端点策略选了「仅反代」,但没填反代地址".to_string()); + } + + if conn.id.is_empty() { + conn.id = new_conn_id(); + } + + // 运行期信息(上次成功 / HA 版本 / 实例名)不随编辑清空 + if let Some(existing) = settings.connection(&conn.id) { + conn.last_ok_url = existing.last_ok_url.clone(); + conn.last_ok_at = existing.last_ok_at; + conn.ha_version = existing.ha_version.clone(); + conn.location_name = existing.location_name.clone(); + } + + let id = conn.id.clone(); + let is_new = !settings.connections.iter().any(|c| c.id == id); + match settings.connections.iter_mut().find(|c| c.id == id) { + Some(slot) => *slot = conn, + None => settings.connections.push(conn), + } + if settings.active_id.is_empty() { + settings.active_id = id.clone(); + } + // 首次保存连接时**默认打开实时连接**:按设备 / 按房间浏览、状态实时更新、 + // 本地规则触发都依赖 WebSocket,默认关闭会让第一次打开模块的人看到一个 + // "什么都点不了"的设备页。用户仍可在设置页显式关掉。 + if is_new && !settings.realtime.enabled { + settings.realtime.enabled = true; + settings.realtime.last_connected_at = chrono::Utc::now().timestamp(); + } + state.save_settings(settings)?; + // 地址可能刚被改动:缓存里的端点可能已经不适用了 + state.clear_endpoint_cache(); + restart_ws(&app, &state).await; + Ok(HaSaveConnectionResult { + id, + settings: state.settings_view(), + }) +} + +/// 写入长期访问令牌(进系统凭据管理器,**不落 settings.json**)。 +/// +/// 令牌换了,已经建立的实时连接用的还是旧令牌 → 重连一次。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_set_token( + app: AppHandle, + state: State<'_, HaManager>, + conn_id: String, + token: String, +) -> Result { + if state.load_settings().connection(&conn_id).is_none() { + return Err("该连接不存在".to_string()); + } + let t = token.trim(); + if t.is_empty() { + return Err("请填写访问令牌".to_string()); + } + state.set_token(&conn_id, t)?; + restart_ws(&app, &state).await; + Ok(state.settings_view()) +} + +/// 清除令牌(连接本身保留)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_clear_token( + app: AppHandle, + state: State<'_, HaManager>, + conn_id: String, +) -> Result { + state.clear_token(&conn_id)?; + restart_ws(&app, &state).await; + Ok(state.settings_view()) +} + +/// 删除一条连接(连带清除它的令牌)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_delete_connection( + app: AppHandle, + state: State<'_, HaManager>, + conn_id: String, +) -> Result { + let mut settings = state.load_settings(); + settings.connections.retain(|c| c.id != conn_id); + if settings.active_id == conn_id { + settings.active_id = settings + .connections + .first() + .map(|c| c.id.clone()) + .unwrap_or_default(); + } + state.save_settings(settings)?; + // 凭据库里那条令牌也要清掉:连接都删了,留着它是纯粹的残留 + if let Err(e) = state.clear_token(&conn_id) { + crate::logger::log_warn("smarthome", &format!("删除连接时清理令牌失败:{e}")); + } + state.clear_endpoint_cache(); + state.clear_entities_cache(); + state.clear_registry_cache(); + restart_ws(&app, &state).await; + Ok(state.settings_view()) +} + +/// 切换激活连接。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_activate_connection( + app: AppHandle, + state: State<'_, HaManager>, + conn_id: String, +) -> Result { + let mut settings = state.load_settings(); + if settings.connection(&conn_id).is_none() { + return Err("该连接不存在".to_string()); + } + settings.active_id = conn_id; + state.save_settings(settings)?; + state.clear_endpoint_cache(); + // 房间 / 实体都属于"上一条连接",切连接必须一并作废 + state.clear_entities_cache(); + state.clear_registry_cache(); + restart_ws(&app, &state).await; + Ok(state.settings_view()) +} + +/// 修改端点选择策略(auto / local / remote)。 +/// +/// 策略变了,实时连接也应当按新策略重新选端点 → 重连一次。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_set_endpoint_mode( + app: AppHandle, + state: State<'_, HaManager>, + conn_id: String, + mode: EndpointMode, +) -> Result { + let mut settings = state.load_settings(); + let conn = settings + .connections + .iter_mut() + .find(|c| c.id == conn_id) + .ok_or_else(|| "该连接不存在".to_string())?; + conn.endpoint_mode = mode; + state.save_settings(settings)?; + state.clear_endpoint_cache(); + restart_ws(&app, &state).await; + Ok(state.settings_view()) +} + +/// 测试连接:**逐个地址**探测,每个地址各给一条结果。 +/// +/// `token` 留空时回落到该连接已存的令牌(编辑连接时不必重输)。 +/// 草案也能直接测(不必先保存)——`input.id` 为空只是没有回落令牌可用。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_test_connection( + state: State<'_, HaManager>, + input: HaConnectionInput, + token: String, +) -> Result, String> { + let stored = if input.id.trim().is_empty() { + String::new() + } else { + state.token(input.id.trim()) + }; + let token = if token.trim().is_empty() { + stored + } else { + token.trim().to_string() + }; + if token.is_empty() { + return Err("请填写访问令牌".to_string()); + } + + let local_url = client::normalize_url(&input.local_url, false); + let remote_url = client::normalize_url(&input.remote_url, true); + if local_url.is_empty() && remote_url.is_empty() { + return Err("请至少填写一个地址(局域网或反代)".to_string()); + } + client::validate_url(&local_url, "局域网地址")?; + client::validate_url(&remote_url, "反代地址")?; + + let probes = client::probe_all(&local_url, &remote_url, &token, input.insecure).await; + + // 测的是已保存的连接,且有一条成功 → 记下"上次成功"(含版本 / 实例名 / 温度单位) + let conn_id = input.id.trim(); + if !conn_id.is_empty() { + if let Some(ok) = probes.iter().find(|p| p.ok) { + let meta = InstanceMeta { + ha_version: ok.ha_version.clone(), + location_name: ok.location_name.clone(), + temperature_unit: ok.temperature_unit.clone(), + }; + if let Err(e) = state.mark_ok(conn_id, &ok.url, &meta) { + crate::logger::log_warn("smarthome", &format!("记录上次成功失败:{e}")); + } + } + } + Ok(probes) +} + +/// 检测当前链路:按端点策略**强制新探测**一次,返回实际使用的地址与耗时。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_check_link( + state: State<'_, HaManager>, + conn_id: String, +) -> Result { + let conn = state + .load_settings() + .connection(&conn_id) + .cloned() + .ok_or_else(|| "该连接不存在".to_string())?; + match state.resolve_fresh(&conn).await { + Ok((url, kind, latency_ms)) => { + // 顺带取一次实例信息(版本 / 名称 / 温度单位):只有「检测链路」这个显式动作需要它, + // 取到就记进设置,设置页与设备页因此不必再单独请求 /api/config。 + let meta = { + let token = state.token(&conn_id); + match client::fetch_meta(&url, &token, conn.insecure, kind).await { + Ok((version, location, unit)) => InstanceMeta { + ha_version: version, + location_name: location, + temperature_unit: unit, + }, + Err(e) => { + crate::logger::log_warn( + "smarthome", + &format!("读取 HA 实例信息失败(不影响链路判定):{}", e.message), + ); + InstanceMeta::default() + } + } + }; + if let Err(e) = state.mark_ok(&conn_id, &url, &meta) { + crate::logger::log_warn("smarthome", &format!("记录上次成功失败:{e}")); + } + Ok(LinkInfo { + url: Some(url), + kind: Some(kind), + ok: true, + latency_ms, + error: None, + error_kind: None, + }) + } + Err(e) => Ok(LinkInfo { + url: None, + kind: None, + ok: false, + latency_ms: 0, + error: Some(e.message), + error_kind: Some(e.kind.to_string()), + }), + } +} + +/// 拉取实体列表(精简视图)。 +/// +/// `force = false` 且内存缓存未过期(60s)时直接返回缓存 —— 在反代链路上, +/// 每次切回设备页都重新拉几百 KB 是明显的浪费(§5.2)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_list_entities( + state: State<'_, HaManager>, + conn_id: String, + force: bool, +) -> Result { + let conn = state + .load_settings() + .connection(&conn_id) + .cloned() + .ok_or_else(|| HaApiError::new("config", "该连接不存在"))?; + + if !force { + if let Some((entities, fetched_at)) = state.cached_entities(&conn_id) { + return Ok(EntityListResult { + entities, + fetched_at, + from_cache: true, + }); + } + } + + let (url, kind, _latency) = state.resolve(&conn).await.map_err(to_api_error)?; + let token = state.token(&conn_id); + + // 首次进入还不知道实例信息?顺带取一次 `/api/config`。 + // 温度单位必须从实例读(`°F` 的实例上写死 `°C` 会显示成"77°C"), + // 而它只在"还不知道"时才需要这一跳;之后 `ha_version` 有了就不再请求。 + if conn.ha_version.is_empty() { + match client::fetch_meta(&url, &token, conn.insecure, kind).await { + Ok((version, location, unit)) => { + let meta = InstanceMeta { + ha_version: version, + location_name: location, + temperature_unit: unit, + }; + if let Err(e) = state.mark_ok(&conn_id, &url, &meta) { + crate::logger::log_warn("smarthome", &format!("记录实例信息失败:{e}")); + } + } + Err(e) => crate::logger::log_warn( + "smarthome", + &format!("读取实例信息失败(不影响设备列表):{}", e.message), + ), + } + } + + match client::fetch_entities(&url, &token, conn.insecure, kind).await { + Ok(entities) => { + let fetched_at = chrono::Utc::now().timestamp(); + state.store_entities(&conn_id, entities.clone()); + if let Err(e) = state.mark_ok(&conn_id, &url, &InstanceMeta::default()) { + crate::logger::log_warn("smarthome", &format!("记录上次成功失败:{e}")); + } + Ok(EntityListResult { + entities, + fetched_at, + from_cache: false, + }) + } + Err(f) => { + // 端点可能已经不可用(出门 / 断网 / 隧道挂了):清掉,让下次请求重新探测 + state.clear_endpoint_cache(); + if f.fatal_auth { + // 令牌失效时旧数据不再可信,留着会让下次把它误当成"还能用" + state.clear_entities_cache(); + } + Err(HaApiError::new(f.kind, f.message)) + } + } +} + +/// 保存界面偏好(自动刷新间隔 / 收藏等)。 +/// +/// 整体覆盖写入:偏好字段少且同屏修改,没必要为每个开关单开一条命令 +/// (多命令各自的字段同步反倒容易漏)。 +/// +/// 注意:**实时推送开关不在 `ui` 里**(它在 `settings.realtime`), +/// 因此这里不碰实时连接;收藏 / 自动刷新这类改动不该引起重连。 +#[tauri::command] +#[specta::specta] +pub fn smarthome_save_ui_settings( + state: State<'_, HaManager>, + ui: HaUiSettings, +) -> Result { + let mut settings = state.load_settings(); + settings.ui = ui; + // heal 里会把非法的 autoRefreshSec 收敛回 0 + state.save_settings(settings)?; + Ok(state.settings_view()) +} + +/// 开关实时推送(WebSocket)。 +/// +/// 打开 = 建立 WS(设备状态不再依赖手动刷新);关闭 = 断开。 +/// **本地规则也依赖它**:只要规则总开关开着,关掉推送 Rust 侧仍会保持连接 +/// (见 `HaManager::sync_ws`)—— 规则没连接永远不会触发。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_set_realtime_enabled( + app: AppHandle, + state: State<'_, HaManager>, + enabled: bool, +) -> Result { + let mut settings = state.load_settings(); + if settings.realtime.enabled == enabled { + return Ok(state.settings_view()); + } + settings.realtime.enabled = enabled; + if enabled { + settings.realtime.last_connected_at = chrono::Utc::now().timestamp(); + } + state.save_settings(settings)?; + // 用 `sync_ws` 而不是 `restart_ws`:关掉推送但本地规则总开关还开着时, + // 连接本来就该保留 —— `sync_ws` 会据此保持不动,不会做无谓的重连。 + state.sync_ws(&app).await; + Ok(state.settings_view()) +} + +/// `client::ResolveFailure` → 命令层错误(保留分类)。 +fn to_api_error(e: client::ResolveFailure) -> HaApiError { + HaApiError::new(e.kind, e.message) +} + +/// 调用设备服务(控制)。 +/// +/// 前端流程(§5.3):乐观更新 → 本命令 → **若响应带回新状态就直接采用**(省一次往返), +/// 否则在分级窗口后调 `smarthome_get_entity` 校正。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_call_service( + state: State<'_, HaManager>, + conn_id: String, + domain: String, + service: String, + entity_id: String, + params: ServiceParams, +) -> Result { + let conn = state + .load_settings() + .connection(&conn_id) + .cloned() + .ok_or_else(|| HaApiError::new("config", "该连接不存在"))?; + let domain = domain.trim().to_string(); + let service = service.trim().to_string(); + let entity_id = entity_id.trim().to_string(); + if domain.is_empty() || service.is_empty() || entity_id.is_empty() { + return Err(HaApiError::new( + "badRequest", + "domain / service / entity_id 都不能为空", + )); + } + + let (url, kind, _latency) = state.resolve(&conn).await.map_err(to_api_error)?; + let token = state.token(&conn_id); + match client::call_service( + &url, &token, conn.insecure, kind, &domain, &service, &entity_id, ¶ms, + ) + .await + { + Ok(entities) => { + // 缓存要与 UI 保持一致:带回新状态就并进去,没带回就整份作废 + // (否则"开灯 → 切页 → 切回来"会看到控制前的旧状态) + if entities.is_empty() { + state.clear_entities_cache(); + } else { + state.merge_entities(&conn_id, &entities); + } + if let Err(e) = state.mark_ok(&conn_id, &url, &InstanceMeta::default()) { + crate::logger::log_warn("smarthome", &format!("记录上次成功失败:{e}")); + } + Ok(ServiceCallResult { entities }) + } + Err(f) => { + state.clear_endpoint_cache(); + if f.fatal_auth { + state.clear_entities_cache(); + } + Err(HaApiError::new(f.kind, f.message)) + } + } +} + +/// 取单个实体状态(控制后的校正用,不是常规路径)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_get_entity( + state: State<'_, HaManager>, + conn_id: String, + entity_id: String, +) -> Result { + let conn = state + .load_settings() + .connection(&conn_id) + .cloned() + .ok_or_else(|| HaApiError::new("config", "该连接不存在"))?; + let (url, kind, _latency) = state.resolve(&conn).await.map_err(to_api_error)?; + let token = state.token(&conn_id); + match client::fetch_entity(&url, &token, conn.insecure, kind, entity_id.trim()).await { + Ok(e) => { + state.merge_entities(&conn_id, std::slice::from_ref(&e)); + Ok(e) + } + Err(f) => { + if !f.fatal_auth { + state.clear_endpoint_cache(); + } + Err(HaApiError::new(f.kind, f.message)) + } + } +} + +/// 新建连接 id(不依赖 uuid crate,同 music 的 `new_conn_id` 做法)。 +fn new_conn_id() -> String { + let n = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_nanos()) + .unwrap_or(0); + format!("h{n:x}") +} + +/// 新建规则 id。 +fn new_rule_id() -> String { + let n = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_nanos()) + .unwrap_or(0); + format!("r{n:x}") +} + +/// 端点 / 令牌 / 连接发生变化后:先停当前的实时连接,再按需重连。 +/// +/// 必须"先停再起"而不是直接 `sync_ws`:`sync_ws` 对**同一个**连接是幂等的(不动它), +/// 而这里恰恰要重连 —— 换了令牌或换了链路却继续粘在旧连接上是最坏的结果 +/// (UI 显示着新配置,实际走的是老链路)。 +async fn restart_ws(app: &AppHandle, state: &State<'_, HaManager>) { + state.stop_ws(); + state.sync_ws(app).await; +} + +/// 落盘规则文件并更新内存。 +/// +/// 同步磁盘 IO 丢到阻塞线程池(编辑器模块的教训:在异步线程里直接读写文件 +/// 会占住 IPC 线程)。 +async fn persist_rules(state: &State<'_, HaManager>, file: RulesFile) -> Result<(), String> { + let path = state.rules_path(); + let snapshot = file.clone(); + tauri::async_runtime::spawn_blocking(move || automation::save(&path, &snapshot)) + .await + .map_err(|e| format!("保存规则失败:{e}"))??; + state.set_rules_memory(file); + Ok(()) +} + +// ============================== P4:实时连接命令 ============================== + +/// 启动实时连接(显式动作)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_ws_start( + app: AppHandle, + state: State<'_, HaManager>, + conn_id: String, +) -> Result { + let conn = state + .load_settings() + .connection(&conn_id) + .cloned() + .ok_or_else(|| "该连接不存在".to_string())?; + state.start_ws(&app, &conn).await +} + +/// 停止实时连接(**不改持久化开关**:设置页的开关走 `smarthome_set_realtime_enabled`)。 +#[tauri::command] +#[specta::specta] +pub fn smarthome_ws_stop(state: State<'_, HaManager>) -> WsStatus { + state.stop_ws(); + state.ws_status() +} + +/// 当前实时连接状态(诊断用)。 +#[tauri::command] +#[specta::specta] +pub fn smarthome_ws_status(state: State<'_, HaManager>) -> WsStatus { + state.ws_status() +} + +// ============================== P4:注册表(房间分组) ============================== + +/// 拉取区域 / 设备 / 实体注册表,返回 `entity_id → area_id`(三级回退已算好)。 +/// +/// **需要实时连接**:注册表只能通过 WebSocket 查(plan §0.4),因此这里显式依赖 +/// `smarthome_ws_start` 已经连上;没连上就给出可操作的错误文案(不是笼统的"失败")。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_list_registry( + state: State<'_, HaManager>, + conn_id: String, + force: bool, +) -> Result { + if let Some(cached) = state.cached_registry(&conn_id, force) { + return Ok(cached); + } + let Some(handle) = state.ws_handle() else { + return Err(HaApiError::new( + "ws", + "房间分组需要实时连接:请在设置页开启「实时推送」", + )); + }; + if handle.conn_id != conn_id { + return Err(HaApiError::new( + "ws", + "实时连接属于另一条连接,请先切换回该连接", + )); + } + let registry = registry::fetch(&handle) + .await + .map_err(|e| HaApiError::new("ws", e))?; + state.store_registry(&conn_id, registry.clone()); + Ok(registry) +} + +// ============================== P4:本地规则命令 ============================== + +/// 规则列表(含总开关与最近运行记录)。 +#[tauri::command] +#[specta::specta] +pub fn smarthome_list_rules(state: State<'_, HaManager>) -> RuleListResult { + state.rules_result() +} + +/// 新建或更新一条规则。 +/// +/// **动作的合法性只在 Rust 侧判定一次**(`automation::validate`):前端可以少校验, +/// 但"能不能真的执行"这套规则必须只有一份。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_save_rule( + app: AppHandle, + state: State<'_, HaManager>, + rule: Rule, +) -> Result { + let mut rule = rule; + automation::validate(&rule)?; + if rule.id.trim().is_empty() { + rule.id = new_rule_id(); + } else { + rule.id = rule.id.trim().to_string(); + } + + let mut file = state.rules_file(); + // 编辑既有规则时保留运行统计(前端提交的是"规则定义",统计属于运行期数据) + if let Some(existing) = file.rules.iter().find(|r| r.id == rule.id) { + rule.last_fired_at = existing.last_fired_at; + rule.fire_count = existing.fire_count; + rule.last_error = existing.last_error.clone(); + } + match file.rules.iter_mut().find(|r| r.id == rule.id) { + Some(slot) => *slot = rule, + None => file.rules.push(rule), + } + persist_rules(&state, file).await?; + // 规则总开关开着就需要实时连接(事件驱动),幂等对齐一次 + state.sync_ws(&app).await; + Ok(state.rules_result()) +} + +/// 删除一条规则。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_delete_rule( + app: AppHandle, + state: State<'_, HaManager>, + rule_id: String, +) -> Result { + let mut file = state.rules_file(); + file.rules.retain(|r| r.id != rule_id); + persist_rules(&state, file).await?; + state.sync_ws(&app).await; + Ok(state.rules_result()) +} + +/// 规则总开关(关掉后所有规则都不求值,规则本身保留)。 +#[tauri::command] +#[specta::specta] +pub async fn smarthome_set_rules_enabled( + app: AppHandle, + state: State<'_, HaManager>, + enabled: bool, +) -> Result { + let mut file = state.rules_file(); + file.enabled = enabled; + persist_rules(&state, file).await?; + // 打开总开关意味着"现在就要开始跑规则":它依赖 WS,因此强制对齐(必要时建连) + state.sync_ws(&app).await; + Ok(state.rules_result()) +} diff --git a/src-tauri/src/smarthome/mod.rs b/src-tauri/src/smarthome/mod.rs new file mode 100644 index 0000000..50e30de --- /dev/null +++ b/src-tauri/src/smarthome/mod.rs @@ -0,0 +1,582 @@ +//! 智能家居模块(Home Assistant):状态容器、设置持久化、会话内端点缓存。 +//! +//! 分工:`types` 数据模型(specta 导出)· `client` HTTP 客户端与端点选择 · `commands` Tauri 命令。 +//! +//! 目录布局(`{app_data_dir}/smarthome/`): +//! - `settings.json` 模块设置(版本号 + 自愈) +//! +//! 凭据:长期访问令牌存**系统凭据管理器**,键 `smarthome-token-`, +//! **不落 settings.json**(见 `crate::secrets` 的模块注释)。 + +use std::collections::VecDeque; +use std::path::{Path, PathBuf}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use tauri::AppHandle; + +use types::{ + EndpointKind, EntitySummary, HaConnection, HaConnectionView, HaSettings, HaSettingsView, + RegistryResult, RuleListResult, RuleRecord, RulesFile, WsStatus, SECRET_PREFIX, +}; + +pub mod automation; +pub mod client; +pub mod commands; +pub mod registry; +pub mod types; +pub mod ws; + +// 命令在 lib.rs 里按模块路径导入(`smarthome::smarthome_xxx`),因此在这里 re-export +pub use commands::{ + smarthome_activate_connection, smarthome_call_service, smarthome_check_link, + smarthome_clear_token, smarthome_delete_connection, smarthome_delete_rule, + smarthome_get_entity, smarthome_get_settings, smarthome_list_entities, smarthome_list_registry, + smarthome_list_rules, smarthome_save_connection, smarthome_save_rule, + smarthome_save_ui_settings, smarthome_set_endpoint_mode, smarthome_set_realtime_enabled, + smarthome_set_rules_enabled, smarthome_set_token, smarthome_test_connection, + smarthome_ws_start, smarthome_ws_status, smarthome_ws_stop, +}; + +/// 会话内端点缓存 TTL。 +/// +/// - 缓存在**局域网**上给 60s:短一点,好尽快发现"出门了"(失败也会立即重探)。 +/// - 缓存在**反代**上给 300s:此时唯一的提升空间是"回家切回局域网", +/// 为它每分钟白花 900ms 去探局域网不值得。 +const CACHE_TTL_LOCAL: Duration = Duration::from_secs(60); +const CACHE_TTL_REMOTE: Duration = Duration::from_secs(300); + +/// 会话内端点缓存条目(**不落盘**:它表达的是"这次跑在哪个网络环境", +/// 下次启动的网络环境可能完全不同,落盘只会让人先走错一次)。 +struct CachedEndpoint { + conn_id: String, + url: String, + kind: EndpointKind, + latency_ms: u64, + at: Instant, +} + +/// 实体列表内存缓存(**不落盘**)。 +/// +/// 理由同 §3.7-c:智能家居里"显示灯已关、实际还亮着"的误导比"多等一秒"糟得多, +/// 所以不把可能过期的状态持久化。这里只是省掉"切走再切回设备页就重拉一次全量" +/// 的那次请求(在反代链路上那是几百 KB)。 +struct EntityCache { + conn_id: String, + entities: Vec, + fetched_at: i64, +} + +/// 实体缓存 TTL(秒)—— 约束的是"多久之内不重新拉全量"。 +const ENTITY_CACHE_TTL_SECS: i64 = 60; + +/// 注册表缓存 TTL(秒)。 +/// +/// 房间归属变化极少(用户在 HA 里改名 / 挪设备才会变),给 5 分钟足够; +/// 而且每次查注册表在反代上是 3 个来回(约 2s),不该每次进设备页都查一遍。 +const REGISTRY_CACHE_TTL_SECS: i64 = 300; + +/// 一次成功通信里学到的实例信息(版本 / 实例名 / 温度单位)。 +/// +/// 数据请求(拉实体、调服务)只带空的那份 —— 它们不请求 `/api/config`, +/// 因此 `mark_ok` 里**空值不覆盖旧值**,免得把已经记住的元信息抹掉。 +#[derive(Debug, Default, Clone)] +pub struct InstanceMeta { + pub ha_version: String, + pub location_name: String, + pub temperature_unit: String, +} + +/// 智能家居模块管理器(Tauri State)。 +pub struct HaManager { + /// 模块目录 `{app_data_dir}/smarthome` + module_dir: PathBuf, + /// 设置(内存为真相;写盘即同步) + settings: Mutex, + /// 端点选择缓存 + endpoint_cache: Mutex>, + /// 实体列表缓存 + entity_cache: Mutex>, + // ---------- P4 ---------- + /// 运行中的 WebSocket 连接(生命周期归属应用,Tab 切走不关) + ws: Mutex>, + /// 最近一次 WS 启动失败原因(没有运行中的连接时用于诊断) + ws_error: Mutex, + /// 本地规则(内存为真相;与 WS 任务共享同一份 Arc) + rules: Arc>, + /// 规则运行记录(内存环形,最多 `automation::MAX_RECORDS` 条) + records: Arc>>, + /// 规则突发护栏用的最近触发时刻(与 WS 任务共享) + recent: Arc>>, + /// 注册表缓存(房间分组,不落盘)。**带 connId**:房间归属是每条连接各自的, + /// 切了实例还返回上一实例的房间,用户会看到"房间名全对不上、筛选后一片空白"。 + registry_cache: Mutex>, +} + +impl HaManager { + pub fn new(app_data_dir: PathBuf) -> Self { + let module_dir = app_data_dir.join("smarthome"); + if let Err(e) = std::fs::create_dir_all(&module_dir) { + crate::logger::log_warn("smarthome", &format!("创建模块目录失败:{e}")); + } + let mut settings: HaSettings = std::fs::read_to_string(module_dir.join("settings.json")) + .ok() + .and_then(|t| serde_json::from_str(&t).ok()) + .unwrap_or_default(); + if settings.heal() { + // 首次启动(version = 0)也走这里:落一份带版本号的默认设置 + let _ = write_settings_file(&module_dir, &settings); + } + // 规则文件:**启动阶段不建文件**(还没人用过本地规则时不必产生空文件) + let rules = automation::load(&module_dir.join("automations.json")); + Self { + module_dir, + settings: Mutex::new(settings), + endpoint_cache: Mutex::new(None), + entity_cache: Mutex::new(None), + ws: Mutex::new(None), + ws_error: Mutex::new(String::new()), + rules: Arc::new(Mutex::new(rules)), + records: Arc::new(Mutex::new(VecDeque::new())), + recent: Arc::new(Mutex::new(VecDeque::new())), + registry_cache: Mutex::new(None), + } + } + + // ---------- 设置 ---------- + + pub fn load_settings(&self) -> HaSettings { + match self.settings.lock() { + Ok(s) => s.clone(), + Err(e) => { + crate::logger::log_error("smarthome", &format!("设置锁中毒:{e}")); + HaSettings::default() + } + } + } + + pub fn save_settings(&self, mut next: HaSettings) -> Result<(), String> { + next.heal(); + write_settings_file(&self.module_dir, &next)?; + if let Ok(mut s) = self.settings.lock() { + *s = next; + } + Ok(()) + } + + // ---------- 令牌(系统凭据管理器) ---------- + + fn token_key(conn_id: &str) -> String { + format!("{SECRET_PREFIX}{conn_id}") + } + + /// 读取明文令牌,失败/未配置一律退化为空串(调用方无需区分两者)。 + pub fn token(&self, conn_id: &str) -> String { + crate::secrets::read_or_empty(&Self::token_key(conn_id)) + } + + pub fn set_token(&self, conn_id: &str, token: &str) -> Result<(), String> { + crate::secrets::secret_write(&Self::token_key(conn_id), token) + } + + pub fn clear_token(&self, conn_id: &str) -> Result<(), String> { + crate::secrets::secret_delete(&Self::token_key(conn_id)) + } + + // ---------- 视图 ---------- + + pub fn connection_view(&self, conn: &HaConnection) -> HaConnectionView { + let token = self.token(&conn.id); + let cached = self.cached_endpoint(&conn.id); + HaConnectionView { + id: conn.id.clone(), + name: conn.name.clone(), + local_url: conn.local_url.clone(), + remote_url: conn.remote_url.clone(), + endpoint_mode: conn.endpoint_mode, + insecure: conn.insecure, + has_token: !token.is_empty(), + token_masked: crate::secrets::mask(&token), + last_ok_url: conn.last_ok_url.clone(), + last_ok_at: conn.last_ok_at, + ha_version: conn.ha_version.clone(), + location_name: conn.location_name.clone(), + temperature_unit: conn.temperature_unit.clone(), + endpoint_url: cached.as_ref().map(|c| c.0.clone()), + endpoint_kind: cached.as_ref().map(|c| c.1), + endpoint_latency_ms: cached.as_ref().map(|c| c.2), + } + } + + pub fn settings_view(&self) -> HaSettingsView { + let s = self.load_settings(); + HaSettingsView { + version: s.version, + active_id: s.active_id.clone(), + connections: s + .connections + .iter() + .map(|c| self.connection_view(c)) + .collect(), + ui: s.ui.clone(), + realtime: s.realtime.clone(), + } + } + + // ---------- 端点缓存 ---------- + + pub fn cached_endpoint(&self, conn_id: &str) -> Option<(String, EndpointKind, u64)> { + let guard = self.endpoint_cache.lock().ok()?; + let c = guard.as_ref()?; + if c.conn_id != conn_id { + return None; + } + let ttl = if c.kind == EndpointKind::Local { + CACHE_TTL_LOCAL + } else { + CACHE_TTL_REMOTE + }; + if c.at.elapsed() > ttl { + return None; + } + Some((c.url.clone(), c.kind, c.latency_ms)) + } + + fn store_endpoint(&self, conn_id: &str, url: &str, kind: EndpointKind, latency_ms: u64) { + if let Ok(mut c) = self.endpoint_cache.lock() { + *c = Some(CachedEndpoint { + conn_id: conn_id.to_string(), + url: url.to_string(), + kind, + latency_ms, + at: Instant::now(), + }); + } + } + + /// 失效端点缓存。触发点:地址被改动、请求失败、用户手动重探。 + pub fn clear_endpoint_cache(&self) { + if let Ok(mut c) = self.endpoint_cache.lock() { + *c = None; + } + } + + // ---------- 实体缓存 ---------- + + /// 读取**未过期**的实体缓存(过期视为未命中)。 + pub fn cached_entities(&self, conn_id: &str) -> Option<(Vec, i64)> { + let guard = self.entity_cache.lock().ok()?; + let c = guard.as_ref()?; + if c.conn_id != conn_id { + return None; + } + if chrono::Utc::now().timestamp() - c.fetched_at > ENTITY_CACHE_TTL_SECS { + return None; + } + Some((c.entities.clone(), c.fetched_at)) + } + + pub fn store_entities(&self, conn_id: &str, entities: Vec) { + if let Ok(mut c) = self.entity_cache.lock() { + *c = Some(EntityCache { + conn_id: conn_id.to_string(), + entities, + fetched_at: chrono::Utc::now().timestamp(), + }); + } + } + + /// 清空实体缓存。触发点:令牌失效(旧数据不再可信)、删除连接。 + pub fn clear_entities_cache(&self) { + if let Ok(mut c) = self.entity_cache.lock() { + *c = None; + } + } + + /// 把控制命令带回的新状态并进缓存。 + /// + /// 必须做,否则会出现这种误导:开灯 → 切到设置页 → 切回设备页(60s 内命中缓存) + /// → 又显示"灯是关的"。响应没带回状态时(部分云端集成)调用方应改为清缓存。 + pub fn merge_entities(&self, conn_id: &str, changed: &[EntitySummary]) { + if changed.is_empty() { + return; + } + let Ok(mut guard) = self.entity_cache.lock() else { + return; + }; + let Some(cache) = guard.as_mut() else { + return; + }; + if cache.conn_id != conn_id { + return; + } + for e in changed { + match cache.entities.iter_mut().find(|x| x.entity_id == e.entity_id) { + Some(slot) => *slot = e.clone(), + None => cache.entities.push(e.clone()), + } + } + } + + /// 解析当前端点(命中会话缓存则不再探测)。 + /// + /// 数据请求走这里;**失败时必须调用 `clear_endpoint_cache()`**, + /// 否则会一直粘在一个已经不可用的端点上。 + pub async fn resolve( + &self, + conn: &HaConnection, + ) -> Result<(String, EndpointKind, u64), client::ResolveFailure> { + if let Some(hit) = self.cached_endpoint(&conn.id) { + return Ok(hit); + } + self.resolve_fresh(conn).await + } + + /// 强制重新探测(「检测链路」按钮、以及缓存未命中时)。 + pub async fn resolve_fresh( + &self, + conn: &HaConnection, + ) -> Result<(String, EndpointKind, u64), client::ResolveFailure> { + let token = self.token(&conn.id); + if token.is_empty() { + return Err(client::ResolveFailure { + kind: "auth", + message: "尚未配置访问令牌".to_string(), + }); + } + let r = client::resolve_endpoint(conn, &token).await?; + self.store_endpoint(&conn.id, &r.url, r.kind, r.latency_ms); + Ok((r.url, r.kind, r.latency_ms)) + } + + /// 记录一次成功通信的结果(供设置页展示"上次成功 / HA 版本 / 实例名 / 温度单位")。 + pub fn mark_ok( + &self, + conn_id: &str, + url: &str, + meta: &InstanceMeta, + ) -> Result<(), String> { + let mut s = self.load_settings(); + let Some(conn) = s.connections.iter_mut().find(|c| c.id == conn_id) else { + return Ok(()); + }; + conn.last_ok_url = url.to_string(); + conn.last_ok_at = chrono::Utc::now().timestamp(); + // 空值不覆盖:数据请求带的是空 meta,不能因此把已记住的版本 / 单位抹掉 + if !meta.ha_version.is_empty() { + conn.ha_version = meta.ha_version.clone(); + } + if !meta.location_name.is_empty() { + conn.location_name = meta.location_name.clone(); + } + if !meta.temperature_unit.is_empty() { + conn.temperature_unit = meta.temperature_unit.clone(); + } + self.save_settings(s) + } + + // ---------- 本地规则(P4) ---------- + + pub fn rules_path(&self) -> PathBuf { + self.module_dir.join("automations.json") + } + + /// 当前规则文件快照。 + pub fn rules_file(&self) -> RulesFile { + match self.rules.lock() { + Ok(g) => g.clone(), + Err(e) => { + crate::logger::log_error("smarthome", &format!("规则锁中毒:{e}")); + RulesFile::default() + } + } + } + + /// 规则列表视图(含总开关与最近运行记录)。 + pub fn rules_result(&self) -> RuleListResult { + let file = self.rules_file(); + let records = self + .records + .lock() + .map(|g| g.iter().cloned().collect()) + .unwrap_or_default(); + RuleListResult { + enabled: file.enabled, + rules: file.rules, + records, + } + } + + /// 更新内存里的规则(写盘由调用方在 `spawn_blocking` 里做)。 + pub fn set_rules_memory(&self, file: RulesFile) { + if let Ok(mut g) = self.rules.lock() { + *g = file; + } + } + + // ---------- 实时连接(P4) ---------- + + pub fn ws_handle(&self) -> Option { + self.ws.lock().ok().and_then(|g| g.as_ref().cloned()) + } + + fn set_ws_error(&self, message: &str) { + if let Ok(mut g) = self.ws_error.lock() { + *g = message.to_string(); + } + } + + /// 当前实时连接状态(没有运行中的连接时,用最近一次失败原因作诊断信息)。 + pub fn ws_status(&self) -> WsStatus { + if let Some(handle) = self.ws_handle() { + return handle.status(); + } + let detail = self.ws_error.lock().map(|g| g.clone()).unwrap_or_default(); + let conn_id = self.load_settings().active_id; + let mut status = WsStatus::new( + &conn_id, + if detail.is_empty() { "idle" } else { "disconnected" }, + ); + status.detail = detail; + status + } + + /// 停止实时连接(幂等)。 + pub fn stop_ws(&self) { + let taken = self.ws.lock().ok().and_then(|mut g| g.take()); + if let Some(handle) = taken { + handle.stop(); + } + self.set_ws_error(""); + } + + /// 启动实时连接:复用 P0 的端点选择(`resolve`),把所选端点换成 `ws(s)://`。 + /// + /// **一旦连上就固定在该端点**(plan §3.7-a):不允许同一屏数据来自两条链路。 + /// 幂等:同一条连接已经连着 / 正在连时直接返回它的状态,不重复建连。 + pub async fn start_ws( + &self, + app: &AppHandle, + conn: &HaConnection, + ) -> Result { + if let Some(handle) = self.ws_handle() { + if handle.conn_id == conn.id { + let status = handle.status(); + if status.state == "connected" || status.state == "connecting" { + return Ok(status); + } + } + } + let result = self.start_ws_fresh(app, conn).await; + if let Err(e) = &result { + self.set_ws_error(e); + } + result + } + + async fn start_ws_fresh( + &self, + app: &AppHandle, + conn: &HaConnection, + ) -> Result { + // 已有句柄但连接不可用(断线 / 鉴权失败):先彻底停掉,避免留下第二个任务 + self.stop_ws(); + let token = self.token(&conn.id); + if token.is_empty() { + return Err("尚未配置访问令牌".to_string()); + } + let (url, kind, _latency) = self.resolve(conn).await.map_err(|e| e.message)?; + let ws_url = client::ws_url(&url)?; + let cfg = ws::WsTaskConfig { + conn_id: conn.id.clone(), + app: app.clone(), + base_url: url, + ws_url, + token, + insecure: conn.insecure, + kind, + rules: self.rules.clone(), + records: self.records.clone(), + recent: self.recent.clone(), + rules_path: self.rules_path(), + }; + let handle = ws::spawn(cfg); + if let Ok(mut g) = self.ws.lock() { + *g = Some(handle); + } + self.set_ws_error(""); + Ok(self.ws_status()) + } + + /// 按"该不该有实时连接"对齐运行状态(幂等)。 + /// + /// 触发条件:**实时推送开关开着**,或**本地规则总开关开着** —— + /// 后者是硬依赖:规则靠 WS 事件驱动,没有实时连接它永远不会触发。 + /// 调用点:启动时、保存界面偏好 / 连接 / 规则之后。 + pub async fn sync_ws(&self, app: &AppHandle) { + let settings = self.load_settings(); + let want = settings.realtime.enabled || self.rules_file().enabled; + let conn = settings.connection(&settings.active_id).cloned(); + + if !want { + self.stop_ws(); + return; + } + let Some(conn) = conn else { + self.stop_ws(); + self.set_ws_error("没有可用的连接(请先在设置页配置 Home Assistant)"); + return; + }; + // 已经连着同一个连接:不动它(避免切个设置页就重连一次)。 + // 但 **authFailed 例外**:那种句柄是"永久放弃重连"的状态(§3.3 要求不刷日志), + // 若用户刚补了新令牌,这里必须给它一次重新尝试的机会。 + if let Some(handle) = self.ws_handle() { + if handle.conn_id == conn.id && handle.status().state != "authFailed" { + return; + } + } + self.stop_ws(); + if let Err(e) = self.start_ws(app, &conn).await { + crate::logger::log_warn("smarthome", &format!("启动实时连接失败:{e}")); + self.set_ws_error(&e); + } + } + + // ---------- 注册表(房间分组,P4) ---------- + + /// 命中缓存的前提:**是同一个连接**且未超过 TTL。 + pub fn cached_registry(&self, conn_id: &str, force: bool) -> Option { + if force { + return None; + } + let guard = self.registry_cache.lock().ok()?; + let (cached_conn, cached) = guard.as_ref()?; + if cached_conn != conn_id { + return None; + } + if chrono::Utc::now().timestamp() - cached.fetched_at > REGISTRY_CACHE_TTL_SECS { + return None; + } + Some(cached.clone()) + } + + pub fn store_registry(&self, conn_id: &str, registry: RegistryResult) { + if let Ok(mut g) = self.registry_cache.lock() { + *g = Some((conn_id.to_string(), registry)); + } + } + + /// 失效注册表缓存。触发点:切换/删除连接(房间归属跟着连接走)。 + pub fn clear_registry_cache(&self) { + if let Ok(mut g) = self.registry_cache.lock() { + *g = None; + } + } +} + +fn write_settings_file(module_dir: &Path, settings: &HaSettings) -> Result<(), String> { + let json = serde_json::to_string_pretty(settings) + .map_err(|e| format!("序列化智能家居设置失败:{e}"))?; + std::fs::write(module_dir.join("settings.json"), json) + .map_err(|e| format!("写入智能家居设置失败:{e}")) +} diff --git a/src-tauri/src/smarthome/registry.rs b/src-tauri/src/smarthome/registry.rs new file mode 100644 index 0000000..33045d8 --- /dev/null +++ b/src-tauri/src/smarthome/registry.rs @@ -0,0 +1,109 @@ +//! 区域 / 设备 / 实体注册表查询(P4)。 +//! +//! **房间分组的唯一来源**:纯 REST 拿不到 area(plan §0.4),注册表只能走 WebSocket 的 +//! `config/area_registry/list` 等命令。 +//! +//! **真机修正(§9.5-1)**:目标实例上实体级 `area_id` **全空**(606 条 0 条), +//! 房间归属在**设备**上(36 设备 / 27 有 area)。照原计划只读实体的 `area_id` +//! 会得到"一间房都没有",因此这里必须做三级回退: +//! `entity.area_id` → `device.area_id` → 归入「未分配房间」(前端负责这一档)。 +//! 这个"未分配"分组是**必需的**而不是兜底:那台实例上 9 个设备确实没有房间。 + +use std::collections::HashMap; + +use serde_json::{json, Value}; + +use super::types::{EntityRegistryEntry, HaArea, HaDevice, RegistryResult}; +use super::ws::WsHandle; + +/// 拉取三张注册表并算出 `entity_id → area_id` 映射 + 设备聚合所需的实体注册表。 +pub async fn fetch(ws: &WsHandle) -> Result { + let timeout = super::ws::request_timeout(); + let areas = ws + .request(json!({ "type": "config/area_registry/list" }), timeout) + .await?; + let devices = ws + .request(json!({ "type": "config/device_registry/list" }), timeout) + .await?; + let entities = ws + .request(json!({ "type": "config/entity_registry/list" }), timeout) + .await?; + + let area_list: Vec = items(&areas) + .iter() + .map(|a| HaArea { + area_id: text(a, "area_id"), + name: text(a, "name"), + }) + .filter(|a| !a.area_id.is_empty()) + .collect(); + + let device_list: Vec = items(&devices) + .iter() + .map(|d| HaDevice { + id: text(d, "id"), + name: text(d, "name"), + name_by_user: text(d, "name_by_user"), + area_id: text(d, "area_id"), + manufacturer: text(d, "manufacturer"), + model: text(d, "model"), + }) + .filter(|d| !d.id.is_empty()) + .collect(); + + // 设备级房间(真机上房间归属实际就在这一层) + let device_area: HashMap<&str, &str> = device_list + .iter() + .filter(|d| !d.area_id.is_empty()) + .map(|d| (d.id.as_str(), d.area_id.as_str())) + .collect(); + + let mut entity_areas: HashMap = HashMap::new(); + let mut entity_registry: Vec = Vec::new(); + for e in items(&entities) { + let entity_id = text(e, "entity_id"); + if entity_id.is_empty() { + continue; + } + let device_id = text(e, "device_id"); + let direct = text(e, "area_id"); + let area = if !direct.is_empty() { + direct + } else { + device_area + .get(device_id.as_str()) + .map(|a| a.to_string()) + .unwrap_or_default() + }; + // 三级都拿不到 → 不进表;前端把它归入「未分配房间」 + if !area.is_empty() { + entity_areas.insert(entity_id.clone(), area); + } + entity_registry.push(EntityRegistryEntry { + entity_id, + device_id, + name: text(e, "name"), + original_name: text(e, "original_name"), + entity_category: text(e, "entity_category"), + }); + } + + Ok(RegistryResult { + areas: area_list, + devices: device_list, + entity_areas, + entity_registry, + fetched_at: chrono::Utc::now().timestamp(), + }) +} + +fn items(v: &Value) -> &[Value] { + v.as_array().map(|a| a.as_slice()).unwrap_or(&[]) +} + +fn text(v: &Value, key: &str) -> String { + v.get(key) + .and_then(|x| x.as_str()) + .unwrap_or_default() + .to_string() +} diff --git a/src-tauri/src/smarthome/types.rs b/src-tauri/src/smarthome/types.rs new file mode 100644 index 0000000..b24a2e0 --- /dev/null +++ b/src-tauri/src/smarthome/types.rs @@ -0,0 +1,699 @@ +//! 智能家居(Home Assistant)模块的数据模型。 +//! +//! 全部走 specta 导出到 `src/lib/bindings.ts`,字段 camelCase。 +//! +//! 持久化:`{app_data_dir}/smarthome/settings.json`(范式同 dsh / editor / terminal)。 +//! **长期访问令牌不在这里** —— 它只进系统凭据管理器(`crate::secrets`), +//! 键名 `smarthome-token-`;前端拿到的永远是掩码。 + +use std::collections::HashMap; + +use serde::{Deserialize, Serialize}; +use specta::Type; + +/// 设置结构版本号(自愈用;**只补增量、不清空**,避免误删用户配置)。 +pub const SETTINGS_VERSION: u32 = 1; + +/// 凭据键前缀:`smarthome-token-`。 +pub const SECRET_PREFIX: &str = "smarthome-token-"; + +/// 允许的自动刷新间隔(秒),0 = 关闭。远端(反代)链路下强制为 0,见 §3.7-b。 +pub const AUTO_REFRESH_OPTIONS: [u32; 4] = [0, 5, 10, 30]; + +/// 端点(链路)类型。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Type)] +#[serde(rename_all = "lowercase")] +pub enum EndpointKind { + /// 局域网直连 + Local, + /// 反代(Cloudflare Tunnel 等) + Remote, +} + +/// 端点选择策略。 +/// +/// 探测顺序与超时见 `client.rs` 的常量;`auto` 是「先短超时试局域网、失败再试反代」, +/// 而不是「优先上次成功的端点」—— 后者会把人困在反代上:回家后反代仍然可用, +/// 就永远不会切回局域网(§3.7-a)。 +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "lowercase")] +pub enum EndpointMode { + /// 自动(局域网优先,反代兜底) + #[default] + Auto, + /// 强制局域网 + Local, + /// 强制反代 + Remote, +} + +/// 一条 Home Assistant 连接。 +/// +/// 支持**两个地址**:局域网直连(在家、快)+ 反代(在外面、慢但可达)。 +/// 两者至少填一个;只填一个时 `endpoint_mode` 退化为对应模式。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct HaConnection { + pub id: String, + pub name: String, + /// 局域网地址,如 `http://192.168.1.10:8123`(可空) + pub local_url: String, + /// 反代地址,如 `https://ha.example.com`(可空) + pub remote_url: String, + /// 端点选择策略 + pub endpoint_mode: EndpointMode, + /// 忽略 HTTPS 证书校验(自签证书时勾选) + pub insecure: bool, + /// 上次成功的地址(**仅用于展示**;不参与探测排序,理由见 `EndpointMode` 注释) + pub last_ok_url: String, + /// 上次成功时间(unix 秒,0 = 从未) + pub last_ok_at: i64, + /// HA 版本(`GET /api/config` 的 `version`) + pub ha_version: String, + /// HA 实例名(`GET /api/config` 的 `location_name`) + pub location_name: String, + /// 温度单位(`GET /api/config` 的 `unit_system.temperature`,如 `°C` / `°F`)。 + /// + /// **必须从实例读**:HA 的 `climate.temperature` / `min_temp` / `max_temp` 都按 + /// 系统单位制给值,写死 `°C` 在美制实例上会显示成"77°C"。 + pub temperature_unit: String, +} + +impl HaConnection { + /// 局域网候选(空串表示未配置)。 + pub fn local_candidate(&self) -> Option<(&str, EndpointKind)> { + let u = self.local_url.trim(); + if u.is_empty() { + None + } else { + Some((u, EndpointKind::Local)) + } + } + + /// 反代候选(空串表示未配置)。 + pub fn remote_candidate(&self) -> Option<(&str, EndpointKind)> { + let u = self.remote_url.trim(); + if u.is_empty() { + None + } else { + Some((u, EndpointKind::Remote)) + } + } +} + +/// 界面与行为偏好。 +#[derive(Debug, Clone, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct HaUiSettings { + /// 自动刷新间隔(秒),0 = 关闭 + pub auto_refresh_sec: u32, + /// 不展示的 domain(如 `sensor` 太多时可隐藏) + pub hidden_domains: Vec, + /// 不展示的具体实体 + pub hidden_entity_ids: Vec, + /// 收藏(置顶) + pub favorite_entity_ids: Vec, + /// 危险操作(解锁 / 开门 / 全开)二次确认 + pub confirm_dangerous: bool, +} + +impl Default for HaUiSettings { + fn default() -> Self { + Self { + auto_refresh_sec: 0, + hidden_domains: Vec::new(), + hidden_entity_ids: Vec::new(), + favorite_entity_ids: Vec::new(), + // 默认开启:这是有实际后果的操作(开锁 / 开门),宁可多一次确认 + confirm_dangerous: true, + } + } +} + +/// 实时推送配置(P4 才真正使用;P0 只落字段,避免以后升级设置结构)。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct HaRealtimeSettings { + /// 是否启用 WebSocket 实时推送 + pub enabled: bool, + /// 上次连接成功时间(unix 秒,0 = 从未) + pub last_connected_at: i64, +} + +/// 模块设置(`{app_data}/smarthome/settings.json`)。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct HaSettings { + pub version: u32, + /// 激活连接 id(空 = 未选择) + pub active_id: String, + pub connections: Vec, + pub ui: HaUiSettings, + pub realtime: HaRealtimeSettings, +} + +impl HaSettings { + /// 自愈:补版本号、校正激活连接、收敛非法的自动刷新间隔。返回「是否发生过修改」。 + pub fn heal(&mut self) -> bool { + let mut changed = false; + if self.version != SETTINGS_VERSION { + self.version = SETTINGS_VERSION; + changed = true; + } + // 激活连接指向一个已不存在的 id(删连接后旧快照回写等):回落到第一条 + let active_ok = self.connections.iter().any(|c| c.id == self.active_id); + if !active_ok { + let next = self.connections.first().map(|c| c.id.clone()).unwrap_or_default(); + if next != self.active_id { + self.active_id = next; + changed = true; + } + } + if !AUTO_REFRESH_OPTIONS.contains(&self.ui.auto_refresh_sec) { + self.ui.auto_refresh_sec = 0; + changed = true; + } + changed + } + + pub fn connection(&self, id: &str) -> Option<&HaConnection> { + self.connections.iter().find(|c| c.id == id) + } +} + +/// 前端提交的连接草案(新建或编辑)。令牌**不在此结构里**,走独立命令写入凭据库。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct HaConnectionInput { + /// 空 = 新建 + pub id: String, + pub name: String, + pub local_url: String, + pub remote_url: String, + pub endpoint_mode: EndpointMode, + pub insecure: bool, +} + +/// 发给前端的连接视图:**不含明文令牌**,只有掩码与"是否已配置"。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct HaConnectionView { + pub id: String, + pub name: String, + pub local_url: String, + pub remote_url: String, + pub endpoint_mode: EndpointMode, + pub insecure: bool, + pub has_token: bool, + /// 掩码(`secrets::mask`):长度不足 8 时整串打码,绝不泄露完整明文 + pub token_masked: String, + pub last_ok_url: String, + pub last_ok_at: i64, + pub ha_version: String, + pub location_name: String, + /// 温度单位(`°C` / `°F`)—— climate 的温度显示必须用它 + pub temperature_unit: String, + /// 本次会话实际使用的端点(未探测过为 null) + pub endpoint_url: Option, + pub endpoint_kind: Option, + /// 该端点最近一次实测耗时(毫秒) + pub endpoint_latency_ms: Option, +} + +/// 模块设置视图。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct HaSettingsView { + pub version: u32, + pub active_id: String, + pub connections: Vec, + pub ui: HaUiSettings, + pub realtime: HaRealtimeSettings, +} + +/// 保存连接的结果:**回传 id**(新建时前端要靠它接着写令牌,按名称/地址反查不可靠), +/// 外加刷新后的整份视图。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct HaSaveConnectionResult { + pub id: String, + pub settings: HaSettingsView, +} + +/// 单个地址的探测结果(「测试连接」逐地址返回)。 +/// +/// 逐地址给结果而不是一个笼统的成功/失败:用户在外面测时,局域网失败是**预期内**的, +/// 只有把两条链路的结果分开呈现,这个信息才有用(§5.1)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct EndpointProbe { + pub url: String, + pub kind: EndpointKind, + pub ok: bool, + pub ha_version: String, + pub location_name: String, + /// 实例的温度单位(见 `HaConnection::temperature_unit`) + pub temperature_unit: String, + /// 耗时(毫秒):既是诊断信息,也是"反代比局域网慢多少"的直觉来源 + pub elapsed_ms: u64, + /// 失败原因(中文可读) + pub error: Option, + /// 失败分类:auth | network | server | other(前端据此决定是否提示"重填令牌") + pub error_kind: Option, +} + +/// 当前链路信息(诊断区)。 +/// +/// 失败时 `url` / `kind` 也可能为空 —— 例如 `auto` 模式下两个地址都不可达, +/// 这时没有"当前链路"可言,只能把失败原因(包含每个地址的尝试结果)交给前端展示。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct LinkInfo { + pub url: Option, + pub kind: Option, + pub ok: bool, + /// 成功时:该端点实测耗时(毫秒)。失败时为 0 + pub latency_ms: u64, + /// 失败原因(含各候选地址的尝试结果) + pub error: Option, + /// 失败分类:auth | network | config(前端据此决定提示"重填令牌"还是"重试") + pub error_kind: Option, +} + +/// 实体摘要(发给前端的**精简结构**)。 +/// +/// 只带前端**要显示**的字段。完整 `attributes` 因 domain 而异(灯有 +/// `supported_color_modes`、窗帘有 `current_position`、气候有 `hvac_modes`…), +/// 几百个实体整份过 IPC 会让序列化与前端响应式都明显变重(§6.1)。 +/// +/// 「是否可控 / 分组 / 图标 / 状态文案」这类**表现层语义由前端 `format.ts` 决定**, +/// 不在这里算 —— Rust 侧只负责"协议 → 数据的忠实搬运"。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct EntitySummary { + pub entity_id: String, + /// `entity_id` 的前半段(light / switch / sensor…) + pub domain: String, + /// `friendly_name`,缺失时回落 `entity_id` + pub name: String, + /// 原始状态字符串:`on` / `off` / `24.5` / `unavailable` / `unknown` … + pub state: String, + /// `state` 可解析为数字时的数值(sensor 这类读数就在 `state` 里) + pub numeric: Option, + /// `unit_of_measurement` + pub unit: String, + /// `device_class`(binary_sensor / sensor 的语义细分) + pub device_class: String, + /// 灯亮度 0–255 + pub brightness: Option, + /// 窗帘当前位置 0–100 + pub position: Option, + /// 空调目标温度 + pub target_temp: Option, + /// 空调可设的上下限(**单位随系统单位制**,如美制是 61–86 °F)。 + /// 控件必须用它,不能自己写死 5–35 —— 美制下 77 会被钳成 35(真机踩到过)。 + pub min_temp: Option, + pub max_temp: Option, + /// 空调当前温度(室温) + pub current_temp: Option, + /// 最后变化时间(HA 的 ISO8601 串,前端格式化成相对时间) + pub last_changed: String, + /// `attributes.last_triggered` —— 自动化 / 脚本的"上次触发时间"(空 = 从未触发)。 + /// P3 的自动化列表要靠它回答"这条规则最近到底跑没跑"。 + pub last_triggered: String, + // ---- 以下为 P2 控制所需的能力位与参数(同一次拉取里拿到,不必为控制再请求一次)---- + /// HA 的 `supported_features` 位掩码。**语义按 domain 不同**(窗帘 OPEN/CLOSE/…、 + /// 气候 TARGET_TEMPERATURE/…),因此这里原样透传,由前端按 domain 解释。 + pub supported_features: u32, + /// 灯的 `supported_color_modes`(`onoff` / `brightness` / `color_temp` / `hs` …)。 + /// 判断"能不能调亮度 / 色温"必须用它,而不是 `supported_features` 的旧位约定。 + pub supported_color_modes: Vec, + /// 色温可调范围(灯) + pub min_color_temp_kelvin: Option, + pub max_color_temp_kelvin: Option, + /// 当前色温(灯)。**必须有**:没有它,色温滑杆只能猜一个初始位置, + /// 那就成了一个会骗人的控件。 + pub color_temp_kelvin: Option, + /// 空调可选模式(cool / heat / off / auto …) + pub hvac_modes: Vec, + /// 空调温度步进(0.5 / 1) + pub target_temp_step: Option, + /// 媒体播放器音量 0.0–1.0 + pub volume_level: Option, + /// 风扇档位 0–100 + pub percentage: Option, + // ---- 通用域(`number` / `select` / `button`):这三类能覆盖最多"能控但没控件"的实体 ---- + /// `number` 实体的可设上下限与步长(各集成差异极大:0–100 音量、10–90 变焦、步长 180 的翻转角) + pub min: Option, + pub max: Option, + pub step: Option, + /// `select` 实体的可选项 + pub options: Vec, +} + +/// 服务调用的可选参数。 +/// +/// **用固定字段而不是 `serde_json::Value`**:specta 无法为 `Value` 生成类型 +/// (见 lib.rs 的豁免清单);而且固定字段顺带把"能传什么参数"限死了, +/// 前端不可能把任意键塞进 HA 的 `service_data`。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct ServiceParams { + /// 灯亮度百分比 0–100(HA 侧换算成 `brightness`) + pub brightness_pct: Option, + /// 色温(开尔文) + pub color_temp_kelvin: Option, + /// 窗帘位置 0–100 + pub position: Option, + /// 空调目标温度 + pub temperature: Option, + /// 空调模式(`cool` / `heat` / `off` …) + pub hvac_mode: Option, + /// 风扇档位 0–100 + pub percentage: Option, + /// 媒体音量 0.0–1.0 + pub volume_level: Option, + /// `number.set_value` 的目标值 + pub value: Option, + /// `select.select_option` 的目标项 + pub option: Option, +} + +/// 服务调用结果。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct ServiceCallResult { + /// HA 在 `200` 响应体里带回的**已变化实体**新状态(已转成精简结构)。 + /// + /// **可能为空**:部分集成(尤其走云端的设备)是"发完就返回",状态要稍后才反映。 + /// 前端据此决定"直接采用服务端结果"还是"等分级窗口后重拉一次"(§9.3)。 + pub entities: Vec, +} + +/// 实体列表结果。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct EntityListResult { + pub entities: Vec, + /// 抓取时间(unix 秒)。"更新于 x 秒前"必须用它 —— 那是**服务端数据的时刻**, + /// 而不是前端收到响应的时刻。 + pub fetched_at: i64, + /// true = 命中内存缓存,未重新请求 + pub from_cache: bool, +} + +// ============================== P4:实时推送 ============================== + +/// WebSocket 连接状态(`smarthome_ws_status` 的返回,也是 `smarthome-connection-status` 的载荷)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct WsStatus { + pub conn_id: String, + /// idle | connecting | connected | authFailed | disconnected + pub state: String, + /// 失败原因 / 补充说明(正常时为空) + pub detail: String, + /// 本次连上的时间(unix 秒,0 = 未连上) + pub connected_at: i64, + /// 最近一次收到服务端消息的时间(unix 秒)—— 半开连接靠它判断 + pub last_event_at: i64, + /// 已订阅到的实体数(`subscribe_entities` 首帧后写入) + pub entity_count: u32, +} + +impl WsStatus { + pub fn new(conn_id: &str, state: &str) -> Self { + Self { + conn_id: conn_id.to_string(), + state: state.to_string(), + detail: String::new(), + connected_at: 0, + last_event_at: 0, + entity_count: 0, + } + } + + /// 状态变化时重置"连上时间 / 事件时间"(只有 connected 才重新计时)。 + pub fn set(&mut self, state: &str, detail: impl Into) { + self.state = state.to_string(); + self.detail = detail.into(); + } +} + +/// `smarthome-state-batch` 事件的载荷。 +/// +/// **200ms 聚合后**才发(plan §6.5):一次全屋状态变化(HA 重启恢复、场景切换) +/// 会造成数十条消息,逐条 IPC 会把 WebView 卡住。窗口内的多次变更按 `entity_id` +/// 合并,只发最终值。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct StateBatch { + pub conn_id: String, + /// 本次窗口内新出现的实体(含首次订阅的全量快照) + pub added: Vec, + /// 本次窗口内发生变化的实体(只带最终值) + pub changed: Vec, + /// 本次窗口内被移除的实体 id + pub removed: Vec, +} + +/// 规则列表结果(含总开关与最近运行记录)。 +/// +/// 计划 §6.2 只列了 `Rule[]`,这里把「总开关 + 最近记录」并进同一个返回: +/// 自动化页进来就要用这三样,拆成三条命令只是多两次往返。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct RuleListResult { + /// 规则总开关(关掉后所有规则都不求值) + pub enabled: bool, + pub rules: Vec, + /// 最近运行记录(新的在前,最多 `automation::MAX_RECORDS` 条;仅本次运行期内有) + pub records: Vec, +} + +// ============================== P4:注册表(房间分组) ============================== + +/// 区域(房间)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct HaArea { + pub area_id: String, + pub name: String, +} + +/// 设备(设备聚合与详情页头部所需的最小字段集合)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct HaDevice { + pub id: String, + pub name: String, + /// 用户在 HA 里改过的名字(为空时用 `name`) + pub name_by_user: String, + /// 空 = 未分配房间 + pub area_id: String, + /// 厂商 / 型号(详情页头部显示,便于认出是哪台设备) + pub manufacturer: String, + pub model: String, +} + +/// 实体注册表条目(**设备聚合的唯一来源**:REST 的 `/api/states` 里没有 device_id)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct EntityRegistryEntry { + pub entity_id: String, + /// 空 = 未归组到设备(真机上是 `person` / `todo` 这类) + pub device_id: String, + /// 注册表里的名字(小米集成上**大量为空**,因此只作兜底) + pub name: String, + /// 集成给的原始名字 + pub original_name: String, + /// `""` | `config` | `diagnostic` —— HA 官方标记的"高级 / 配置"类实体。 + /// + /// 真机上只有 30/606 条有值,所以它只是"三级"的**判据之一**,不是全部。 + pub entity_category: String, +} + +/// 注册表查询结果(房间分组 + 设备聚合的唯一来源)。 +/// +/// **真机修正(§9.5-1)**:目标实例上实体级 `area_id` 全空,房间归属在设备上, +/// 因此 `entity_areas` 已按「实体 → 设备 → 区域」三级回退算好;仍未解析到的不进表 +/// (前端把它归入「未分配房间」,这是必需的分组而不是兜底)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct RegistryResult { + pub areas: Vec, + pub devices: Vec, + /// `entity_id` → `area_id` + pub entity_areas: HashMap, + /// 实体注册表(`entity_id` → 设备 / 名字 / 分类) + pub entity_registry: Vec, + /// 抓取时间(unix 秒) + pub fetched_at: i64, +} + +// ============================== P4:本地规则 ============================== + +/// 规则触发段(线性三段式的第一段)。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct RuleTrigger { + pub entity_id: String, + /// 命中这些状态才触发(空 = 任意变化) + pub to: Vec, + /// 仅当从这些状态变化而来(空 = 不限) + pub from: Vec, + /// 持续 N 秒仍然满足才触发(0 = 立即;用于去抖) + pub for_sec: u32, + /// 数值比较运算符(空 = 不做数值判断;否则 `>` `>=` `<` `<=` `==` `!=`) + pub numeric_op: String, + /// 数值比较的阈值 + pub numeric_value: Option, +} + +/// 规则条件段(全部 AND)。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct RuleCondition { + /// state | time + pub kind: String, + /// `state` 条件:实体 id + pub entity_id: String, + /// `state` 条件:要求的状态 + pub state: String, + /// `time` 条件:起始 `HH:MM` + pub from_time: String, + /// `time` 条件:结束 `HH:MM`(跨零点时 `to < from` 视为跨天) + pub to_time: String, + /// `time` 条件:星期(1=周一 … 7=周日;空 = 每天) + pub weekdays: Vec, +} + +/// 规则动作段(顺序执行)。 +#[derive(Debug, Clone, Default, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct RuleAction { + /// service | delay | notify + pub kind: String, + /// `service`:domain / service / 目标实体 + pub domain: String, + pub service: String, + pub entity_id: String, + pub params: ServiceParams, + /// `delay`:秒(上限见 `automation::MAX_DELAY_SEC`) + pub seconds: u32, + /// `notify`:标题与正文 + pub title: String, + pub message: String, +} + +/// 一条本地规则。 +#[derive(Debug, Clone, Serialize, Deserialize, Type)] +#[serde(rename_all = "camelCase", default)] +pub struct Rule { + pub id: String, + pub name: String, + pub enabled: bool, + pub trigger: RuleTrigger, + pub conditions: Vec, + pub actions: Vec, + /// 冷却秒数:窗口内的重复触发直接丢弃(护栏 1) + pub cooldown_sec: u32, + /// 上次触发时间(unix 秒,0 = 从未) + pub last_fired_at: i64, + /// 累计触发次数 + pub fire_count: u32, + /// 上次失败原因(空 = 上次正常) + pub last_error: String, +} + +impl Default for Rule { + fn default() -> Self { + Self { + id: String::new(), + name: String::new(), + enabled: true, + trigger: RuleTrigger::default(), + conditions: Vec::new(), + actions: Vec::new(), + // 默认 30s:小米设备的状态抖动(如功率传感器反复跳)很容易把规则刷爆 + cooldown_sec: 30, + last_fired_at: 0, + fire_count: 0, + last_error: String::new(), + } + } +} + +/// 规则运行记录(内存里保留最近 `automation::MAX_RECORDS` 条)。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct RuleRecord { + pub rule_id: String, + pub rule_name: String, + pub at: i64, + pub ok: bool, + pub detail: String, +} + +/// `smarthome-rule-fired` 事件的载荷(与 `RuleRecord` 同构,但字段名对齐计划 §6.3)。 +#[derive(Debug, Clone, Serialize)] +#[serde(rename_all = "camelCase")] +pub struct RuleFiredEvent { + pub rule_id: String, + pub rule_name: String, + pub at: i64, + pub ok: bool, + pub detail: String, +} + +/// 规则文件(`{app_data}/smarthome/automations.json`)。 +/// +/// `enabled` 是**总开关**:关掉后所有规则都不求值(但规则本身保留)。 +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(rename_all = "camelCase", default)] +pub struct RulesFile { + pub version: u32, + pub enabled: bool, + pub rules: Vec, +} + +impl Default for RulesFile { + fn default() -> Self { + Self { + version: RULES_VERSION, + enabled: false, + rules: Vec::new(), + } + } +} + +/// 规则文件版本号(自愈用)。 +pub const RULES_VERSION: u32 = 1; + +/// 命令层错误:带分类。 +/// +/// 前端据此区分"重填令牌"(`auth`,重试无意义)与"重试 / 检查地址" +/// (`network` / `config`)—— **分类判定留在 Rust 侧**,不让前端靠匹配错误文案猜(§3.6)。 +/// 这是本项目第一个不用 `String` 作错误类型的命令模块;理由见 §9.1。 +#[derive(Debug, Clone, Serialize, Type)] +#[serde(rename_all = "camelCase")] +pub struct HaApiError { + /// auth | network | config | server | other + pub kind: String, + pub message: String, +} + +impl HaApiError { + pub fn new(kind: &str, message: impl Into) -> Self { + Self { + kind: kind.to_string(), + message: message.into(), + } + } +} + +impl std::fmt::Display for HaApiError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(&self.message) + } +} diff --git a/src-tauri/src/smarthome/ws.rs b/src-tauri/src/smarthome/ws.rs new file mode 100644 index 0000000..5475d41 --- /dev/null +++ b/src-tauri/src/smarthome/ws.rs @@ -0,0 +1,768 @@ +//! Home Assistant WebSocket 实时客户端(P4)。 +//! +//! 职责(plan §3.3 / §6.1):握手鉴权 → `subscribe_entities` → 增量合并 → 200ms 聚合后 +//! 发 `smarthome-state-batch`;顺带把状态变化喂给本地规则引擎(`automation`)。 +//! 还提供「请求 / 应答」通道,供 `registry` 拉区域 / 实体 / 设备注册表。 +//! +//! 生命周期归属**应用**而非页面:连接由 Rust 侧持有(后台任务),模块 Tab 切走不关连接; +//! 只有用户显式关掉实时、规则总开关关闭、或应用退出才断(plan §3.3 第一条)。 +//! +//! 真机实测前提(§9.5): +//! - 握手 `auth_required` → `auth` → `auth_ok`,HA 2026.10.1; +//! - `subscribe_entities` 首帧是**一条大消息**(577 实体 / 152 KB / 2.23s), +//! 之后 30 秒仅 2 个增量事件 —— 这就是"实时优于轮询"的量化依据; +//! - `ping/pong` 往返 617ms(反代),心跳与聚合窗口按它设计; +//! - **`c`(changed)里的 attributes 可能是差量**(`{"+": {...}, "-": [...]}`), +//! 因此必须维护一份原始 attributes 再合并,然后重新推导 `EntitySummary`, +//! 不能整份替换(整份替换会在下一次事件把未变化的字段抹掉)。 + +use std::collections::{HashMap, HashSet}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use futures_util::{SinkExt, StreamExt}; +use serde_json::{json, Map, Value}; +use tauri::{AppHandle, Emitter}; +use tokio::sync::{mpsc, oneshot, watch}; +use tokio_tungstenite::tungstenite::Message; + +use super::automation::{self, RuleEnv}; +use super::client::{self, RawState}; +use super::types::{EntitySummary, StateBatch, WsStatus}; +use crate::constants::events; + +/// 心跳间隔(秒)。 +/// +/// 反代链路上的 `ping/pong` 实测 **617ms**(§9.5),25s 足够保活,也给 Cloudflare +/// 约 100s 的空闲超时留足余量。**必须主动发**:不能只依赖 TCP keepalive, +/// 路由器 / NAT 把连接悄悄丢掉时 TCP 是不会有反应的。 +const PING_SECS: u64 = 25; +/// 超过这么久没收到任何入站消息 → 判定半开连接,主动断开重连。 +const STALE_SECS: u64 = PING_SECS * 3; +/// 聚合窗口(毫秒)—— **硬要求**(plan §6.5):一次全屋变化会有数十条消息。 +const AGG_MS: u64 = 200; +/// 重连退避上限(秒)。 +const MAX_BACKOFF_SECS: u64 = 30; +/// 握手 / 鉴权等待超时(秒)。反代上首帧可能慢,给足。 +const HANDSHAKE_TIMEOUT_SECS: u64 = 20; +/// 连上后至少活这么久才认为"这次连接是成功的",从而把退避重置回 1s +/// (否则"连上即断"会退化成 1s 一次的重连风暴)。 +const STABLE_CONNECT_SECS: u64 = 5; +/// 实时命令(注册表查询)的等待超时(秒)。 +const REQUEST_TIMEOUT_SECS: u64 = 20; + +/// 应答等待表:`id` → 一次性回执。 +type Pending = Arc>>>>; + +/// 客户端连接的具体类型(`MaybeTlsStream` 在开了 `rustls-tls-webpki-roots` 后 +/// 会带上 TLS 分支,因此必须用具名别名而不是泛型参数)。 +type WsStream = tokio_tungstenite::WebSocketStream>; + +/// 传给后台任务的配置。 +pub struct WsTaskConfig { + pub conn_id: String, + pub app: AppHandle, + /// REST 端点(规则动作走 REST 下发;不重造一份"WS 版 call_service") + pub base_url: String, + /// WebSocket 端点(由 `client::ws_url` 从 REST 端点推出来) + pub ws_url: String, + pub token: String, + pub insecure: bool, + pub kind: super::types::EndpointKind, + pub rules: Arc>, + pub records: Arc>>, + pub recent: Arc>>, + pub rules_path: std::path::PathBuf, +} + +/// 运行中的 WS 连接的句柄(克隆是廉价的:内部全是 Arc / channel)。 +#[derive(Clone)] +pub struct WsHandle { + pub conn_id: String, + out: mpsc::UnboundedSender, + pending: Pending, + next_id: Arc, + stop: watch::Sender, + status: Arc>, +} + +impl WsHandle { + /// 当前状态快照。 + pub fn status(&self) -> WsStatus { + match self.status.lock() { + Ok(g) => g.clone(), + Err(e) => { + crate::logger::log_error("smarthome", &format!("WS 状态锁中毒:{e}")); + WsStatus::new(&self.conn_id, "disconnected") + } + } + } + + /// 请求停止(任务会在下一个 select 轮次退出)。 + pub fn stop(&self) { + let _ = self.stop.send(true); + } + + /// 发一条实时命令并等应答(注册表查询用它)。 + /// + /// 超时后要把等待表里的条目删掉 —— 否则应答迟到时会往一个已丢弃的 oneshot + /// 里写(无害但会泄漏一条记录)。 + pub async fn request(&self, mut payload: Value, timeout: Duration) -> Result { + let id = self.next_id.fetch_add(1, Ordering::Relaxed); + match payload.as_object_mut() { + Some(o) => { + o.insert("id".to_string(), json!(id)); + } + None => return Err("内部错误:实时命令载荷不是对象".to_string()), + } + let (tx, rx) = oneshot::channel(); + if let Ok(mut g) = self.pending.lock() { + g.insert(id, tx); + } + self.out + .send(payload.to_string()) + .map_err(|_| "实时连接已断开".to_string())?; + match tokio::time::timeout(timeout, rx).await { + Ok(Ok(v)) => v, + Ok(Err(_)) => Err("实时连接已断开".to_string()), + Err(_) => { + if let Ok(mut g) = self.pending.lock() { + g.remove(&id); + } + Err("Home Assistant 未在预期时间内应答".to_string()) + } + } + } +} + +/// 启动一条实时连接,返回句柄(**不阻塞**:连接建立与重连都在后台任务里)。 +pub fn spawn(cfg: WsTaskConfig) -> WsHandle { + let status = Arc::new(Mutex::new(WsStatus::new(&cfg.conn_id, "connecting"))); + let (out_tx, out_rx) = mpsc::unbounded_channel::(); + let pending: Pending = Arc::new(Mutex::new(HashMap::new())); + let next_id = Arc::new(AtomicU64::new(1)); + let (stop_tx, stop_rx) = watch::channel(false); + let summaries: Arc>> = Arc::new(Mutex::new(HashMap::new())); + + let rule_env = RuleEnv { + app: cfg.app.clone(), + base_url: cfg.base_url.clone(), + token: cfg.token.clone(), + insecure: cfg.insecure, + kind: cfg.kind, + rules: cfg.rules.clone(), + records: cfg.records.clone(), + recent: cfg.recent.clone(), + pending: Arc::new(Mutex::new(HashMap::new())), + last_persist: Arc::new(Mutex::new(Instant::now())), + rules_path: cfg.rules_path.clone(), + summaries: summaries.clone(), + }; + let session = Session { + cfg, + pending: pending.clone(), + next_id: next_id.clone(), + status: status.clone(), + summaries, + rule_env, + raw: HashMap::new(), + added: HashSet::new(), + changed: HashSet::new(), + removed: HashSet::new(), + }; + // `for`(持续 N 秒)触发器的巡检任务:与连接同生共死(stop 信号一响就退出), + // 因此不会有"连接已经换了、旧定时器还在跑旧端点"的残留(见自动化模块注释) + automation::spawn_sweeper(&session.rule_env, stop_rx.clone()); + let handle = WsHandle { + conn_id: session.cfg.conn_id.clone(), + out: out_tx, + pending, + next_id, + stop: stop_tx, + status, + }; + tauri::async_runtime::spawn(run(session, out_rx, stop_rx)); + handle +} + +// ============================== 任务主体 ============================== + +/// 任务内部状态。 +struct Session { + cfg: WsTaskConfig, + pending: Pending, + next_id: Arc, + status: Arc>, + /// 原始实体状态(**差量合并的基准**,见文件头注释) + raw: HashMap, + /// 当前摘要(与规则引擎共享同一份 Arc,条件判断直接读它) + summaries: Arc>>, + rule_env: RuleEnv, + added: HashSet, + changed: HashSet, + removed: HashSet, +} + +/// 合并基准:一份完整的原始状态。 +struct RawEntity { + state: String, + attrs: Map, + last_changed: String, +} + +impl Session { + /// 更新状态并推给前端(同状态同原因不重复推)。 + fn push_status(&mut self, state: &str, detail: impl Into) { + let detail = detail.into(); + let Ok(mut g) = self.status.lock() else { + return; + }; + if g.state == state && g.detail == detail { + return; + } + g.set(state, detail); + if state == "connected" { + g.connected_at = now_secs(); + } else if state == "idle" || state == "disconnected" || state == "authFailed" { + // 断开/停止后"连上时间"不再有效,别让它在那儿假装还连着 + g.connected_at = 0; + } + let payload = g.clone(); + drop(g); + let _ = self + .cfg + .app + .emit(events::SMARTHOME_CONNECTION_STATUS, payload); + } + + /// 记一次"收到服务端消息"的时刻(诊断用,不推事件:状态本身没变)。 + fn note_event(&mut self) { + if let Ok(mut g) = self.status.lock() { + g.last_event_at = now_secs(); + } + } + + /// 断线后清空本地状态:增量已经丢了,重连时 `subscribe_entities` 会给全量快照。 + fn reset_state(&mut self) { + self.raw.clear(); + if let Ok(mut g) = self.summaries.lock() { + g.clear(); + } + self.added.clear(); + self.changed.clear(); + self.removed.clear(); + } + + /// 分配一个自增 id 并直接发送(不等应答:订阅与心跳的结果不参与流程)。 + async fn send_fire_and_forget( + &mut self, + write: &mut futures_util::stream::SplitSink, + mut payload: Value, + ) { + let id = self.next_id.fetch_add(1, Ordering::Relaxed); + if let Some(o) = payload.as_object_mut() { + o.insert("id".to_string(), json!(id)); + } + if let Err(e) = write.send(Message::Text(payload.to_string())).await { + crate::logger::log_warn("smarthome", &format!("发送实时命令失败:{e}")); + } + } + + /// 收到一条文本消息:先路由应答,再处理事件。 + fn on_text(&mut self, text: &str) { + let v: Value = match serde_json::from_str(text) { + Ok(v) => v, + Err(e) => { + crate::logger::log_warn("smarthome", &format!("忽略无法解析的实时消息:{e}")); + return; + } + }; + + // 1) 应答路由(订阅 / 心跳 / 注册表查询都带 id) + if let Some(id) = v.get("id").and_then(|x| x.as_u64()) { + let ty = v.get("type").and_then(|x| x.as_str()).unwrap_or(""); + if ty == "result" || ty == "pong" { + let sender = self.pending.lock().ok().and_then(|mut g| g.remove(&id)); + if let Some(tx) = sender { + let outcome = if ty == "pong" { + Ok(Value::Null) + } else if v.get("success").and_then(|x| x.as_bool()).unwrap_or(false) { + Ok(v.get("result").cloned().unwrap_or(Value::Null)) + } else { + Err(error_message(&v)) + }; + let _ = tx.send(outcome); + } + return; + } + } + + // 2) 事件(只订阅了 subscribe_entities) + if v.get("type").and_then(|x| x.as_str()) == Some("event") { + if let Some(ev) = v.get("event") { + self.apply_event(ev); + } + } + } + + /// `subscribe_entities` 的事件:`a` 新增全量 / `c` 变化(可能是差量)/ `r` 移除。 + fn apply_event(&mut self, ev: &Value) { + if let Some(map) = ev.get("a").and_then(|x| x.as_object()) { + let first = self.summaries.lock().map(|g| g.is_empty()).unwrap_or(false); + if first && !map.is_empty() { + // 首帧是一条大消息:记下实际大小(plan §2.2-3 要求把它记进日志) + crate::logger::log_info( + "smarthome", + &format!("实时订阅首帧:{} 个实体(约 {} KB)", map.len(), approx_kb(ev)), + ); + } + for (entity_id, obj) in map { + self.upsert_full(entity_id, obj); + } + } + if let Some(map) = ev.get("c").and_then(|x| x.as_object()) { + for (entity_id, obj) in map { + self.apply_change(entity_id, obj); + } + } + if let Some(list) = ev.get("r").and_then(|x| x.as_array()) { + for item in list { + if let Some(id) = item.as_str() { + self.remove_entity(id); + } + } + } + } + + /// 全量状态(`a` 段,或变化数据里带了完整状态时)。 + fn upsert_full(&mut self, entity_id: &str, obj: &Value) { + let raw = RawEntity { + state: obj + .get("s") + .and_then(|x| x.as_str()) + .unwrap_or_default() + .to_string(), + attrs: obj + .get("a") + .and_then(|x| x.as_object()) + .cloned() + .unwrap_or_default(), + last_changed: last_changed_of(obj), + }; + self.commit(entity_id, raw); + } + + /// 差量变化(`c` 段):**先合并回原始对象再推导摘要**,绝不整份替换。 + fn apply_change(&mut self, entity_id: &str, obj: &Value) { + match self.raw.get_mut(entity_id) { + Some(stored) => { + if let Some(s) = obj.get("s").and_then(|x| x.as_str()) { + stored.state = s.to_string(); + } + if let Some(a) = obj.get("a").and_then(|x| x.as_object()) { + // 差量形态:`+` 是要补的键、`-` 是要删的键;其余键按普通属性合并 + if let Some(plus) = a.get("+").and_then(|x| x.as_object()) { + for (k, v) in plus { + stored.attrs.insert(k.clone(), v.clone()); + } + } + if let Some(minus) = a.get("-").and_then(|x| x.as_array()) { + for k in minus { + if let Some(k) = k.as_str() { + stored.attrs.remove(k); + } + } + } + for (k, v) in a { + if k == "+" || k == "-" { + continue; + } + stored.attrs.insert(k.clone(), v.clone()); + } + } + let lc = last_changed_of(obj); + if !lc.is_empty() { + stored.last_changed = lc; + } + let raw = RawEntity { + state: stored.state.clone(), + attrs: stored.attrs.clone(), + last_changed: stored.last_changed.clone(), + }; + self.commit(entity_id, raw); + } + None => { + // 没见过这个实体(订阅之后才出现的实体理论上会先走 `a`): + // 用这条变化消息构造一份(属性可能不全),下一次全量会补齐 + self.upsert_full(entity_id, obj); + } + } + } + + fn remove_entity(&mut self, entity_id: &str) { + self.raw.remove(entity_id); + if let Ok(mut g) = self.summaries.lock() { + g.remove(entity_id); + } + self.added.remove(entity_id); + self.changed.remove(entity_id); + self.removed.insert(entity_id.to_string()); + } + + /// 落一份新状态:算摘要、标记批次、喂规则引擎。 + fn commit(&mut self, entity_id: &str, raw: RawEntity) { + let summary = summary_of(entity_id, &raw); + let previous = self + .summaries + .lock() + .ok() + .and_then(|mut g| g.insert(entity_id.to_string(), summary.clone())); + self.raw.insert(entity_id.to_string(), raw); + self.removed.remove(entity_id); + match previous { + Some(prev) => { + self.changed.insert(entity_id.to_string()); + if prev.state != summary.state || prev.numeric != summary.numeric { + automation::on_entity_changed(&self.rule_env, entity_id, Some(&prev), &summary); + } + } + None => { + // **首次见到不触发规则。** + // `subscribe_entities` 的首帧就是全量快照,重连后也会重放一遍 —— + // 把快照当成"状态变化"会让只配了「变化为 on」的边沿触发规则在每次 + // 连接/重连时凭空执行一次(门开着 → 每次都重新锁门)。 + // 订阅之后**新出现**的实体同样走这条路径,代价是"实体一出现就触发" + // 这种玩法不支持 —— 那本来也不是"状态变化"。 + self.added.insert(entity_id.to_string()); + } + } + } + + /// 聚合窗口到点:把窗口内累计的变化合并成一批发出去。 + fn flush(&mut self) { + if self.added.is_empty() && self.changed.is_empty() && self.removed.is_empty() { + return; + } + let removed: Vec = self.removed.drain().collect(); + let removed_set: HashSet = removed.iter().cloned().collect(); + + let mut added = Vec::new(); + let mut changed = Vec::new(); + // 一次锁住摘要表把两批都取出来:首帧是 577 个实体,逐个 lock/clone 没必要 + match self.summaries.lock() { + Ok(summaries) => { + for id in self.added.drain() { + if removed_set.contains(&id) { + continue; + } + if let Some(s) = summaries.get(&id) { + added.push(s.clone()); + } + } + for id in self.changed.drain() { + if removed_set.contains(&id) { + continue; + } + if let Some(s) = summaries.get(&id) { + changed.push(s.clone()); + } + } + } + Err(e) => { + crate::logger::log_error("smarthome", &format!("实体摘要锁中毒:{e}")); + self.added.clear(); + self.changed.clear(); + return; + } + } + + // 实体数变了要**推一次状态**:否则设置页的「实时连接」永远显示 + // "已连接(0 个实体实时同步)」—— 那个数字只存在 Rust 内存里没人看得到 + let payload = match self.status.lock() { + Ok(mut g) => { + let total = self.summaries.lock().map(|m| m.len()).unwrap_or(0) as u32; + if g.entity_count != total { + g.entity_count = total; + Some(g.clone()) + } else { + None + } + } + Err(_) => None, + }; + if let Some(payload) = payload { + let _ = self + .cfg + .app + .emit(events::SMARTHOME_CONNECTION_STATUS, payload); + } + + let _ = self.cfg.app.emit( + events::SMARTHOME_STATE_BATCH, + StateBatch { + conn_id: self.cfg.conn_id.clone(), + added, + changed, + removed, + }, + ); + } +} + +enum Outcome { + /// 用户主动停止 + Stopped, + /// 令牌无效:**停止重连**(继续试只会刷爆日志,见 plan §3.3) + AuthFailed(String), + /// 链路断开:指数退避后重连 + Lost(String), +} + +async fn run( + mut session: Session, + mut rx: mpsc::UnboundedReceiver, + mut stop_rx: watch::Receiver, +) { + let mut backoff = Duration::from_secs(1); + loop { + if *stop_rx.borrow() { + session.push_status("idle", ""); + return; + } + session.push_status("connecting", ""); + match connect_and_run(&mut session, &mut rx, &mut stop_rx, &mut backoff).await { + Outcome::Stopped => { + session.push_status("idle", ""); + return; + } + Outcome::AuthFailed(msg) => { + crate::logger::log_error("smarthome", &format!("实时连接鉴权失败:{msg}")); + session.push_status("authFailed", msg); + return; + } + Outcome::Lost(msg) => { + crate::logger::log_warn("smarthome", &format!("实时连接断开:{msg}")); + session.push_status("disconnected", msg); + session.reset_state(); + tokio::select! { + _ = stop_rx.changed() => {} + _ = tokio::time::sleep(backoff) => {} + } + backoff = std::cmp::min(backoff * 2, Duration::from_secs(MAX_BACKOFF_SECS)); + } + } + } +} + +async fn connect_and_run( + session: &mut Session, + rx: &mut mpsc::UnboundedReceiver, + stop_rx: &mut watch::Receiver, + backoff: &mut Duration, +) -> Outcome { + let started = Instant::now(); + let mut stream: WsStream = match tokio_tungstenite::connect_async(session.cfg.ws_url.as_str()) + .await + { + Ok((s, _resp)) => s, + Err(e) => return Outcome::Lost(format!("建立 WebSocket 失败:{e}")), + }; + + // ---- 握手:等 auth_required ---- + let hello = match timeout_json( + wait_for_type(&mut stream, "auth_required"), + HANDSHAKE_TIMEOUT_SECS, + "等待 Home Assistant 握手", + ) + .await + { + Ok(Ok(v)) => v, + Ok(Err(e)) | Err(e) => return Outcome::Lost(e), + }; + if hello.get("type").and_then(|x| x.as_str()) != Some("auth_required") { + return Outcome::Lost("握手消息类型异常".to_string()); + } + + // ---- 鉴权 ---- + let auth = json!({ "type": "auth", "access_token": session.cfg.token }); + if let Err(e) = stream.send(Message::Text(auth.to_string())).await { + return Outcome::Lost(format!("发送鉴权消息失败:{e}")); + } + let result = match timeout_json( + wait_for_any(&mut stream, &["auth_ok", "auth_invalid"]), + HANDSHAKE_TIMEOUT_SECS, + "等待鉴权结果", + ) + .await + { + Ok(Ok(v)) => v, + Ok(Err(e)) | Err(e) => return Outcome::Lost(e), + }; + match result.get("type").and_then(|x| x.as_str()) { + Some("auth_ok") => {} + Some("auth_invalid") => { + return Outcome::AuthFailed(error_message(&result)); + } + _ => return Outcome::Lost("鉴权应答类型异常".to_string()), + } + + session.push_status("connected", ""); + crate::logger::log_info("smarthome", "实时连接已建立(WebSocket 已鉴权)"); + + // ---- 拆分读写两半,进入主循环 ---- + let (mut write, mut read) = stream.split(); + + // 订阅全实体(省略 entity_ids = 全量;首帧就是完整快照) + session + .send_fire_and_forget(&mut write, json!({ "type": "subscribe_entities" })) + .await; + + let mut ping_at = tokio::time::Instant::now() + Duration::from_secs(PING_SECS); + let mut flush_at = tokio::time::Instant::now() + Duration::from_millis(AGG_MS); + let mut last_rx = tokio::time::Instant::now(); + + let outcome = loop { + tokio::select! { + _ = stop_rx.changed() => break Outcome::Stopped, + out = rx.recv() => match out { + Some(text) => { + if let Err(e) = write.send(Message::Text(text)).await { + break Outcome::Lost(format!("发送实时命令失败:{e}")); + } + } + None => break Outcome::Stopped, + }, + msg = read.next() => match msg { + Some(Ok(Message::Text(text))) => { + last_rx = tokio::time::Instant::now(); + session.note_event(); + session.on_text(&text); + } + Some(Ok(Message::Binary(_))) => {} + Some(Ok(Message::Ping(payload))) => { + // 协议级 ping 必须回 pong,否则服务端会判为死连接 + let _ = write.send(Message::Pong(payload)).await; + } + Some(Ok(Message::Close(_))) => break Outcome::Lost("服务端关闭了连接".to_string()), + Some(Ok(_)) => {} + Some(Err(e)) => break Outcome::Lost(format!("WebSocket 读取失败:{e}")), + None => break Outcome::Lost("WebSocket 已断开".to_string()), + }, + _ = tokio::time::sleep_until(ping_at) => { + ping_at += Duration::from_secs(PING_SECS); + session.send_fire_and_forget(&mut write, json!({ "type": "ping" })).await; + if last_rx.elapsed() > Duration::from_secs(STALE_SECS) { + break Outcome::Lost(format!( + "{} 秒未收到任何消息(连接可能已被中间设备半开)", + STALE_SECS + )); + } + } + _ = tokio::time::sleep_until(flush_at) => { + flush_at += Duration::from_millis(AGG_MS); + session.flush(); + } + } + }; + + // 连上后稳定存活过一段时间才算"这次连接是成功的":否则"连上即断"会变成 + // 1s 一次的重连风暴(真机上半开连接就是这种表现) + if started.elapsed() >= Duration::from_secs(STABLE_CONNECT_SECS) { + *backoff = Duration::from_secs(1); + } + outcome +} + +// ============================== 小工具 ============================== + +fn now_secs() -> i64 { + chrono::Utc::now().timestamp() +} + +/// 事件 / 应答里的可读错误信息。 +fn error_message(v: &Value) -> String { + v.get("error") + .and_then(|e| e.get("message")) + .and_then(|m| m.as_str()) + .or_else(|| v.get("message").and_then(|m| m.as_str())) + .map(|s| s.to_string()) + .unwrap_or_else(|| "Home Assistant 拒绝了这条实时命令".to_string()) +} + +/// 粗略估算一条消息的 KB 数(只用于日志,不值得精确序列化)。 +fn approx_kb(v: &Value) -> usize { + v.to_string().len() / 1024 +} + +/// 紧凑状态里的时间戳。 +/// +/// HA 的紧凑形态是 `c` = `last_changed`、`lc` = `last_updated`; +/// 个别版本在变化帧里只带 `lc`,所以这里按 `c` → `lc` → `lu` 兜底取用。 +/// 两者都是时间戳,最坏情况是"x 分钟前"差一点,不影响状态本身。 +fn last_changed_of(obj: &Value) -> String { + for key in ["c", "lc", "lu"] { + if let Some(s) = obj.get(key).and_then(|x| x.as_str()) { + if !s.is_empty() { + return s.to_string(); + } + } + } + String::new() +} + +/// 原始状态 → 精简摘要(与 REST 路径共用同一份推导逻辑,见 `client::to_summary`)。 +fn summary_of(entity_id: &str, raw: &RawEntity) -> EntitySummary { + client::to_summary(RawState { + entity_id: entity_id.to_string(), + state: raw.state.clone(), + attributes: Value::Object(raw.attrs.clone()), + last_changed: raw.last_changed.clone(), + }) +} + +/// 带超时的等待(把两个 Result 层级压平成一个)。 +async fn timeout_json( + fut: impl std::future::Future>, + secs: u64, + what: &str, +) -> Result, String> { + match tokio::time::timeout(Duration::from_secs(secs), fut).await { + Ok(r) => Ok(r), + Err(_) => Err(format!("{what}超时")), + } +} + +/// 读到指定 `type` 的消息为止(其余消息按协议回 pong / 跳过)。 +async fn wait_for_type(stream: &mut WsStream, want: &str) -> Result { + wait_for_any(stream, &[want]).await +} + +async fn wait_for_any(stream: &mut WsStream, want: &[&str]) -> Result { + loop { + match stream.next().await { + Some(Ok(Message::Text(text))) => { + let Ok(v) = serde_json::from_str::(&text) else { + continue; + }; + let ty = v.get("type").and_then(|x| x.as_str()).unwrap_or(""); + if want.contains(&ty) { + return Ok(v); + } + } + Some(Ok(Message::Ping(payload))) => { + let _ = stream.send(Message::Pong(payload)).await; + } + Some(Ok(Message::Close(_))) | None => { + return Err("连接被服务端关闭".to_string()); + } + Some(Err(e)) => return Err(format!("WebSocket 读取失败:{e}")), + _ => {} + } + } +} + +/// 供 `commands` 复用的等待超时。 +pub fn request_timeout() -> Duration { + Duration::from_secs(REQUEST_TIMEOUT_SECS) +} diff --git a/src/components/layout/Sidebar.vue b/src/components/layout/Sidebar.vue index 9c31e1a..5f0525f 100644 --- a/src/components/layout/Sidebar.vue +++ b/src/components/layout/Sidebar.vue @@ -24,50 +24,65 @@ const displayModules = computed(() => { class="w-17 shrink-0 flex flex-col items-center py-4 border-r border-border transition-[background-color,border-color] duration-300" :style="{ backgroundColor: 'var(--effect-bg)', backdropFilter: 'var(--effect-blur)' }" > -
-
- - - - - -

{{ module.name }}

-
-
+ + -
- - - - - - -

常规设置

-
-
+ +
+ + + + + +

常规设置

+
+
+
+ + diff --git a/src/lib/bindings.ts b/src/lib/bindings.ts index 1eee23c..66cc087 100644 --- a/src/lib/bindings.ts +++ b/src/lib/bindings.ts @@ -98,6 +98,25 @@ export const commands = { quickpanelClearAppIconCache: () => __TAURI_INVOKE("quickpanel_clear_app_icon_cache"), /** 在资源管理器中显示文件(选中) */ quickpanelRevealInExplorer: (path: string) => __TAURI_INVOKE("quickpanel_reveal_in_explorer", { path }), + /** + * 在资源管理器中定位文件(选中)并**进入重命名编辑状态**。 + * + * # 为什么不用 `explorer.exe /select,` + * + * 本仓原先的定位做法是 `ShellExecuteW("explorer.exe", "/select,\"path\"")`。 + * 那条命令行在 Win10/11 上**经常新开一个窗口**而不是复用用户已经打开的那个 + * (尤其目标文件夹已通过标签页 / 其他窗口打开时)—— 表现就是"点保存后又弹出 + * 一个资源管理器打开了这个文件夹"。`SHOpenFolderAndSelectItems` 才是 shell 为此 + * 提供的 API:复用已有窗口、滚到条目并选中,随后该窗口即为前台窗口。 + * + * 重命名仍然只能借 Explorer 自己的快捷键 F2 —— shell 没有"开始重命名"的 API。 + * + * `spawn_blocking`:命令里有 sleep;同时 shell 调用要求 **STA** 线程,而 async 命令 + * 跑在 tokio 工作线程(MTA)上 —— 所以在工作线程里自己 + * `CoInitializeEx(APARTMENTTHREADED)`(与 `quickpanel::explorer` 同一做法), + * 既不占 IPC 线程,也不依赖命令所在线程的既有套间模型。 + */ + quickpanelRevealInExplorerRename: (path: string) => __TAURI_INVOKE("quickpanel_reveal_in_explorer_rename", { path }), /** * 用系统默认程序打开文件/文件夹。 * - 目录:explorer.exe 直接打开(修复索引目录点击后未打开的问题) @@ -1164,6 +1183,101 @@ export const commands = { * 「清空快捷键」也能通过传空串生效)—— 同 `editor_save_settings`。 */ diffSaveSettings: (settings: DiffSettings) => __TAURI_INVOKE("diff_save_settings", { settings }), + /** 读取模块设置视图(连接列表 + 偏好;令牌只有掩码)。 */ + smarthomeGetSettings: () => __TAURI_INVOKE("smarthome_get_settings"), + /** + * 新建或更新一条连接(令牌**不在**此命令里,见 `smarthome_set_token`)。 + * + * 地址可能刚被改动,已建立的实时连接仍粘在旧端点上 → 重连一次(P4)。 + */ + smarthomeSaveConnection: (input: HaConnectionInput) => __TAURI_INVOKE("smarthome_save_connection", { input }), + /** + * 写入长期访问令牌(进系统凭据管理器,**不落 settings.json**)。 + * + * 令牌换了,已经建立的实时连接用的还是旧令牌 → 重连一次。 + */ + smarthomeSetToken: (connId: string, token: string) => __TAURI_INVOKE("smarthome_set_token", { connId, token }), + /** 清除令牌(连接本身保留)。 */ + smarthomeClearToken: (connId: string) => __TAURI_INVOKE("smarthome_clear_token", { connId }), + /** 删除一条连接(连带清除它的令牌)。 */ + smarthomeDeleteConnection: (connId: string) => __TAURI_INVOKE("smarthome_delete_connection", { connId }), + /** 切换激活连接。 */ + smarthomeActivateConnection: (connId: string) => __TAURI_INVOKE("smarthome_activate_connection", { connId }), + /** + * 修改端点选择策略(auto / local / remote)。 + * + * 策略变了,实时连接也应当按新策略重新选端点 → 重连一次。 + */ + smarthomeSetEndpointMode: (connId: string, mode: EndpointMode) => __TAURI_INVOKE("smarthome_set_endpoint_mode", { connId, mode }), + /** + * 测试连接:**逐个地址**探测,每个地址各给一条结果。 + * + * `token` 留空时回落到该连接已存的令牌(编辑连接时不必重输)。 + * 草案也能直接测(不必先保存)——`input.id` 为空只是没有回落令牌可用。 + */ + smarthomeTestConnection: (input: HaConnectionInput, token: string) => __TAURI_INVOKE("smarthome_test_connection", { input, token }), + /** 检测当前链路:按端点策略**强制新探测**一次,返回实际使用的地址与耗时。 */ + smarthomeCheckLink: (connId: string) => __TAURI_INVOKE("smarthome_check_link", { connId }), + /** + * 拉取实体列表(精简视图)。 + * + * `force = false` 且内存缓存未过期(60s)时直接返回缓存 —— 在反代链路上, + * 每次切回设备页都重新拉几百 KB 是明显的浪费(§5.2)。 + */ + smarthomeListEntities: (connId: string, force: boolean) => __TAURI_INVOKE("smarthome_list_entities", { connId, force }), + /** + * 保存界面偏好(自动刷新间隔 / 收藏等)。 + * + * 整体覆盖写入:偏好字段少且同屏修改,没必要为每个开关单开一条命令 + * (多命令各自的字段同步反倒容易漏)。 + * + * 注意:**实时推送开关不在 `ui` 里**(它在 `settings.realtime`), + * 因此这里不碰实时连接;收藏 / 自动刷新这类改动不该引起重连。 + */ + smarthomeSaveUiSettings: (ui: HaUiSettings) => __TAURI_INVOKE("smarthome_save_ui_settings", { ui }), + /** + * 调用设备服务(控制)。 + * + * 前端流程(§5.3):乐观更新 → 本命令 → **若响应带回新状态就直接采用**(省一次往返), + * 否则在分级窗口后调 `smarthome_get_entity` 校正。 + */ + smarthomeCallService: (connId: string, domain: string, service: string, entityId: string, params: ServiceParams) => __TAURI_INVOKE("smarthome_call_service", { connId, domain, service, entityId, params }), + /** 取单个实体状态(控制后的校正用,不是常规路径)。 */ + smarthomeGetEntity: (connId: string, entityId: string) => __TAURI_INVOKE("smarthome_get_entity", { connId, entityId }), + /** + * 开关实时推送(WebSocket)。 + * + * 打开 = 建立 WS(设备状态不再依赖手动刷新);关闭 = 断开。 + * **本地规则也依赖它**:只要规则总开关开着,关掉推送 Rust 侧仍会保持连接 + * (见 `HaManager::sync_ws`)—— 规则没连接永远不会触发。 + */ + smarthomeSetRealtimeEnabled: (enabled: boolean) => __TAURI_INVOKE("smarthome_set_realtime_enabled", { enabled }), + /** 启动实时连接(显式动作)。 */ + smarthomeWsStart: (connId: string) => __TAURI_INVOKE("smarthome_ws_start", { connId }), + /** 停止实时连接(**不改持久化开关**:设置页的开关走 `smarthome_set_realtime_enabled`)。 */ + smarthomeWsStop: () => __TAURI_INVOKE("smarthome_ws_stop"), + /** 当前实时连接状态(诊断用)。 */ + smarthomeWsStatus: () => __TAURI_INVOKE("smarthome_ws_status"), + /** + * 拉取区域 / 设备 / 实体注册表,返回 `entity_id → area_id`(三级回退已算好)。 + * + * **需要实时连接**:注册表只能通过 WebSocket 查(plan §0.4),因此这里显式依赖 + * `smarthome_ws_start` 已经连上;没连上就给出可操作的错误文案(不是笼统的"失败")。 + */ + smarthomeListRegistry: (connId: string, force: boolean) => __TAURI_INVOKE("smarthome_list_registry", { connId, force }), + /** 规则列表(含总开关与最近运行记录)。 */ + smarthomeListRules: () => __TAURI_INVOKE("smarthome_list_rules"), + /** + * 新建或更新一条规则。 + * + * **动作的合法性只在 Rust 侧判定一次**(`automation::validate`):前端可以少校验, + * 但"能不能真的执行"这套规则必须只有一份。 + */ + smarthomeSaveRule: (rule: Rule) => __TAURI_INVOKE("smarthome_save_rule", { rule }), + /** 删除一条规则。 */ + smarthomeDeleteRule: (ruleId: string) => __TAURI_INVOKE("smarthome_delete_rule", { ruleId }), + /** 规则总开关(关掉后所有规则都不求值,规则本身保留)。 */ + smarthomeSetRulesEnabled: (enabled: boolean) => __TAURI_INVOKE("smarthome_set_rules_enabled", { enabled }), /** * 设置某个窗口的任务栏身份(独立 AUMID + 组合图标)。 * @@ -2045,6 +2159,50 @@ export type EditorSettings = { recentFolders?: RecentEntry[], }; +/** 端点(链路)类型。 */ +export type EndpointKind = +/** 局域网直连 */ +"local" | +/** 反代(Cloudflare Tunnel 等) */ +"remote"; + +/** + * 端点选择策略。 + * + * 探测顺序与超时见 `client.rs` 的常量;`auto` 是「先短超时试局域网、失败再试反代」, + * 而不是「优先上次成功的端点」—— 后者会把人困在反代上:回家后反代仍然可用, + * 就永远不会切回局域网(§3.7-a)。 + */ +export type EndpointMode = +/** 自动(局域网优先,反代兜底) */ +"auto" | +/** 强制局域网 */ +"local" | +/** 强制反代 */ +"remote"; + +/** + * 单个地址的探测结果(「测试连接」逐地址返回)。 + * + * 逐地址给结果而不是一个笼统的成功/失败:用户在外面测时,局域网失败是**预期内**的, + * 只有把两条链路的结果分开呈现,这个信息才有用(§5.1)。 + */ +export type EndpointProbe = { + url: string, + kind: EndpointKind, + ok: boolean, + haVersion: string, + locationName: string, + /** 实例的温度单位(见 `HaConnection::temperature_unit`) */ + temperatureUnit: string, + /** 耗时(毫秒):既是诊断信息,也是"反代比局域网慢多少"的直觉来源 */ + elapsedMs: number, + /** 失败原因(中文可读) */ + error: string | null, + /** 失败分类:auth | network | server | other(前端据此决定是否提示"重填令牌") */ + errorKind: string | null, +}; + /** * 引擎连通性自检结果。 * @@ -2079,6 +2237,114 @@ export type EngineView = { issue: string | null, }; +/** 实体列表结果。 */ +export type EntityListResult = { + entities: EntitySummary[], + /** + * 抓取时间(unix 秒)。"更新于 x 秒前"必须用它 —— 那是**服务端数据的时刻**, + * 而不是前端收到响应的时刻。 + */ + fetchedAt: number, + /** true = 命中内存缓存,未重新请求 */ + fromCache: boolean, +}; + +/** 实体注册表条目(**设备聚合的唯一来源**:REST 的 `/api/states` 里没有 device_id)。 */ +export type EntityRegistryEntry = { + entityId: string, + /** 空 = 未归组到设备(真机上是 `person` / `todo` 这类) */ + deviceId: string, + /** 注册表里的名字(小米集成上**大量为空**,因此只作兜底) */ + name: string, + /** 集成给的原始名字 */ + originalName: string, + /** + * `""` | `config` | `diagnostic` —— HA 官方标记的"高级 / 配置"类实体。 + * + * 真机上只有 30/606 条有值,所以它只是"三级"的**判据之一**,不是全部。 + */ + entityCategory: string, +}; + +/** + * 实体摘要(发给前端的**精简结构**)。 + * + * 只带前端**要显示**的字段。完整 `attributes` 因 domain 而异(灯有 + * `supported_color_modes`、窗帘有 `current_position`、气候有 `hvac_modes`…), + * 几百个实体整份过 IPC 会让序列化与前端响应式都明显变重(§6.1)。 + * + * 「是否可控 / 分组 / 图标 / 状态文案」这类**表现层语义由前端 `format.ts` 决定**, + * 不在这里算 —— Rust 侧只负责"协议 → 数据的忠实搬运"。 + */ +export type EntitySummary = { + entityId: string, + /** `entity_id` 的前半段(light / switch / sensor…) */ + domain: string, + /** `friendly_name`,缺失时回落 `entity_id` */ + name: string, + /** 原始状态字符串:`on` / `off` / `24.5` / `unavailable` / `unknown` … */ + state: string, + /** `state` 可解析为数字时的数值(sensor 这类读数就在 `state` 里) */ + numeric: number | null, + /** `unit_of_measurement` */ + unit: string, + /** `device_class`(binary_sensor / sensor 的语义细分) */ + deviceClass: string, + /** 灯亮度 0–255 */ + brightness: number | null, + /** 窗帘当前位置 0–100 */ + position: number | null, + /** 空调目标温度 */ + targetTemp: number | null, + /** + * 空调可设的上下限(**单位随系统单位制**,如美制是 61–86 °F)。 + * 控件必须用它,不能自己写死 5–35 —— 美制下 77 会被钳成 35(真机踩到过)。 + */ + minTemp: number | null, + maxTemp: number | null, + /** 空调当前温度(室温) */ + currentTemp: number | null, + /** 最后变化时间(HA 的 ISO8601 串,前端格式化成相对时间) */ + lastChanged: string, + /** + * `attributes.last_triggered` —— 自动化 / 脚本的"上次触发时间"(空 = 从未触发)。 + * P3 的自动化列表要靠它回答"这条规则最近到底跑没跑"。 + */ + lastTriggered: string, + /** + * HA 的 `supported_features` 位掩码。**语义按 domain 不同**(窗帘 OPEN/CLOSE/…、 + * 气候 TARGET_TEMPERATURE/…),因此这里原样透传,由前端按 domain 解释。 + */ + supportedFeatures: number, + /** + * 灯的 `supported_color_modes`(`onoff` / `brightness` / `color_temp` / `hs` …)。 + * 判断"能不能调亮度 / 色温"必须用它,而不是 `supported_features` 的旧位约定。 + */ + supportedColorModes: string[], + /** 色温可调范围(灯) */ + minColorTempKelvin: number | null, + maxColorTempKelvin: number | null, + /** + * 当前色温(灯)。**必须有**:没有它,色温滑杆只能猜一个初始位置, + * 那就成了一个会骗人的控件。 + */ + colorTempKelvin: number | null, + /** 空调可选模式(cool / heat / off / auto …) */ + hvacModes: string[], + /** 空调温度步进(0.5 / 1) */ + targetTempStep: number | null, + /** 媒体播放器音量 0.0–1.0 */ + volumeLevel: number | null, + /** 风扇档位 0–100 */ + percentage: number | null, + /** `number` 实体的可设上下限与步长(各集成差异极大:0–100 音量、10–90 变焦、步长 180 的翻转角) */ + min: number | null, + max: number | null, + step: number | null, + /** `select` 实体的可选项 */ + options: string[], +}; + export type EnvVar = { key?: string, value?: string, @@ -2194,6 +2460,113 @@ export type FingerprintChange = { accepted?: boolean, }; +/** + * 命令层错误:带分类。 + * + * 前端据此区分"重填令牌"(`auth`,重试无意义)与"重试 / 检查地址" + * (`network` / `config`)—— **分类判定留在 Rust 侧**,不让前端靠匹配错误文案猜(§3.6)。 + * 这是本项目第一个不用 `String` 作错误类型的命令模块;理由见 §9.1。 + */ +export type HaApiError = { + /** auth | network | config | server | other */ + kind: string, + message: string, +}; + +/** 区域(房间)。 */ +export type HaArea = { + areaId: string, + name: string, +}; + +/** 前端提交的连接草案(新建或编辑)。令牌**不在此结构里**,走独立命令写入凭据库。 */ +export type HaConnectionInput = { + /** 空 = 新建 */ + id?: string, + name?: string, + localUrl?: string, + remoteUrl?: string, + endpointMode?: EndpointMode, + insecure?: boolean, +}; + +/** 发给前端的连接视图:**不含明文令牌**,只有掩码与"是否已配置"。 */ +export type HaConnectionView = { + id: string, + name: string, + localUrl: string, + remoteUrl: string, + endpointMode: EndpointMode, + insecure: boolean, + hasToken: boolean, + /** 掩码(`secrets::mask`):长度不足 8 时整串打码,绝不泄露完整明文 */ + tokenMasked: string, + lastOkUrl: string, + lastOkAt: number, + haVersion: string, + locationName: string, + /** 温度单位(`°C` / `°F`)—— climate 的温度显示必须用它 */ + temperatureUnit: string, + /** 本次会话实际使用的端点(未探测过为 null) */ + endpointUrl: string | null, + endpointKind: EndpointKind | null, + /** 该端点最近一次实测耗时(毫秒) */ + endpointLatencyMs: number | null, +}; + +/** 设备(设备聚合与详情页头部所需的最小字段集合)。 */ +export type HaDevice = { + id: string, + name: string, + /** 用户在 HA 里改过的名字(为空时用 `name`) */ + nameByUser: string, + /** 空 = 未分配房间 */ + areaId: string, + /** 厂商 / 型号(详情页头部显示,便于认出是哪台设备) */ + manufacturer: string, + model: string, +}; + +/** 实时推送配置(P4 才真正使用;P0 只落字段,避免以后升级设置结构)。 */ +export type HaRealtimeSettings = { + /** 是否启用 WebSocket 实时推送 */ + enabled?: boolean, + /** 上次连接成功时间(unix 秒,0 = 从未) */ + lastConnectedAt?: number, +}; + +/** + * 保存连接的结果:**回传 id**(新建时前端要靠它接着写令牌,按名称/地址反查不可靠), + * 外加刷新后的整份视图。 + */ +export type HaSaveConnectionResult = { + id: string, + settings: HaSettingsView, +}; + +/** 模块设置视图。 */ +export type HaSettingsView = { + version: number, + activeId: string, + connections: HaConnectionView[], + ui: HaUiSettings, + realtime: HaRealtimeSettings, +}; + +/** 界面与行为偏好。 */ +export type HaUiSettings = { + /** 自动刷新间隔(秒),0 = 关闭 */ + autoRefreshSec?: number, + /** 不展示的 domain(如 `sensor` 太多时可隐藏) */ + hiddenDomains?: string[], + /** 不展示的具体实体 */ + hiddenEntityIds?: string[], + /** 收藏(置顶) */ + favoriteEntityIds?: string[], + /** 危险操作(解锁 / 开门 / 全开)二次确认 */ + confirmDangerous?: boolean, +}; + /** 一条历史记录 */ export type HistoryItem = { id: number, @@ -2444,6 +2817,24 @@ export type LinkEdge = { to: string, }; +/** + * 当前链路信息(诊断区)。 + * + * 失败时 `url` / `kind` 也可能为空 —— 例如 `auto` 模式下两个地址都不可达, + * 这时没有"当前链路"可言,只能把失败原因(包含每个地址的尝试结果)交给前端展示。 + */ +export type LinkInfo = { + url: string | null, + kind: EndpointKind | null, + ok: boolean, + /** 成功时:该端点实测耗时(毫秒)。失败时为 0 */ + latencyMs: number, + /** 失败原因(含各候选地址的尝试结果) */ + error: string | null, + /** 失败分类:auth | network | config(前端据此决定提示"重填令牌"还是"重试") */ + errorKind: string | null, +}; + /** 目录列举结果。 */ export type LocalDir = { /** 规范化之后的目录(`canonicalize` 结果,已去掉 Windows 的 `\\?\` 前缀) */ @@ -2965,6 +3356,24 @@ export type RecentEntry = { exists?: boolean, }; +/** + * 注册表查询结果(房间分组 + 设备聚合的唯一来源)。 + * + * **真机修正(§9.5-1)**:目标实例上实体级 `area_id` 全空,房间归属在设备上, + * 因此 `entity_areas` 已按「实体 → 设备 → 区域」三级回退算好;仍未解析到的不进表 + * (前端把它归入「未分配房间」,这是必需的分组而不是兜底)。 + */ +export type RegistryResult = { + areas: HaArea[], + devices: HaDevice[], + /** `entity_id` → `area_id` */ + entityAreas: { [key in string]: string }, + /** 实体注册表(`entity_id` → 设备 / 名字 / 分类) */ + entityRegistry: EntityRegistryEntry[], + /** 抓取时间(unix 秒) */ + fetchedAt: number, +}; + /** 远程配置(§5.1 命令 `remote_get_config` / `remote_set_enabled`)。 */ export type RemoteConfig = { /** 开关(持久化) */ @@ -3031,6 +3440,94 @@ export type RenameResult = { error: string, }; +/** 一条本地规则。 */ +export type Rule = { + id?: string, + name?: string, + enabled?: boolean, + trigger?: RuleTrigger, + conditions?: RuleCondition[], + actions?: RuleAction[], + /** 冷却秒数:窗口内的重复触发直接丢弃(护栏 1) */ + cooldownSec?: number, + /** 上次触发时间(unix 秒,0 = 从未) */ + lastFiredAt?: number, + /** 累计触发次数 */ + fireCount?: number, + /** 上次失败原因(空 = 上次正常) */ + lastError?: string, +}; + +/** 规则动作段(顺序执行)。 */ +export type RuleAction = { + /** service | delay | notify */ + kind?: string, + /** `service`:domain / service / 目标实体 */ + domain?: string, + service?: string, + entityId?: string, + params?: ServiceParams, + /** `delay`:秒(上限见 `automation::MAX_DELAY_SEC`) */ + seconds?: number, + /** `notify`:标题与正文 */ + title?: string, + message?: string, +}; + +/** 规则条件段(全部 AND)。 */ +export type RuleCondition = { + /** state | time */ + kind?: string, + /** `state` 条件:实体 id */ + entityId?: string, + /** `state` 条件:要求的状态 */ + state?: string, + /** `time` 条件:起始 `HH:MM` */ + fromTime?: string, + /** `time` 条件:结束 `HH:MM`(跨零点时 `to < from` 视为跨天) */ + toTime?: string, + /** `time` 条件:星期(1=周一 … 7=周日;空 = 每天) */ + weekdays?: number[], +}; + +/** + * 规则列表结果(含总开关与最近运行记录)。 + * + * 计划 §6.2 只列了 `Rule[]`,这里把「总开关 + 最近记录」并进同一个返回: + * 自动化页进来就要用这三样,拆成三条命令只是多两次往返。 + */ +export type RuleListResult = { + /** 规则总开关(关掉后所有规则都不求值) */ + enabled: boolean, + rules: Rule[], + /** 最近运行记录(新的在前,最多 `automation::MAX_RECORDS` 条;仅本次运行期内有) */ + records: RuleRecord[], +}; + +/** 规则运行记录(内存里保留最近 `automation::MAX_RECORDS` 条)。 */ +export type RuleRecord = { + ruleId: string, + ruleName: string, + at: number, + ok: boolean, + detail: string, +}; + +/** 规则触发段(线性三段式的第一段)。 */ +export type RuleTrigger = { + entityId?: string, + /** 命中这些状态才触发(空 = 任意变化) */ + to?: string[], + /** 仅当从这些状态变化而来(空 = 不限) */ + from?: string[], + /** 持续 N 秒仍然满足才触发(0 = 立即;用于去抖) */ + forSec?: number, + /** 数值比较运算符(空 = 不做数值判断;否则 `>` `>=` `<` `<=` `==` `!=`) */ + numericOp?: string, + /** 数值比较的阈值 */ + numericValue?: number | null, +}; + /** `music_decrypt_scan` 的返回(前端零手写类型) */ export type ScanSummary = { total: number, @@ -3149,6 +3646,45 @@ export type SelectionSettings = { blacklist?: string[], }; +/** 服务调用结果。 */ +export type ServiceCallResult = { + /** + * HA 在 `200` 响应体里带回的**已变化实体**新状态(已转成精简结构)。 + * + * **可能为空**:部分集成(尤其走云端的设备)是"发完就返回",状态要稍后才反映。 + * 前端据此决定"直接采用服务端结果"还是"等分级窗口后重拉一次"(§9.3)。 + */ + entities: EntitySummary[], +}; + +/** + * 服务调用的可选参数。 + * + * **用固定字段而不是 `serde_json::Value`**:specta 无法为 `Value` 生成类型 + * (见 lib.rs 的豁免清单);而且固定字段顺带把"能传什么参数"限死了, + * 前端不可能把任意键塞进 HA 的 `service_data`。 + */ +export type ServiceParams = { + /** 灯亮度百分比 0–100(HA 侧换算成 `brightness`) */ + brightnessPct?: number | null, + /** 色温(开尔文) */ + colorTempKelvin?: number | null, + /** 窗帘位置 0–100 */ + position?: number | null, + /** 空调目标温度 */ + temperature?: number | null, + /** 空调模式(`cool` / `heat` / `off` …) */ + hvacMode?: string | null, + /** 风扇档位 0–100 */ + percentage?: number | null, + /** 媒体音量 0.0–1.0 */ + volumeLevel?: number | null, + /** `number.set_value` 的目标值 */ + value?: number | null, + /** `select.select_option` 的目标项 */ + option?: string | null, +}; + /** 会话元信息(回传前端;**不含任何 I/O 句柄**)。 */ export type SessionInfo = { id: string, @@ -3742,3 +4278,18 @@ export type WindowInfo = { visualRect: ScreenRect | null, }; +/** WebSocket 连接状态(`smarthome_ws_status` 的返回,也是 `smarthome-connection-status` 的载荷)。 */ +export type WsStatus = { + connId: string, + /** idle | connecting | connected | authFailed | disconnected */ + state: string, + /** 失败原因 / 补充说明(正常时为空) */ + detail: string, + /** 本次连上的时间(unix 秒,0 = 未连上) */ + connectedAt: number, + /** 最近一次收到服务端消息的时间(unix 秒)—— 半开连接靠它判断 */ + lastEventAt: number, + /** 已订阅到的实体数(`subscribe_entities` 首帧后写入) */ + entityCount: number, +}; + diff --git a/src/modules/editor/EditorWindow.vue b/src/modules/editor/EditorWindow.vue index c13422d..1cf6f2d 100644 --- a/src/modules/editor/EditorWindow.vue +++ b/src/modules/editor/EditorWindow.vue @@ -1119,7 +1119,7 @@ async function saveThenRedecode(): Promise { - +
@@ -1141,19 +1141,6 @@ async function saveThenRedecode(): Promise { @open-search="openSearch(searchDir ? 'dir' : 'library')" /> - - -
{ @replaced="onPathReplaced" /> + +
+
+ + +
@@ -1255,13 +1260,16 @@ async function saveThenRedecode(): Promise {
+
+
+
@@ -1285,8 +1293,7 @@ async function saveThenRedecode(): Promise { class="min-h-0 flex-1" />
- - +
diff --git a/src/modules/editor/components/EditorHost.vue b/src/modules/editor/components/EditorHost.vue index 2dcd1eb..d60d244 100644 --- a/src/modules/editor/components/EditorHost.vue +++ b/src/modules/editor/components/EditorHost.vue @@ -30,14 +30,13 @@ import { createEditorState, jumpToPosition, reconfigureEditor, - replaceDoc, setLanguageExtension, type EditorConfig } from '../editor/core' import { editorBackground } from '../editor/themes' import { createLogger } from '@/lib/logger' import type { LanguageLoader } from '../editor/languages' -import type { Extension } from '@codemirror/state' +import type { EditorState, Extension } from '@codemirror/state' const logger = createLogger('editor') @@ -104,13 +103,29 @@ const hostBackground = computed(() => let view: EditorView | null = null let autosaveTimer: ReturnType | null = null -/** 程序化替换文档期间抑制「变更 → 置脏」 */ -let applyingDoc = false /** 已应用的文档版本,避免重复整篇替换 */ let appliedRevision = -1 /** 语言令牌:丢弃过期的异步加载结果(与 store 里的令牌是两层保险) */ let languageSeq = 0 +/** + * 每个标签自己的 EditorState(撤销历史随标签保留)。 + * + * CM6 的撤销历史挂在 **EditorState 的字段**上,没有「只导出历史」的公开 API,因此 + * 「按标签保存撤销历史」就等于「按标签保存整个 state」:切换标签时把当前 state + * 收进缓存、把目标标签的 state 装回同一个 `EditorView`。缓存只保留仍打开的标签 + * (见下方按标签集合的清理 watch),关闭标签即释放。 + */ +const stateCache = new Map() +/** 当前 view 装载的是哪个标签的 state(空串 = 未绑定)。 */ +let boundKey = '' + +/** 当前面板的缓存键:主面板 = 活动标签,副面板 = 它绑定的标签。 */ +function paneKey(): string { + if (isPane.value) return props.tabId ?? '' + return store.activeTabId || '' +} + function currentConfig(): EditorConfig { const s = store.settings const large = paneLarge.value @@ -139,6 +154,35 @@ function currentConfig(): EditorConfig { } } +/** + * 构造一个**全新的**编辑器状态(初次装配 / 无法复用缓存时)。 + * + * # 为什么整篇装载必须换 state,而不是 dispatch 一次替换 + * + * CM6 的撤销历史是 `history()` 里的状态字段,按**同一个 EditorState** 记录。 + * 若用 `dispatch({changes: 全文替换})` 装载另一个文件,新文档会继承上一份文档的 + * 撤销栈:随后的 Ctrl+Z 就会把别的文件的历史改动「回退」进当前标签页。 + * `EditorView.setState` 会连同历史字段一起换成新的状态(焦点保留)。 + * + * 可复用的标签状态由 `stateCache` 提供(见上方);这里只负责「缓存不可用」的情形: + * 首次打开、或该标签的内容已在别处被改过(并排副面板编辑 / 外部重载)。 + */ +function buildState(doc: string): EditorState { + return createEditorState({ + doc, + config: currentConfig(), + onDocChanged: next => { + if (isPane.value && props.tabId) store.setTabContent(props.tabId, next) + else store.setContent(next) + scheduleAutosave() + }, + // 副面板的光标不该覆盖状态栏(状态栏跟随活动文档) + onSelectionChanged: (line, column) => { + if (!isPane.value) emit('cursor-moved', line, column) + } + }) +} + function scheduleAutosave(): void { const ms = store.settings.autosaveMs if (!ms) return @@ -180,29 +224,23 @@ onMounted(() => { if (!hostRef.value) return view = new EditorView({ parent: hostRef.value, - state: createEditorState({ - doc: paneContent.value, - config: currentConfig(), - onDocChanged: doc => { - if (applyingDoc) return - if (isPane.value && props.tabId) store.setTabContent(props.tabId, doc) - else store.setContent(doc) - scheduleAutosave() - }, - // 副面板的光标不该覆盖状态栏(状态栏跟随活动文档) - onSelectionChanged: (line, column) => { - if (!isPane.value) emit('cursor-moved', line, column) - } - }) + state: buildState(paneContent.value) }) + boundKey = paneKey() + if (boundKey) stateCache.set(boundKey, view.state) appliedRevision = paneRevision.value void applyLanguage(++languageSeq) }) /** - * 整篇装载(打开笔记 / 打开文件 / 重载):替换文档。 + * 整篇装载(切标签 / 打开笔记 / 打开文件 / 重载):换入目标文档的状态。 * * 用 `docRevision` 而不是路径:重载同一篇时路径没变,但内容必须被换掉。 + * + * 两条路: + * - **切标签**(缓存键变了)且该标签的缓存内容与当前内容一致 → 装回缓存 state, + * 撤销历史 / 选区随之保留; + * - 否则(首次打开、同标签重载、内容已在别处被改过)→ 重建全新 state。 */ watch( paneRevision, @@ -214,22 +252,63 @@ watch( } if (appliedRevision === revision) return appliedRevision = revision - // 目标光标行要在 replaceDoc **之前**取:替换会派发 selection 变化, - // updateListener 随即把 store.cursorLine 覆盖成 1,之后再读就只剩第 1 行了。 + + const key = paneKey() + const switching = key !== boundKey + // 离开当前文档前把它的 state 收回缓存(撤销历史 + 选区都在里面) + if (boundKey && switching) stateCache.set(boundKey, view.state) + + // 只复用「换到另一个标签」且内容对得上的缓存。内容不一致说明该标签在别处 + // 被改过(并排副面板编辑 / 外部重载),旧 state 的文档与撤销历史都不能再用。 + const cached = switching && key ? stateCache.get(key) : undefined + if (cached && cached.doc.toString() === paneContent.value) { + view.setState(cached) + boundKey = key + // 缓存期间设置可能变过:主题 / 排版 / Live Preview / wikilink 重新配置。 + // 语言不进 reconfigure(见 currentConfig 的注释),由下面的 applyLanguage 负责。 + try { + reconfigureEditor(view, currentConfig()) + } catch (e) { + logger.error(`恢复标签状态后重配置失败:${String(e)}`) + } + void applyLanguage(++languageSeq) + return + } + + // 目标光标行要在 setState **之前**取:新状态的 selection 变化会被 + // updateListener 回写成 1,之后再读就只剩第 1 行了。 const restoreLine = isPane.value ? 1 : store.cursorLine - applyingDoc = true - replaceDoc(view, paneContent.value) + // 重建状态而不是 dispatch 整篇替换:撤销历史必须随文档隔离(见 buildState) + view.setState(buildState(paneContent.value)) + boundKey = key + if (key) stateCache.set(key, view.state) // 标签切换 / 会话恢复:按 store.cursorLine 复位光标(默认第 1 行不动) if (restoreLine > 1) { const line = Math.min(restoreLine, view.state.doc.lines) const pos = view.state.doc.line(line).from view.dispatch({ selection: { anchor: pos }, scrollIntoView: false }) } - applyingDoc = false void applyLanguage(++languageSeq) } ) +/** + * 标签集合变化时丢掉已关闭标签的状态。 + * + * 每个缓存项持有一整份文档 + 撤销栈,不清理会随「开过多少文件」一直增长。 + * 副面板的缓存只有它自己绑定的那一个标签,同样随标签关闭失效。 + */ +watch( + () => store.tabs.map(t => t.id).join('\u0000'), + () => { + if (!stateCache.size) return + const alive = new Set(store.tabs.map(t => t.id)) + for (const key of stateCache.keys()) { + if (!alive.has(key)) stateCache.delete(key) + } + } +) + /** 语言变化(异步加载完成 / 切换到另一种语言)。 */ watch(paneLanguage, () => { void applyLanguage(++languageSeq) @@ -269,6 +348,8 @@ onBeforeUnmount(() => { flushAutosave() view?.destroy() view = null + stateCache.clear() + boundKey = '' }) defineExpose({ diff --git a/src/modules/editor/editor/core.ts b/src/modules/editor/editor/core.ts index a01a820..ca90bb3 100644 --- a/src/modules/editor/editor/core.ts +++ b/src/modules/editor/editor/core.ts @@ -230,15 +230,6 @@ export function setLanguageExtension(view: EditorView, extension: Extension | nu }) } -/** 用新文档整体替换(切换笔记 / 打开文件时)。 */ -export function replaceDoc(view: EditorView, doc: string): void { - view.dispatch({ - changes: { from: 0, to: view.state.doc.length, insert: doc }, - selection: { anchor: 0 }, - scrollIntoView: true - }) -} - /** * 把光标移到某个字符偏移并滚动到可见位置(大纲点击跳转用)。 * diff --git a/src/modules/icons.ts b/src/modules/icons.ts index e0b7176..ce83645 100644 --- a/src/modules/icons.ts +++ b/src/modules/icons.ts @@ -13,7 +13,8 @@ import { SquareTerminal, Bot, FileCode2, - Diff + Diff, + House } from '@lucide/vue' /** @@ -37,7 +38,8 @@ export const moduleIconMap: Record = { terminal: SquareTerminal, dsh: Bot, editor: FileCode2, - diff: Diff + diff: Diff, + smarthome: House } /** 获取模块图标组件,未找到时回退到 Settings 图标 */ diff --git a/src/modules/index.ts b/src/modules/index.ts index e1600c7..b586bfb 100644 --- a/src/modules/index.ts +++ b/src/modules/index.ts @@ -16,6 +16,7 @@ import { moduleConfig as terminal } from './terminal' import { moduleConfig as dsh } from './dsh' import { moduleConfig as editor } from './editor' import { moduleConfig as diff } from './diff' +import { moduleConfig as smarthome } from './smarthome' const allModules: ModuleConfig[] = [ proxy, @@ -31,7 +32,8 @@ const allModules: ModuleConfig[] = [ terminal, dsh, editor, - diff + diff, + smarthome ] // 启动时注册所有模块 diff --git a/src/modules/quickpanel/QuickPanel.vue b/src/modules/quickpanel/QuickPanel.vue index fffb32d..9772295 100644 --- a/src/modules/quickpanel/QuickPanel.vue +++ b/src/modules/quickpanel/QuickPanel.vue @@ -5,11 +5,12 @@ import { getCurrentWindow, LogicalSize, Effect, EffectState } from '@tauri-apps/ // Rust 端通过 tauri-specta 生成的命令绑定(bindings.ts) import { commands } from '@/lib/bindings' import type { ArchiveInfo, DeleteResult, ExtractResult, FileEntry, RenamePreview, RenameResult } from '@/lib/bindings' -import { Search, Command, Loader2, CornerDownLeft, Calculator, Globe, Lock, ChevronRight, ChevronLeft, ChevronDown, History, FolderOpen, Ruler, Trash2, Terminal, Archive as ArchiveIcon, Regex, FileText, Settings } from '@lucide/vue' +import { Search, Command, Loader2, CornerDownLeft, Calculator, Globe, Lock, ChevronRight, ChevronLeft, ChevronDown, History, FolderOpen, Ruler, Trash2, Terminal, Archive as ArchiveIcon, Regex, FileText, Settings, ImageDown, CircleAlert } from '@lucide/vue' import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip' import { Switch } from '@/components/ui/switch' import { aggregateSearch, loadAppIconsForResults, recordHistoryItem, getAllHistoryItems, setFileIndexReady, type QPItem, type QPSubAction } from './providers' import { EVENTS, STORAGE_KEYS } from '@/lib/constants' +import { latestCaptureCachePath, screenshotFileName } from '@/stores/screenshotStore' import { applyStoredAccent } from '@/lib/theme' import HistoryPicker from './HistoryPicker.vue' @@ -143,8 +144,14 @@ const renameResults = ref(null) const renameOkCount = ref(0) let renameTimer: ReturnType | null = null +// ===== 保存截图(联动截图模块) ===== +// 源是"最近一张截图"的历史缓存(完整 PNG 落盘在截图缓存目录,历史里只有缩略图), +// 目标目录就是资源管理器当前打开的文件夹 —— 与三个目录操作项同一个上下文。 +const savingShot = ref(false) +const saveShotError = ref('') + // ===== 结果分区(从 results 中分离历史项与其他结果) ===== -// 展示顺序:目录操作(批量解压/重命名/删除)> 历史(折叠分组)> 其他 +// 展示顺序:目录操作(保存截图/批量解压/重命名/删除)> 历史(折叠分组)> 其他 // 目录操作为置顶行为项;历史在空查询时置顶但默认折叠,按 Tab 展开 const dirActionItems = ref([]) const otherItems = computed(() => results.value) @@ -263,11 +270,56 @@ watch(query, () => { searchTimer = setTimeout(doSearch, 120) }) -// ===== 当前目录文件操作(批量解压 / 批量重命名) ===== +// ===== 当前目录文件操作(批量解压 / 批量重命名 / 保存截图) ===== +/** + * 把最近一张截图保存成文件(**不弹任何对话框**,直接落到资源管理器当前目录), + * 随后在资源管理器里定位到它并**进入重命名编辑状态** —— 落盘之后最常见的下一步就是改名。 + * + * 文件名在项生成时就定下来(`screenshotFileName()`,与截图编辑栏「保存」同一规则), + * 这样列表上显示的名字与实际写下的**必然一致**。保存用截图模块现成的两条命令 + * (`screenshot_load_cache`:历史只留缩略图,完整 PNG 按需读 + `screenshot_save_png`)。 + * + * 顺序不能反:**先收起面板**再让资源管理器到前台 —— 面板仍盖在屏幕上时就送 F2, + * 那个键会打到面板自己身上。 + */ +async function saveLatestShot(srcPath: string, fileName: string) { + if (savingShot.value) return + savingShot.value = true + try { + const pngBase64 = await commands.screenshotLoadCache(srcPath) + const dir = explorerDir.value.replace(/[\\/]+$/, '') + const savedPath = `${dir}\\${fileName}` + await commands.screenshotSavePng(pngBase64, savedPath) + await hideWindow() + await commands.quickpanelRevealInExplorerRename(savedPath) + } catch (e) { + console.error('[quickpanel] 保存截图失败:', e) + saveShotError.value = String(e) + } finally { + savingShot.value = false + } +} + /** 空查询时注入到结果顶部的目录操作项 */ function getExplorerActions(): QPItem[] { if (!explorerDir.value) return [] + // 「保存截图」排在最前:它是唯一"点一下就有结果"的项(其余三项都要先进子面板)。 + // 只在确实有截图历史时才出现 —— 没有截图时这个项没有任何意义。 + const shotPath = latestCaptureCachePath() + const shotItems: QPItem[] = [] + if (shotPath) { + const fileName = screenshotFileName() + shotItems.push({ + id: 'fa-save-shot', + title: '保存截图', + subtitle: `最近一张 · ${fileName}`, + group: '截图', + score: 100001, + action: () => saveLatestShot(shotPath, fileName), + }) + } return [ + ...shotItems, { id: 'fa-extract', title: '批量解压', @@ -650,8 +702,9 @@ async function openSettings() { } async function executeItem(item: QPItem) { - // 目录操作(批量解压/重命名):进入面板模式,不关闭窗口 - if (item.id === 'fa-extract' || item.id === 'fa-rename' || item.id === 'fa-delete') { + // 目录操作组(`fa-` 前缀:保存截图/批量解压/重命名/删除):或自行收尾、或进入面板模式, + // 一律不在这里关窗口(保存截图成功时由 saveLatestShot 自己关) + if (item.id.startsWith('fa-')) { await item.action() return } @@ -847,6 +900,7 @@ const groupIcon = (group: string) => { if (group === '快捷') return FolderOpen if (group === '换算') return Ruler if (group === '目录操作') return FolderOpen + if (group === '截图') return ImageDown return Search } @@ -861,6 +915,7 @@ const GROUP_COLORS: Record = { 快捷: 'bg-info-soft text-info-text', 换算: 'bg-success-soft text-success-text', 目录操作: 'bg-info-soft text-info-text', + 截图: 'bg-info-soft text-info-text', 应用: 'bg-info-soft text-info-text', 文件: 'bg-success-soft text-success-text', 剪贴板: 'bg-success-soft text-success-text', @@ -1565,6 +1620,19 @@ onUnmounted(() => {
+ +
+
+
+ +

保存截图失败

+
+

{{ saveShotError }}

+
+ +
+
+
diff --git a/src/modules/smarthome/SmartHomeModule.vue b/src/modules/smarthome/SmartHomeModule.vue new file mode 100644 index 0000000..4a6e79e --- /dev/null +++ b/src/modules/smarthome/SmartHomeModule.vue @@ -0,0 +1,60 @@ + + + diff --git a/src/modules/smarthome/components/AutomationPane.vue b/src/modules/smarthome/components/AutomationPane.vue new file mode 100644 index 0000000..7e55c36 --- /dev/null +++ b/src/modules/smarthome/components/AutomationPane.vue @@ -0,0 +1,407 @@ + + + diff --git a/src/modules/smarthome/components/ConnectionDialog.vue b/src/modules/smarthome/components/ConnectionDialog.vue new file mode 100644 index 0000000..aaa65d2 --- /dev/null +++ b/src/modules/smarthome/components/ConnectionDialog.vue @@ -0,0 +1,245 @@ + + + diff --git a/src/modules/smarthome/components/DeviceCard.vue b/src/modules/smarthome/components/DeviceCard.vue new file mode 100644 index 0000000..f4b88dc --- /dev/null +++ b/src/modules/smarthome/components/DeviceCard.vue @@ -0,0 +1,142 @@ + + + diff --git a/src/modules/smarthome/components/DeviceDetail.vue b/src/modules/smarthome/components/DeviceDetail.vue new file mode 100644 index 0000000..5617c9f --- /dev/null +++ b/src/modules/smarthome/components/DeviceDetail.vue @@ -0,0 +1,253 @@ + + + diff --git a/src/modules/smarthome/components/DevicePane.vue b/src/modules/smarthome/components/DevicePane.vue new file mode 100644 index 0000000..7729fa1 --- /dev/null +++ b/src/modules/smarthome/components/DevicePane.vue @@ -0,0 +1,512 @@ + + + + diff --git a/src/modules/smarthome/components/EntityPicker.vue b/src/modules/smarthome/components/EntityPicker.vue new file mode 100644 index 0000000..55eb0cc --- /dev/null +++ b/src/modules/smarthome/components/EntityPicker.vue @@ -0,0 +1,121 @@ + + + diff --git a/src/modules/smarthome/components/EntityRow.vue b/src/modules/smarthome/components/EntityRow.vue new file mode 100644 index 0000000..c6a3fa4 --- /dev/null +++ b/src/modules/smarthome/components/EntityRow.vue @@ -0,0 +1,83 @@ + + + diff --git a/src/modules/smarthome/components/HaStatusBanner.vue b/src/modules/smarthome/components/HaStatusBanner.vue new file mode 100644 index 0000000..09cfdf8 --- /dev/null +++ b/src/modules/smarthome/components/HaStatusBanner.vue @@ -0,0 +1,131 @@ + + + diff --git a/src/modules/smarthome/components/RuleEditorDialog.vue b/src/modules/smarthome/components/RuleEditorDialog.vue new file mode 100644 index 0000000..cb9850f --- /dev/null +++ b/src/modules/smarthome/components/RuleEditorDialog.vue @@ -0,0 +1,584 @@ + + + diff --git a/src/modules/smarthome/components/SettingsPane.vue b/src/modules/smarthome/components/SettingsPane.vue new file mode 100644 index 0000000..77fe86e --- /dev/null +++ b/src/modules/smarthome/components/SettingsPane.vue @@ -0,0 +1,427 @@ + + + diff --git a/src/modules/smarthome/components/controls/ActionControl.vue b/src/modules/smarthome/components/controls/ActionControl.vue new file mode 100644 index 0000000..8628114 --- /dev/null +++ b/src/modules/smarthome/components/controls/ActionControl.vue @@ -0,0 +1,63 @@ + + + + diff --git a/src/modules/smarthome/components/controls/ClimateControl.vue b/src/modules/smarthome/components/controls/ClimateControl.vue new file mode 100644 index 0000000..1573825 --- /dev/null +++ b/src/modules/smarthome/components/controls/ClimateControl.vue @@ -0,0 +1,122 @@ + + + diff --git a/src/modules/smarthome/components/controls/ControlSlider.vue b/src/modules/smarthome/components/controls/ControlSlider.vue new file mode 100644 index 0000000..e44eb1e --- /dev/null +++ b/src/modules/smarthome/components/controls/ControlSlider.vue @@ -0,0 +1,58 @@ + + + diff --git a/src/modules/smarthome/components/controls/CoverControl.vue b/src/modules/smarthome/components/controls/CoverControl.vue new file mode 100644 index 0000000..23ba622 --- /dev/null +++ b/src/modules/smarthome/components/controls/CoverControl.vue @@ -0,0 +1,121 @@ + + + diff --git a/src/modules/smarthome/components/controls/FanControl.vue b/src/modules/smarthome/components/controls/FanControl.vue new file mode 100644 index 0000000..139b54d --- /dev/null +++ b/src/modules/smarthome/components/controls/FanControl.vue @@ -0,0 +1,46 @@ + + + diff --git a/src/modules/smarthome/components/controls/LightControl.vue b/src/modules/smarthome/components/controls/LightControl.vue new file mode 100644 index 0000000..a72f5f7 --- /dev/null +++ b/src/modules/smarthome/components/controls/LightControl.vue @@ -0,0 +1,99 @@ + + + diff --git a/src/modules/smarthome/components/controls/MediaControl.vue b/src/modules/smarthome/components/controls/MediaControl.vue new file mode 100644 index 0000000..6333915 --- /dev/null +++ b/src/modules/smarthome/components/controls/MediaControl.vue @@ -0,0 +1,65 @@ + + + diff --git a/src/modules/smarthome/components/controls/NumberControl.vue b/src/modules/smarthome/components/controls/NumberControl.vue new file mode 100644 index 0000000..30fb028 --- /dev/null +++ b/src/modules/smarthome/components/controls/NumberControl.vue @@ -0,0 +1,59 @@ + + + diff --git a/src/modules/smarthome/components/controls/SelectControl.vue b/src/modules/smarthome/components/controls/SelectControl.vue new file mode 100644 index 0000000..9489722 --- /dev/null +++ b/src/modules/smarthome/components/controls/SelectControl.vue @@ -0,0 +1,53 @@ + + + diff --git a/src/modules/smarthome/components/controls/SwitchControl.vue b/src/modules/smarthome/components/controls/SwitchControl.vue new file mode 100644 index 0000000..b6dd470 --- /dev/null +++ b/src/modules/smarthome/components/controls/SwitchControl.vue @@ -0,0 +1,90 @@ + + + diff --git a/src/modules/smarthome/components/controls/index.ts b/src/modules/smarthome/components/controls/index.ts new file mode 100644 index 0000000..71639cd --- /dev/null +++ b/src/modules/smarthome/components/controls/index.ts @@ -0,0 +1,40 @@ +import type { Component } from 'vue' +import ActionControl from './ActionControl.vue' +import ClimateControl from './ClimateControl.vue' +import CoverControl from './CoverControl.vue' +import FanControl from './FanControl.vue' +import LightControl from './LightControl.vue' +import MediaControl from './MediaControl.vue' +import NumberControl from './NumberControl.vue' +import SelectControl from './SelectControl.vue' +import SwitchControl from './SwitchControl.vue' + +/** + * domain → 控件组件。 + * + * 与 `format.ts` 的 `CONTROLLABLE_DOMAINS` **必须一致**:只有这里存在的 domain + * 才允许声明"可控",否则卡片会拿到一个点不了的控制位(§3.4 的取舍)。 + * 新增 domain 时两边一起改。 + */ +const CONTROL_MAP: Record = { + light: LightControl, + switch: SwitchControl, + input_boolean: SwitchControl, + automation: SwitchControl, + lock: SwitchControl, + cover: CoverControl, + climate: ClimateControl, + fan: FanControl, + media_player: MediaControl, + scene: ActionControl, + script: ActionControl, + // 通用域(真机上覆盖 206 个"能控但没控件"的实体) + number: NumberControl, + select: SelectControl, + button: ActionControl +} + +/** 取该实体的控件(无对应控件时返回 null,卡片就不渲染控制位) */ +export function controlFor(domain: string): Component | null { + return CONTROL_MAP[domain] ?? null +} diff --git a/src/modules/smarthome/components/controls/shared.ts b/src/modules/smarthome/components/controls/shared.ts new file mode 100644 index 0000000..000f998 --- /dev/null +++ b/src/modules/smarthome/components/controls/shared.ts @@ -0,0 +1,12 @@ +import { toast } from 'vue-sonner' +import { toApiError } from '@/stores/smartHomeStore' + +/** + * 控制类命令的统一失败提示。 + * + * 一律用 toast 就地反馈:顶部横幅只留给"链路 / 令牌"这类**全局**问题 + * (否则每次点错一个参数都会挂一条常驻横幅)。 + */ +export function controlFail(e: unknown) { + toast.error(toApiError(e).message) +} diff --git a/src/modules/smarthome/format.ts b/src/modules/smarthome/format.ts new file mode 100644 index 0000000..964e038 --- /dev/null +++ b/src/modules/smarthome/format.ts @@ -0,0 +1,1070 @@ +import type { Component } from 'vue' +// 实体摘要的唯一来源是 store(与 Rust `EntitySummary` 对齐):这里只 re-export, +// 不在本地再声明一份 —— 两份字段漂移是隐性的(P2 加能力位时正是这么发现的) +import type { EntitySummary, HaDevice, RegistryResult, Rule } from '@/stores/smartHomeStore' +import { + Activity, + AirVent, + Blinds, + Bot, + Camera, + CircleHelp, + DoorOpen, + Droplets, + Flame, + Gauge, + Lightbulb, + ListChecks, + Lock, + MapPin, + Play, + Power, + Radio, + SlidersHorizontal, + Speaker, + Sparkles, + Thermometer, + ToggleRight, + User, + Wind, + Workflow +} from '@lucide/vue' + +/** + * 智能家居 · 表现层语义。 + * + * 分工(plan §6.1):Rust 侧只忠实搬运协议数据(`EntitySummary`), + * 「分组 / 图标 / 状态文案 / 是否可控」这些**表现层判断全部在这里**。 + * 这样 HA 新增一个 domain 时,改动只落在这一个文件里。 + */ + +export type { EntitySummary } + +/** + * 设备分类(设备页顶部横排按钮 + 卡片副标题共用)。 + * + * **按设备能力分,不按 domain 分**:`number` / `select` / `button` 是"控件形态" + * 而不是"设备类别",拿它们当分类只在真机上暴露过笑话 ——「投影仪」落进「数值」、 + * 「米家体脂秤」与「酷态科10U」落进「按钮」。这里只保留人一眼能认得的角色。 + */ +export interface DeviceGroup { + value: string + label: string + /** 归属该分类的设备主 domain(`null` = 其余全部) */ + domains: string[] | null +} + +export const DEVICE_GROUPS: DeviceGroup[] = [ + { value: 'light', label: '灯', domains: ['light'] }, + { value: 'switch', label: '插座·开关', domains: ['switch', 'input_boolean'] }, + { value: 'climate', label: '空调', domains: ['climate'] }, + { value: 'fan', label: '风扇', domains: ['fan'] }, + { value: 'media', label: '影音', domains: ['media_player'] }, + { value: 'cover', label: '窗帘', domains: ['cover'] }, + { value: 'lock', label: '门锁', domains: ['lock'] }, + { + value: 'sensor', + label: '传感器', + domains: ['sensor', 'binary_sensor', 'person', 'device_tracker', 'weather'] + }, + { value: 'other', label: '其它', domains: null } +] + +/** domain → 图标(全部来自 lucide,不给装饰性图标上 primary 色) */ +const DOMAIN_ICON: Record = { + light: Lightbulb, + switch: ToggleRight, + input_boolean: ToggleRight, + cover: Blinds, + climate: Thermometer, + fan: Wind, + media_player: Speaker, + lock: Lock, + vacuum: Bot, + camera: Camera, + scene: Sparkles, + script: Play, + automation: Workflow, + person: User, + device_tracker: MapPin, + sensor: Gauge, + binary_sensor: Radio, + weather: Wind, + sun: Activity, + update: Activity, + button: Power, + number: SlidersHorizontal, + select: ListChecks, + humidifier: Droplets, + air_quality: AirVent +} + +/** `binary_sensor` 按 device_class 细分图标 */ +const BINARY_CLASS_ICON: Record = { + door: DoorOpen, + window: DoorOpen, + garage_door: DoorOpen, + motion: Radio, + moisture: Droplets, + smoke: Flame, + gas: Flame, + heat: Flame +} + +export function domainIcon(e: EntitySummary): Component { + if (e.domain === 'binary_sensor' && BINARY_CLASS_ICON[e.deviceClass]) { + return BINARY_CLASS_ICON[e.deviceClass] + } + return DOMAIN_ICON[e.domain] ?? CircleHelp +} + +/** 按设备主 domain 取分类键(设备视角只有 domain,没有完整实体) */ +export function groupOfDomain(domain: string): string { + const g = DEVICE_GROUPS.find((x) => x.domains?.includes(domain)) + return g?.value ?? 'other' +} + +/** + * 是否可控。 + * + * 只列**P2 已明确要支持**的 domain(plan §3.5)。宁可少给控件,也不要在 P2 + * 给一个点了没反应的按钮 —— 与编辑器模块"避免误报优先于覆盖完整"是同一取舍。 + */ +const CONTROLLABLE_DOMAINS = new Set([ + 'light', + 'switch', + 'input_boolean', + 'cover', + 'climate', + 'fan', + 'media_player', + 'lock', + 'scene', + 'script', + 'automation', + // 通用域:真机数据显示这三类能覆盖最多"能控但没控件"的实体(数值 / 下拉 / 按钮) + 'number', + 'select', + 'button' +]) + +/** + * 是否可控(**卡片渲染控件与"只显示可控设备"过滤共用这一个口径**)。 + * + * 通用域还要看实体自己有没有给出必要参数:`number` 缺 min/max/step、 + * `select` 缺 options 时,控件根本渲染不出来 —— 那样的实体应当算作只读, + * 否则会出现"在'可控'过滤里、却没有控件"的别扭状态。 + */ +export function isControllable(e: EntitySummary): boolean { + if (!CONTROLLABLE_DOMAINS.has(e.domain)) return false + if (e.domain === 'number') return numberUsable(e) + if (e.domain === 'select') return selectUsable(e) + return true +} + +/** `number` 是否具备完整的下限/上限/步长 */ +export function numberUsable(e: EntitySummary): boolean { + return e.min != null && e.max != null && e.max > e.min && (e.step ?? 0) > 0 +} + +/** `select` 是否给了可选项 */ +export function selectUsable(e: EntitySummary): boolean { + return e.options.length > 0 +} + +/** `unavailable` / `unknown` 是**合法状态**而非错误(plan §3.4 第 3 条) */ +export function isOffline(e: EntitySummary): boolean { + return e.state === 'unavailable' || e.state === 'unknown' +} + +/** 状态点语义:on/活动 = success,off = neutral,离线 = warning,告警 = danger */ +export type StatusState = 'success' | 'neutral' | 'warning' | 'danger' + +const ALARM_CLASSES = new Set(['smoke', 'gas', 'heat', 'moisture', 'carbon_monoxide']) + +export function statusState(e: EntitySummary): StatusState { + if (isOffline(e)) return 'warning' + if (e.domain === 'binary_sensor' && ALARM_CLASSES.has(e.deviceClass)) { + return e.state === 'on' ? 'danger' : 'neutral' + } + // sensor 这类读数型实体没有"开/关"语义,用中性点即可 + if (e.domain === 'sensor') return 'neutral' + return e.state === 'on' ? 'success' : 'neutral' +} + +const BINARY_TEXT: Record = { + door: ['开', '关'], + window: ['开', '关'], + garage_door: ['开', '关'], + opening: ['开', '关'], + motion: ['有人', '无人'], + occupancy: ['有人', '无人'], + presence: ['有人', '无人'], + moisture: ['漏水', '干燥'], + smoke: ['有烟', '正常'], + gas: ['有燃气', '正常'], + heat: ['过热', '正常'], + carbon_monoxide: ['有一氧化碳', '正常'], + battery: ['低电量', '正常'], + battery_charging: ['充电中', '未充电'], + plug: ['已接入', '已断开'], + power: ['有电', '断电'], + problem: ['异常', '正常'], + running: ['运行中', '已停止'], + update: ['有更新', '已是最新'], + vibration: ['有震动', '静止'], + sound: ['有声', '安静'], + light: ['亮', '暗'], + lock: ['已开锁', '已上锁'], + connectivity: ['在线', '离线'], + tamper: ['被拆动', '正常'], + cold: ['过冷', '正常'] +} + +/** + * 卡片主状态文案。 + * + * 返回 `metric` 时表示这行应当用大号数值渲染(数值型读数), + * 否则用普通 13px 文字。 + */ +export function primaryDisplay(e: EntitySummary): { + text: string + metric?: boolean + unit?: string +} { + if (isOffline(e)) return { text: e.state === 'unavailable' ? '离线' : '未知' } + + switch (e.domain) { + case 'sensor': + case 'number': + if (e.numeric != null) return { text: formatNumber(e.numeric), metric: true, unit: e.unit } + return { text: e.state } + case 'button': + // 按钮的 `state` 是"上次按下时间"而不是状态 —— 状态行说这句更有用 + return { text: '按下即执行' } + case 'binary_sensor': { + const pair = BINARY_TEXT[e.deviceClass] + const on = e.state === 'on' + if (pair) return { text: on ? pair[0] : pair[1] } + return { text: on ? '触发' : '正常' } + } + case 'light': + return { text: e.state === 'on' ? '开' : '关' } + case 'cover': + // 有位置就显示百分比("开着"这种说法对窗帘没信息量) + if (e.position != null) return { text: `${e.position}%`, metric: true } + return { text: COVER_TEXT[e.state] ?? e.state } + case 'climate': + return { text: HVAC_TEXT[e.state] ?? e.state } + case 'media_player': + return { text: MEDIA_TEXT[e.state] ?? e.state } + case 'lock': + return { text: e.state === 'locked' ? '已上锁' : e.state === 'unlocked' ? '已开锁' : e.state } + default: + return { text: STATE_TEXT[e.state] ?? e.state } + } +} + +const COVER_TEXT: Record = { + open: '已打开', + opening: '正在打开', + closing: '正在关闭', + closed: '已关闭' +} + +const HVAC_TEXT: Record = { + off: '已关闭', + heat: '制热', + cool: '制冷', + auto: '自动', + dry: '除湿', + fan_only: '送风', + heat_cool: '冷暖自动' +} + +const MEDIA_TEXT: Record = { + playing: '播放中', + paused: '已暂停', + idle: '空闲', + off: '已关闭', + standby: '待机', + buffering: '缓冲中' +} + +const STATE_TEXT: Record = { + on: '开', + off: '关', + home: '在家', + not_home: '离家' +} + +/** 数值格式化:整数不带小数点,小数最多两位(避免 24.500000 这种噪声) */ +export function formatNumber(n: number): string { + if (Number.isInteger(n)) return String(n) + return String(Math.round(n * 100) / 100) +} + +/** 副状态行:卡片上除主状态之外还能补的一句(如灯的亮度) */ +export function secondaryDisplay(e: EntitySummary): string | null { + if (isOffline(e)) return null + if (e.domain === 'light' && e.state === 'on' && e.brightness != null) { + // HA 的亮度是 0–255,人看的是百分比 + return `亮度 ${Math.round((e.brightness / 255) * 100)}%` + } + if (e.domain === 'climate') { + const parts: string[] = [] + if (e.targetTemp != null) parts.push(`目标 ${formatNumber(e.targetTemp)}°`) + if (e.currentTemp != null) parts.push(`室温 ${formatNumber(e.currentTemp)}°`) + return parts.length ? parts.join(' · ') : null + } + if (e.domain === 'media_player') return null + return null +} + +/** + * 相对时间("3 分钟前")。 + * + * HA 返回的是带偏移的 ISO8601(`2026-10-16T12:00:00.123456+00:00`), + * `Date` 能直接解析;解析失败就原样回退,不抛错。 + */ +export function relativeTime(iso: string, nowMs = Date.now()): string { + if (!iso) return '' + const t = new Date(iso).getTime() + if (Number.isNaN(t)) return '' + const diff = Math.max(0, Math.floor((nowMs - t) / 1000)) + if (diff < 10) return '刚刚' + if (diff < 60) return `${diff} 秒前` + if (diff < 3600) return `${Math.floor(diff / 60)} 分钟前` + if (diff < 86400) return `${Math.floor(diff / 3600)} 小时前` + if (diff < 86400 * 7) return `${Math.floor(diff / 86400)} 天前` + return new Date(t).toLocaleDateString('zh-CN') +} + +/** 中文名排序(默认 localeCompare 对中文按码位排,不是拼音) */ +const collator = new Intl.Collator('zh-Hans-CN') + +/** 字符串中文排序(房间名这类纯文本用它) */ +export function compareText(a: string, b: string): number { + return collator.compare(a, b) +} + +export function compareByName(a: EntitySummary, b: EntitySummary): number { + return collator.compare(a.name, b.name) +} + +/** 相对时间:入参是 unix 秒(`fetchedAt` / `lastOkAt` 这类) */ +export function relativeTimeFromSec(sec: number, nowMs = Date.now()): string { + if (!sec) return '尚未获取' + const diff = Math.max(0, Math.floor(nowMs / 1000 - sec)) + if (diff < 60) return '刚刚' + if (diff < 3600) return `${Math.floor(diff / 60)} 分钟前` + if (diff < 86400) return `${Math.floor(diff / 3600)} 小时前` + return new Date(sec * 1000).toLocaleString('zh-CN', { hour12: false }) +} + +// ============ 能力判定(P2 控制用)============ +// +// 原则:**宁可少给控件,也不要给一个点了没反应的滑杆**(§3.4 第 2 条)。 +// 因此每个控件前面都要有一个明确的能力判断,判断不了就不渲染。 + +/** + * 灯能否调亮度。 + * + * 优先看 `supported_color_modes`(HA 2022 之后的正式能力声明):除 `onoff` / + * `unknown` 之外的任何模式都意味着可调亮度;老集成没这个属性时才退回 + * `supported_features` 的 `SUPPORT_BRIGHTNESS`(bit 1)。 + */ +export function lightHasBrightness(e: EntitySummary): boolean { + const modes = e.supportedColorModes + if (modes.length === 0) return (e.supportedFeatures & 1) !== 0 + return modes.some((m) => m !== 'onoff' && m !== 'unknown') +} + +export function lightHasColorTemp(e: EntitySummary): boolean { + return e.supportedColorModes.includes('color_temp') +} + +export function lightColorTempRange(e: EntitySummary): [number, number] { + const min = e.minColorTempKelvin ?? 2000 + const max = e.maxColorTempKelvin ?? 6500 + return min < max ? [min, max] : [max, min] +} + +/** HA `cover` 的 `supported_features` 位(窗帘控件按它决定给哪几个按钮) */ +export const COVER_FEATURE = { + OPEN: 1, + CLOSE: 2, + SET_POSITION: 4, + STOP: 8 +} as const + +/** 窗帘 / 风扇这类实体是否带某能力位 */ +export function hasFeature(e: EntitySummary, bit: number): boolean { + return (e.supportedFeatures & bit) !== 0 +} + +/** 数值 ⇄ 百分比(HA 的亮度是 0–255,人看的是百分比) */ +export function brightnessToPct(b: number): number { + return Math.round((b / 255) * 100) +} + +export function pctToBrightness(pct: number): number { + return Math.round((pct / 100) * 255) +} + +/** 空调模式的中文名(`hvac_modes` 里的原始值 → 显示文案) */ +export function hvacModeLabel(mode: string): string { + return HVAC_TEXT[mode] ?? mode +} + +// ============ 设备视角(设备聚合 + 三级分层)============ +// +// 真机前提(2026-10-19 普查,见 plan §9.9): +// - 606 条实体里 **604 条有 device_id**(只有 person / todo 没有)→ 按设备聚合可行; +// - 每个设备的实体数中位数 9、最大 **110**(摄像机),直接平铺必然混乱; +// - `friendly_name` 的结构是 `"<设备名> <功能组> <项>"`,去掉设备名前缀后剩下的 +// 就是「功能组 + 项」—— 这是把设备内部再分层的最强信号; +// - 集成给"扩展/实验性功能"的功能组打 `* ` 前缀,正好可以当"高级项"的判据; +// - HA 官方的 `entity_category`(config / diagnostic)在真机上只覆盖 30/606 条, +// 只能作为**判据之一**。 + +/** 注册表索引:一次构建,供设备聚合与详情分层反复使用 */ +export interface RegistryIndex { + /** `entity_id` → `device_id`(空串表示未归组) */ + deviceOf: Map + /** `entity_id` → `entity_category`(`''` | `config` | `diagnostic`) */ + categoryOf: Map + /** `entity_id` → 注册表里的名字(小米集成上大量为空) */ + registryNameOf: Map + deviceById: Map + areaNameById: Map +} + +export function buildRegistryIndex(registry: RegistryResult | null): RegistryIndex { + const index: RegistryIndex = { + deviceOf: new Map(), + categoryOf: new Map(), + registryNameOf: new Map(), + deviceById: new Map(), + areaNameById: new Map() + } + if (!registry) return index + for (const e of registry.entityRegistry ?? []) { + index.deviceOf.set(e.entityId, e.deviceId) + index.categoryOf.set(e.entityId, e.entityCategory) + const registryName = e.name || e.originalName + if (registryName) index.registryNameOf.set(e.entityId, registryName) + } + for (const d of registry.devices ?? []) index.deviceById.set(d.id, d) + for (const a of registry.areas ?? []) index.areaNameById.set(a.areaId, a.name) + return index +} + +/** 一级卡片最多露几个关键读数 */ +export const KEY_READING_LIMIT = 2 + +/** 设备视图(一级首页的元素) */ +export interface DeviceView { + /** `device_id`;未归组实体用 `solo:` 单独成卡 */ + id: string + name: string + areaId: string | null + areaName: string + manufacturer: string + model: string + /** 该设备在实体列表里存在的全部实体 */ + entities: EntitySummary[] + /** 一级卡片的主控实体(`null` = 只读设备,如温度计 / 人体传感器) */ + primary: EntitySummary | null + /** 一级卡片的关键读数(≤ `KEY_READING_LIMIT` 个) */ + readings: EntitySummary[] + /** 任一实体在线即算在线 */ + online: boolean + /** 有可主控实体 */ + controllable: boolean + /** 高级项数量(详情页折叠区标题用) */ + advancedCount: number + /** 排序 / 分组用的主 domain */ + domain: string + /** + * 卡上放不出任何东西的设备:没有**常用**可控项,也拿不到读数。 + * + * 两类都算:`Sun` / `Backup` / HA 自身的 Core / Supervisor / OS 这类服务设备, + * 以及「酷态科10U」「米家体脂秤」这种只剩高级按钮 / 事件的设备。 + * 真机上这类有 12+ 个,全放首页会把真正的设备淹掉;默认隐藏, + * 顶部有「显示无控件设备」开关(`store.showSystemDevices`)。 + */ + systemOnly: boolean +} + +/** 设备内的一个实体(含它在设备里的"功能组 / 项"位置) */ +export interface DeviceEntity { + entity: EntitySummary + /** 功能组名(`''` = 本体,如灯的 `light.xxx`) */ + group: string + /** 组内的项名 */ + item: string + /** 是否高级项(三级) */ + advanced: boolean +} + +export interface EntityGroup { + key: string + label: string + items: DeviceEntity[] +} + +/** 判定为"高级项"的 domain:事件 / 通知 / 文本 / 系统类,都不是日常要点的 */ +const ADVANCED_DOMAINS = new Set([ + 'event', + 'notify', + 'text', + 'todo', + 'tts', + 'image', + 'camera', + 'date', + 'time', + 'datetime', + 'update', + 'stt' +]) + +/** 关键读数的 device_class 优先级(小的优先;不在表里的按有无单位兜底) */ +const READING_ORDER = [ + 'power', + 'energy', + 'temperature', + 'humidity', + 'illuminance', + 'current', + 'voltage', + 'battery', + 'occupancy', + 'motion', + 'door', + 'window', + 'moisture', + 'smoke', + 'gas', + 'carbon_monoxide', + 'pm25', + 'carbon_dioxide' +] + +/** 主控实体的 domain 优先级(小的优先) */ +const PRIMARY_ORDER = [ + 'cover', + 'lock', + 'climate', + 'vacuum', + 'light', + 'fan', + 'media_player', + 'water_heater', + 'humidifier', + 'switch', + 'input_boolean', + 'number', + 'select', + 'button', + 'scene', + 'script' +] + +/** 所有实体的最长公共前缀(截到最后一个空格),用于去掉 friendly_name 里的设备名前缀 */ +function commonNamePrefix(names: string[]): string { + if (names.length === 0) return '' + let prefix = names[0] + for (const n of names.slice(1)) { + let i = 0 + while (i < prefix.length && i < n.length && prefix[i] === n[i]) i++ + prefix = prefix.slice(0, i) + if (!prefix) break + } + const cut = prefix.lastIndexOf(' ') + return cut > 0 ? prefix.slice(0, cut + 1) : '' +} + +/** + * 设备内实体的名字前缀(剥掉它之后剩下的就是「功能组 + 项」)。 + * + * **优先用设备名**,`commonNamePrefix` 只作兜底 —— 后者在**单实体设备**上会把 + * 整条名字截到最后一个空格,从而吃掉集成给扩展功能打的 `* ` 高级标记。 + * 真机上的后果是「酷态科10U」(只有一条 `酷态科10U * 充电器 恢复默认设置`) + * 里的"恢复默认设置"按钮被当成主控,卡片上真的渲染出一个会重置设备的「按下」按钮。 + * + * 真机上 36 台设备除未归组的 `LFeng` / `Shopping list` 外,实体名都以 + * 「设备名 + 空格」开头(含摄像机那种双空格分隔的 `… 4 变焦版 摄像机控制 …`)。 + */ +function deviceNamePrefix(list: EntitySummary[], name: string): string { + const byName = name ? `${name} ` : '' + if (byName && list.some((e) => e.name.startsWith(byName))) return byName + return commonNamePrefix(list.map((e) => e.name)) +} + +/** 解析实体名 → 「功能组 / 项」;`* ` 前缀(集成的扩展功能)会被剥掉并标记 */ +function parseDeviceName( + fullName: string, + prefix: string +): { group: string; item: string; starred: boolean } { + let rest = fullName.startsWith(prefix) ? fullName.slice(prefix.length) : fullName + rest = rest.trim() + const starred = rest.startsWith('*') + if (starred) rest = rest.replace(/^\*\s*/, '').trim() + const tokens = rest.split(/\s+/).filter(Boolean) + if (tokens.length <= 1) return { group: '', item: rest || fullName, starred } + return { group: tokens.slice(0, -1).join(' '), item: tokens[tokens.length - 1], starred } +} + +/** + * `device_class` 里**不是读数**的那些:时间戳与枚举。 + * + * 真机上它们会骗过"有 device_class 就算读数"的兜底 —— 太阳的「下个清晨」、 + * 备份的「下一次计划的自检」都会因此跑到卡片上。 + */ +const NON_READING_CLASSES = new Set(['timestamp', 'date', 'time', 'enum']) + +/** 读数排序分(越小越该放在卡片上;`Infinity` = 不适合当读数) */ +function readingScore(e: EntitySummary): number { + const idx = READING_ORDER.indexOf(e.deviceClass) + if (idx >= 0) return idx + if (NON_READING_CLASSES.has(e.deviceClass)) return Number.POSITIVE_INFINITY + // 有量纲的数值(温度 24.5 °C、电量 100 %)比裸数字更值得放上卡片。 + // **只看单位不看数值**:设备离线时数值解析不出来,但那仍然是它的读数 + // (体脂秤离线时卡片应该显示"体重 离线",而不是什么都没有) + if (e.unit) return READING_ORDER.length + 1 + if (e.domain === 'person' || e.domain === 'device_tracker') return READING_ORDER.length + 2 + if (e.domain === 'sensor' || e.domain === 'binary_sensor') { + // 枚举型(带 `options`)不是"读数",是状态枚举 —— 真机上摄像机卡片因此露过 + // 「存储卡状态」「区域形状」,这里把它排到最后 + if (e.options.length > 0) return READING_ORDER.length + 8 + if (e.deviceClass) return READING_ORDER.length + 3 + if (e.numeric != null) return READING_ORDER.length + 6 + return Number.POSITIVE_INFINITY + } + return Number.POSITIVE_INFINITY +} + +/** + * 关键读数(≤ `KEY_READING_LIMIT`)。 + * + * 优先级:常用实体的读数 → (**仅当设备没有主控时**)退到全部实体。 + * + * 为什么有主控就不兜底:真机上"电脑"这台设备的读数全是集成的扩展功能 + * (「开机时间提醒 4294967295 min」这类),宁可卡片干净一点 —— 名字 + 开关就够了。 + * 而没有任何控件的设备(体脂秤 / 温度计 / 人体传感器)必须给读数,否则卡片是空的。 + */ +function pickReadings( + list: EntitySummary[], + primary: EntitySummary | null, + isAdv: (e: EntitySummary) => boolean +): EntitySummary[] { + const pick = (pool: EntitySummary[]) => + pool + .filter((e) => e.entityId !== primary?.entityId) + .filter((e) => readingScore(e) !== Number.POSITIVE_INFINITY) + .sort((a, b) => readingScore(a) - readingScore(b)) + .slice(0, KEY_READING_LIMIT) + const common = pick(list.filter((e) => !isAdv(e))) + if (common.length > 0 || primary) return common + return pick(list) +} + +/** + * 把实体列表按设备聚合(一级首页的数据源)。 + * + * 未归组到设备的实体(真机上是 `person` / `todo`)**各自单独成卡**: + * 它们之间没有任何关系,硬塞进一张"未归组"卡反而更难找。 + */ +export function buildDevices( + entities: EntitySummary[], + index: RegistryIndex +): DeviceView[] { + const buckets = new Map() + for (const e of entities) { + const deviceId = index.deviceOf.get(e.entityId) ?? '' + const key = deviceId || `solo:${e.entityId}` + const list = buckets.get(key) + if (list) list.push(e) + else buckets.set(key, [e]) + } + + const out: DeviceView[] = [] + for (const [key, list] of buckets) { + const device = index.deviceById.get(key) + const areaId = device?.areaId || null + const name = + key.startsWith('solo:') + ? list[0].name + : device + ? device.nameByUser || device.name || list[0].name + : list[0].name + + const prefix = deviceNamePrefix(list, name) + const parsed = new Map() + for (const e of list) parsed.set(e.entityId, parseDeviceName(e.name, prefix)) + const isAdv = (e: EntitySummary) => isAdvanced(e, parsed.get(e.entityId)!.starred, index) + + const advancedCount = list.filter(isAdv).length + + // 主控:在「常用」实体里按 domain 优先级 + 是否本体取第一个 + const controlPick = (onlyOnline: boolean) => + [...list] + .filter((e) => !isAdv(e)) + .filter((e) => isControllable(e) && (!onlyOnline || !isOffline(e))) + .sort( + (a, b) => primaryScore(a, parsed.get(a.entityId)!) - primaryScore(b, parsed.get(b.entityId)!) + )[0] ?? null + const primary = controlPick(true) ?? controlPick(false) + + const readings = pickReadings(list, primary, isAdv) + // **必须与 `primary` 同一口径**(都排除高级项):否则会出现"自称可控、卡片上却没有控件" + // 的设备 —— 「酷态科10U」只有一个高级按钮,正是靠这一条才落进「无控件设备」 + const hasControl = list.some((e) => isControllable(e) && !isAdv(e)) + + out.push({ + id: key, + name, + areaId, + areaName: areaId ? (index.areaNameById.get(areaId) ?? '') : '', + manufacturer: device?.manufacturer ?? '', + model: device?.model ?? '', + entities: list, + primary, + readings, + online: list.some((e) => !isOffline(e)), + controllable: list.some((e) => isControllable(e) && !isOffline(e)), + advancedCount, + domain: deviceRoleDomain(list, primary, readings, isAdv), + // 卡上放不出任何东西的设备(没有常用可控项、也拿不到读数): + // `Sun` / `Backup` / HA 自身组件,以及「酷态科10U」这类只有高级项的设备。 + // 默认不占首页,顶部有「显示无控件设备」开关可以显出来 + systemOnly: !hasControl && readings.length === 0 + }) + } + + return out +} + +/** + * 设备 role(决定分类与卡片副标题)。 + * + * 顺序:主控 domain → 读数 domain → 可见(非高级)实体的多数 domain → `other`。 + * + * **不能用 `mostCommonDomain(list)` 兜底**:它不排除 `button`,于是 + * 「酷态科10U」「米家体脂秤」这类只剩高级按钮 / 事件的设备会被判成「按钮」设备。 + * 逐级回退到 `other` 才是诚实的 —— 它们确实什么都控不了、也读不出东西。 + */ +function deviceRoleDomain( + list: EntitySummary[], + primary: EntitySummary | null, + readings: EntitySummary[], + isAdv: (e: EntitySummary) => boolean +): string { + if (primary) return primary.domain + if (readings.length > 0) return readings[0].domain + const visible = list.filter((e) => !isAdv(e)) + return visible.length > 0 ? mostCommonDomain(visible) : 'other' +} + +/** 主控排序:本体(功能组为空)优先 → `_s_2` / `_p_2_1`(真机上的"基础功能")→ domain 优先级 */ +function primaryScore( + e: EntitySummary, + parsed: { group: string; starred: boolean } +): number { + let score = PRIMARY_ORDER.indexOf(e.domain) + if (score < 0) score = PRIMARY_ORDER.length + if (parsed.group === '') score -= 100 + if (/_s_2$/.test(e.entityId) || /_p_2_1$/.test(e.entityId)) score -= 50 + if (parsed.group.startsWith('开关') || parsed.group.startsWith('灯')) score -= 10 + return score +} + +function mostCommonDomain(list: EntitySummary[]): string { + const counts = new Map() + for (const e of list) { + if (ADVANCED_DOMAINS.has(e.domain)) continue + counts.set(e.domain, (counts.get(e.domain) ?? 0) + 1) + } + let best = list[0]?.domain ?? '' + let bestCount = 0 + for (const [d, c] of counts) { + if (c > bestCount) { + best = d + bestCount = c + } + } + return best +} + +/** 高级项判定:HA 的 config/diagnostic ∪ 扩展功能(`*`)∪ 事件/通知/文本/系统类 */ +function isAdvanced( + e: EntitySummary, + starred: boolean, + index: RegistryIndex +): boolean { + const category = index.categoryOf.get(e.entityId) ?? '' + if (category === 'config' || category === 'diagnostic') return true + if (starred) return true + return ADVANCED_DOMAINS.has(e.domain) +} + +/** 关键读数在卡片上的短标签(`device_class` → 中文);没命中时回退到实体名 */ +const READING_LABEL: Record = { + power: '功率', + energy: '耗电', + temperature: '温度', + humidity: '湿度', + illuminance: '光照', + current: '电流', + voltage: '电压', + battery: '电量', + occupancy: '有人', + motion: '移动', + door: '门磁', + window: '窗磁', + moisture: '漏水', + smoke: '烟感', + gas: '燃气', + carbon_monoxide: '一氧化碳', + pm25: 'PM2.5', + carbon_dioxide: 'CO₂', + pressure: '气压', + signal_strength: '信号' +} + +/** 读数标签:优先 `device_class` 的中文短标签,否则取实体名的最后一段 */ +export function readingLabel(e: EntitySummary): string { + const byClass = READING_LABEL[e.deviceClass] + if (byClass) return byClass + // 小米的实体名常带"单位说明"后缀,取最后一段再截断,避免卡片被长名字撑爆 + const tail = e.name.split(/\s+/).filter(Boolean).pop() ?? e.name + return tail.length > 6 ? `${tail.slice(0, 6)}…` : tail +} + +/** 读数值(数值 + 单位;非数值实体给状态文案) */ +export function readingValue(e: EntitySummary): { text: string; unit: string } { + if (isOffline(e)) return { text: '离线', unit: '' } + if (e.numeric != null) return { text: formatNumber(e.numeric), unit: e.unit } + const display = primaryDisplay(e) + return { text: display.text, unit: display.unit ?? '' } +} + +/** + * 把一个设备的实体切成「常用」与「高级」两组(二级详情页用)。 + * + * **高级项也需要分组**:摄像机的高级项有 30+ 条,平铺一样没法看, + * 因此两边都按功能组归拢,只是视觉上高级区默认折叠、整体降级。 + */ +export function splitDevice( + device: DeviceView, + index: RegistryIndex +): { common: EntityGroup[]; advanced: EntityGroup[] } { + const prefix = deviceNamePrefix(device.entities, device.name) + const common = new Map() + const advanced = new Map() + + for (const e of device.entities) { + const parsed = parseDeviceName(e.name, prefix) + const advancedFlag = isAdvanced(e, parsed.starred, index) + const bucket = advancedFlag ? advanced : common + // 本体(group 为空)用具名 + 项名,避免整页出现多个"(本体)" + const label = parsed.group || parsed.item + let group = bucket.get(label) + if (!group) { + group = { key: label, label, items: [] } + bucket.set(label, group) + } + group.items.push({ + entity: e, + group: parsed.group, + item: parsed.group ? parsed.item : parsed.item, + advanced: advancedFlag + }) + } + + const order = (groups: Map) => + [...groups.values()].sort((a, b) => { + // 本体在最前,其余按中文名 + if (!a.items[0].group) return -1 + if (!b.items[0].group) return 1 + return compareText(a.label, b.label) + }) + return { common: order(common), advanced: order(advanced) } +} + +/** 设备按"主 domain"归入的分类(顶部横排按钮用) */ +export function deviceGroupKey(device: DeviceView): string { + return groupOfDomain(device.domain) +} + +/** 设备的中文分类名(卡片副标题用) */ +export function deviceTypeLabel(device: DeviceView): string { + const g = DEVICE_GROUPS.find((x) => x.value === deviceGroupKey(device)) + return g?.label ?? '其它' +} + +/** 设备主控 / 主要类型的图标 */ +export function deviceIcon(device: DeviceView): Component { + if (device.primary) return domainIcon(device.primary) + const sample = device.readings[0] ?? device.entities[0] + return sample ? domainIcon(sample) : CircleHelp +} + +/** 设备的收藏判定:收藏其主实体(没有主控时收藏第一个实体) */ +export function favoriteTargetOf(device: DeviceView): string { + return device.primary?.entityId ?? device.entities[0]?.entityId ?? '' +} + +/** + * 「未分配房间」的哨兵值。 + * + * 它不是兜底:真机数据显示 36 个设备里有 9 个确实没有区域(§9.5-1), + * 这些实体需要一个明确的分组,否则它们在"按房间看"的视角里会凭空消失。 + */ +export const NO_AREA = '__none__' + +// ============ P4:本地规则(表现层语义)============ + +/** 规则里的状态值 → 中文(用于摘要与下拉) */ +export function stateText(state: string): string { + return STATE_TEXT[state] ?? state +} + +/** `entity_id` → domain(与 Rust 侧同一口径) */ +export function domainOf(entityId: string): string { + const i = entityId.indexOf('.') + return i > 0 ? entityId.slice(0, i) : '' +} + +/** + * 一个 domain 可选的「服务」预设(规则动作里的"调服务"用它)。 + * + * **刻意不是"HA 支持的全部服务"**:那是几百个枚举,让用户在里面挑只会配错。 + * 这里只给每个 domain 最常见的几个;**没有**"手填服务名"的自定义入口 + * (冷门服务请在 HA 里建自动化,那是"简单自动化"的边界)。 + */ +export interface ServicePreset { + value: string + label: string + /** 该服务需要填的参数(对应 `ServiceParams` 的字段名) */ + params: ParamKey[] +} + +export type ParamKey = + | 'brightnessPct' + | 'colorTempKelvin' + | 'position' + | 'temperature' + | 'percentage' + | 'volumeLevel' + | 'value' + | 'option' + +export const PARAM_LABEL: Record = { + brightnessPct: '亮度(%)', + colorTempKelvin: '色温(K)', + position: '位置(%)', + temperature: '温度', + percentage: '档位(%)', + volumeLevel: '音量(0–1)', + value: '数值', + option: '选项' +} + +const SERVICE_PRESETS: Record = { + light: [ + { value: 'turn_on', label: '开灯', params: ['brightnessPct', 'colorTempKelvin'] }, + { value: 'turn_off', label: '关灯', params: [] }, + { value: 'toggle', label: '切换', params: [] } + ], + switch: [ + { value: 'turn_on', label: '打开', params: [] }, + { value: 'turn_off', label: '关闭', params: [] }, + { value: 'toggle', label: '切换', params: [] } + ], + input_boolean: [ + { value: 'turn_on', label: '打开', params: [] }, + { value: 'turn_off', label: '关闭', params: [] }, + { value: 'toggle', label: '切换', params: [] } + ], + light_group: [ + { value: 'turn_on', label: '开灯', params: ['brightnessPct'] }, + { value: 'turn_off', label: '关灯', params: [] } + ], + cover: [ + { value: 'open_cover', label: '打开', params: [] }, + { value: 'close_cover', label: '关闭', params: [] }, + { value: 'stop_cover', label: '停止', params: [] }, + { value: 'set_cover_position', label: '设为位置', params: ['position'] } + ], + climate: [ + { value: 'set_temperature', label: '设为目标温度', params: ['temperature'] }, + { value: 'set_hvac_mode', label: '设为模式', params: [] }, + { value: 'turn_off', label: '关闭', params: [] } + ], + fan: [ + { value: 'turn_on', label: '打开', params: [] }, + { value: 'turn_off', label: '关闭', params: [] }, + { value: 'set_percentage', label: '设为档位', params: ['percentage'] } + ], + media_player: [ + { value: 'turn_on', label: '打开', params: [] }, + { value: 'turn_off', label: '关闭', params: [] }, + { value: 'media_play_pause', label: '播放 / 暂停', params: [] }, + { value: 'volume_set', label: '设为音量', params: ['volumeLevel'] } + ], + lock: [ + { value: 'lock', label: '上锁', params: [] }, + { value: 'unlock', label: '开锁', params: [] } + ], + scene: [{ value: 'turn_on', label: '执行场景', params: [] }], + script: [{ value: 'turn_on', label: '执行脚本', params: [] }], + automation: [ + { value: 'trigger', label: '立即运行', params: [] }, + { value: 'turn_on', label: '启用', params: [] }, + { value: 'turn_off', label: '停用', params: [] } + ], + number: [{ value: 'set_value', label: '设为数值', params: ['value'] }], + select: [{ value: 'select_option', label: '选择选项', params: ['option'] }], + button: [{ value: 'press', label: '按下', params: [] }] +} + +/** 该 domain 的服务预设(没有预设时退回通用的开关两项)。 */ +export function servicePresets(domain: string): ServicePreset[] { + return ( + SERVICE_PRESETS[domain] ?? [ + { value: 'turn_on', label: '打开', params: [] }, + { value: 'turn_off', label: '关闭', params: [] } + ] + ) +} + +/** 规则的一句话摘要("门厅门磁 开 → 开 门厅灯")。 */ +export function ruleSummary(rule: Rule, labelOf: (entityId: string) => string): string { + const t = rule.trigger + const trigger = !t.entityId + ? '未配置触发' + : t.numericOp + ? `${labelOf(t.entityId)} ${t.numericOp} ${t.numericValue ?? '?'}` + : `${labelOf(t.entityId)} ${t.to.length ? t.to.map(stateText).join('/') : '任意变化'}` + const first = rule.actions[0] + let action = '无动作' + if (first) { + if (first.kind === 'service') { + const label = + servicePresets(domainOf(first.entityId)).find((p) => p.value === first.service)?.label ?? + first.service + action = `${label} ${labelOf(first.entityId)}` + } else if (first.kind === 'delay') { + action = `延时 ${first.seconds} 秒` + } else { + action = `通知「${first.title || '无标题'}」` + } + } + const more = rule.actions.length > 1 ? ` 等 ${rule.actions.length} 个动作` : '' + return `${trigger} → ${action}${more}` +} + +export type { Rule, RuleAction, RuleCondition, RuleTrigger, RuleRecord } from '@/stores/smartHomeStore' diff --git a/src/modules/smarthome/index.ts b/src/modules/smarthome/index.ts new file mode 100644 index 0000000..5dbd2e6 --- /dev/null +++ b/src/modules/smarthome/index.ts @@ -0,0 +1,50 @@ +import type { ModuleConfig } from '@/types/module' +import type { SearchIndexItem } from '@/stores/searchIndex' + +/** + * 智能家居模块(Home Assistant 对接)。 + * + * 规划见 doc/SMART_HOME_MODULE_PLAN.md: + * - P0 连接管理(双地址:局域网 / 反代)+ 令牌入系统凭据管理器 + 端点选择 + 链路诊断 + * - P1 设备状态列表 P2 设备控制 P3 HA 已有自动化 + * - P4 WebSocket 实时推送(含房间分组)+ 本地规则引擎(三段式,仅在 Thing 运行时生效) + */ + +const searchItems: SearchIndexItem[] = [ + { + title: '智能家居', + description: '查看与控制 Home Assistant 中的智能家居设备', + keywords: ['智能家居', 'home assistant', 'ha', '设备', '实体', '灯', '开关', 'smarthome'], + tab: 'devices' + }, + { + title: '智能家居 · 自动化', + description: '查看与运行 Home Assistant 自动化,管理本地联动规则', + keywords: ['自动化', 'automation', '场景', 'scene', '脚本', 'script', '联动', '规则'], + tab: 'automations' + }, + { + title: '智能家居连接设置', + description: '配置 Home Assistant 地址(局域网 / 反代)与长期访问令牌', + keywords: ['连接', '令牌', 'token', '地址', '反代', '局域网', 'home assistant', '设置'], + tab: 'settings' + }, + { + title: '检测智能家居链路', + description: '探测当前使用的是局域网还是反代,并显示耗时', + keywords: ['链路', '延迟', '检测', '局域网', '反代', 'cloudflare', 'tunnel', '诊断'], + tab: 'settings' + } +] + +export const moduleConfig: ModuleConfig = { + id: 'smarthome', + name: '智能家居', + icon: 'smarthome', + description: '对接 Home Assistant:设备状态、控制与简单自动化', + category: 'system', + defaultEnabled: false, + loader: () => import('./SmartHomeModule.vue'), + searchItems, + order: 85 +} diff --git a/src/modules/tray/TrayMenu.vue b/src/modules/tray/TrayMenu.vue index 22ac99d..15db349 100644 --- a/src/modules/tray/TrayMenu.vue +++ b/src/modules/tray/TrayMenu.vue @@ -72,6 +72,30 @@ function resetMenuState() { } } +/** 被禁用的模块 ID 集合(模块启停状态的真相在 appSettings.modules) */ +const disabledModules = ref>(new Set()) + +/** 读取模块启停状态:未记录的模块按默认启用处理 */ +function readModuleStates() { + const disabled = new Set() + try { + const raw = localStorage.getItem(STORAGE_KEYS.appSettings) + if (raw) { + const parsed = JSON.parse(raw) + if (Array.isArray(parsed.modules)) { + for (const m of parsed.modules) { + if (m && typeof m.id === 'string' && m.enabled === false) disabled.add(m.id) + } + } + } + } catch { /* 忽略 */ } + disabledModules.value = disabled +} + +function moduleEnabled(id: string): boolean { + return !disabledModules.value.has(id) +} + function readOsdVisible(): boolean { try { const raw = localStorage.getItem(STORAGE_KEYS.monitorOsdConfig) @@ -87,6 +111,19 @@ const proxyLoading = computed(() => loadingAction.value !== null && loadingAction.value.startsWith('proxy') ) +// 各区块/快捷入口跟随模块启停状态显示;分隔线只在其上方确实有内容时出现 +const showMusic = computed(() => moduleEnabled('music')) +const showProxy = computed(() => moduleEnabled('proxy')) +const showMonitor = computed(() => moduleEnabled('monitor')) +const showProxySeparator = computed(() => showProxy.value && showMusic.value) +const showMonitorSeparator = computed(() => showMonitor.value && (showMusic.value || showProxy.value)) +const showQuickLaunch = computed(() => + moduleEnabled('terminal') || moduleEnabled('dsh') || moduleEnabled('editor') +) +const showQuickSeparator = computed(() => + showQuickLaunch.value && (showMusic.value || showProxy.value || showMonitor.value) +) + const REGION_MAP: Record = { '日本': 'JP', '香港': 'HK', '美国': 'US', '新加坡': 'SG', '台湾': 'TW', '韩国': 'KR', '印度': 'IN', '英国': 'UK', @@ -397,6 +434,11 @@ const modeTitle = computed(() => let musicTimer: number | null = null function startMusicPolling() { + // 音乐模块被禁用时不查询、不轮询音乐状态 + if (!moduleEnabled('music')) { + stopMusicPolling() + return + } void refreshMusic() if (musicTimer !== null) return musicTimer = window.setInterval(() => void refreshMusic(), 1000) @@ -534,6 +576,7 @@ async function applyTheme() { } onMounted(async () => { + readModuleStates() await applyTheme() const mq = window.matchMedia('(prefers-color-scheme: dark)') @@ -541,9 +584,16 @@ onMounted(async () => { mq.addEventListener('change', onThemeChange) unlistenFns.push(() => mq.removeEventListener('change', onThemeChange)) - // 主窗口改主题/效果/主题色时同步(托盘菜单常驻,不监听就会一直用旧值) + // 主窗口改主题/效果/主题色或模块启停时同步(托盘菜单常驻,不监听就会一直用旧值) const onStorage = (e: StorageEvent) => { - if (e.key === STORAGE_KEYS.appSettings) void applyTheme() + if (e.key !== STORAGE_KEYS.appSettings) return + void applyTheme() + readModuleStates() + // 音乐模块关闭后立即停止轮询并收起音量面板,避免无效查询与残留 UI + if (!moduleEnabled('music')) { + stopMusicPolling() + volumeOpen.value = false + } } window.addEventListener('storage', onStorage) unlistenFns.push(() => window.removeEventListener('storage', onStorage)) @@ -556,6 +606,8 @@ onMounted(async () => { unlistenFns.push(await listen('tray-menu-show', async (event) => { await applyTheme() + // 每次弹出前重读模块启停状态,设置页刚改完立即生效 + readModuleStates() Object.assign(state, event.payload) osdVisible.value = readOsdVisible() // 显示前重置上次残留的下拉/焦点状态(双保险) @@ -604,7 +656,7 @@ onUnmounted(() => {
-
+
@@ -674,9 +726,9 @@ onUnmounted(() => {
-
+
-
+
代理 @@ -740,9 +792,9 @@ onUnmounted(() => {
-
+
-
+
监控 @@ -767,17 +819,17 @@ onUnmounted(() => {
-
+
- - - diff --git a/src/stores/screenshotStore.ts b/src/stores/screenshotStore.ts index b3af327..efaf553 100644 --- a/src/stores/screenshotStore.ts +++ b/src/stores/screenshotStore.ts @@ -1,7 +1,7 @@ import { defineStore } from 'pinia' import { ref } from 'vue' +import { invoke } from '@tauri-apps/api/core' import { WebviewWindow } from '@tauri-apps/api/webviewWindow' -import { PhysicalPosition, PhysicalSize } from '@tauri-apps/api/dpi' import { availableMonitors } from '@tauri-apps/api/window' import { emit, listen, type UnlistenFn } from '@tauri-apps/api/event' import { toast } from 'vue-sonner' @@ -70,6 +70,49 @@ const DEFAULT_SETTINGS: ScreenshotSettings = { shortcutDefaultsVersion: SHORTCUT_DEFAULTS_VERSION, } +// ===== 历史持久化(键 / 结构 / 跨窗口只读访问) ===== +const HISTORY_KEY = STORAGE_KEYS.screenshotHistory +const HISTORY_VERSION = 1 + +/** 历史在 localStorage 里的持久化形态 */ +interface HistorySnapshot { + version?: number + items?: RecentCapture[] +} + +/** + * 截图文件名 —— 与截图**编辑栏**的「保存」(`ScreenshotOverlay.doSave`)、 + * 本 store 的 `saveImage`(历史项保存)以及自动保存**同一条规则**: + * `screenshot_.png`(如 `screenshot_2026-10-20T12-34-56.png`)。 + * + * 抽成函数是为了让"快速面板 → 保存截图"落下的文件名**不可能**与那几个按钮漂移。 + */ +export function screenshotFileName(now: Date = new Date()): string { + const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19) + return `screenshot_${ts}.png` +} + +/** + * 最近一张截图的完整 PNG 缓存路径(**只读**,无任何副作用)。 + * + * 为什么快速面板不用 store 而是直接读 localStorage:它是独立窗口,Pinia 是 + * **窗口级**的(`main.ts` 里每个窗口装一份,store 实例互不可见),读 store 就得先 + * `loadSettings` + `loadHistory` —— 而 `loadHistory` 会按"当前设置里的保留条数" + * 删除超限的缓存文件;设置没加载时限额取默认值,可能误删用户的历史缓存。 + * 这里只取 `items[0].filePath`(历史里只有缩略图,完整 PNG 在缓存目录按需读取)。 + */ +export function latestCaptureCachePath(): string | null { + try { + const raw = localStorage.getItem(HISTORY_KEY) + if (!raw) return null + const parsed = JSON.parse(raw) as HistorySnapshot + if (parsed.version !== HISTORY_VERSION || !Array.isArray(parsed.items)) return null + return parsed.items[0]?.filePath ?? null + } catch { + return null + } +} + export const useScreenshotStore = defineStore('screenshot', () => { const capturing = ref(false) const recent = ref([]) @@ -98,10 +141,6 @@ export const useScreenshotStore = defineStore('screenshot', () => { /** 贴图全局快捷键事件监听 */ let pinShortcutUnlisten: UnlistenFn | null = null - // ===== 历史持久化 ===== - const HISTORY_KEY = STORAGE_KEYS.screenshotHistory - const HISTORY_VERSION = 1 - // ===== 设置持久化 ===== function loadSettings() { try { @@ -205,8 +244,16 @@ export const useScreenshotStore = defineStore('screenshot', () => { // 矩形未变化时跳过(覆盖层仅由本流程定位,跳过安全),省 2 次 IPC 往返 const rectKey = `${rect.x},${rect.y},${rect.width},${rect.height}` if (rectKey !== lastOverlayRectKey) { - await overlayWin?.setPosition(new PhysicalPosition(rect.x, rect.y)) - await overlayWin?.setSize(new PhysicalSize(rect.width, rect.height)) + // 原生 SetWindowPos 一次设置位置 + 尺寸(物理像素,同步生效,窗口隐藏态也立即落位)。 + // 覆盖层创建时即为不可缩放(见 ensureOverlay),Tauri 的 setSize 在非 resizable 窗口上 + // 不生效,所以这里统一走原生命令。 + await invoke('osd_set_bounds', { + label: OVERLAY_LABEL, + x: rect.x, + y: rect.y, + w: rect.width, + h: rect.height, + }).catch((e) => logger.warn(`覆盖层定位失败: ${e}`)) lastOverlayRectKey = rectKey } await ensureOverlayReady() @@ -269,6 +316,8 @@ export const useScreenshotStore = defineStore('screenshot', () => { overlayWin = null } resetOverlayReady() + // 新窗口必须重新定位:清空上次矩形记录,否则会跳过定位,新窗口停留在初始 800×600 + lastOverlayRectKey = '' overlayWin = new WebviewWindow(OVERLAY_LABEL, { url: 'index.html#screenshot-overlay', title: '截图', @@ -276,9 +325,12 @@ export const useScreenshotStore = defineStore('screenshot', () => { y: 0, width: 800, height: 600, - // 必须 true:resizable:false 在 Windows 上会导致 setSize 失效, - // 覆盖层无法铺满虚拟屏,选区被 clamp 到初始 800x600 区域(表现为工具栏始终停在左上角) - resizable: true, + // 直接创建为不可缩放:可缩放的无边框窗口在屏幕原点会暴露系统缩放手柄 + // (tao 在 WM_NCHITTEST 中按 RESIZABLE 标志返回 HTTOPLEFT 等), + // 于是「从屏幕左上角 (0,0) 起笔框选」会被判定为拖动窗口缩放边框,把整个覆盖层拉小。 + // 覆盖层始终铺满虚拟屏,无需用户调整大小;尺寸改由原生 SetWindowPos + // (osd_set_bounds)设置,不受 resizable 限制(Tauri setSize 在非 resizable 窗口上不生效)。 + resizable: false, decorations: false, alwaysOnTop: true, skipTaskbar: true, @@ -434,7 +486,7 @@ export const useScreenshotStore = defineStore('screenshot', () => { try { const raw = localStorage.getItem(HISTORY_KEY) if (!raw) return - const parsed = JSON.parse(raw) as { version?: number; items?: RecentCapture[] } + const parsed = JSON.parse(raw) as HistorySnapshot if (parsed.version !== HISTORY_VERSION || !Array.isArray(parsed.items)) { localStorage.removeItem(HISTORY_KEY) return @@ -506,12 +558,8 @@ export const useScreenshotStore = defineStore('screenshot', () => { async function saveImage(pngBase64: string) { const { save } = await import('@tauri-apps/plugin-dialog') - const ts = new Date() - .toISOString() - .replace(/[:.]/g, '-') - .slice(0, 19) const path = await save({ - defaultPath: `screenshot_${ts}.png`, + defaultPath: screenshotFileName(), filters: [{ name: 'PNG', extensions: ['png'] }], }) if (!path) return @@ -546,11 +594,7 @@ export const useScreenshotStore = defineStore('screenshot', () => { } // 自动保存到指定目录 if (settings.value.autoSave && settings.value.saveDir) { - const ts = new Date() - .toISOString() - .replace(/[:.]/g, '-') - .slice(0, 19) - const path = `${settings.value.saveDir.replace(/\\$/, '')}\\screenshot_${ts}.png` + const path = `${settings.value.saveDir.replace(/\\$/, '')}\\${screenshotFileName()}` try { await commands.screenshotSavePng(pngBase64, path) } catch (e) { diff --git a/src/stores/smartHomeStore.ts b/src/stores/smartHomeStore.ts new file mode 100644 index 0000000..d9e48ea --- /dev/null +++ b/src/stores/smartHomeStore.ts @@ -0,0 +1,1071 @@ +import { defineStore } from 'pinia' +import { computed, ref, watch } from 'vue' +import { invoke } from '@tauri-apps/api/core' +import { listen } from '@tauri-apps/api/event' +import { openUrl } from '@tauri-apps/plugin-opener' +import { toast } from 'vue-sonner' + +/** + * 智能家居模块(Home Assistant)前端状态。 + * + * P0:连接 + 端点(链路)。P1:实体列表(只读)。 + * 迁移注意:本模块一律用裸 `invoke`(同 monitorStore 的做法),不依赖 + * `src/lib/bindings.ts` —— 那份是 debug 构建时由 specta 覆盖生成的, + * 依赖它会让「还没跑过一次 debug 构建」的开发态直接编译不过。 + * + * 边界:这里只存**原始数据 + 偏好**;「分组 / 图标 / 状态文案 / 是否可控」 + * 由 `src/modules/smarthome/format.ts` 决定,不需要的语义不进 store。 + */ + +/** 端点(链路)类型:局域网直连 / 反代(Cloudflare Tunnel 等) */ +export type EndpointKind = 'local' | 'remote' +/** 端点选择策略:自动(局域网优先)/ 强制局域网 / 强制反代 */ +export type EndpointMode = 'auto' | 'local' | 'remote' + +export interface HaConnectionView { + id: string + name: string + localUrl: string + remoteUrl: string + endpointMode: EndpointMode + insecure: boolean + hasToken: boolean + /** 令牌掩码(明文永远不回前端) */ + tokenMasked: string + lastOkUrl: string + /** unix 秒,0 = 从未 */ + lastOkAt: number + haVersion: string + locationName: string + /** 温度单位(`°C` / `°F`)—— climate 的温度显示必须用它,不能写死 */ + temperatureUnit: string + /** 本次会话实际使用的端点(未探测过为 null) */ + endpointUrl: string | null + endpointKind: EndpointKind | null + endpointLatencyMs: number | null +} + +export interface HaUiSettings { + autoRefreshSec: number + hiddenDomains: string[] + hiddenEntityIds: string[] + favoriteEntityIds: string[] + confirmDangerous: boolean +} + +export interface HaRealtimeSettings { + enabled: boolean + lastConnectedAt: number +} + +export interface HaSettingsView { + version: number + activeId: string + connections: HaConnectionView[] + ui: HaUiSettings + realtime: HaRealtimeSettings +} + +export interface HaSaveConnectionResult { + id: string + settings: HaSettingsView +} + +export interface HaConnectionInput { + id: string + name: string + localUrl: string + remoteUrl: string + endpointMode: EndpointMode + insecure: boolean +} + +/** 单个地址的探测结果(「测试连接」逐地址返回) */ +export interface EndpointProbe { + url: string + kind: EndpointKind + ok: boolean + haVersion: string + locationName: string + temperatureUnit: string + elapsedMs: number + error: string | null + /** auth | network | server | other */ + errorKind: string | null +} + +/** 当前链路检测结果 */ +export interface LinkInfo { + url: string | null + kind: EndpointKind | null + ok: boolean + latencyMs: number + error: string | null + /** auth | network | config */ + errorKind: string | null +} + +/** 实体摘要(与 Rust `EntitySummary` 对齐;表现层语义见 modules/smarthome/format.ts) */ +export interface EntitySummary { + entityId: string + domain: string + name: string + state: string + numeric: number | null + unit: string + deviceClass: string + brightness: number | null + position: number | null + targetTemp: number | null + /** 空调可设上下限(**单位随系统单位制**,如美制 61–86) */ + minTemp: number | null + maxTemp: number | null + currentTemp: number | null + lastChanged: string + /** 自动化 / 脚本的上次触发时间(空 = 从未触发) */ + lastTriggered: string + /** HA 的 `supported_features` 位掩码(语义按 domain 不同,由前端解释) */ + supportedFeatures: number + /** 灯的 `supported_color_modes` */ + supportedColorModes: string[] + minColorTempKelvin: number | null + maxColorTempKelvin: number | null + colorTempKelvin: number | null + hvacModes: string[] + targetTempStep: number | null + volumeLevel: number | null + percentage: number | null + /** `number` 的可设上下限与步长 */ + min: number | null + max: number | null + step: number | null + /** `select` 的可选项 */ + options: string[] +} + +/** 服务调用的可选参数(与 Rust `ServiceParams` 对齐;只传真正需要的字段) */ +export interface ServiceParams { + brightnessPct?: number + colorTempKelvin?: number + position?: number + temperature?: number + hvacMode?: string + percentage?: number + volumeLevel?: number + /** `number.set_value` */ + value?: number + /** `select.select_option` */ + option?: string +} + +export interface ServiceCallResult { + /** 服务响应里带回的已变化实体(可能为空:部分云端集成"发完就返回") */ + entities: EntitySummary[] +} + +export interface EntityListResult { + entities: EntitySummary[] + /** unix 秒:服务端数据的抓取时刻 */ + fetchedAt: number + fromCache: boolean +} + +/** + * 命令层错误(Rust `HaApiError`)。 + * + * 分类由 Rust 判定,前端只做呈现分支 —— 不靠匹配错误文案猜。 + */ +export interface HaApiError { + /** auth | network | config | server | other */ + kind: string + message: string +} + +/** Tauri 的 rejected promise 带的是**序列化后的值**(不是 Error 实例),这里做归一化 */ +export function toApiError(e: unknown): HaApiError { + if (e && typeof e === 'object' && 'kind' in e && 'message' in e) { + const o = e as { kind: unknown; message: unknown } + return { kind: String(o.kind), message: String(o.message) } + } + return { kind: 'other', message: String(e) } +} + +// ============================== P4:实时推送 ============================== + +/** WebSocket 连接状态(与 Rust `WsStatus` 对齐) */ +export interface WsStatus { + connId: string + /** idle | connecting | connected | authFailed | disconnected */ + state: string + detail: string + connectedAt: number + lastEventAt: number + entityCount: number +} + +/** 一条状态增量批次(Rust 200ms 聚合后发来) */ +export interface StateBatch { + connId: string + added: EntitySummary[] + changed: EntitySummary[] + removed: string[] +} + +/** 区域(房间) */ +export interface HaArea { + areaId: string + name: string +} + +export interface HaDevice { + id: string + name: string + /** 用户在 HA 里改过的名字(为空时用 `name`) */ + nameByUser: string + /** 空 = 未分配房间 */ + areaId: string + manufacturer: string + model: string +} + +/** 实体注册表条目(**设备聚合的唯一来源**:REST 的状态里没有 device_id) */ +export interface EntityRegistryEntry { + entityId: string + /** 空 = 未归组到设备 */ + deviceId: string + name: string + originalName: string + /** `''` | `config` | `diagnostic` */ + entityCategory: string +} + +/** 注册表结果(房间分组 + 设备聚合的唯一来源) */ +export interface RegistryResult { + areas: HaArea[] + devices: HaDevice[] + /** `entityId` → `areaId`(Rust 侧已做「实体 → 设备 → 区域」三级回退) */ + entityAreas: Record + entityRegistry: EntityRegistryEntry[] + fetchedAt: number +} + +// ============================== P4:本地规则 ============================== + +export interface RuleTrigger { + entityId: string + /** 命中这些状态才触发(空 = 任意变化) */ + to: string[] + from: string[] + /** 持续 N 秒仍满足才触发(0 = 立即) */ + forSec: number + /** 空 = 不做数值判断;否则 `>` `>=` `<` `<=` `==` `!=` */ + numericOp: string + numericValue: number | null +} + +export interface RuleCondition { + /** state | time */ + kind: string + entityId: string + state: string + fromTime: string + toTime: string + /** 1=周一 … 7=周日;空 = 每天 */ + weekdays: number[] +} + +export interface RuleAction { + /** service | delay | notify */ + kind: string + domain: string + service: string + entityId: string + params: ServiceParams + seconds: number + title: string + message: string +} + +export interface Rule { + id: string + name: string + enabled: boolean + trigger: RuleTrigger + conditions: RuleCondition[] + actions: RuleAction[] + cooldownSec: number + lastFiredAt: number + fireCount: number + lastError: string +} + +export interface RuleRecord { + ruleId: string + ruleName: string + at: number + ok: boolean + detail: string +} + +export interface RuleListResult { + enabled: boolean + rules: Rule[] + records: RuleRecord[] +} + +/** 新建规则:默认值与 Rust `Rule::default()` 对齐(冷却 30s 防抖动) */ +export function emptyRule(): Rule { + return { + id: '', + name: '', + enabled: true, + trigger: { + entityId: '', + to: [], + from: [], + forSec: 0, + numericOp: '', + numericValue: null + }, + conditions: [], + actions: [], + cooldownSec: 30, + lastFiredAt: 0, + fireCount: 0, + lastError: '' + } +} + +/** 新建一个空动作(默认"调服务",这是最常见的一种) */ +export function emptyAction(): RuleAction { + return { + kind: 'service', + domain: '', + service: '', + entityId: '', + params: {}, + seconds: 0, + title: '', + message: '' + } +} + +/** 规则记录的内存条数上限(与 Rust `automation::MAX_RECORDS` 对齐) */ +const MAX_RULE_RECORDS = 50 + +/** 自动刷新可选间隔(秒),0 = 关闭 */ +export const AUTO_REFRESH_OPTIONS = [0, 5, 10, 30] as const + +/** + * 控制后的校正窗口。 + * + * 远端(反代)必须给得更宽:命令下发 → HA 处理 → 米家云确认 → 状态反映, + * 一路加上 100–400ms 的 RTT,600ms 在远端必然误判成"状态没变"。 + */ +export const LOCAL_CORRECTION_MS = 600 +export const REMOTE_CORRECTION_MS = 2000 + +/** + * 实时推送下的"没等到推送"兜底窗口。 + * + * plan §5.3 的 P4 分支要求:乐观更新 + 等 WS 推送校正,**1.5s 超时兜底**。 + * 没有兜底时,命令返回 200 但设备真没变(小米云断连的典型表现)会让 UI + * 永远停在乐观值 —— 那正是 P2 特意要避免的"假装成功"。 + */ +export const WS_CORRECTION_FALLBACK_MS = 1500 + +/** 两个实体"看起来是否一样":只比一次控制能改动的字段(用于校正判定) */ +function sameVisualState(a: EntitySummary, b: EntitySummary): boolean { + return ( + a.state === b.state && + a.brightness === b.brightness && + a.position === b.position && + a.targetTemp === b.targetTemp && + a.volumeLevel === b.volumeLevel && + a.percentage === b.percentage + ) +} + +export const useSmartHomeStore = defineStore('smartHome', () => { + const settings = ref(null) + /** 首次读取设置是否完成(驱动四态,避免首帧误显示"未配置") */ + const ready = ref(false) + const loading = ref(false) + const error = ref('') + /** 最近一次链路结果 / 最近一次数据请求的失败(共用顶部横幅) */ + const link = ref(null) + const linkChecking = ref(false) + + // ---- 实体列表(P1) ---- + const entities = ref([]) + const fetchedAt = ref(0) + const fromCache = ref(false) + const entitiesLoading = ref(false) + const entitiesError = ref(null) + + // ---- 筛选(会话内状态:放 store 里是为了"切走再切回"不丢) ---- + const filterGroup = ref('all') + /** 房间筛选(`'all'` / `areaId` / 未分配用 format.ts 的 `NO_AREA`) */ + const filterRoom = ref('all') + const searchQuery = ref('') + const onlyControllable = ref(false) + const hideUnavailable = ref(false) + /** + * 是否显示"卡上放不出任何东西的设备"(`Sun`、`Backup`、HA 自身的 Core / Supervisor / OS, + * 以及只有高级项 / 事件的「酷态科10U」「米家体脂秤」…)。真机上这类有 12 个以上, + * **默认隐藏**:它们既没有常用控件也没有读数,放在首页只会把真正的设备淹掉(见 plan §9.9 / §9.10)。 + */ + const showSystemDevices = ref(false) + /** + * 当前打开的**设备详情**(`null` = 停在设备列表)。 + * + * 放在 store 而不是组件 ref:模块 Tab 切走会卸载面板,放组件里切回来就丢了 + * (与 P1 的筛选条件同一个理由,见 plan §9.2)。 + */ + const selectedDeviceId = ref(null) + + // ---- 实时推送(P4) ---- + const wsStatus = ref(null) + const wsBusy = ref(false) + + // ---- 注册表 / 房间(P4) ---- + const registry = ref(null) + const registryLoading = ref(false) + const registryError = ref('') + + // ---- 本地规则(P4) ---- + const rules = ref([]) + const rulesEnabled = ref(false) + const ruleRecords = ref([]) + /** 首次读取规则列表是否还在进行(驱动自动化页的加载态,避免"还没有规则"闪一下) */ + const rulesLoading = ref(false) + /** Tauri 事件监听只注册一次(模块可能被反复挂载) */ + let listenersBound = false + + const connections = computed(() => settings.value?.connections ?? []) + const activeId = computed(() => settings.value?.activeId ?? '') + const activeConnection = computed( + () => connections.value.find((c) => c.id === activeId.value) ?? null + ) + const configured = computed(() => connections.value.length > 0) + const ui = computed(() => settings.value?.ui ?? null) + const autoRefreshSec = computed(() => ui.value?.autoRefreshSec ?? 0) + /** 当前是否走在反代上(远端不提供自动刷新,见 plan §5.2) */ + const isRemoteLink = computed(() => activeConnection.value?.endpointKind === 'remote') + + /** 实时推送开关(持久化偏好) */ + const realtimeEnabled = computed(() => settings.value?.realtime.enabled ?? false) + /** WS 状态字符串(idle / connecting / connected / authFailed / disconnected) */ + const wsState = computed(() => wsStatus.value?.state ?? 'idle') + const wsConnected = computed(() => wsState.value === 'connected') + /** 是否需要实时连接的说明:实时推送开着,或本地规则总开关开着 */ + const realtimeWanted = computed(() => realtimeEnabled.value || rulesEnabled.value) + /** `entityId` → `areaId`(未分配 / 未命中返回 null) */ + function areaIdOf(entityId: string): string | null { + return registry.value?.entityAreas[entityId] ?? null + } + /** 实体友好名(规则摘要里用它,取不到就退回 id —— 规则可能引用已删除的实体) */ + function entityLabel(entityId: string): string { + return entities.value.find((e) => e.entityId === entityId)?.name ?? entityId + } + + function isFavorite(entityId: string): boolean { + return (ui.value?.favoriteEntityIds ?? []).includes(entityId) + } + + /** 模块挂载时读一次设置 */ + async function refresh() { + loading.value = true + error.value = '' + try { + settings.value = await invoke('smarthome_get_settings') + } catch (e) { + error.value = toApiError(e).message + } finally { + loading.value = false + ready.value = true + } + } + + // ---------- 连接 ---------- + + async function saveConnection(input: HaConnectionInput): Promise { + const r = await invoke('smarthome_save_connection', { input }) + settings.value = r.settings + return r.id + } + + async function setToken(connId: string, token: string) { + settings.value = await invoke('smarthome_set_token', { connId, token }) + } + + async function clearToken(connId: string) { + settings.value = await invoke('smarthome_clear_token', { connId }) + } + + async function removeConnection(connId: string) { + settings.value = await invoke('smarthome_delete_connection', { connId }) + resetConnectionScope() + } + + async function activate(connId: string) { + settings.value = await invoke('smarthome_activate_connection', { connId }) + resetConnectionScope() + } + + /** + * 清掉一切"属于上一条连接"的会话状态。 + * + * 为什么连**房间**也要清:房间 id 与实体 id 都是实例级的东西。换实例后若 + * `filterRoom` 还锁着旧实例的 areaId,左栏列表是旧的、卡片网格却是空的 + * (而且用户看不出原因);Rust 侧的注册表缓存同理(带 connId 校验 + 显式失效)。 + */ + function resetConnectionScope() { + link.value = null + entities.value = [] + entitiesError.value = null + fetchedAt.value = 0 + registry.value = null + registryError.value = '' + filterRoom.value = 'all' + // 打开的详情页属于旧实例 + selectedDeviceId.value = null + } + + /** 打开某个设备的详情(二级页面) */ + function openDevice(deviceId: string) { + selectedDeviceId.value = deviceId + } + + /** 从详情页返回设备列表 */ + function closeDevice() { + selectedDeviceId.value = null + } + + async function setEndpointMode(connId: string, mode: EndpointMode) { + settings.value = await invoke('smarthome_set_endpoint_mode', { + connId, + mode + }) + link.value = null + } + + /** 逐个地址测试(草案也能测,无需先保存)。token 留空则沿用已存令牌 */ + async function testConnection( + input: HaConnectionInput, + token: string + ): Promise { + return invoke('smarthome_test_connection', { input, token }) + } + + /** 检测当前链路:按端点策略强制新探测一次(顺带补齐 HA 版本 / 实例名) */ + async function checkLink(connId: string): Promise { + linkChecking.value = true + try { + const info = await invoke('smarthome_check_link', { connId }) + link.value = info + if (info.ok) await refresh() + return info + } finally { + linkChecking.value = false + } + } + + /** 用浏览器打开 HA 自己的前端(可带路径)—— 排障与"去 HA 里改"的统一出口 */ + async function openHaPage(path = '') { + const c = activeConnection.value + const base = c?.endpointUrl || c?.localUrl || c?.remoteUrl + if (!base) { + toast.error('还没有可用的 HA 地址') + return + } + try { + await openUrl(`${base}${path}`) + } catch (e) { + toast.error(String(e)) + } + } + + // ---------- 实体 ---------- + + /** + * 拉取实体列表。 + * + * `force = false` 时后端在 60s 缓存内直接返回缓存(反代链路上省一次几百 KB 的请求)。 + * + * 失败处理有**分叉**: + * - `auth`(令牌失效)→ 清空实体:旧数据可能是上一个有效令牌留下的,留着会误导 + * - 其它(网络抖动 / 隧道瞬断)→ **保留**已有数据,只在页面上加一条错误提示: + * 远端链路上的瞬时失败很常见,把整屏清空比"看到略旧的数据 + 明确的更新时间"更糟 + */ + async function loadEntities(force = false) { + if (!activeId.value) return + // 并发守卫:挂载触发与自动刷新可能撞在一起(重复拉全量在远端链路上很贵) + if (entitiesLoading.value) return + entitiesLoading.value = true + try { + const r = await invoke('smarthome_list_entities', { + connId: activeId.value, + force + }) + entities.value = r.entities + fetchedAt.value = r.fetchedAt + fromCache.value = r.fromCache + entitiesError.value = null + // 拉取成功即说明链路可用:清掉上一次的失败横幅 + if (link.value && !link.value.ok) link.value = null + // 首次拉取时后端会顺带补上实例信息(版本 / 实例名 / 温度单位,见 commands.rs), + // 但那是写进设置的,前端要再读一次设置才拿得到 —— 只在他还不知道时读一次 + if (!activeConnection.value?.haVersion) await refresh() + } catch (e) { + const err = toApiError(e) + entitiesError.value = err + // 顶部横幅复用同一份失败信息(auth → 提示重填令牌) + link.value = { + url: null, + kind: null, + ok: false, + latencyMs: 0, + error: err.message, + errorKind: err.kind + } + if (err.kind === 'auth') { + entities.value = [] + fetchedAt.value = 0 + } + } finally { + entitiesLoading.value = false + } + } + + // ============================== P4:实时推送 ============================== + + /** + * 把一批增量合并进实体列表。 + * + * 为什么不是整份替换:WS 打开时每次只变几个实体,整份替换会让 577 个卡片 + * 全部重算一遍(plan §6.5 说的就是这件事)。这里重建一次索引后 O(1) 合并, + * 每条批次只换一次数组引用。 + */ + function applyBatch(batch: StateBatch) { + if (batch.connId !== activeId.value) return + const index = new Map(entities.value.map((e) => [e.entityId, e])) + for (const e of batch.added) index.set(e.entityId, e) + for (const e of batch.changed) index.set(e.entityId, e) + for (const id of batch.removed) index.delete(id) + entities.value = [...index.values()] + // 推送即新鲜:`更新于` 立刻回到"刚刚" + fetchedAt.value = Math.floor(Date.now() / 1000) + fromCache.value = false + entitiesError.value = null + if (link.value && !link.value.ok) link.value = null + } + + /** 注册 Rust → 前端的事件监听(只注册一次)。 */ + async function initListeners() { + if (listenersBound) return + listenersBound = true + // 连接状态(含 WS):authFailed / disconnected 要显示在横幅上 + await listen('smarthome-connection-status', (e) => { + wsStatus.value = e.payload + }) + await listen('smarthome-state-batch', (e) => { + applyBatch(e.payload) + }) + await listen('smarthome-rule-fired', (e) => { + const record = e.payload + ruleRecords.value = [record, ...ruleRecords.value].slice(0, MAX_RULE_RECORDS) + // **只在失败时弹提示**:成功是常态,一条"每 30 秒触发一次"的规则 + // 会变成持续弹窗;成功与否看运行记录与列表里的最近触发即可 + if (!record.ok) { + toast.error(`规则「${record.ruleName}」执行失败`, { description: record.detail }) + } + // 触发后统计变了(fireCount / lastError),刷一次列表 + void loadRules() + }) + await refreshWsStatus() + void loadRules() + } + + async function refreshWsStatus() { + try { + wsStatus.value = await invoke('smarthome_ws_status') + } catch { + /* 状态读不到不影响使用(没有连接时 Rust 也会返回 idle) */ + } + } + + /** 开关实时推送(持久化)。 */ + async function setRealtimeEnabled(enabled: boolean) { + settings.value = await invoke('smarthome_set_realtime_enabled', { enabled }) + await refreshWsStatus() + } + + async function startRealtime() { + const conn = activeConnection.value + if (!conn) return + wsBusy.value = true + try { + wsStatus.value = await invoke('smarthome_ws_start', { connId: conn.id }) + } finally { + wsBusy.value = false + } + } + + async function stopRealtime() { + wsBusy.value = true + try { + wsStatus.value = await invoke('smarthome_ws_stop') + } finally { + wsBusy.value = false + } + } + + /** + * 确保实时连接已建立(幂等)。 + * + * 为什么前端也要做一次:Rust 侧在启动时会按设置恢复连接,但那可能失败 + * (启动时网络还没就绪、令牌刚被吊销又补填)。模块打开时补一次, + * 用户不必自己去设置页点"重新连接"。 + */ + async function ensureRealtime() { + if (!activeId.value || !realtimeWanted.value) return + if (wsConnected.value || wsState.value === 'connecting') return + try { + await startRealtime() + } catch (e) { + wsStatus.value = { + connId: activeId.value, + state: 'disconnected', + detail: toApiError(e).message, + connectedAt: 0, + lastEventAt: 0, + entityCount: 0 + } + } + } + + // ============================== P4:注册表(房间) ============================== + + /** 拉取房间映射(需要实时连接;缓存 5 分钟)。失败**不影响设备页**,只在左栏给一条提示。 */ + async function loadRegistry(force = false) { + if (!activeId.value || registryLoading.value) return + registryLoading.value = true + try { + registry.value = await invoke('smarthome_list_registry', { + connId: activeId.value, + force + }) + registryError.value = '' + } catch (e) { + registry.value = null + registryError.value = toApiError(e).message + } finally { + registryLoading.value = false + } + } + + // ============================== P4:本地规则 ============================== + + function applyRules(result: RuleListResult) { + rulesEnabled.value = result.enabled + rules.value = result.rules + ruleRecords.value = result.records.slice(0, MAX_RULE_RECORDS) + } + + async function loadRules() { + rulesLoading.value = true + try { + applyRules(await invoke('smarthome_list_rules')) + } catch { + /* 规则读失败不弹错(设置页 / 自动化页会显示空态) */ + } finally { + rulesLoading.value = false + } + } + + async function saveRule(rule: Rule): Promise { + const result = await invoke('smarthome_save_rule', { rule }) + applyRules(result) + return result + } + + async function deleteRule(ruleId: string): Promise { + const result = await invoke('smarthome_delete_rule', { ruleId }) + applyRules(result) + return result + } + + async function setRulesEnabled(enabled: boolean): Promise { + const result = await invoke('smarthome_set_rules_enabled', { enabled }) + applyRules(result) + // 开关动过之后 Rust 可能刚建/断了连接,同步一下状态 + await refreshWsStatus() + return result + } + + /** 整体覆盖写入界面偏好;失败时回滚(乐观更新的代价) */ + async function saveUi(next: HaUiSettings) { + const prev = settings.value?.ui ?? null + if (settings.value) settings.value = { ...settings.value, ui: next } + try { + settings.value = await invoke('smarthome_save_ui_settings', { ui: next }) + } catch (e) { + if (prev && settings.value) settings.value = { ...settings.value, ui: prev } + throw toApiError(e) + } + } + + /** 就地替换某个实体(数组元素赋值即可触发更新,不必整份重拉) */ + function patchEntity(entityId: string, patch: Partial) { + const i = entities.value.findIndex((e) => e.entityId === entityId) + if (i < 0) return + entities.value[i] = { ...entities.value[i], ...patch } + } + + /** + * 校正:分级窗口后拉一次单个实体。 + * + * - 状态**确实变了** → 采用服务端结果(可能是"用户的意图被拒绝"或"被其他规则改了") + * - 状态**没变** → 回滚 + 诚实提示。小米设备经米家云时这种情况真的会出现, + * 措辞必须诚实(§5.3),不能假装成功 + * - 请求本身失败 → 不动 UI:宁可相信意图已生效,等下次刷新见真章 + */ + function scheduleCorrection(entityId: string, prev: EntitySummary) { + const delay = isRemoteLink.value ? REMOTE_CORRECTION_MS : LOCAL_CORRECTION_MS + window.setTimeout(() => { + void (async () => { + try { + const fresh = await invoke('smarthome_get_entity', { + connId: activeId.value, + entityId + }) + if (sameVisualState(fresh, prev)) { + patchEntity(entityId, prev) + toast.warning('命令已下发,但设备状态未变化') + } else { + patchEntity(entityId, fresh) + } + } catch { + /* 校正失败不改 UI */ + } + })() + }, delay) + } + + /** + * 实时推送开的场景:等 WS 推送来校正,但**必须有兜底**。 + * + * 判定标准只看"这个实体在这 1.5s 内有没有被推送改过": + * - 改过(且与乐观值一致或不一致)→ 采用推送结果,不做任何回滚 + * - 没改过(推送可能没来、也可能是设备压根没动)→ 回滚 + 诚实提示 + */ + function scheduleWsFallback(entityId: string, prev: EntitySummary) { + window.setTimeout(() => { + const cur = entities.value.find((e) => e.entityId === entityId) + if (!cur) return + if (!sameVisualState(cur, prev)) return + patchEntity(entityId, prev) + toast.warning('命令已下发,但设备状态未变化') + }, WS_CORRECTION_FALLBACK_MS) + } + + /** + * 下发一次控制(P2 的统一入口)。 + * + * 顺序(§5.3 的落地版,§9.3 记录了与计划的差异): + * 1. **乐观更新**:立刻按"意图"改写本地状态(点灯就马上亮) + * 2. 调服务 + * 3. 服务响应若**确实带回了新状态**(与发起前不同)→ 直接采用,省掉一次往返 + * 4. 否则在分级窗口后拉单个实体校正 + * + * `optimistic` 为空对象 = 这类动作**本就没有可预期的状态变化**(执行场景 / 脚本、 + * 停止窗帘):那就既不用快速通道也不做校正 —— 否则会拿"状态没变"去冤枉一次成功执行。 + */ + async function control( + entity: EntitySummary, + service: string, + params: ServiceParams, + optimistic: Partial, + domain: string = entity.domain + ): Promise { + if (!activeId.value) return + const prev = entities.value.find((e) => e.entityId === entity.entityId) + if (!prev) return + + patchEntity(entity.entityId, optimistic) + + try { + const r = await invoke('smarthome_call_service', { + connId: activeId.value, + domain, + service, + entityId: entity.entityId, + params + }) + // 下发成功即说明链路可用:清掉上一次的失败横幅 + if (link.value && !link.value.ok) link.value = null + + if (Object.keys(optimistic).length === 0) return + + const server = r.entities.find((e) => e.entityId === entity.entityId) + if (server && !sameVisualState(server, prev)) { + patchEntity(entity.entityId, server) + return + } + // 实时推送开着时不再单独拉单实体校正(plan §5.3 的"P4 之后"分支): + // 推送本身就是服务端真值;但**必须有超时兜底** —— 推送可能根本没来 + if (wsConnected.value) { + scheduleWsFallback(entity.entityId, prev) + return + } + scheduleCorrection(entity.entityId, prev) + } catch (e) { + patchEntity(entity.entityId, prev) + const err = toApiError(e) + if (err.kind === 'auth') { + link.value = { + url: null, + kind: null, + ok: false, + latencyMs: 0, + error: err.message, + errorKind: 'auth' + } + } + throw err + } + } + + async function toggleFavorite(entityId: string) { + const cur = ui.value + if (!cur) return + const list = new Set(cur.favoriteEntityIds) + if (list.has(entityId)) list.delete(entityId) + else list.add(entityId) + await saveUi({ ...cur, favoriteEntityIds: [...list] }) + } + + async function setAutoRefreshSec(sec: number) { + const cur = ui.value + if (!cur) return + await saveUi({ ...cur, autoRefreshSec: sec }) + } + + /** + * 首次拉取:**等设置就绪**再触发。 + * + * 不能写在组件的 `onMounted` 里 —— 挂载那一刻 `activeId` 还是空串,`loadEntities()` + * 会命中"无激活连接就直接返回"的守卫而静默不做事(真机测试踩到过,见 §9.2)。 + * 放在 store 里,设备页与自动化页就不必各自重复这一段。 + */ + watch([ready, activeId], () => { + if (ready.value && activeId.value) void loadEntities() + }) + + /** + * 实时连接建立后:拉一次房间映射(注册表只能走 WS)。 + * + * 放在"连上之后"而不是"打开实时开关之后":从建连到 `auth_ok` 在反代上要 2 秒左右, + * 开关一开就去查注册表必然失败(那时 WS 还没连上)。 + */ + watch(wsState, (state) => { + if (state === 'connected') void loadRegistry() + }) + + /** 规则列表与设置就绪后拉一次(自动化页不重复这段)。 */ + watch([ready, activeId], () => { + if (ready.value) void loadRules() + }) + + /** + * 设置就绪 / 换连接 / 实时需求变化后,**幂等地**确保实时连接存在。 + * + * 放在 watch 里而不是组件的 `onMounted`:挂载那一刻设置还没读完 + * (`void store.refresh()` 是异步的),`realtimeWanted` 必然是 false, + * 在 onMounted 里做这件事会静默什么都不做。 + */ + watch([ready, activeId, realtimeWanted], () => { + if (ready.value) void ensureRealtime() + }) + + return { + // 设置 + settings, + ready, + loading, + error, + connections, + activeId, + activeConnection, + configured, + ui, + autoRefreshSec, + isRemoteLink, + isFavorite, + refresh, + // 连接 + saveConnection, + setToken, + clearToken, + removeConnection, + activate, + setEndpointMode, + testConnection, + checkLink, + openHaPage, + link, + linkChecking, + // 实体 + entities, + fetchedAt, + fromCache, + entitiesLoading, + entitiesError, + loadEntities, + control, + saveUi, + toggleFavorite, + setAutoRefreshSec, + // 实时推送(P4) + wsStatus, + wsState, + wsConnected, + wsBusy, + realtimeEnabled, + realtimeWanted, + initListeners, + refreshWsStatus, + setRealtimeEnabled, + startRealtime, + stopRealtime, + ensureRealtime, + // 注册表 / 房间(P4) + registry, + registryLoading, + registryError, + loadRegistry, + areaIdOf, + entityLabel, + // 本地规则(P4) + rules, + rulesEnabled, + rulesLoading, + ruleRecords, + loadRules, + saveRule, + deleteRule, + setRulesEnabled, + // 筛选(会话内) + filterGroup, + filterRoom, + searchQuery, + onlyControllable, + hideUnavailable, + showSystemDevices, + // 设备详情(会话内) + selectedDeviceId, + openDevice, + closeDevice + } +})