docs: reorganize project documentation

docs/testing/device-data-capability-matrix.md

@@ -1,32 +1,42 @@
 # 设备数据能力矩阵
 
-本文只记录当前代码中有领域端口、实现和测试支撑的设备数据能力。未列出的数据不应在界面中以固定值、随机值、`--` 或伪造图表呈现。
+本文记录正式版代码能够从领域端口获得、确认和持久化的数据能力。未列出的数据不得在界面、活动记录或自动化中以固定值、随机值、占位趋势或推测结果呈现。
 
-| 能力 | ABox | 本地体验 | 依据 | 界面策略 |
-|---|---|---|---|---|
-| 插座开关状态读取 | 支持 | 支持 | `SocketGateway.getStatus` | 展示已确认状态 |
-| 插座开关控制 | 支持 | 支持 | `SocketGateway.commandPower` / `setPower` | 命令完成后回读；回读失败显示等待确认 |
-| 温度当前读数 | 支持，字段可能缺失 | 支持 | `TemperatureHumidityGateway.getReading` | 仅字段存在时展示 |
-| 湿度当前读数 | 支持，字段可能缺失 | 支持 | `TemperatureHumidityGateway.getReading` | 仅字段存在时展示 |
-| 红外按键发送 | 支持 | 支持 | `InfraredGateway.sendKey` | 展示真实操作结果 |
-| 红外按键学习 | 支持 | 支持 | `InfraredGateway.learnKey` | 展示学习状态和结果 |
-| 红外码下载 | 支持 | 支持 | `InfraredGateway.downloadCodes` | 仅用于真实下载流程 |
-| 插座电压/电流/功率/电量 | 不可用 | 不可用 | 没有对应领域端口 | 不渲染 |
-| 插座倒计时 | 不可用 | 不可用 | 没有对应领域端口 | 不渲染 |
-| 插座历史趋势 | 不可用 | 不可用 | 没有历史数据端口 | 不渲染 |
-| 温湿度历史趋势 | 不可用 | 不可用 | 没有历史数据端口 | 不渲染 |
-| 网关诊断延迟 | 不可用 | 不适用 | 没有诊断端口 | 不渲染 |
-| Token 有效期展示 | 不可用 | 不适用 | SDK 未提供可安全展示的有效期端口 | 不渲染 |
+| 能力 | ABox | 本地体验 | 界面与自动化策略 |
+|---|---|---|---|
+| 插座状态读取 | 支持 | 支持 | 展示已确认状态；可作为状态触发器或条件 |
+| 插座开关控制 | 支持 | 支持 | 命令成功后回读；回读失败显示等待确认 |
+| 温度当前读数 | 支持，字段可能缺失 | 支持 | 字段存在时展示；可作为触发器或条件 |
+| 湿度当前读数 | 支持，字段可能缺失 | 支持 | 字段存在时展示；可作为触发器或条件 |
+| 红外按键发送 | 支持 | 支持 | 只记录领域结果，不记录原始码值 |
+| 红外按键学习 | 支持 | 支持 | 仅自定义遥控器使用，区分未学习、失败和完成 |
+| 红外码下载 | 支持 | 支持 | 用于预置遥控器导入，保留逐项成功或失败 |
+| 情景与自动化结果 | 支持 | 支持 | 记录情景及动作级结果 |
+| 系统通知 | 支持，受通知权限影响 | 支持，受通知权限影响 | 权限缺失或系统拒绝时明确失败 |
+| 活动记录 | App 本地持久化 | App 本地持久化 | 按 profile 隔离，支持分页读取 |
+| 插座电压、电流、功率和电量 | 不可用 | 不可用 | 不渲染，不作为自动化数据源 |
+| 插座倒计时 | 不可用 | 不可用 | 不渲染 |
+| 插座与温湿度历史趋势 | 不可用 | 不可用 | 不生成伪历史图表 |
+| 网关诊断延迟 | 不可用 | 不适用 | 不渲染 |
+| Token 精确有效期 | 不可用 | 不适用 | 不展示倒计时或推测时间 |
 
-## Provider 边界
+## 状态确认
 
-- ABox 设备目录只包含用户明确配置的 `DeviceName` 和 `DeviceType`。
-- 本地体验设备来自确定性的模拟目录。
-- 两个 Provider 的设备描述、状态和历史记录不可互换。
-- “不可用”表示没有对应能力，不表示设备故障；界面不添加禁用的伪功能控件。
+- 控制请求成功只表示网关接受了命令，不等于物理设备状态已经确认。
+- 插座控制后必须回读状态；只有回读值与目标一致才显示确认成功。
+- 设备断电、离线或无法读取时，不得在前端仅依据用户点击更新为开启或关闭。
+- 温湿度单个字段缺失时保留另一个有效字段，两个字段都缺失时进入无数据状态。
 
-## 数据处理
+## 自动化数据语义
 
-- ABSDK 原始 Map、响应文本、Token、密码和红外原始码值不进入 UI 活动记录。
-- 错误记录最多保留经过领域层确认的外部错误码。
-- 温湿度单个字段缺失时保留另一个有效字段；两个字段均缺失时进入无数据状态。
+- 温度、湿度和插座状态来自一次评估快照。
+- 状态型触发器在“不匹配”到“匹配”的转换上触发，不会因持续满足而在每次轮询重复执行。
+- 条件只决定一次已触发执行是否可以继续，不会单独启动自动化。
+- 设备数据不可用时，对应触发器或条件为不可用，本轮不执行。
+
+## 数据与隐私边界
+
+- ABox 设备目录只保存用户确认的设备名称和类型；本地体验使用独立模拟目录。
+- 两个 Provider 的设备状态、遥控器、情景和活动记录不可互换。
+- 活动记录不得包含密码、Token、原始 SDK Map、完整响应文本或红外原始码值。
+- 外部错误码可以在领域层脱敏后保留，用于区分认证、网络、离线和操作失败。

docs/testing/infrared-hardware-validation.md

@@ -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、脱敏设备名、遥控器类型、操作类别、成功/失败/取消分类、粗粒度耗时、实体设备响应摘要和缺陷编号。

docs/testing/release-lan-hardware-validation.md

@@ -1,38 +1,89 @@
-# 发布版局域网硬件验证协议
+# 正式版局域网硬件验收
 
 ## 目的与边界
 
-本协议只用于获授权的隔离局域网。使用签名的 Release APK、已确认的测试账号和明确授权的实体设备；不得把测试扩展到未授权网络或设备。
+本协议验证签名 Release APK 在已授权 ABox 局域网中的完整产品路径。本地体验和测试 Fake 不能替代真实硬件验收。
 
-协议验证真实产品路径，不把本地体验或测试 Fake 的结果当作 ABox 硬件证据。每条记录使用脱敏 profile、设备和操作标识。
+报告不得包含密码、Token、原始厂商响应、红外码值、完整网关地址或完整硬件标识。设备和 profile 使用脱敏别名。
 
 ## 执行前检查
 
-- 确认 APK 签名、版本和提交号，记录到测试报告。
-- 确认测试网络与设备均获授权，并记录网络的脱敏名称。
-- 先使用已知无效凭据验证登录失败，再使用授权凭据登录。
-- 检查当前 profile、会话状态和已配置设备目录；只验证用户明确配置的设备。
-- 不在报告、截图、日志或缺陷单中保存密码、令牌、原始厂商响应、红外码值、完整网关地址或完整 IEEE 地址。
+- 记录 App 版本、versionCode、Git 提交和 APK 签名摘要；
+- 确认测试网络、账号、网关和实体设备均已授权；
+- 确认 Android 通知权限和系统省电策略；
+- 准备实际名称分别为 `智能插座`、`温湿度传感器` 和 `红外控制器` 的设备，或在 App 中改成网关当前名称；
+- 清楚标记哪些步骤是界面验证、网关响应验证和实体设备响应验证。
 
-## 验证流程
+## 验收流程
 
-1. 登录失败路径：确认无效凭据停留在登录页，并显示本地化错误。
-2. 授权登录路径：确认授权凭据登录成功，进入认证后的设备中心。
-3. 设备目录：配置一个已授权的真实设备名，确认只显示当前 profile 的设备，并可进行只读列表检查。
-4. 插座操作：对一个已配置插座执行一次开或关命令，随后读取状态确认；记录结果分类，不记录原始响应。
-5. 传感器读取：读取已配置的温湿度设备，验证有数据、部分数据和无数据状态的显示边界。
-6. 红外学习：对已授权红外控制器学习一个测试按键，确认状态从学习中到完成或明确失败。
-7. 红外取消：学习过程中离开页面或取消，确认不会留下可继续发送的半成品记录。
-8. 红外发送：发送已完成的测试按键，确认授权电器产生预期响应。
-9. 情景执行：执行一个只包含已配置设备的情景，观察实际步骤结果和终态。
-10. 活动记录：确认上述真实终态写入当前 profile 的活动时间线，失败、等待确认和取消保持不同分类。
-11. 会话失效：使远端会话失效后重试一次设备操作，确认本地会话清理并返回登录流程。
-12. Local 隔离复核：切换到本地体验后，确认 ABox 设备、遥控器、活动和会话数据不出现；该步骤不作为真实硬件通过证据。
+### 1. 安装、启动与登录
+
+1. 覆盖安装或全新安装 Release APK，确认启动不闪退。
+2. 使用无效凭据登录，确认停留在登录页并显示本地化错误。
+3. 使用授权凭据登录，确认进入设备中心。
+4. 重启 App，验证记住用户名和自动登录的已选行为。
+5. 使 Token 失效后执行操作，确认会话清理并返回登录流程。
+
+### 2. 默认内容与数据隔离
+
+1. 首次登录 ABox 后确认三类默认设备存在，名称逐字为 `智能插座`、`温湿度传感器`、`红外控制器`。
+2. 确认红外控制器包含两个自定义遥控器，不自动添加预置码库遥控器。
+3. 重命名设备并重启，确认 App 保留用户名称，不执行自动迁移或覆盖。
+4. 切换到本地体验，确认 ABox 设备、遥控器、情景、活动和会话数据不出现。
+
+### 3. 设备控制
+
+1. 在设备中心和插座详情各执行一次开关操作。
+2. 确认命令后回读真实状态；插座断电时不得仅因点击而显示已切换。
+3. 连续点击电源按钮，确认页面不抖动且不会并发重复发送。
+4. 读取温度和湿度，验证完整数据、单字段缺失、无数据和离线状态。
+5. 确认设备离线在设备中心和详情页均有明确视觉状态。
+
+### 4. 红外控制器
+
+1. 按 `infrared-hardware-validation.md` 完成一个预置遥控器下载和发送流程。
+2. 完成一个自定义按钮的添加、学习、发送和重新学习流程。
+3. 验证学习失败与未学习状态不同。
+4. 验证遥控器排序、编辑、删除和硬件槽位管理。
+
+### 5. 手动指令
+
+1. 创建包含插座、红外、延迟和通知动作的手动指令。
+2. 按配置顺序执行，确认失败策略和动作结果汇总符合设置。
+3. 验证同一指令执行期间不会被重复启动。
+
+### 6. 自动指令
+
+1. 创建一个温度阈值触发的自动指令，并添加插座状态条件。
+2. 使用手动执行入口验证动作本身可用。
+3. 让传感器状态从不匹配进入匹配，确认执行一次。
+4. 在持续匹配期间等待后续轮询，确认不会重复执行。
+5. 先恢复到不匹配，再重新进入匹配，确认可以再次执行。
+6. 验证时间、湿度和插座状态触发器至少各一次。
+7. 验证温度、湿度、插座状态和跨午夜时间范围条件。
+8. 拒绝通知权限后执行通知动作，确认显示明确失败而不是成功。
+
+### 7. 活动记录
+
+1. 确认设备命令、状态确认、传感器刷新、红外学习/发送、手动指令和自动指令均写入活动记录。
+2. 确认来源区分用户、自动化和系统，结果区分成功、失败、取消和等待确认。
+3. 在存在大量记录时验证分页加载和重新进入页面，不得闪退。
+4. 确认记录不包含凭据、原始响应或红外码值。
+
+### 8. 外观、导航与本地化
+
+1. 验证浅色、深色、动态颜色、手动强调色、色彩风格、色彩规范和界面缩放。
+2. 在英文和简体中文下检查设备、红外、情景、自动化、活动、主题和关于页面。
+3. 验证二级页面不显示主页顶栏和底栏。
+4. 验证系统返回和左上角返回不会进入空白页面或重复回退。
+5. 验证 About 页面显示 `1.0.0 (1)`、包名和 Flagship 团队信息，点击入口不闪退。
 
 ## 结果记录
 
-每个步骤只记录：日期、Release 版本或提交号、脱敏 profile、脱敏设备名、操作类别、成功/失败/取消/不可用分类、粗粒度耗时和物理响应摘要。错误只记录已脱敏的领域错误分类；不要复制堆栈或原始 SDK 文本。
+每个步骤记录：日期、版本与提交、脱敏 profile、脱敏设备名、操作类别、成功/失败/取消/不可用分类、粗粒度耗时、物理响应摘要和缺陷编号。真实硬件终态与 App 显示不一致必须判定为失败。
 
-## 风险说明
+## 已知风险
 
-真实 ABSDK 使用厂商 JAR 中的明文 HTTP 传输。Release 与 Debug 使用相同的提供方和硬件路由；明文传输不提供机密性或完整性，因此只能在隔离且获授权的局域网执行本协议。
+- ABSDK 使用厂商 JAR 中的明文 HTTP，只能在隔离且获授权的局域网中验收；
+- Android 后台限制和省电策略可能影响自动化轮询时效，应记录测试设备设置；
+- 网关依赖设备名称匹配，App 名称与网关名称不一致会导致设备操作失败。