ES Documentation
手册
API
手册
API
简体中文

下载固件文件

验证状态：已源码核验、未联调；适用基线：源码归纳 @ 2026-09-14

用途与 App 场景

按固件详情返回的 filePath 下载持久化文件。本页是 http-firmware-package-download 的唯一正本；已找到最终 Nginx 静态文件责任端，不把 Vite 代理或字符串拼接单独当服务合同。

Web 使用位置

页面/功能 角色或空间分支
原始固件列表下载 当前 $spaceId
SpiritCam 固件列表下载 当前 $spaceId
原始固件编辑页下载 当前 $spaceId
SpiritCam 固件编辑页下载 当前 $spaceId

协议身份

项 值
operationId http-firmware-package-download
method + path GET /firmware-package{filePath}
动态值来源 filePath 来自固件详情/列表；服务保存后形如 /{tenantId}/{yyyyMM}/{dd}/{filename}，SpiritCam 固定租户目录为 scm
base URL 浏览器同源；开发环境代理到 VITE_STATIC_SERVICE_URL，部署 Nginx alias 到主服务固件目录
response 文件 bytes；不是 ApiResult JSON

前置条件与权限

当前部署 Nginx location 没有独立鉴权指令，链接本身可直接 GET；不要因此推断其他部署必然公开。取得元数据仍需固件读取权限。调用方必须只使用服务返回的 filePath，不能拼接任意文件系统路径。

输入

参数 JSON 类型 位置 必填 可空 默认值 枚举/范围/单位 说明 字段证据
filePath string path suffix 是 否 无 最长 1024（元数据 DTO） 包含前导 / 的持久化相对路径 固件字段

输出、应答或事件

信号 类型 出现条件 可空 说明 证据
HTTP status number 总是 否 Nginx 静态文件状态；不存在通常不是 ApiResult Nginx location
body bytes 成功 否 固件原始字节；MIME 由 Nginx 运行配置决定 Nginx alias
Content-Type/Length header 运行时 是 当前仓库未固定 MIME 映射细节 Nginx

完成判据

HTTP 成功且客户端完整接收字节才表示下载结束；若用于升级，还应按详情中的 fileSize 和 md5 校验。下载完成不代表设备已安装。

示例

按已核验路径规则构造的请求：

1{
2 "method": "GET",
3 "path": "/firmware-package/tenant-01/202609/12/firmware.bin"
4}

按责任端合同构造的成功元信息（body 为 bytes，JSON 仅用于表达）：

1{
2 "httpStatus": 200,
3 "bodyType": "bytes",
4 "expectedFileSize": 4096,
5 "expectedMd5": "0123456789abcdef0123456789abcdef"
6}

按已核验边界构造的不存在结果：

1{
2 "httpStatus": 404,
3 "apiResultEnvelope": false
4}

错误与边界

该入口不使用中心服务 ApiResult 错误信封；参见HTTP 约定。仓库配置没有把 Range、缓存有效期或签名 URL 固定为产品合同，调用方不得依赖断点续传或长期有效。数据库删除先静默删除物理文件，旧 URL 之后可能变为 404。

调用关系与资源清理

先调用固件详情/列表取得 filePath/fileSize/md5；接收完成后校验长度与 MD5。普通 GET 无需额外释放服务端资源。

已知缺口

已找到 Web 代理、主服务存储路径和部署 Nginx alias；尚未对真实部署的 MIME、Range、缓存和访问控制做联调，所以只保证源码中的完整 GET 路径和 bytes 语义。

验证状态与依据

结论 状态 基线 依据
动态 URL 拼接与开发代理 已源码核验 依据 Web 端实现归纳（2026-09） 四个固件页面的下载链接构造
存储路径生成 已源码核验 源码归纳 @ 2026-09-14 中心侧固件包保存与静态路径派生
最终静态文件责任端 已源码核验 部署样例归纳（2026-09） 部署 Nginx 的固件静态目录映射
清单归属 已重新比对 inventory（2026-09-14） 清单层固件域条目
真实下载联调 未执行 — 未请求文件、未验证 Nginx 运行配置
目录