文件上报与检索#

验证状态：本页为接入视角新写（19 号票）。事实取材自清单层生成页（provenance 见各链接目标）与机构手册已核验场景正本，本页自身不做二次核验、未联调。

用途与场景#

设备文件（录像/图片等）如何进入中心、如何被检索与回放消费。这是接入动线的第四步，涉及三条链：触发上报（MQTT）、中心文件存储区设备号视图（HTTP）、回放消费（Web 经采集服务器 data/v1 服务面查询）。

动线#

上报触发（MQTT retrieve）#

「让设备上传文件」不是 HTTP 接口，而是 MQTT retrieve 命令：{identity}/{id}/iot/retrieve/v1，params.items 取 upload/<category>（设备获得上传目标）或 firmware（固件信息，见运维与 Web 指令面）。中心应答投递到设备 deliver topic，调用方不可见——场景正本见机构手册触发设备固件与文件上报（retrieve）；谓词族契约见MQTT 主题清单 · 谓词族，yaml 详解retrieve。

中心文件存储区设备号视图（HTTP）#

data-service v1-general 资源是面向中心文件存储区（服务器本地文件系统）的设备号视图，不是数据库查询——采集服务器/集成方可用于核对设备文件的落地情况：

端点（导航级）	用途	契约
GET /main-service/main-api/v1/general/device/data-acquisition-device/listDeviceNos	枚举中心文件存储区 files/device/ 下已有的设备号目录	清单层 · 业务
GET /main-service/main-api/v1/general/device/data-acquisition-device/listFilesByDeviceNoAndType	按设备号 + 类型列出文件清单	同上
POST /main-service/main-api/v1/general/device/data-acquisition-device/uploadByDeviceNo	按设备号向存储区上传文件（设备文件备份链路的一环）	同上

行为规则（一句话点名，细节见设备业务 · v1-general）：listDeviceNos 与设备资产库无外键关系（只反映文件系统现有目录）且有 3 秒缓存；listFilesByDeviceNoAndType 的 [] 是成功空态、路径段按纯字母数字白名单校验。

检索（MQTT retrieve 检索面）#

设备文件索引的检索走 retrieve 通道（按 params.items 检索词汇表：ice / firmware / dms / ptt / upload/*，未知项静默忽略；应答经 reply 回包、data 以检索项为键）——见设备消息链（MQTT）上行检索小节与yaml 详解 · retrieve。

回放消费（Web → 采集服务器 data/v1）#

机构 Web 回放域不查中心数据库，而是经 Broker 直达采集服务器的 data/v1 服务面拉文件清单与内容操作：list-file-existence（按日存在性）、list-file-category-total（类型计数）、list-file-info（单日文件清单）、gps（轨迹）、decrypt（解密）——逐命令正本在机构手册回放与文件域（拉取当日文件清单、按日文件存在性、类型计数、解密、GPS 轨迹、回放媒体地址），实现方（采集服务器）以这些正本为需求清单；媒体播放/下载 URL 由文件行或解密应答中的 ip/port/playUrl 动态构造（*.node.netbodycamera.com 直连，语义在机构侧已标缺证）。该服务面的完整清单与通道口径见运维与 Web 指令面。

文件存储服务器的绑定（管理侧）#

设备文件的存储落点与文件存储服务器相关：采集服务器与文件存储服务器的绑定关联由管理侧维护（CRUD）——

端点（导航级）	用途	契约
POST /main-service/main-api/device/data-acquisition-server-file-storage-server/list	（管理侧）查询采集服务器—文件存储服务器绑定列表	清单层 · 业务
POST /main-service/main-api/device/file-storage-server/list	（管理侧）文件存储服务器登记列表	清单层 · 业务

已知缺口#

1. 设备收到 deliver 应答后的实际上传协议（目标 URL 形态、断点/重试）属设备固件侧，机构正本已标缺证（upload/<category> 的 category 权威枚举缺证）。
2. 平台客户端 ID 规则中有「采集服务器文件服务 server,{serverNo},file,{sessionId}」，但其完整职责面（与 uploadByDeviceNo 的调用关系）无文档正本。
3. 回放媒体 URL 的有效期/鉴权/Range 语义机构侧已标缺证，本页不补。