story/docs/device-commands.md

设备命令可靠下发说明

当前版本实现“云端排队、设备主动拉取、分阶段回执”的设备命令基线，避免依赖设备持续在线或由公网直接访问设备。家庭内具有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验签、确定性灰度、暂停和已验证版本回滚详见固件制品、签名、灰度与回滚开发说明，不接受任意公网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全状态链测试。