25 lines
3.0 KiB
Markdown
25 lines
3.0 KiB
Markdown
|
# 设备命令可靠下发说明
|
||
|
|
|
||
|
|
当前版本实现“云端排队、设备主动拉取、分阶段回执”的设备命令基线，避免依赖设备持续在线或由公网直接访问设备。家庭内具有`device.manage`能力的成员可创建命令；设备使用原有HMAC身份从固定设备边界拉取，只能读取和回执自己的命令。
|
||
|
|
|
||
|
|
## 状态机
|
||
|
|
|
||
|
|
`QUEUED → DELIVERED → ACKNOWLEDGED → SUCCEEDED/FAILED`为正常主链。超过`expires_at`且尚未终结的命令转为`EXPIRED`；重复拉取会增加`delivery_attempts`并返回同一未终结命令。设备已上报`ACKNOWLEDGED`但尚未提交终态时，命令仍可被同一设备重新拉取用于进程重启恢复，服务端保持`ACKNOWLEDGED`而不回退为`DELIVERED`。重复提交相同阶段或终态回执保持幂等。非法跨设备回执、过期回执和状态回退返回409。
|
||
|
|
|
||
|
|
## 接口
|
||
|
|
|
||
|
|
| 接口 | 身份 | 作用 |
|
||
|
|
|---|---|---|
|
||
|
|
| `POST /api/v1/devices/{id}/commands` | OIDC + `device.manage` | 以`Idempotency-Key`创建30秒至24小时有效的命令 |
|
||
|
|
| `GET /api/v1/devices/{id}/commands` | OIDC + `device.manage` | 查看最近100条命令、投递次数和结果摘要 |
|
||
|
|
| `GET /device/v2/commands?limit=10` | 设备HMAC | 拉取本设备未过期、未终结命令；首次投递记为`DELIVERED`，处理中重拉保持`ACKNOWLEDGED` |
|
||
|
|
| `POST /device/v2/commands/{id}/ack` | 设备HMAC | 上报`ACKNOWLEDGED`、`SUCCEEDED`或`FAILED` |
|
||
|
|
|
||
|
|
支持`apply_config`、`reboot`、`diagnostics`和`firmware_update`四类命令。`firmware_update`只接受固件发布服务生成的私有对象引用、已验证SHA-256摘要和签名清单；制品直传、Ed25519验签、确定性灰度、暂停和已验证版本回滚详见[固件制品、签名、灰度与回滚开发说明](firmware-rollout.md)，不接受任意公网URL作为固件来源。
|
||
|
|
|
||
|
|
家庭工作台的诊断命令使用页面内受控操作表单，不再点击按钮后立即排队。表单固定展示设备公开编号、型号、长者、硬件/固件版本、在线状态、期望配置版本和设备记录版本，并明确诊断范围固定为音频、网络和存储。操作者必须确认命令有效期为5分钟、离线设备可能来不及领取，以及该动作不会重启设备或修改配置；取消，或切换页签、家庭、长者，会清空草稿且不创建命令。服务端仍执行`device.manage`、家庭租户隔离、设备状态、幂等和可靠投递门禁。
|
||
|
|
|
||
|
|
V11迁移建立`device_command`表，包含租户/设备复合外键、申请人幂等约束、JSON对象约束、过期索引和投递索引。`scripts/smoke-device-commands.ps1`已用真实OIDC与设备HMAC验证权限拒绝、幂等重放、拉取、两阶段回执、终态和测试数据清理。
|
||
|
|
|
||
|
|
页面增量只执行`test/e2e/visual-family-invitation-device-controls.mjs`的真实OIDC无提交冒烟：检查设备目标和固定诊断范围、确认门禁、取消关闭、诊断命令数量不变、零POST、零横向溢出、零控制台错误和零失败请求，不重复设备HMAC全状态链测试。
|