From 29de3f2eb5b5abe621d1448bacf291b54b1dcc17 Mon Sep 17 00:00:00 2001
From: mxhsnd <2049295946@qq.com>
Date: Mon, 24 Aug 2026 15:01:18 +0800
Subject: [PATCH] docs: design infrared remote control multi-scene UI

---
 .../2026-08-24-infrared-remote-ui-design.md   | 115 ++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-24-infrared-remote-ui-design.md

diff --git a/docs/superpowers/specs/2026-08-24-infrared-remote-ui-design.md b/docs/superpowers/specs/2026-08-24-infrared-remote-ui-design.md
new file mode 100644
index 0000000..35608ce
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-24-infrared-remote-ui-design.md
@@ -0,0 +1,115 @@
+# 红外遥控器界面与多场景控制设计规范 / Infrared Remote Control UI Specification
+
+## 1. 背景与目标 (Background & Goals)
+
+在完成了底层红外学习、发射、Room 数据库、1~100 整数 Key 槽位管理以及 Fake/Real ABSDK 路由的基础上，本项目需要提供专业且直观的前端遥控器人机交互界面。
+
+### 核心目标
+1. **多场景遥控面板**：提供空调 (Air Conditioner) 与电视 (Television) 两大经典场景遥控器界面，使用圆形、圆角矩形、胶囊、圆形方向盘等拟物/现代图形组件构建真实遥控器外观。
+2. **学习模式与控制模式切换**：右上角提供“红外学习模式”开关，在控制模式下点击按键发射红外，在学习模式下点击按键录制红外。
+3. **固定槽位绑定 (Fixed Slot Binding)**：遥控器上的每一个功能按键具有预设唯一的 1~100 整数槽位编号（例如空调电源为 Slot 1，电视电源为 Slot 21）。
+4. **简洁的符号化设计**：遥控器按键表面只展示标准图标与简写符号（⏻, +, -, ∧, ∨, ❄, 🔊 等），不展示底层数据库中文长名称。
+5. **设置页面解耦与导航**：原“红外控制页面”定位为“红外学习设置页面”（Infrared Settings），通过遥控器右上角设置图标 ⚙️ 进入，用于配置红外设备名和管理全部已学按键列表。
+
+---
+
+## 2. 槽位与按键分配定义 (Slot & Button Mapping)
+
+每个按键定义为一个 `RemoteButtonSpec`，包含按键唯一标识 `id`、对应默认槽位 `defaultSlot`、默认显示名称 `displayName`、图标及在遥控器面板中的图形位置。
+
+### 2.1 空调遥控器 (Air Conditioner: Slots 1–20)
+| 按键 ID | 功能/符号 | 槽位 (irKey) | 默认名称 | UI 形态 |
+|---|---|---|---|---|
+| `AC_POWER` | 电源 ⏻ | `1` | `空调-电源` | 顶部圆形独立红色高亮按键 |
+| `AC_TEMP_UP` | 温度+ 🔼 | `2` | `空调-温度+` | 垂直胶囊上半部分 |
+| `AC_TEMP_DOWN` | 温度- 🔽 | `3` | `空调-温度-` | 垂直胶囊下半部分 |
+| `AC_MODE` | 模式 ❄/☀ | `4` | `空调-模式` | 圆角矩形 |
+| `AC_FAN` | 风速 💨 | `5` | `空调-风速` | 圆角矩形 |
+| `AC_SWING` | 扫风 ↔️ | `6` | `空调-扫风` | 圆角矩形 |
+| `AC_TIMER` | 定时 ⏱️ | `7` | `空调-定时` | 圆角矩形 |
+
+### 2.2 电视遥控器 (Television: Slots 21–50)
+| 按键 ID | 功能/符号 | 槽位 (irKey) | 默认名称 | UI 形态 |
+|---|---|---|---|---|
+| `TV_POWER` | 电源 ⏻ | `21` | `电视-电源` | 顶部圆形红色按键 |
+| `TV_MUTE` | 静音 🔇 | `22` | `电视-静音` | 顶部圆形灰色按键 |
+| `TV_NAV_UP` | 方向上 🔼 | `23` | `电视-上` | 方向环形盘上弧段 |
+| `TV_NAV_DOWN` | 方向下 🔽 | `24` | `电视-下` | 方向环形盘下弧段 |
+| `TV_NAV_LEFT` | 方向左 ◀️ | `25` | `电视-左` | 方向环形盘左弧段 |
+| `TV_NAV_RIGHT` | 方向右 ▶️ | `26` | `电视-右` | 方向环形盘右弧段 |
+| `TV_OK` | 确认 🆗 | `27` | `电视-确定` | 方向盘中心圆形 |
+| `TV_VOL_UP` | 音量+ 🔊+ | `28` | `电视-音量+` | 垂直胶囊上半部分 |
+| `TV_VOL_DOWN` | 音量- 🔉- | `29` | `电视-音量-` | 垂直胶囊下半部分 |
+| `TV_CH_UP` | 频道+ 📺+ | `30` | `电视-频道+` | 垂直胶囊上半部分 |
+| `TV_CH_DOWN` | 频道- 📺- | `31` | `电视-频道-` | 垂直胶囊下半部分 |
+| `TV_HOME` | 主页 🏠 | `32` | `电视-主页` | 中部圆角胶囊按键 |
+| `TV_BACK` | 返回 ↩️ | `33` | `电视-返回` | 中部圆角胶囊按键 |
+| `TV_MENU` | 菜单 ☰ | `34` | `电视-菜单` | 中部圆角胶囊按键 |
+
+---
+
+## 3. 架构与组件设计 (Architecture & Component Design)
+
+### 3.1 导航结构
+```text
+FoundationScreen (首页/网关登录)
+      ↓ 点击 "红外控制" (infrared/{profileId})
+InfraredRemoteScreen (遥控器主界面，默认空调/电视)
+      ├─ 学习模式开关 (Toggle: Learning Mode)
+      ├─ 场景切换器 (Tab: ❄️ 空调 | 📺 电视)
+      ├─ 空调遥控器面板 (AcRemotePanel)
+      ├─ 电视遥控器面板 (TvRemotePanel)
+      └─ 点击右上角 ⚙️ 设置图标
+             ↓ (infrared_settings/{profileId})
+         InfraredSettingsScreen (原红外设置/按键管理列表页面)
+```
+
+### 3.2 状态管理 (`InfraredRemoteViewModel` & `InfraredRemoteUiState`)
+- `InfraredRemoteUiState`:
+  - `selectedScene`: `RemoteScene.AIR_CONDITIONER` 或 `RemoteScene.TELEVISION`
+  - `isLearningMode`: `Boolean`（是否处于学习录制模式）
+  - `activeLearningKeySlot`: `String?`（当前正在进行学习请求的按键槽位）
+  - `sendingKeySlot`: `String?`（当前正在发射信号的按键槽位）
+  - `learnedSlots`: `Map<String, SavedInfraredKey>`（已在 Room 数据库中记录为 READY 的槽位映射）
+  - `savedDeviceName`: `DeviceName?`（当前配置的红外设备名，如 `红外控制器`）
+  - `runtimeMode`: `InfraredRuntimeMode`（Fake 或 Real ABSDK）
+  - `message`: `UiMessage?`（提示信息或错误）
+
+---
+
+## 4. 交互与视觉规范 (Interaction & Visuals)
+
+### 4.1 视觉造型
+1. **遥控器本体外壳 (Remote Body Chassis)**：
+   - 居中放置的圆角卡片，具有微阴影、圆角半径 `28.dp`、外框及哑光质感。
+2. **空调 LCD 虚拟屏**：
+   - 顶部黑色圆角框，内部呈现液晶感绿色/白色字样（如当前目标温度 `26°C` 与工作状态）。
+3. **垂直双向胶囊摇杆 (Vertical Capsule Rockers)**：
+   - 上半区与下半区独立响应点击，中间由细微分割线隔开，常用于“温度 +/-”、“音量 +/-”及“频道 +/-”。
+4. **圆形导航方向盘 (D-Pad Wheel)**：
+   - 直径约 `180.dp` 的圆形组合组件，外环包含 4 个扇区方向按键，内嵌独立的圆形 OK 键。
+
+### 4.2 按键状态机反馈
+1. **控制模式 (学习开关 OFF)**：
+   - **已录制 (READY)**：按键实体呈现饱满质感，点击触发波纹反馈，调用 `sendKey` 发射红外，提示“已发射”。
+   - **未录制 (UNLEARNED)**：按键显示浅色未激活状态；点击弹出轻量提示：`“按键尚未学习，请打开右上角学习模式”`。
+2. **学习录制模式 (学习开关 ON)**：
+   - 顶部呈现橙色高亮提示条：`“🔴 学习模式已开启：点击任意按键开始录制”`。
+   - 所有按键进入可录制状态（带提示外框）。
+   - 点击目标按键后：
+     - 按键上显示微型 Loading 光圈。
+     - 调用 `learnKey(deviceName, defaultSlot, displayName)`。
+     - 手机或控制器捕获红外信号成功后，按键变为 READY 并伴随成功提示。
+
+---
+
+## 5. 验证与测试标准 (Verification & Acceptance Criteria)
+
+1. **单元测试 (Unit Tests)**：
+   - `InfraredRemoteViewModelTest` 覆盖场景切换、学习模式开关、按键已学/未学状态映射、点击发射以及点击学习请求的转发。
+2. **UI 测试 (Compose Tests)**：
+   - 空调与电视遥控器按键正常渲染并带正确 Tag。
+   - 学习模式切换后 UI 状态正确切换。
+3. **真机与编译验收**：
+   - 模块与 App 通过 JVM 测试与打包验证。
+   - 手机上点击空调/电视按键能发起正确的 Slot 编号学习与发射。