触发设备固件与文件上报（retrieve）#

验证状态：已源码核验、未联调。Web 发布与中心设备服务的受理链（订阅、路由、消费者、应答发布）已在源码闭合；设备收到应答后的实际上报行为属设备固件职责，不在工作区，未联调。 适用基线：源码归纳 @ 2026-09-14

用途与场景#

请求中心为指定设备生成上报指令数据并把结果投递到设备：items:["firmware"] 让设备获得最新固件包信息（固件升级入口），items:["upload/<category>"] 让设备获得文件上传目标（设备文件备份页的手动上传）。本页是 device/{deviceNo}/iot/retrieve/v1 的唯一操作正本。与 configs 命令不同，本命令由中心设备服务消费并应答；Web 看不到中心投递给设备的内容。

使用位置#

页面/功能	items
设备列表·固件升级	["firmware"]
远控首页·设备信息·固件升级	["firmware"]
运维·设备文件备份·发送上传命令	["upload/<category>"]；category 为弹窗自由文本输入

对应 inventory operationId：mqtt-module-device-var-iot-retrieve-v1-116a449c、mqtt-senduploadcommand-device-var-iot-retrieve-v1-a61d2e78。

端点#

MQTT 发布 device/{deviceNo}/iot/retrieve/v1（中心消费后把应答投递到设备侧 device/{deviceNo}/iot/deliver/v1，Web 不可见）— 请求中心为指定设备生成固件/文件上报数据并下发。

谓词族契约全量事实（identity ∈ device/server/user、汇入静态 RETRIEVE destination、消费方）见 MQTT 主题清单 · 谓词族与yaml 详解 · retrieve；应答信封与 deliver 投递链的业务语义（firmware/upload 数据构成）见设备业务 · mqtt-bridge 设备消息链。载荷形态 {sub:"retrieve", id, reply, params:{items:[]}}——固件入口 id 固定 device,{deviceNo},iot,simulate-sending、上传入口为 device,{deviceNo},iot,{nanoId}，reply 固定为 device/{deviceNo}/iot/deliver/v1，items 取 firmware 或 upload/<category>。

动线与完成判据#

层级	判据
发布完成	publishAsync Promise 成功；Web 随即 toast"操作成功/已发送"——这只代表 Broker 接收发布调用
中心受理	无 Web 可观察信号：中心应答发往设备 topic，Web 不订阅；受理失败（如 id 非法）同样静默
设备执行	不可观测：设备收到 deliver 应答后是否上传/升级、结果如何，无任何回传到本命令的调用方
中心副作用	每次调用都会把 device,{deviceNo},iot 标记为在线并刷新最后在线时间——Web 触发固件查询会顺带刷新该设备的在线状态

错误与边界#

• 中心技术异常以固定 internal error 应答（不回传原始异常）；固件查询的业务缺失（设备不存在、无固件包）不报错，而是成功应答内带 data.firmware.error 键——设备侧如何处理这两种形态缺证。
• reply 与来源 topic 相同的报文被网关守卫丢弃（MqttReplyTopicGuard）；本命令 Web 构造不会触发。
• 消息 JSON 解析失败、id 非法时中心仅记 error 日志，无应答、无重试。
• params.replyNumberMax/replyInterval 未由 Web 使用；若 App 设置，取值被钳制在 1-10 次、1-10 秒，且续发前会检查该 id 前缀的在线状态。
• MQTT 族公共边界见MQTT 连接与消息边界；固件包管理 HTTP 契约见设备与资产域 · firmware-package。

调用关系与资源清理#

• 无订阅、无会话资源；命令为一次性发布。
• 设备备份页的上传变体与设备文件列表 HTTP 接口（generalDataAcquisitionDeviceListFilesByDeviceNoAndTypeApi）配合使用；上传目标接口本身属 HTTP 契约，App 调用前应核对其鉴权要求。
• 固件变体后，设备固件信息如何回流到 Web（设备列表页的固件列）经由其他上报通道，不在本正本展开。

已知缺口#

1. 设备收到 deliver 应答后的行为（下载、校验、上传、升级与失败重试）属设备固件，源码不在工作区，完成语义在设备侧断链。
2. upload/<category> 的 category 权威枚举缺证：Web 为自由文本输入，仅与设备文件备份的类型取值一致时才有意义。
3. Broker ACL 与部署环境订阅清单、mqtt.client-id 实际配置与默认 profile 的一致性待部署核验。
4. data.firmware.url 依赖租户字典 domainUrl 与部署参数 firmware-package-download-root-url；实际部署取值未核验。