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、完整响应文本或红外原始码值。
+- 外部错误码可以在领域层脱敏后保留，用于区分认证、网络、离线和操作失败。