feat(infrared): add infrared control, learning, and virtual remote module #9
@@ -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 编号学习与发射。
|
||||||
Reference in New Issue
Block a user