拉取当日文件清单（list-file-info）#

验证状态：存在关键缺口，不可作为完整契约发布。Web 发布与应答消费已源码核验；采集服务器是 server/{采集服务器 deviceNo}/data/v1/list-file-info 的最终消费者，其源码不在本工作区，应答权威 schema、错误形态与分页语义缺证。 适用基线：源码归纳 @ 2026-09-14

用途与场景#

回放设备页按所选日期（单日窗口）拉取目标设备的文件清单，写入 fileInfoList：驱动媒体类型/报警筛选计数、文件列表面板与播放器。本页是回放域该 topic 的唯一操作正本，覆盖 （视频回放）与 （最近记录）两个调用点。文件行中的 ip/port/playUrl/crypto/fileUrl 等字段是后续播放、下载、解密与 GPS 轨迹操作的直接输入（见调用关系）。

使用位置#

页面/功能	角色或空间分支
视频回放设备页查询文件列表	登录用户；视频回放设备页
最近记录设备页查询（payload 与消费同构，另按 fileUrl 文件名筛选）	登录用户；最近记录设备页
消费：写入 fileInfoList，派生分类/报警计数与筛选	—
消费：文件列表面板（排序、时长、报警与类型图标）	—

对应 inventory operationId：mqtt-listfileinfofn-server-var-data-v1-list-file-info-33db6818。

端点#

MQTT 请求 server/{serverDeviceNo}/data/v1/list-file-info（Web → Broker → 采集服务器直连，应答按 reply topic 回流；中心网关不消费）— 按所选日期（单日窗口）拉取目标设备的文件清单。

通道口径：该 topic 不在中心消费/发布点清单内（网关默认订阅清单无 server/+/data/#，见MQTT 主题清单 · 服务端订阅面）；应答回流、凭据与 QoS 等 wire 约定见MQTT 连接与消息边界。

请求形态 {id, reply, replyNumberMax:3, replyInterval:3, params:{deviceNo, takenAtStrRangeStart, takenAtStrRangeEnd}}；窗口为站点本地时区零点到次日零点（半开区间为 Web 构造意图，采集端解释缺证）。

动线与完成判据#

层级	判据
发布完成	publishAsync Promise 成功；仅代表 Broker 受理
应答到达	reply topic 收到应答，fileInfoList 整表替换、fileInfoLoading 复位
空结果	data 缺失按 []，页面展示"无结果"
超时	无内置请求超时；切换日期/设备（100ms 节流）触发重发；无失败终态

错误与边界#

• 本操作不经中心 HTTP 出口，错误响应差异总表的 HTTP 条目不适用；采集服务器业务错误形态缺证（待核验）。
• 发布失败被 Promise 链记录后丢弃；fileInfoLoading 停留 true 时页面显示骨架屏，靠下一次触发或重挂载复位。
• 无分页参数：单日窗口内全量返回是 Web 的使用假设；清单超出 Web 声明的 3 帧应答上限时如何截断缺证。
• 大清单性能未在 Web 侧虚拟化（普通排序/筛选），文件量极大时的可用性由浏览器决定。

调用关系与资源清理#

• 前置：文件按日存在性标记有文件的日期；设备清单与在线状态（listCache 正本、list-online-status 正本）。
• 下游（均以文件行为输入）：回放媒体地址（ip/port/playUrl）、解密（id/crypto）、GPS 轨迹（fileUrl）。
• 无订阅需取消；fileInfoList 随组件生命周期销毁。

已知缺口#

1. 采集服务器是最终消费者：文件行权威 schema（字段全集、takenAtStr 时区、playUrl 查询串构成）、错误形态、分帧与截断语义缺证。
2. Broker ACL（server/{no}/data/v1/#）待部署核验；未执行真实联调。