去掉component_asset表,使用明确的 DTO 和参数校验,统一 connectableTargets 格式。区分编辑版本与几何修订,普通信息修改不会让组件端口失效;过期版本返回 409。上传时校验会话和文件大小,采用流式处理,绑定失败自动清理本次上传对象。修复并发重名创建、分页参数、HTTP 状态码及失败操作日志。
This commit is contained in:
@@ -69,7 +69,7 @@ JSON 请求使用 `Content-Type: application/json`。文件接口分别使用 mu
|
||||
}
|
||||
```
|
||||
|
||||
组件、用户和操作日志列表使用 `items / page / size / total`;`page` 从 1 开始,默认 1;`size` 默认 20,超过 100 按 100 处理。前端传正整数,用户和日志接口会对非正数返回 `422`。接口库列表不分页,`data` 直接为数组。
|
||||
组件、用户和操作日志列表使用 `items / page / size / total`;`page` 从 1 开始,默认 1;`size` 默认 20,超过 100 按 100 处理。前端传正整数,组件、用户和日志接口会对非正数返回 `422`。接口库列表不分页,`data` 直接为数组。
|
||||
|
||||
时间使用 ISO 本地时间,例如 `2026-10-09T17:00:00.123`,不带 `Z` 或时区偏移。日志时间及服务端维护的创建/更新时间按上海时区处理。
|
||||
|
||||
@@ -120,14 +120,15 @@ STEP 点坐标转换到接口几何前,乘以返回的 `scaleToMeters`,当
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | string | 创建时是 | 唯一且非空;建议不超过 64 字符;修改以路径 ID 为准 |
|
||||
| name | string | 是 | 非空,建议不超过 128 字符 |
|
||||
| description | string | 否 | 默认空串,建议不超过 500 字符 |
|
||||
| id | string | 创建时是 | 唯一且非空;最多 64 字符;修改时若提供 ID,必须与路径一致 |
|
||||
| name | string | 是 | 非空,最多 128 字符 |
|
||||
| description | string | 否 | 默认空串,最多 500 字符 |
|
||||
| geometry | object | 是 | 安装平面与完整孔组,见下表 |
|
||||
| tolerances | object | 是 | 三个容差必须提供正值 |
|
||||
| displayForward | number[3] | 否 | 安装面内的默认前方;不传则服务端生成,不能平行于面法向 |
|
||||
| connectableTargets | string[] | 否 | 可连接目标路径,一维字符串数组;例如 `["机械臂/末端工具", "移动底盘/附件"]` |
|
||||
| geometryRevision | integer | 修改时是 | 详情返回的当前修订号;创建自动为 1 |
|
||||
| geometryRevision | integer | 修改时是 | 当前几何修订号;创建自动为 1,几何、容差或源文件变化时递增 |
|
||||
| editRevision | integer | 修改时是 | 当前编辑版本;创建为 1,每次修改或源文件绑定变化时递增;从详情/保存响应取值 |
|
||||
| sourceAssetKey | string | 否 | 源文件上传后返回的存储 Key;前端不能通过保存定义直接绑定文件 |
|
||||
| sourceGeometryHash | string | 否 | 已绑定源文件的 SHA-256,通常带 `sha256:`;源文件变更时可随保存传入新哈希以清除旧绑定,最终绑定由上传源文件接口完成 |
|
||||
|
||||
@@ -237,7 +238,8 @@ X-Request-Id: req-demo-001
|
||||
"connectableTargets": [
|
||||
"机械臂/末端工具",
|
||||
"移动底盘/附件"
|
||||
]
|
||||
],
|
||||
"editRevision": 1
|
||||
}
|
||||
],
|
||||
"requestId": "req-demo-001"
|
||||
@@ -330,7 +332,8 @@ X-Request-Id: req-demo-001
|
||||
"connectableTargets": [
|
||||
"机械臂/末端工具",
|
||||
"移动底盘/附件"
|
||||
]
|
||||
],
|
||||
"editRevision": 1
|
||||
},
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
@@ -487,7 +490,8 @@ Content-Type: application/json
|
||||
"connectableTargets": [
|
||||
"机械臂/末端工具",
|
||||
"移动底盘/附件"
|
||||
]
|
||||
],
|
||||
"editRevision": 1
|
||||
},
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
@@ -499,7 +503,7 @@ Content-Type: application/json
|
||||
|
||||
`PUT /admin-api/interfaces/{id}`
|
||||
|
||||
请求字段见 2.1,必须携带当前 `geometryRevision`,并提交完整定义。省略描述、目标或展示方向可能将其恢复为空值/默认值。
|
||||
请求字段见 2.1,必须携带当前 `geometryRevision` 和 `editRevision`,并提交完整定义。省略描述、目标或展示方向可能将其恢复为空值/默认值。
|
||||
|
||||
**请求示例**
|
||||
|
||||
@@ -573,7 +577,8 @@ Content-Type: application/json
|
||||
"机械臂/末端工具",
|
||||
"移动底盘/附件"
|
||||
],
|
||||
"geometryRevision": 1
|
||||
"geometryRevision": 1,
|
||||
"editRevision": 1
|
||||
}
|
||||
```
|
||||
|
||||
@@ -587,7 +592,7 @@ Content-Type: application/json
|
||||
"id": "mount-2-hole",
|
||||
"name": "双孔安装接口",
|
||||
"description": "更新后的接口说明",
|
||||
"geometryRevision": 2,
|
||||
"geometryRevision": 1,
|
||||
"geometry": {
|
||||
"plane": {
|
||||
"pointM": [
|
||||
@@ -646,16 +651,17 @@ Content-Type: application/json
|
||||
"机械臂/末端工具",
|
||||
"移动底盘/附件"
|
||||
],
|
||||
"sourceAssetKey": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/plate.step",
|
||||
"sourceGeometryHash": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7"
|
||||
"sourceAssetKey": "",
|
||||
"sourceGeometryHash": "",
|
||||
"editRevision": 2
|
||||
},
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
```
|
||||
|
||||
示例从修订 1 更新为 2。修改名称、描述、孔组、容差或可连接目标等会产生新修订;仅展示方向变化且其他内容不变时通常保留修订号。始终以响应为准。
|
||||
名称、描述、可连接目标或展示方向修改只增加 `editRevision`,不增加 `geometryRevision`。几何、容差或源文件变化才产生新几何修订。下面示例只修改描述,几何修订仍为 1、编辑版本变为 2;始终以响应为准。
|
||||
|
||||
旧修订仍保留历史快照。修订号不匹配返回 `422 / INVALID_INTERFACE`;前端应重新查询详情,再提示用户重新确认修改。引用旧修订的组件端口,在下一次保存组件时需要重新计算并确认。
|
||||
旧修订仍保留历史快照。编辑版本或几何修订号不匹配返回 `409 / INTERFACE_REVISION_CONFLICT`;前端应重新查询详情并保留本地编辑内容,再由用户确认合并。引用旧修订的组件端口,在下一次保存组件时需要重新计算并确认。
|
||||
|
||||
### 2.6 删除接口
|
||||
|
||||
@@ -702,7 +708,7 @@ X-Request-Id: req-demo-001
|
||||
|
||||
先保存接口定义,再上传源文件。后端校验修订号,计算文件 SHA-256,并更新当前修订的源文件绑定。该接口本身不执行 STEP 解析或校验文件拓扑;需要精确解析时先调用第 5 节接口。
|
||||
|
||||
单个文件和整个 multipart 请求默认均限制 100 MB;边界开销也占请求大小。当前修订已有不同内容的源文件时,绑定会被拒绝,应按源文件变更流程先保存新修订。
|
||||
单个文件和整个 multipart 请求默认均限制 100 MB;边界开销也占请求大小。源文件还受存储上传大小限制,绑定失败会补偿清理本次上传对象。上传成功后重新查询接口详情,取得最新 `editRevision`。当前修订已有不同内容的源文件时,绑定会被拒绝,应按源文件变更流程先保存新修订。
|
||||
|
||||
**请求示例**
|
||||
|
||||
@@ -720,12 +726,12 @@ curl -X POST 'http://127.0.0.1:8992/admin-api/interfaces/mount-2-hole/assets?geo
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "success",
|
||||
"data": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/plate.step",
|
||||
"data": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/22222222-2222-4222-8222-222222222222/plate.step",
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
```
|
||||
|
||||
成功 `data` 是对象 Key 字符串,不是 URL。再调用接口详情可获得 `sourceAssetKey` 和 `sourceGeometryHash`。源文件可通过 `/admin-api/component-assets/{objectKey}` 下载,对象路径各段需要 URL 编码。
|
||||
成功 `data` 是对象 Key 字符串,不是 URL;Key 含本次上传的随机路径段,应保存服务端返回值,不要自行推导。再调用接口详情可获得 `sourceAssetKey` 和 `sourceGeometryHash`。源文件可通过 `/admin-api/component-assets/{objectKey}` 下载,对象路径各段需要 URL 编码。
|
||||
|
||||
**上传后的详情示例:HTTP 200**
|
||||
|
||||
@@ -796,8 +802,9 @@ curl -X POST 'http://127.0.0.1:8992/admin-api/interfaces/mount-2-hole/assets?geo
|
||||
"机械臂/末端工具",
|
||||
"移动底盘/附件"
|
||||
],
|
||||
"sourceAssetKey": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/plate.step",
|
||||
"sourceGeometryHash": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7"
|
||||
"sourceAssetKey": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/22222222-2222-4222-8222-222222222222/plate.step",
|
||||
"sourceGeometryHash": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7",
|
||||
"editRevision": 2
|
||||
},
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
@@ -1010,7 +1017,7 @@ Content-Type: application/json
|
||||
| selectedPose | object | 是 | 至少提供当前候选 `id`;建议同时复制候选的姿态、孔映射和方向字段 |
|
||||
| sourceGeometryHash | string | 是 | 与计算候选时一致的 URDF 源几何哈希 |
|
||||
| solverVersion | string | 是 | 复制候选集返回值,当前为 `mount-geometry-3` |
|
||||
| connectableTargets | array | 否 | 不传或为空时使用模板目标;多目标建议采用二维路径数组,见下文 |
|
||||
| connectableTargets | array | 否 | 不传或为空时使用模板目标;一维数组表示多个独立目标;兼容二维 Cascader 路径数组 |
|
||||
|
||||
**请求示例**
|
||||
|
||||
@@ -1211,7 +1218,7 @@ Content-Type: application/json
|
||||
|
||||
服务端依据候选 `id` 重新计算,返回规范化端口;提交的旋转和孔映射不会作为最终可信结果。该接口只计算和确认,不自动保存组件。
|
||||
|
||||
**可连接目标的输入兼容规则**:接口定义 CRUD 使用一维路径字符串数组;`confirm-port` 和 `componentJson.interfaces` 会把一维字符串数组视为“一条级联路径”,例如 `["机械臂", "末端工具"]` 被合并为 `"机械臂/末端工具"`。多个目标请提交二维数组,例如 `[["机械臂", "末端工具"], ["移动底盘", "附件"]]`。返回统一为一维路径字符串数组。将确认结果用于保存组件时,多目标应先转换为二维数组,避免被合并为一条路径。
|
||||
**可连接目标的输入兼容规则**:接口定义、姿态确认和组件端口统一使用一维路径字符串数组,例如 `["机械臂/末端工具", "移动底盘/附件"]` 表示两个独立目标;兼容二维 Cascader 路径数组 `[["机械臂", "末端工具"], ["移动底盘", "附件"]]`。返回始终为一维字符串数组,可以直接用于后续确认和组件保存,无需再次转换。
|
||||
|
||||
<a id="components"></a>
|
||||
|
||||
@@ -1261,7 +1268,7 @@ Content-Type: application/json
|
||||
|
||||
`componentJson.interfaces` 非空时,必须同时提供原始 `urdfSource` 快照、资源清单以及已经确认的端口。后端会核对源文件资源、link、源哈希、模板当前修订和选中候选;不能只填端口名称和坐标。详见 8.3。
|
||||
|
||||
每次成功新增/修改会由后端写入或递增 `componentJson.componentRevision`。存在 `interfaces` 数组时会返回 `interfaceSchemaVersion: 3`;前端不自行生成这些版本值。
|
||||
每次成功新增/修改会由后端写入或递增 `componentJson.componentRevision`。修改时必须携带详情返回的当前值;缺少版本返回 `422 / INVALID_COMPONENT_REVISION`,版本冲突返回 `409 / COMPONENT_REVISION_CONFLICT`,旧数据不会覆盖新记录。历史组件未包含该字段时按 0 处理,修改时传 0。存在 `interfaces` 数组时会返回 `interfaceSchemaVersion: 3`;前端不自行生成这些版本值。
|
||||
|
||||
### 3.2 查询组件列表
|
||||
|
||||
@@ -1776,7 +1783,7 @@ Content-Type: application/json
|
||||
|
||||
`PUT /admin-api/components/{id}`
|
||||
|
||||
请求字段同新增。使用完整必填字段;省略分类、封面和描述会将这些可选文本重置为空。
|
||||
请求字段同新增,另须在 `componentJson` 中携带详情返回的 `componentRevision`。使用完整必填字段;省略分类、封面和描述会将这些可选文本重置为空。
|
||||
|
||||
**请求示例**
|
||||
|
||||
@@ -1894,7 +1901,8 @@ Content-Type: application/json
|
||||
]
|
||||
]
|
||||
}
|
||||
]
|
||||
],
|
||||
"componentRevision": 1
|
||||
},
|
||||
"assemblyMetadata": {
|
||||
"tags": [
|
||||
@@ -2160,7 +2168,10 @@ Content-Type: application/json
|
||||
"message": "success",
|
||||
"data": {
|
||||
"uploadUrl": "http://127.0.0.1:8992/admin-api/component-assets/upload?objectKey=components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
|
||||
"objectKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png"
|
||||
"objectKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
|
||||
"uploadHeaders": {
|
||||
"X-Upload-Session-Token": "<uploadSessionToken>"
|
||||
}
|
||||
},
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
@@ -2280,7 +2291,10 @@ Content-Type: application/json
|
||||
"message": "success",
|
||||
"data": {
|
||||
"uploadUrl": "http://127.0.0.1:8992/admin-api/component-assets/upload?objectKey=components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
|
||||
"objectKey": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf"
|
||||
"objectKey": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
|
||||
"uploadHeaders": {
|
||||
"X-Upload-Session-Token": "<uploadSessionToken>"
|
||||
}
|
||||
},
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
@@ -2349,6 +2363,7 @@ Content-Type: application/json
|
||||
| 位置 | 字段 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| Query | objectKey | 是 | 获取上传地址返回的完整对象 Key;应直接使用返回的 `uploadUrl` |
|
||||
| Header | X-Upload-Session-Token | 是 | 获取上传地址返回的 `uploadHeaders` 中的会话凭证;使用同一会话的当前值 |
|
||||
| Header | Content-Type | 否 | 真实文件 MIME 类型;省略时按通用二进制类型处理 |
|
||||
| Body | 文件二进制 | 是 | 直接发送 File/Blob/ArrayBuffer;不用 FormData,不做 JSON 或 Base64 包装 |
|
||||
|
||||
@@ -2358,6 +2373,7 @@ Content-Type: application/json
|
||||
curl -X PUT \
|
||||
'http://127.0.0.1:8992/admin-api/component-assets/upload?objectKey=components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf' \
|
||||
-H 'Content-Type: application/xml' \
|
||||
-H 'X-Upload-Session-Token: <uploadSessionToken>' \
|
||||
-H 'X-Request-Id: req-demo-001' \
|
||||
--data-binary '@./robot.urdf'
|
||||
```
|
||||
@@ -2369,9 +2385,9 @@ HTTP/1.1 204 No Content
|
||||
X-Request-Id: req-demo-001
|
||||
```
|
||||
|
||||
响应体为空,不执行 `response.json()`。失败时仍按第 9 节处理 JSON 错误响应。当前应用只允许写入配置操作人的组件资源目录;接口源文件通过第 2.7 节上传。
|
||||
响应体为空,不执行 `response.json()`。失败时仍按第 9 节处理 JSON 错误响应。后端在实际 PUT 时校验会话签名、签发者、有效期、操作人和精确会话目录;不能直接拼接对象路径绕过会话。接口源文件通过第 2.7 节上传。
|
||||
|
||||
这里的 PUT 是原始文件流,Spring multipart 的 100 MB 限制不直接作用于此接口;实际大小还可能受到部署网关限制,前端应与部署环境保持一致。
|
||||
原始 PUT 和接口源文件上传均受 `APP_STORAGE_MAX_UPLOAD_BYTES` 限制,默认 104857600 字节(100 MiB)。缺少 Content-Length 的流式上传同样检查实际读取大小;超限返回 `413 / UPLOAD_TOO_LARGE`。部署网关还可设置更小的限制。
|
||||
|
||||
### 4.2 下载或读取资源
|
||||
|
||||
@@ -3067,7 +3083,7 @@ async function uploadModel(files) {
|
||||
const response = await fetch(prepared.uploadUrl, {
|
||||
method: 'PUT',
|
||||
headers: { ...prepared.uploadHeaders, 'Content-Type': contentType },
|
||||
body: file
|
||||
body: file
|
||||
});
|
||||
if (response.status !== 204) {
|
||||
// 失败通常为 JSON;如网关返回非 JSON,保留 HTTP 状态信息。
|
||||
@@ -3089,7 +3105,7 @@ async function uploadModel(files) {
|
||||
### 8.3 保存带机械端口的组件
|
||||
|
||||
1. 取得接口模板详情,记录 `geometryRevision`;编辑模板时还需携带 `editRevision`。
|
||||
2. 保存原始 URDF XML 快照,并为其引用的网格/纹理建立资源清单;资源先通过模型会话上传。
|
||||
2. 保存原始 URDF XML 快照,并为其引用的网格/纹理建立资源清单;资源先通过模型会话上传。
|
||||
3. 用 link 局部坐标中的实际几何调用 `/pose-candidates`。
|
||||
4. 用户选择候选后,携带候选 ID、对应修订和源哈希调用 `/confirm-port`。
|
||||
5. 将规范化端口加入 `componentJson.interfaces`;按照 2.9 处理多目标路径的输入格式。
|
||||
@@ -3153,11 +3169,11 @@ sourceGeometryHash = SHA256(documentHash + "\n" + manifest)
|
||||
```
|
||||
|
||||
**接口编辑版本过期失败示例:HTTP 409**
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "INTERFACE_REVISION_CONFLICT",
|
||||
"message": "接口已修改,请刷新后保存",
|
||||
"message": "接口已修改,请刷新后保存",
|
||||
"requestId": "req-demo-001"
|
||||
}
|
||||
```
|
||||
@@ -3176,7 +3192,14 @@ sourceGeometryHash = SHA256(documentHash + "\n" + manifest)
|
||||
| --- | --- | --- |
|
||||
| 422 | INVALID_REQUEST | 必填、字段长度、枚举、JSON 格式、参数类型或几何结构不合法,提示修改输入 |
|
||||
| 422 | INVALID_INTERFACE / INVALID_INTERFACE_ASSET | 接口业务校验或源文件绑定不合法 |
|
||||
| 409 | USER_PHONE_DUPLICATE | 手机号冲突,已删除用户也会占用手机号 |
|
||||
| 404 | INTERFACE_NOT_FOUND | 当前接口定义不存在 |
|
||||
| 409 | INTERFACE_ID_DUPLICATE | 接口 ID 已占用或归档 |
|
||||
| 409 | INTERFACE_REVISION_CONFLICT / COMPONENT_REVISION_CONFLICT | 编辑数据已过期;重新查询详情并确认修改 |
|
||||
| 422 | INVALID_COMPONENT_REVISION | 修改组件缺少合法的客户端版本 |
|
||||
| 405 | INVALID_REQUEST | HTTP 方法不支持,检查 Allow 响应头 |
|
||||
| 415 | INVALID_REQUEST | Content-Type 不支持 |
|
||||
| 413 | UPLOAD_TOO_LARGE | 文件超出存储上传大小限制 |
|
||||
| 409 | USER_PHONE_DUPLICATE | 手机号冲突,已删除用户也会占用手机号 |
|
||||
| 404 | USER_NOT_FOUND | 用户不存在或已删除 |
|
||||
| 409 | COMPONENT_NAME_DUPLICATE | 组件名称重复 |
|
||||
| 404 | COMPONENT_NOT_FOUND | 组件不存在 |
|
||||
@@ -3193,7 +3216,7 @@ sourceGeometryHash = SHA256(documentHash + "\n" + manifest)
|
||||
| 504 | INTERFACE_BREP_TIMEOUT | STEP 解析超时,拆分文件后重试 |
|
||||
| 500 | MINIO_CONFIG_ERROR / STORAGE_CONFIG_ERROR | 存储配置缺失或非法,联系后端 |
|
||||
| 502 | MINIO_BUCKET_FAILED / MINIO_UPLOAD_FAILED / MINIO_OBJECT_CHECK_FAILED / MINIO_DOWNLOAD_FAILED / MINIO_DELETE_FAILED | 存储连接、权限或读写失败,联系后端 |
|
||||
| 404 | MINIO_OBJECT_NOT_FOUND | 资源对象不存在 |
|
||||
| 404 | MINIO_OBJECT_NOT_FOUND | 资源对象不存在 |
|
||||
| 422 | INVALID_STORAGE_OBJECT_KEY | 存储对象 Key 不合法 |
|
||||
| 503 | DATABASE_UNAVAILABLE | 数据库连接不可用,联系后端 |
|
||||
| 500 | INTERNAL_ERROR | 未分类系统异常,反馈 requestId |
|
||||
|
||||
Reference in New Issue
Block a user