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

创建固件包

验证状态：已源码核验、未联调；适用基线：Web aa138d8、services a3e783d2；核验日期：2026-09-12

用途与 App 场景

创建固件包。本页是 http-post-main-service-main-api-device-firmware-package-save-e29fdc3b 的唯一操作正本；只描述当前 Web 可达调用和服务端行为，不把源码核验称为联调。

Web 使用位置

页面/功能 角色或空间分支 调用证据
($lng).$spaceId.device.firmware-package.add/original-1.tsx 当前 $spaceId；前端可见性与后端授权分别校验 app/routes/($lng).$spaceId.device.firmware-package.add/original-1.tsx:80

协议身份

项 值
operationId http-post-main-service-main-api-device-firmware-package-save-e29fdc3b
method + path POST /main-service/main-api/device/firmware-package/save
base URL 当前 Web 使用同源相对 URL；App 的部署 base URL 未由源码固定
headers Accept: application/json;charset=UTF-8；Authorization: Bearer <token>；Content-Type: application/json
序列化 request body 由公共 wrapper 执行 JSON.stringify；没有 query 参数

前置条件与权限

需要有效登录态，并满足 administrator 角色或 device-firmware-package:create。 Bearer、Cookie、空间切换规则见认证与空间。资源表受当前认证租户及已注入数据权限约束；请求中的 tenantId 不能替代空间切换。

输入

JSON 路径/参数 JSON 类型 位置 必填 可空 默认值 枚举/范围/单位 说明 字段证据
body object body 是 否 无 字段长度与必填见字段正本 保存 固件包 写入字段

输出、应答或事件

JSON 路径 JSON 类型 出现条件 可空 枚举/范围/单位 说明 字段证据
timestamp number JSON 响应 否 epoch 毫秒 响应生成时间 ApiResult
status number JSON 响应 否 成功为 200 不能只看 HTTP status ApiResult
error/localizedError/path string | null JSON 响应 是 — 成功通常为 null；失败见差异页 ApiResult
extraData object 成功 否 — 本操作未定义专属键 ApiResult
data boolean 业务成功 否 — 数据库主操作的布尔结果 Controller/Service

完成判据

status=200 && data=true 表示文件处理与元数据保存链未抛异常；它不代表目标设备已经下载或安装固件。

示例

按已核验契约构造的请求 JSON：

1{
2  "firmwarePackageId": "firmware-01",
3  "deviceModelId": "device-model-01",
4  "version": "2.0.1",
5  "description": "稳定版",
6  "releaseDate": 1789142400,
7  "filePath": "/main-service/system-api/upload/upload-01",
8  "md5": "0123456789abcdef0123456789abcdef",
9  "binaryHeader": {
10    "headTag": {
11      "magic": 305419896,
12      "version": 1,
13      "md5sum": "0123456789abcdef0123456789abcdef"
14    },
15    "upgradeInfoTag": {
16      "fwOffset": 128,
17      "fwSize": 4096,
18      "cpuId": 1,
19      "pcbVersion": 2,
20      "imgVersion": "2.0.1",
21      "devType": "scm",
22      "noForceUpgrade": 0
23    }
24  }
25}

按已核验契约构造的成功响应：

1{
2  "timestamp": 1789142400000,
3  "status": 200,
4  "error": null,
5  "localizedError": null,
6  "path": null,
7  "extraData": {},
8  "data": true
9}

按已核实权限出口构造的代表失败（HTTP status 200）：

1{
2  "timestamp": 1789142400000,
3  "status": 1001,
4  "error": "Insufficient permissions, please contact the administrator",
5  "localizedError": null,
6  "path": "<request-path>",
7  "extraData": {},
8  "data": null
9}

错误与边界

认证/权限拒绝分别适用认证失败、权限失败；参数绑定与 Bean Validation 适用请求校验，业务 ApiException 适用业务拒绝。同一 deviceModelId + version 重复时业务拒绝；仅 .bin/.img 的已完成 Tus 文件会被迁移。 若 filePath 查不到已完成 Tus 信息，当前 Controller 不拒绝而会继续保存原路径；调用方必须只提交上传成功回调给出的 URL。 公共 Web helper 默认 15 分钟超时；写入和删除没有幂等键，超时后须先查询资源状态再决定是否重试。

调用关系与资源清理

通常先完成 Tus 固件上传。当 filePath 对应已完成上传时，服务端复制文件到租户年月日目录并删除 Tus 临时项；固件下发/安装不属于此 HTTP 操作。

已知缺口

无已知会阻止按当前源码调用的关键证据缺口。未执行真实 HTTP、数据库、缓存、JMS 或部署环境联调。

验证状态与依据

结论 状态 仓库/基线 路径、符号及定位 内容指纹（脏文件）
Web 方法、路径、序列化与消费 已源码核验 web aa138d8 app/.client/api/main/device/firmwarePackageApi.ts:1 deviceFirmwarePackageSaveApi；见上表 consumers 证据文件与 HEAD 一致
权限、输入、输出和完成语义 已源码核验 services a3e783d2 es-center-server-main-service/src/main/java/com/es/center/server/device/controller/FirmwarePackageController.java:95 save；es-center-server-device-common/src/main/java/com/es/center/server/device/service/FirmwarePackageService.java:35 save 证据文件与 HEAD 一致
JSON 字段与时间类型 已源码核验 services a3e783d2 本资源族字段模型 证据文件与 HEAD 一致
清单归属 已重新比对 inventory .scratch/institutional-app-api-docs/inventory/operations.json SHA-256 b5cce137b4fc602840fdbe74c99d90667b3e581815bddc709e263ffcc64e00f9（工作树仅格式化漂移）
真实部署联调 未执行 — 未发送请求、未连接数据库/缓存/JMS/文件服务 —
目录