docs: reorganize project documentation

2026-08-28 10:38:47 +08:00
parent 32c7d4f8cc
commit 1adcb0fb3b
22 changed files with 495 additions and 5202 deletions
@@ -1,81 +1,75 @@
-# 红外控制硬件验证规范与记录 / Infrared Hardware Validation Guide & Records
+# 红外控制器硬件验证

-## 1. 硬件环境与已知设备信息 / Hardware Environment
+## 范围与安全要求

-真实硬件验证只允许在获授权的隔离局域网中进行。文档不记录完整网关地址、IEEE 地址、凭据、令牌、红外码值或原始 SDK 响应；设备名称也应使用脱敏别名。
+本流程只用于已授权的隔离局域网和实体设备。测试记录使用脱敏 profile、设备和操作标识，不记录密码、Token、完整网关地址、完整硬件标识、原始 SDK 响应或红外码值。

- **设备名称**: 脱敏的红外控制器别名
- **设备类型**: 红外控制器
- **网关/主机**: 获授权的 ABox 智能主机
- **被控实体**: 获授权的实体空调、电视或其他电器
+真机验证必须使用 ABox Provider。本地体验只能验证界面和状态机，不能作为红外硬件通过证据。

---
+## 前置条件

-## 2. 硬件测试记录表 / Hardware Validation Log
+- 使用与待发布提交一致的 APK；
+- 已通过 ABox 登录并进入设备中心；
+- 网关中的红外设备名称与 App 当前设备名称一致；默认名称为 `红外控制器`；
+- 红外控制器已通电，并可对准一个获授权的实体电视、空调、风扇或其他设备；
+- 系统时间、网络和通知权限状态已记录。

-| 日期 | App Commit | 运行模式 | 脱敏 Profile | 脱敏设备名 | 脱敏操作标识 | 操作 | 耗时区间 | 脱敏错误分类 | 物理响应 | 结论 |
-|---|---|---|---|---|---|---|---|---|---|
-| 待填 | 待填 | 本地体验 | local-test | simulation-ir | test-1 | Learn/Send | 待填 | 无 | 模拟流程通过 | 仅软件验证 |
-| 待填 | 待填 | ABox | profile-redacted | device-redacted | operation-redacted | Learn | 待填 | 待填 | 授权遥控器完成学习 | 待真机执行 |
-| 待填 | 待填 | ABox | profile-redacted | device-redacted | operation-redacted | Send | 待填 | 待填 | 授权电器产生预期响应 | 待真机执行 |
+## 验证流程

---
+### 1. 默认内容与管理页

-## 3. 标准真机测试流程 (12 项用例) / Standard 12-Step Test Procedure
+1. 首次进入红外控制器，确认存在“自定义电视遥控器”和“自定义面板遥控器”。
+2. 打开管理页，确认硬件槽位位于顶部。
+3. 确认每个遥控器提供排序和编辑入口，而不是列表内直接删除。
+4. 修改红外控制器设备名称后，确认后续网关调用使用新名称；名称与网关不一致时应明确失败。

-### 用例 1: 真实会话认证前置 (Authenticate Session)
- **前置**: 通过登录模块对进程单例 `AbsdkBridge` 进行登录认证。
- **步骤**: 检查进入红外控制页面前，会话是否有效。
- **预期**: 若未认证，真实模式操作返回会话无效错误并提示返回登录。
+### 2. 添加预置遥控器

-### 用例 2: 输入并保存真实设备名 (Enter and Save irDevName)
- **步骤**: 在“红外设备名称”输入框中输入获授权设备名，点击“保存设备名”。
- **预期**: 本地 Room 保存成功，页面显示脱敏设备名并启用学习入口。
+1. 点击添加遥控器。
+2. 第一步选择从红外码库下载预置遥控器。
+3. 选择一种可用设备类型与预置项并完成下载。
+4. 确认新遥控器出现在列表末尾，并位于遥控器页面导航的最右端。
+5. 发送多个按键，确认实体设备响应，界面显示真实操作结果。
+6. 确认预置遥控器没有学习入口。
+7. 记录逐项下载失败时的状态，确认部分失败不会被显示为全部成功。

-### 用例 3: 学习全新唯一按键 (Learn Unique Key)
- **步骤**: 点击“学习新按键”，输入显示名称（如“空调开”），点击“开始学习”；将物理遥控器对准红外控制器按下按键。
- **预期**: 本地先写入 `LEARNING` 状态，硬件捕获完成后状态自动刷新为 `READY`，记录响应耗时与返回码。
+### 3. 添加自定义遥控器

-### 用例 4: 立即发射已学习按键 (Send Learned Key Immediately)
- **步骤**: 学习成功后，点击该按键右侧的“发射”按钮。
- **预期**: ABSDK 返回 `00000`，实体电器执行对应操作，发射期间按钮防重复点击。
+1. 再次点击添加遥控器。
+2. 第一步选择通过学习模式创建自定义遥控器。
+3. 分别验证电视布局和自定义面板布局。
+4. 在自定义面板中添加新按钮，编辑名称并调整顺序。
+5. 确认新按钮初始状态为“未学习”，而不是“学习失败”。

-### 用例 5: 重复发射验证稳定性 (Repeat Send)
- **步骤**: 间隔 3 秒再次点击同一按键的“发射”按钮。
- **预期**: 发射稳定成功，电器再次响应，按键保持 `READY` 状态不变。
+### 4. 学习与发送

-### 用例 6: 重新学习同一 SDK Key (Relearn Same Key)
- **步骤**: 针对已存在或失败的按键点击“重试”/重新学习。
- **预期**: 复用相同的 `InfraredKeyId` 和 `sdkKey`，先变更为 `LEARNING`，学习完成后恢复 `READY`，不生成冗余记录。
+1. 对一个未学习按钮开始学习，并在物理遥控器上发送信号。
+2. 确认状态从未学习进入学习中，再进入可发送状态。
+3. 立即发送该按键，确认实体设备响应。
+4. 重新学习同一按钮，确认复用原按钮记录，不生成重复按钮。
+5. 学习过程中离开页面，稍后返回，确认任务结果已持久化。
+6. 学习过程中强制结束 App，再次进入后，确认遗留学习状态被保守恢复为失败并允许重试。

-### 用例 7: 控制器断电/离线测试 (Controller Offline)
- **步骤**: 拔掉红外控制器电源，发起学习或发射。
- **预期**: ABSDK 返回 `20206`，领域层转换为 `DomainError.DeviceOffline`，学习按键标为 `FAILED`，UI 提示控制器离线。
+### 5. 失败与离线

-### 用例 8: 遥控器无信号/超时测试 (No Signal / Learning Timeout)
- **步骤**: 点击“开始学习”，但不按物理遥控器任何按键，等待 SDK 返回。
- **预期**: 记录实际超时等待时间与错误码（如 `20204`/`20205`），按键转换为 `FAILED` 并允许重试。
+1. 开始学习但不发送物理信号，确认超时显示为学习失败，而不是未学习。
+2. 断开红外控制器电源后尝试学习和发送，确认显示设备离线或对应领域错误。
+3. 恢复供电后重试，确认成功结果替换失败状态。
+4. 使 ABox 会话失效后操作，确认返回登录流程，不继续使用旧会话。

-### 用例 9: 学习过程中离开页面 (Leave Page During Learning)
- **步骤**: 点击开始学习后，立即点击“返回”离开红外页面；稍后重新进入。
- **预期**: Application 协程作用域内任务继续执行，学习完成后 Room 数据库正确持久化结果，重新进入显示最新状态。
+### 6. 排序、编辑与删除

-### 用例 10: 进程被杀死后状态恢复 (Process Interruption Recovery)
- **步骤**: 在 `LEARNING` 状态下强制杀死 App 进程并重启。
- **预期**: App 启动或重新进入页面时，`RecoverInterruptedInfraredLearning` 将遗留的 `LEARNING` 保守恢复为 `FAILED`，提示用户重新学习。
+1. 调整遥控器顺序，离开并重新进入后确认顺序持久化。
+2. 编辑遥控器名称和布局允许修改的属性，确认列表与详情同步更新。
+3. 删除测试遥控器，确认其按钮和引用得到一致处理，不留下可进入的空详情页。
+4. 验证长英文按钮文本不会溢出、重叠或遮挡操作控件。

-### 用例 11: Token 失效与重新登录 (Token Expiration)
- **步骤**: 使远端会话失效后发起红外操作。
- **预期**: 返回会话无效错误，本地会话被清除，页面提示登录失效并导航返回。
+### 7. 活动记录

-### 用例 12: 检查未文档化响应字段 (Inspect Undocumented Fields)
- **步骤**: 仅在授权的隔离环境中确认响应是否包含已知字段；不得保存或传播原始响应。
- **安全约束**: 严禁将原始响应、令牌、密码、红外码值或未脱敏网络标识打印至日志或写入测试记录。
+1. 完成一次预置按键发送、一次自定义按键学习、一次发送失败和一次离线失败。
+2. 打开活动记录，确认事件按时间显示，并区分操作类型、来源和结果。
+3. 确认记录中没有原始红外码值、Token 或 SDK 响应。

---
+## 结果记录

-## 4. 协议与硬件事实确认记录 / Observed Facts
-
- **SDK 阻塞模式**: 同步阻塞 HTTP POST 调用，由 `AbsdkBridge` 调度至 `Dispatchers.IO` 并通过进程级 `Mutex` 串行执行。
- **数据隔离**: 本地体验使用独立的模拟 profile；ABox 模式使用当前已认证 profile，二者不共享设备、遥控器或会话数据。
- **传输事实**: 真实 ABSDK 使用厂商 JAR 中的明文 HTTP 传输。Debug 与 Release 暴露相同的提供方和硬件路由；项目通过显式传输标记和 manifest 的明文配置接受这一局域网集成风险。该配置不提供机密性或完整性。
+每条记录只包含：日期、App 版本与提交号、脱敏 profile、脱敏设备名、遥控器类型、操作类别、成功/失败/取消分类、粗粒度耗时、实体设备响应摘要和缺陷编号。