abox-mgr/docs/superpowers/specs/2026-08-24-infrared-remote-ui-design.md

红外遥控器界面与多场景控制设计规范 / 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 导航结构

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 编号学习与发射。