docs/testing/infrared-hardware-validation.md

@@ -0,0 +1,85 @@
+# 红外控制硬件验证规范与记录 / Infrared Hardware Validation Guide & Records
+
+## 1. 硬件环境与已知设备信息 / Hardware Environment
+
+本阶段用于真实验证的实体设备信息如下：
+
+- **设备名称**: 红外控制器 (例如 `红外控制器` 或厂商平台绑定的 `irDevName`)
+- **IEEE 地址**: `1c1cfd001dba533c` (短地址: `d822`)
+- **信号强度 (LQI/RSSI)**: `-4`
+- **电量**: `100%`
+- **设备类型**: 红外控制器 (Infrared Controller)
+- **网关/主机**: ABox 智能主机
+- **被控实体**: 实体空调 / 电视遥控器及对应电器
+
+---
+
+## 2. 硬件测试记录表 / Hardware Validation Log
+
+| 日期 (Date) | App Commit | 运行模式 (Mode) | Profile ID | 设备名称 (Device Name) | SDK Key | 操作 (Operation) | 耗时 (ms) | ABSDK Code | 脱敏消息 (Message) | 物理响应 (Physical Response) | 结论 (Result) |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| 2026-08-24 | b27c67f | FAKE | abox:infrared-fake | ir-living | app_ir_power1 | Learn | 120 | 00000 | success | 模拟学习完成并入库 READY | PASS (Fake) |
+| 2026-08-24 | b27c67f | FAKE | abox:infrared-fake | ir-living | app_ir_power1 | Send | 45 | 00000 | success | 模拟发射成功 | PASS (Fake) |
+| 2026-08-24 | 待填 | REAL_ABSDK | abox | 红外控制器 | app_ir_xxxx | Learn | - | - | - | 遥控器对准控制器按下目标按键 | 待真机执行 |
+| 2026-08-24 | 待填 | REAL_ABSDK | abox | 红外控制器 | app_ir_xxxx | Send | - | - | - | 实体电器执行开关/调节响应 | 待真机执行 |
+
+---
+
+## 3. 标准真机测试流程 (12 项用例) / Standard 12-Step Test Procedure
+
+### 用例 1: 真实会话认证前置 (Authenticate Shared Bridge)
+- **前置**: 通过登录模块对进程单例 `AbsdkBridge` 进行登录认证。
+- **步骤**: 检查进入红外控制页面前，会话 Token 是否有效。
+- **预期**: 若未认证，进入 Real 模式操作时返回 `TokenInvalid` 并提示返回登录。
+
+### 用例 2: 输入并保存真实设备名 (Enter and Save irDevName)
+- **步骤**: 在“红外设备名称”输入框中输入 `红外控制器` 或后台分配的真实设备名，点击“保存设备名”。
+- **预期**: 本地 Room 保存成功，页面显示“已保存设备：红外控制器”，启用“学习新按键”入口。
+
+### 用例 3: 学习全新唯一按键 (Learn Unique Key)
+- **步骤**: 点击“学习新按键”，输入显示名称（如“空调开”），点击“开始学习”；将物理遥控器对准红外控制器按下按键。
+- **预期**: 本地先写入 `LEARNING` 状态，硬件捕获完成后状态自动刷新为 `READY`，记录响应耗时与返回码。
+
+### 用例 4: 立即发射已学习按键 (Send Learned Key Immediately)
+- **步骤**: 学习成功后，点击该按键右侧的“发射”按钮。
+- **预期**: ABSDK 返回 `00000`，实体电器执行对应操作，发射期间按钮防重复点击。
+
+### 用例 5: 重复发射验证稳定性 (Repeat Send)
+- **步骤**: 间隔 3 秒再次点击同一按键的“发射”按钮。
+- **预期**: 发射稳定成功，电器再次响应，按键保持 `READY` 状态不变。
+
+### 用例 6: 重新学习同一 SDK Key (Relearn Same Key)
+- **步骤**: 针对已存在或失败的按键点击“重试”/重新学习。
+- **预期**: 复用相同的 `InfraredKeyId` 和 `sdkKey`，先变更为 `LEARNING`，学习完成后恢复 `READY`，不生成冗余记录。
+
+### 用例 7: 控制器断电/离线测试 (Controller Offline)
+- **步骤**: 拔掉红外控制器电源，发起学习或发射。
+- **预期**: ABSDK 返回 `20206`，领域层转换为 `DomainError.DeviceOffline`，学习按键标为 `FAILED`，UI 提示控制器离线。
+
+### 用例 8: 遥控器无信号/超时测试 (No Signal / Learning Timeout)
+- **步骤**: 点击“开始学习”，但不按物理遥控器任何按键，等待 SDK 返回。
+- **预期**: 记录实际超时等待时间与错误码（如 `20204`/`20205`），按键转换为 `FAILED` 并允许重试。
+
+### 用例 9: 学习过程中离开页面 (Leave Page During Learning)
+- **步骤**: 点击开始学习后，立即点击“返回”离开红外页面；稍后重新进入。
+- **预期**: Application 协程作用域内任务继续执行，学习完成后 Room 数据库正确持久化结果，重新进入显示最新状态。
+
+### 用例 10: 进程被杀死后状态恢复 (Process Interruption Recovery)
+- **步骤**: 在 `LEARNING` 状态下强制杀死 App 进程并重启。
+- **预期**: App 启动或重新进入页面时，`RecoverInterruptedInfraredLearning` 将遗留的 `LEARNING` 保守恢复为 `FAILED`，提示用户重新学习。
+
+### 用例 11: Token 失效与重新登录 (Token Expiration)
+- **步骤**: 主机端使 Token 失效或超过 2 小时后发起红外操作。
+- **预期**: 返回 `TokenInvalid`，本地会话被清除，页面提示登录失效并导航返回。
+
+### 用例 12: 检查未文档化响应字段 (Inspect Undocumented Fields)
+- **步骤**: 在调试构建中检查 `ABRet.getDicDatas()` 是否包含未文档化字段。
+- **安全约束**: 严禁将 Raw Payload、Token、密码或未脱敏数据打印至生产日志。
+
+---
+
+## 4. 协议与硬件事实确认记录 / Observed Facts
+
+- **SDK 阻塞模式**: 同步阻塞 HTTP POST 调用，由 `AbsdkBridge` 调度至 `Dispatchers.IO` 并通过进程级 `Mutex` 串行执行。
+- **数据隔离**: `FAKE` 模式自动使用 `profileId:infrared-fake` 隔离数据，`REAL_ABSDK` 模式使用主会话数据。
+- **安全门禁**: 真实 ABSDK 依赖明文传输，Release 构建中完全禁用硬件接口并由 `InfraredReleaseModule` 安全阻断。