From 7a107cc55aca7f3266b5a469932b2573e6481d82 Mon Sep 17 00:00:00 2001
From: KremeCN <3265494849@qq.com>
Date: Wed, 26 Aug 2026 20:50:17 +0800
Subject: [PATCH] docs: record device data capability boundaries

---
 docs/testing/device-data-capability-matrix.md | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 docs/testing/device-data-capability-matrix.md

diff --git a/docs/testing/device-data-capability-matrix.md b/docs/testing/device-data-capability-matrix.md
new file mode 100644
index 0000000..5bb0703
--- /dev/null
+++ b/docs/testing/device-data-capability-matrix.md
@@ -0,0 +1,32 @@
+# 设备数据能力矩阵
+
+本文只记录当前代码中有领域端口、实现和测试支撑的设备数据能力。未列出的数据不应在界面中以固定值、随机值、`--` 或伪造图表呈现。
+
+| 能力 | ABox | 本地体验 | 依据 | 界面策略 |
+|---|---|---|---|---|
+| 插座开关状态读取 | 支持 | 支持 | `SocketGateway.getStatus` | 展示已确认状态 |
+| 插座开关控制 | 支持 | 支持 | `SocketGateway.commandPower` / `setPower` | 命令完成后回读；回读失败显示等待确认 |
+| 温度当前读数 | 支持，字段可能缺失 | 支持 | `TemperatureHumidityGateway.getReading` | 仅字段存在时展示 |
+| 湿度当前读数 | 支持，字段可能缺失 | 支持 | `TemperatureHumidityGateway.getReading` | 仅字段存在时展示 |
+| 红外按键发送 | 支持 | 支持 | `InfraredGateway.sendKey` | 展示真实操作结果 |
+| 红外按键学习 | 支持 | 支持 | `InfraredGateway.learnKey` | 展示学习状态和结果 |
+| 红外码下载 | 支持 | 支持 | `InfraredGateway.downloadCodes` | 仅用于真实下载流程 |
+| 插座电压/电流/功率/电量 | 不可用 | 不可用 | 没有对应领域端口 | 不渲染 |
+| 插座倒计时 | 不可用 | 不可用 | 没有对应领域端口 | 不渲染 |
+| 插座历史趋势 | 不可用 | 不可用 | 没有历史数据端口 | 不渲染 |
+| 温湿度历史趋势 | 不可用 | 不可用 | 没有历史数据端口 | 不渲染 |
+| 网关诊断延迟 | 不可用 | 不适用 | 没有诊断端口 | 不渲染 |
+| Token 有效期展示 | 不可用 | 不适用 | SDK 未提供可安全展示的有效期端口 | 不渲染 |
+
+## Provider 边界
+
+- ABox 设备目录只包含用户明确配置的 `DeviceName` 和 `DeviceType`。
+- 本地体验设备来自确定性的模拟目录。
+- 两个 Provider 的设备描述、状态和历史记录不可互换。
+- “不可用”表示没有对应能力，不表示设备故障；界面不添加禁用的伪功能控件。
+
+## 数据处理
+
+- ABSDK 原始 Map、响应文本、Token、密码和红外原始码值不进入 UI 活动记录。
+- 错误记录最多保留经过领域层确认的外部错误码。
+- 温湿度单个字段缺失时保留另一个有效字段；两个字段均缺失时进入无数据状态。