91 KiB
cadworld 后台接口文档(前端联调用)
适用模块:cadworld-adminapi。依据当前 Controller、请求 DTO、业务校验及实际响应编写,核对日期:2026-10-09。
- 本地默认服务地址:
http://127.0.0.1:8992。 - 业务接口前缀:
/admin-api。旧/api/interfaces、/api/components不提供管理接口。 - 测试环境 Swagger:
http://127.0.0.1:8992/swagger-ui.html;OpenAPI:http://127.0.0.1:8992/api-docs。生产环境默认关闭文档页面。 - 当前阶段不需要登录,也不需要
Authorization请求头;操作人由服务端统一配置,默认0 / TEST_OPERATOR。 - 所有 ID、对象 Key、时间、URL、哈希和令牌均以实际接口返回为准。示例使用虚构名称和配置;
<URDF_UPLOAD_SESSION_TOKEN>等为占位符,调用时替换为创建会话的返回值。 - 示例中 JSON 可以直接作为结构参考;几何、文件内容、哈希、候选姿态 ID 必须来自同一组实际数据,不能混用不同文件或不同修订的示例值。
目录
1. 通用约定
1.1 请求及响应
JSON 请求使用 Content-Type: application/json。文件接口分别使用 multipart 或原始文件流,详见对应接口。除文件接口外,所有成功返回均为 HTTP 200,创建也不使用 201。
请求可以携带 X-Request-Id。服务端会将其放入响应头及 JSON 的 requestId;不传时自动生成。建议用于排查联调错误。
{
"code": "OK",
"message": "success",
"data": {
"success": true
},
"requestId": "req-demo-001"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 成功为 OK,失败为业务错误码 |
| message | string | 成功为 success;失败为提示信息,具体文字不保证固定 |
| data | object / array / string | 每个接口的数据类型不同,见对应示例 |
| requestId | string | 本次请求编号,与响应头 X-Request-Id 对应 |
普通 DTO 的 null 字段默认不输出;失败响应通常没有 data。接口定义和 STEP 等 JSON 树响应中仍可能出现显式 null。前端应兼容字段缺省与 null,不要要求失败响应必须有 data。
资源上传成功返回 HTTP 204,没有 JSON;资源下载成功返回文件内容,不使用上述响应封装。
1.2 分页与时间
{
"code": "OK",
"message": "success",
"data": {
"items": [],
"page": 1,
"size": 20,
"total": 0
},
"requestId": "req-demo-001"
}
组件、用户和操作日志列表使用 items / page / size / total;page 从 1 开始,默认 1;size 默认 20,超过 100 按 100 处理。前端传正整数,用户和日志接口会对非正数返回 422。接口库列表不分页,data 直接为数组。
时间使用 ISO 本地时间,例如 2026-10-09T17:00:00.123,不带 Z 或时区偏移。日志时间及服务端维护的创建/更新时间按上海时区处理。
1.3 几何单位
| 数据 | 单位或顺序 |
|---|---|
接口定义和端口中的 positionM、pointM、pointOnPlaneM、diameterM |
米 |
接口容差及候选误差中的 *AngleRad |
弧度 |
normal、axis、outwardNormal、displayForward |
三维方向向量,后端归一化;不得为零向量 |
quaternionXYZW |
四元数顺序 [x, y, z, w] |
STEP 返回的 *Mm、areaMm2 |
毫米、平方毫米 |
assemblyMetadata.dimensions.*Mm |
毫米 |
STEP 点坐标转换到接口几何前,乘以返回的 scaleToMeters,当前为 0.001。
1.4 接口运行日志
全部 29 个业务接口均记录运行日志,包含接口的中文说明、HTTP 方法、路由模板、请求编号、处理结果、HTTP 状态、业务错误码和耗时。查询、用户管理、文件下载、STEP 解析和姿态计算也记录运行日志;第 7 节数据库操作日志的记录范围仍按原规则执行。
接口开始 description=查询用户列表 method=GET path=/admin-api/users requestId=req-demo-001
接口结束 description=查询用户列表 method=GET path=/admin-api/users requestId=req-demo-001 result=SUCCESS httpStatus=200 code=OK durationMs=8 exceptionType=-
成功请求的开始和结束日志为 INFO;参数校验或业务失败的结束日志为 WARN;服务端错误或请求处理中抛出的未处理异常为 ERROR。文件流接口没有 JSON 业务错误码时,使用 HTTP_204、HTTP_200 等状态标识。文件流已开始发送后发生异常时,日志可能同时显示原 HTTP 状态和 result=FAILURE,需结合异常类型及请求编号排查。
路由只输出模板,例如 /admin-api/users/{id}、/admin-api/component-assets/**,不输出请求体、查询关键词、手机号、上传令牌、文件内容或完整文件路径。测试环境的 Mapper 日志保持 INFO,不输出 SQL 参数。向后端反馈问题时提供响应头或 JSON 中的 requestId,用于关联运行日志和业务操作日志。
2. 接口库管理
这里的“接口”指机械安装接口模板。接口定义 ID 是字符串,例如 mount-2-hole。
| 方法 | 路径 | 功能 |
|---|---|---|
| GET | /admin-api/interfaces |
列表及关键词搜索 |
| GET | /admin-api/interfaces/{id} |
详情 |
| POST | /admin-api/interfaces |
新增 |
| PUT | /admin-api/interfaces/{id} |
修改 |
| DELETE | /admin-api/interfaces/{id} |
删除 |
| POST | /admin-api/interfaces/{id}/assets |
绑定源文件 |
| POST | /admin-api/interfaces/{id}/pose-candidates |
计算候选姿态 |
| POST | /admin-api/interfaces/{id}/confirm-port |
确认组件端口姿态 |
2.1 接口定义字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 创建时是 | 唯一且非空;建议不超过 64 字符;修改以路径 ID 为准 |
| name | string | 是 | 非空,建议不超过 128 字符 |
| description | string | 否 | 默认空串,建议不超过 500 字符 |
| geometry | object | 是 | 安装平面与完整孔组,见下表 |
| tolerances | object | 是 | 三个容差必须提供正值 |
| displayForward | number[3] | 否 | 安装面内的默认前方;不传则服务端生成,不能平行于面法向 |
| connectableTargets | string[] | 否 | 可连接目标路径,一维字符串数组;例如 ["机械臂/末端工具", "移动底盘/附件"] |
| geometryRevision | integer | 修改时是 | 详情返回的当前修订号;创建自动为 1 |
| sourceAssetKey | string | 否 | 源文件上传后返回的存储 Key;前端不能通过保存定义直接绑定文件 |
| sourceGeometryHash | string | 否 | 已绑定源文件的 SHA-256,通常带 sha256:;源文件变更时可随保存传入新哈希以清除旧绑定,最终绑定由上传源文件接口完成 |
| 字段 | 类型 | 说明 |
|---|---|---|
| geometry.plane.pointM | number[3] | 平面上的一点,米 |
| geometry.plane.outwardNormal | number[3] | 安装面的向外法向 |
| geometry.holes | object[] | 至少两个不同孔位,必须提供完整孔组 |
| geometry.holes[].id | string | 同一孔组内唯一且非空 |
| geometry.holes[].pointOnPlaneM | number[3] | 孔轴与安装面的交点,米 |
| geometry.holes[].axis | number[3] | 孔轴方向,必须穿过安装面 |
| geometry.holes[].diameterM | number | 可选;提供时必须为正数,单位米 |
| tolerances.positionM | number | 位置容差,正数;示例 0.0002 m = 0.2 mm |
| tolerances.axisAngleRad | number | 孔轴角度容差,范围 (0, π/2) |
| tolerances.planeAngleRad | number | 平面角度容差,范围 (0, π/2) |
后端归一化法向和孔轴、校正允许容差内的孔交点,并按孔 ID 排序。不要依赖提交孔数组的原始顺序。
不支持旧结构字段 profiles、mateRules、frameInComponent、allowedClockingDeg、xAxisAngleDeg。端口计算及确认使用本文的 geometryInLink / selectedPose 结构。
2.2 查询接口列表
GET /admin-api/interfaces
| Query 参数 | 必填 | 说明 |
|---|---|---|
| keyword | 否 | 按名称或描述模糊搜索;省略时返回全部,按更新时间倒序 |
请求示例
GET /admin-api/interfaces?keyword=双孔 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": [
{
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "孔距 40 mm,孔径 4 mm",
"geometryRevision": 1,
"geometry": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"displayForward": [
1.0,
0.0,
0.0
],
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
]
}
],
"requestId": "req-demo-001"
}
2.3 查询接口详情
GET /admin-api/interfaces/{id}
路径参数 id:接口定义字符串 ID。
请求示例
GET /admin-api/interfaces/mount-2-hole HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "孔距 40 mm,孔径 4 mm",
"geometryRevision": 1,
"geometry": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"displayForward": [
1.0,
0.0,
0.0
],
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
]
},
"requestId": "req-demo-001"
}
2.4 新增接口
POST /admin-api/interfaces
请求字段见 2.1。ID 不可与已有定义或已删除定义的历史 ID 重复。
请求示例
POST /admin-api/interfaces HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "孔距 40 mm,孔径 4 mm",
"geometry": {
"plane": {
"pointM": [
0,
0,
0
],
"outwardNormal": [
0,
0,
1
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
}
]
},
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"displayForward": [
1,
0,
0
],
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
]
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "孔距 40 mm,孔径 4 mm",
"geometryRevision": 1,
"geometry": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"displayForward": [
1.0,
0.0,
0.0
],
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
]
},
"requestId": "req-demo-001"
}
2.5 修改接口
PUT /admin-api/interfaces/{id}
请求字段见 2.1,必须携带当前 geometryRevision,并提交完整定义。省略描述、目标或展示方向可能将其恢复为空值/默认值。
请求示例
PUT /admin-api/interfaces/mount-2-hole HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "更新后的接口说明",
"geometry": {
"plane": {
"pointM": [
0,
0,
0
],
"outwardNormal": [
0,
0,
1
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
}
]
},
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"displayForward": [
1,
0,
0
],
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
],
"geometryRevision": 1
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "更新后的接口说明",
"geometryRevision": 2,
"geometry": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"displayForward": [
1.0,
0.0,
0.0
],
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
],
"sourceAssetKey": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/plate.step",
"sourceGeometryHash": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7"
},
"requestId": "req-demo-001"
}
示例从修订 1 更新为 2。修改名称、描述、孔组、容差或可连接目标等会产生新修订;仅展示方向变化且其他内容不变时通常保留修订号。始终以响应为准。
旧修订仍保留历史快照。修订号不匹配返回 422 / INVALID_INTERFACE;前端应重新查询详情,再提示用户重新确认修改。引用旧修订的组件端口,在下一次保存组件时需要重新计算并确认。
2.6 删除接口
DELETE /admin-api/interfaces/{id}
删除当前定义,保留历史快照。删除后的 ID 不可重新创建;删除接口不会清理存储中的源文件。
请求示例
DELETE /admin-api/interfaces/mount-2-hole HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"success": true
},
"requestId": "req-demo-001"
}
2.7 上传并绑定接口源文件
POST /admin-api/interfaces/{id}/assets
| 位置 | 字段 | 必填 | 说明 |
|---|---|---|---|
| Path | id | 是 | 已创建的接口定义 ID |
| Query | geometryRevision | 是 | 当前修订号 |
| multipart | file | 是 | 非空原始文件;通常为 STEP/STP |
先保存接口定义,再上传源文件。后端校验修订号,计算文件 SHA-256,并更新当前修订的源文件绑定。该接口本身不执行 STEP 解析或校验文件拓扑;需要精确解析时先调用第 5 节接口。
单个文件和整个 multipart 请求默认均限制 100 MB;边界开销也占请求大小。当前修订已有不同内容的源文件时,绑定会被拒绝,应按源文件变更流程先保存新修订。
请求示例
curl -X POST 'http://127.0.0.1:8992/admin-api/interfaces/mount-2-hole/assets?geometryRevision=1' \
-H 'X-Request-Id: req-demo-001' \
-F 'file=@./plate.step'
浏览器使用 FormData,字段名为 file;不要手动设置 multipart 的 Content-Type,让浏览器生成 boundary。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/plate.step",
"requestId": "req-demo-001"
}
成功 data 是对象 Key 字符串,不是 URL。再调用接口详情可获得 sourceAssetKey 和 sourceGeometryHash。源文件可通过 /admin-api/component-assets/{objectKey} 下载,对象路径各段需要 URL 编码。
上传后的详情示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": "mount-2-hole",
"name": "双孔安装接口",
"description": "孔距 40 mm,孔径 4 mm",
"geometryRevision": 1,
"geometry": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"displayForward": [
1.0,
0.0,
0.0
],
"tolerances": {
"positionM": 0.0002,
"axisAngleRad": 0.017453292519943295,
"planeAngleRad": 0.017453292519943295
},
"connectableTargets": [
"机械臂/末端工具",
"移动底盘/附件"
],
"sourceAssetKey": "interfaces/6d6f756e742d322d686f6c65/1/073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7/plate.step",
"sourceGeometryHash": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7"
},
"requestId": "req-demo-001"
}
2.8 计算姿态候选
POST /admin-api/interfaces/{id}/pose-candidates
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| definitionRevision | integer | 是 | 使用的模板修订号 |
| linkName | string | 是 | 端口所属原始 URDF link |
| geometryInLink | object | 是 | 实测安装面和完整孔组;与 geometry 结构一致,坐标位于该 link 的局部坐标系 |
| sourceGeometryHash | string | 是 | 原始 URDF 和资源清单形成的源几何哈希,算法见 8.3 |
请求示例
POST /admin-api/interfaces/mount-2-hole/pose-candidates HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"definitionRevision": 1,
"linkName": "base_link",
"geometryInLink": {
"plane": {
"pointM": [
0,
0,
0
],
"outwardNormal": [
0,
0,
1
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
}
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"solverVersion": "mount-geometry-3",
"candidates": [
{
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
],
"registrationSide": 1,
"maxHoleOffsetM": 0.0,
"rmsHoleOffsetM": 0.0,
"maxAxisAngleRad": 0.0
},
{
"id": "f2fb42e5f5f75f7ec7491ce6dadc61717543d1f38453d95517a1955e86a06c82",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
1.0,
0.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h2"
},
{
"templateHoleId": "h2",
"observedHoleId": "h1"
}
],
"orientationDirectionInLink": [
-1.0,
0.0,
0.0
],
"registrationSide": 1,
"maxHoleOffsetM": 0.0,
"rmsHoleOffsetM": 0.0,
"maxAxisAngleRad": 0.0
}
],
"reasons": []
},
"requestId": "req-demo-001"
}
| 候选字段 | 说明 |
|---|---|
| id | 候选的稳定标识;必须使用当前响应中的值 |
| templateInLink.positionM | 模板坐标系原点在 link 中的位置,米 |
| templateInLink.quaternionXYZW | 模板坐标系到 link 的旋转 |
| holeMapping | 模板孔 ID 与实测孔 ID 的对应 |
| orientationDirectionInLink | 默认前方映射到 link 后的方向 |
| registrationSide | 匹配侧别,为 1 或 -1 |
| maxHoleOffsetM / rmsHoleOffsetM | 最大/均方根孔位误差,米 |
| maxAxisAngleRad | 最大孔轴角度误差,弧度 |
候选可能不唯一,由前端展示并让用户选择。几何结构合法但无法匹配时仍返回 HTTP 200 / OK,此时 candidates 为空,应展示 reasons,并返回几何确认流程。
无法匹配的返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"solverVersion": "mount-geometry-3",
"candidates": [],
"reasons": [
"孔 h1 的孔距组合与模板不符,请核对该孔及完整孔组",
"孔 h2 的孔距组合与模板不符,请核对该孔及完整孔组"
]
},
"requestId": "req-demo-001"
}
2.9 确认端口姿态
POST /admin-api/interfaces/{id}/confirm-port
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 组件端口 ID,同一组件内唯一 |
| linkName | string | 是 | 所属原始 link 名称 |
| definitionId | string | 是 | 必须与 URL 的接口 ID 相同 |
| definitionRevision | integer | 是 | 对应模板修订号 |
| geometryInLink | object | 是 | 与计算候选时一致的实测几何 |
| selectedPose | object | 是 | 至少提供当前候选 id;建议同时复制候选的姿态、孔映射和方向字段 |
| sourceGeometryHash | string | 是 | 与计算候选时一致的 URDF 源几何哈希 |
| solverVersion | string | 是 | 复制候选集返回值,当前为 mount-geometry-3 |
| connectableTargets | array | 否 | 不传或为空时使用模板目标;多目标建议采用二维路径数组,见下文 |
请求示例
POST /admin-api/interfaces/mount-2-hole/confirm-port HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0,
0,
0
],
"outwardNormal": [
0,
0,
1
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0,
0
],
"axis": [
0,
0,
1
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
[
"机械臂",
"末端工具"
]
]
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
"机械臂/末端工具"
]
},
"requestId": "req-demo-001"
}
服务端依据候选 id 重新计算,返回规范化端口;提交的旋转和孔映射不会作为最终可信结果。该接口只计算和确认,不自动保存组件。
可连接目标的输入兼容规则:接口定义 CRUD 使用一维路径字符串数组;confirm-port 和 componentJson.interfaces 会把一维字符串数组视为“一条级联路径”,例如 ["机械臂", "末端工具"] 被合并为 "机械臂/末端工具"。多个目标请提交二维数组,例如 [["机械臂", "末端工具"], ["移动底盘", "附件"]]。返回统一为一维路径字符串数组。将确认结果用于保存组件时,多目标应先转换为二维数组,避免被合并为一条路径。
3. 组件库管理及上传会话
组件 ID 为数值型。新增、修改均需完整提交必填字段。
| 方法 | 路径 | 功能 |
|---|---|---|
| GET | /admin-api/components |
分页搜索 |
| GET | /admin-api/components/{id} |
详情 |
| POST | /admin-api/components |
新增 |
| PUT | /admin-api/components/{id} |
修改 |
| DELETE | /admin-api/components/{id} |
删除 |
| POST | /admin-api/components/cover-image-upload-sessions |
创建封面会话 |
| POST | /admin-api/components/cover-image-upload-sessions/upload-url |
获取封面上传地址 |
| POST | /admin-api/components/cover-image-upload-sessions/complete |
完成封面上传 |
| POST | /admin-api/components/urdf-upload-sessions |
创建 URDF/RFS 会话 |
| POST | /admin-api/components/urdf-upload-sessions/upload-url |
获取单文件上传地址 |
| POST | /admin-api/components/urdf-upload-sessions/complete |
完成 URDF/RFS 上传 |
3.1 组件请求与响应字段
| Body 字段 | 类型 | 必填 | 限制或说明 |
|---|---|---|---|
| componentName | string | 是 | 非空、最多 64 字符,名称不可重复 |
| category | string | 否 | 最多 64 字符,自由填写分类;当前字段名为 category,不是 componentType |
| robotType | string | 是 | 非空、最多 32 字符;当前不是后端枚举,例如 humanoid |
| company | string | 是 | 非空、最多 64 字符 |
| model | string | 是 | 非空、最多 64 字符 |
| source | string | 是 | 非空、最多 255 字符;使用完成 URDF/RFS 上传返回的对象 Key,不填下载 URL |
| coverImageKey | string | 否 | 最多 512 字符;使用完成封面上传返回的 Key |
| description | string | 否 | 组件说明 |
| componentJson | object | 是 | 组件模型数据与端口;无端口可先传 { "interfaces": [] } |
| assemblyMetadata | object | 是 | 检索用的语义元数据,见下表 |
| assemblyMetadata 字段 | 类型 | 说明 |
|---|---|---|
| tags | string[] | 标签;可为空,省略归一化为 [],空白和重复项会被整理 |
| capabilities | string[] | 能力标签;可为空,省略归一化为 [] |
| dimensions | object | 尺寸;可为空对象,省略归一化为 {} |
| dimensions.lengthMm / widthMm / heightMm | number | 可选;提供时必须大于 0,单位毫米 |
服务端会将能力及分类信息合并到返回的标签中。详情响应额外包含 id、sourceUrl、coverImageUrl、createdAt、updatedAt;这些不是保存时必须传入的字段。sourceUrl 和 coverImageUrl 已由后端生成,用于读取资源。
列表返回基础信息和 assemblyMetadata,不包含 componentJson、coverImageKey。详情、新增和修改响应包含完整组件。可选文本为空时通常返回空字符串。
componentJson.interfaces 非空时,必须同时提供原始 urdfSource 快照、资源清单以及已经确认的端口。后端会核对源文件资源、link、源哈希、模板当前修订和选中候选;不能只填端口名称和坐标。详见 8.3。
每次成功新增/修改会由后端写入或递增 componentJson.componentRevision。存在 interfaces 数组时会返回 interfaceSchemaVersion: 3;前端不自行生成这些版本值。
3.2 查询组件列表
GET /admin-api/components
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 否 | 默认 1,请传正整数 |
| size | integer | 否 | 默认 20,上限 100,请传正整数 |
| keyword | string | 否 | 搜索组件名称、分类、标签和能力;当前不搜索厂商及型号 |
请求示例
GET /admin-api/components?page=1&size=20 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"items": [
{
"id": 1,
"componentName": "双孔安装底座",
"category": "安装件",
"robotType": "humanoid",
"company": "示例厂商",
"model": "BASE-001",
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"sourceUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"coverImageUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"description": "双孔固定底座",
"assemblyMetadata": {
"tags": [
"安装件",
"底座",
"固定安装"
],
"capabilities": [
"固定安装"
],
"dimensions": {
"lengthMm": 80.0,
"widthMm": 50.0,
"heightMm": 10.0
}
},
"createdAt": "2026-10-09T17:10:24.926",
"updatedAt": "2026-10-09T17:10:24.926"
}
],
"page": 1,
"size": 20,
"total": 1
},
"requestId": "req-demo-001"
}
搜索示例:GET /admin-api/components?page=1&size=20&keyword=底座;查询字符串使用 URL 编码。结果按更新时间倒序。
3.3 查询组件详情
GET /admin-api/components/{id}
路径参数 id:数值型组件 ID。
请求示例
GET /admin-api/components/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 1,
"componentName": "双孔安装底座",
"category": "安装件",
"robotType": "humanoid",
"company": "示例厂商",
"model": "BASE-001",
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"sourceUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"coverImageKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"coverImageUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"description": "双孔固定底座",
"componentJson": {
"urdfSource": {
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
},
"interfaces": [
{
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
"机械臂/末端工具"
]
}
],
"interfaceSchemaVersion": 3,
"componentRevision": 1
},
"assemblyMetadata": {
"tags": [
"安装件",
"底座",
"固定安装"
],
"capabilities": [
"固定安装"
],
"dimensions": {
"lengthMm": 80.0,
"widthMm": 50.0,
"heightMm": 10.0
}
},
"createdAt": "2026-10-09T17:10:24.926",
"updatedAt": "2026-10-09T17:10:24.926"
},
"requestId": "req-demo-001"
}
3.4 新增组件
POST /admin-api/components
请求字段见 3.1。示例展示带已确认端口的完整保存结构;没有端口时可以将 componentJson 简化为 { "interfaces": [] }。
请求示例
POST /admin-api/components HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"componentName": "双孔安装底座",
"category": "安装件",
"robotType": "humanoid",
"company": "示例厂商",
"model": "BASE-001",
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"coverImageKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"description": "双孔固定底座",
"componentJson": {
"urdfSource": {
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
},
"interfaces": [
{
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
[
"机械臂",
"末端工具"
]
]
}
]
},
"assemblyMetadata": {
"tags": [
"安装件",
"底座"
],
"capabilities": [
"固定安装"
],
"dimensions": {
"lengthMm": 80,
"widthMm": 50,
"heightMm": 10
}
}
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 1,
"componentName": "双孔安装底座",
"category": "安装件",
"robotType": "humanoid",
"company": "示例厂商",
"model": "BASE-001",
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"sourceUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"coverImageKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"coverImageUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"description": "双孔固定底座",
"componentJson": {
"urdfSource": {
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
},
"interfaces": [
{
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
"机械臂/末端工具"
]
}
],
"interfaceSchemaVersion": 3,
"componentRevision": 1
},
"assemblyMetadata": {
"tags": [
"安装件",
"底座",
"固定安装"
],
"capabilities": [
"固定安装"
],
"dimensions": {
"lengthMm": 80.0,
"widthMm": 50.0,
"heightMm": 10.0
}
},
"createdAt": "2026-10-09T17:10:24.926",
"updatedAt": "2026-10-09T17:10:24.926"
},
"requestId": "req-demo-001"
}
3.5 修改组件
PUT /admin-api/components/{id}
请求字段同新增。使用完整必填字段;省略分类、封面和描述会将这些可选文本重置为空。
请求示例
PUT /admin-api/components/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"componentName": "双孔安装底座 V2",
"category": "安装件",
"robotType": "humanoid",
"company": "示例厂商",
"model": "BASE-001",
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"coverImageKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"description": "更新后的组件说明",
"componentJson": {
"urdfSource": {
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
},
"interfaces": [
{
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
[
"机械臂",
"末端工具"
]
]
}
]
},
"assemblyMetadata": {
"tags": [
"安装件",
"底座"
],
"capabilities": [
"固定安装"
],
"dimensions": {
"lengthMm": 80,
"widthMm": 50,
"heightMm": 10
}
}
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 1,
"componentName": "双孔安装底座 V2",
"category": "安装件",
"robotType": "humanoid",
"company": "示例厂商",
"model": "BASE-001",
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"sourceUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf",
"coverImageKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"coverImageUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"description": "更新后的组件说明",
"componentJson": {
"urdfSource": {
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
},
"interfaces": [
{
"id": "port-1",
"linkName": "base_link",
"definitionId": "mount-2-hole",
"definitionRevision": 1,
"geometryInLink": {
"plane": {
"pointM": [
0.0,
0.0,
0.0
],
"outwardNormal": [
0.0,
0.0,
1.0
]
},
"holes": [
{
"id": "h1",
"pointOnPlaneM": [
-0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
},
{
"id": "h2",
"pointOnPlaneM": [
0.02,
0.0,
0.0
],
"axis": [
0.0,
0.0,
1.0
],
"diameterM": 0.004
}
]
},
"selectedPose": {
"id": "fc9c1d72317f9890f0969552f3f73ad9df5f7b6bc5756d7e58963888a25ff4c1",
"templateInLink": {
"positionM": [
0.0,
0.0,
0.0
],
"quaternionXYZW": [
0.0,
0.0,
0.0,
1.0
]
},
"holeMapping": [
{
"templateHoleId": "h1",
"observedHoleId": "h1"
},
{
"templateHoleId": "h2",
"observedHoleId": "h2"
}
],
"orientationDirectionInLink": [
1.0,
0.0,
0.0
]
},
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f",
"solverVersion": "mount-geometry-3",
"connectableTargets": [
"机械臂/末端工具"
]
}
],
"interfaceSchemaVersion": 3,
"componentRevision": 2
},
"assemblyMetadata": {
"tags": [
"安装件",
"底座",
"固定安装"
],
"capabilities": [
"固定安装"
],
"dimensions": {
"lengthMm": 80.0,
"widthMm": 50.0,
"heightMm": 10.0
}
},
"createdAt": "2026-10-09T17:10:24.926",
"updatedAt": "2026-10-09T17:10:24.957"
},
"requestId": "req-demo-001"
}
3.6 删除组件
DELETE /admin-api/components/{id}
物理删除组件及关联资源索引,不删除 MinIO 中已经上传的对象。
请求示例
DELETE /admin-api/components/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"success": true
},
"requestId": "req-demo-001"
}
3.7 上传会话通用规则
- 先创建会话,再为每个文件获取上传 URL,随后向 URL 发起原始文件流 PUT,最后提交对象 Key 列表完成上传。
- 会话默认有效期 30 分钟;创建会话只返回
uploadSessionToken / keyPrefix,不返回expiresAt。令牌过期或服务端临时密钥因重启变化时,重新创建会话。 keyPrefix是服务端生成的完整前缀;不要自己拼操作人、日期或 UUID。objectPath是相对路径,例如robot.urdf、meshes/base.stl;不能以/开头或结尾,不能包含空路径段、.或..。建议统一使用/。- 获取 URL 时
objectPath最多 512 字符、contentType最多 255 字符;拼接后的完整对象 Key 也不得超过 512 字符。 objectKeys必须是获取上传地址时返回的完整 Key,属于同一会话且已经上传,不可重复;不能提交 URL 或仅文件名。- 上传会话令牌放在获取 URL、完成上传的 JSON 请求体中;它不是
Authorization登录令牌,也不需要添加到返回的上传 URL。 - 完成上传仅校验文件并返回可保存字段,不自动创建或修改组件。
3.8 创建封面上传会话
POST /admin-api/components/cover-image-upload-sessions
请求示例
POST /admin-api/components/cover-image-upload-sessions HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"uploadSessionToken": "<COVER_IMAGE_UPLOAD_SESSION_TOKEN>",
"keyPrefix": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/"
},
"requestId": "req-demo-001"
}
3.9 获取封面文件上传地址
POST /admin-api/components/cover-image-upload-sessions/upload-url
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uploadSessionToken | string | 是 | 本类型创建会话的返回值 |
| objectPath | string | 是 | 当前会话中的相对文件路径 |
| contentType | string | 否 | 文件 MIME 类型,建议与实际 PUT 请求保持一致 |
请求示例
POST /admin-api/components/cover-image-upload-sessions/upload-url HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"uploadSessionToken": "<COVER_IMAGE_UPLOAD_SESSION_TOKEN>",
"objectPath": "cover.png",
"contentType": "image/png"
}
成功返回示例:HTTP 200
{
"code": "OK",
"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"
},
"requestId": "req-demo-001"
}
取得 URL 后按第 4.1 节上传文件,收到 204 再调用完成上传接口。
3.10 完成封面上传
POST /admin-api/components/cover-image-upload-sessions/complete
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uploadSessionToken | string | 是 | 创建会话返回值 |
| objectKeys | string[] | 是 | 已上传的完整对象 Key;必须恰好 1 个 |
封面扩展名支持 .jpg、.jpeg、.png、.webp、.gif,不区分大小写。完成后将 coverImageKey 用于保存组件,coverImageUrl 用于预览。
请求示例
POST /admin-api/components/cover-image-upload-sessions/complete HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"uploadSessionToken": "<COVER_IMAGE_UPLOAD_SESSION_TOKEN>",
"objectKeys": [
"components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png"
]
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"coverImageKey": "components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png",
"coverImageUrl": "http://127.0.0.1:8992/admin-api/component-assets/components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png"
},
"requestId": "req-demo-001"
}
3.11 创建 URDF/RFS 上传会话
POST /admin-api/components/urdf-upload-sessions
请求示例
POST /admin-api/components/urdf-upload-sessions HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"uploadSessionToken": "<URDF_UPLOAD_SESSION_TOKEN>",
"keyPrefix": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/"
},
"requestId": "req-demo-001"
}
3.12 获取 URDF/RFS 文件上传地址
POST /admin-api/components/urdf-upload-sessions/upload-url
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uploadSessionToken | string | 是 | 本类型创建会话的返回值 |
| objectPath | string | 是 | 当前会话中的相对文件路径 |
| contentType | string | 否 | 文件 MIME 类型,建议与实际 PUT 请求保持一致 |
请求示例
POST /admin-api/components/urdf-upload-sessions/upload-url HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"uploadSessionToken": "<URDF_UPLOAD_SESSION_TOKEN>",
"objectPath": "robot.urdf",
"contentType": "application/xml"
}
成功返回示例:HTTP 200
{
"code": "OK",
"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"
},
"requestId": "req-demo-001"
}
取得 URL 后按第 4.1 节上传文件,收到 204 再调用完成上传接口。
3.13 完成 URDF/RFS 上传
POST /admin-api/components/urdf-upload-sessions/complete
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| uploadSessionToken | string | 是 | 创建会话返回值 |
| objectKeys | string[] | 是 | 已上传的完整对象 Key;1~1000 个,不可重复 |
所有模型、网格、纹理等文件上传完毕后一起提交。必须恰好包含一个主文件:.urdf、.rfs 或 .rfs.json。URDF 和 RFS 不能同时存在,同类主文件也不能超过一个。资源文件可以有多个,并应保持相对目录结构。
返回 source 是主文件对象 Key,最长 255 字符;用于新增或修改组件。此接口不解析或返回完整 componentJson,前端仍需根据模型准备保存数据。
请求示例
POST /admin-api/components/urdf-upload-sessions/complete HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"uploadSessionToken": "<URDF_UPLOAD_SESSION_TOKEN>",
"objectKeys": [
"components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf"
]
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf"
},
"requestId": "req-demo-001"
}
4. 资源上传与下载
这些接口通过后台读写 MinIO,前端不需要 MinIO Access Key、Secret Key 或直连存储桶。
4.1 上传原始文件流
PUT /admin-api/component-assets/upload
| 位置 | 字段 | 必填 | 说明 |
|---|---|---|---|
| Query | objectKey | 是 | 获取上传地址返回的完整对象 Key;应直接使用返回的 uploadUrl |
| Header | Content-Type | 否 | 真实文件 MIME 类型;省略时按通用二进制类型处理 |
| Body | 文件二进制 | 是 | 直接发送 File/Blob/ArrayBuffer;不用 FormData,不做 JSON 或 Base64 包装 |
请求示例
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-Request-Id: req-demo-001' \
--data-binary '@./robot.urdf'
成功返回示例
HTTP/1.1 204 No Content
X-Request-Id: req-demo-001
响应体为空,不执行 response.json()。失败时仍按第 9 节处理 JSON 错误响应。当前应用只允许写入配置操作人的组件资源目录;接口源文件通过第 2.7 节上传。
这里的 PUT 是原始文件流,Spring multipart 的 100 MB 限制不直接作用于此接口;实际大小还可能受到部署网关限制,前端应与部署环境保持一致。
4.2 下载或读取资源
GET /admin-api/component-assets/{objectKey}
objectKey 表示包含多级 / 的完整对象路径,不只是最后一个文件名。通常直接使用组件详情返回的 sourceUrl / coverImageUrl。
请求示例
GET /admin-api/component-assets/components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例
HTTP/1.1 200 OK
Content-Type: application/xml
Cache-Control: public, max-age=3600
X-Request-Id: req-demo-001
<robot name="demo"><link name="base_link"/></robot>
图片等文件返回对应 MIME 类型和二进制内容,服务端在知道大小时返回 Content-Length。读取时使用 text()、blob() 或 arrayBuffer(),不要统一按 JSON 解析。资源不存在时返回 JSON 错误响应,例如 404 / MINIO_OBJECT_NOT_FOUND。
如需从 Key 手动拼路径,对每个路径段编码后用 / 连接;不要把整个带斜杠的路径当作一个普通路径段。
5. STEP 精确解析
5.1 分析 STEP/STP
POST /admin-api/interface-brep/analyze
| 位置 | 字段 | 必填 | 说明 |
|---|---|---|---|
| multipart | file | 是 | 非空 .step 或 .stp 文件,扩展名不区分大小写;不接受 STL |
默认单文件及整个 multipart 请求上限均为 100 MB;默认解析超时 120 秒、输出上限 100 MB。该接口只返回解析数据,不创建接口定义,也不绑定或永久保存上传文件。
请求示例
curl -X POST 'http://127.0.0.1:8992/admin-api/interface-brep/analyze' \
-H 'X-Request-Id: req-demo-001' \
-F 'file=@./box.step'
浏览器使用 FormData;不要手动指定 multipart boundary。前端 HTTP 超时应略大于服务端解析超时。
以下响应是实际生成的盒体 STEP 的结构节选:只保留一个面、一条边,并截取少量显示采样和三角网格。实际响应返回完整数组;faceCount / edgeCount 是完整模型计数。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"schemaVersion": "interface-step-brep/v1",
"sourceName": "source.step",
"sourceSha256": "073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7",
"sourceUnits": "mm",
"scaleToMeters": 0.001,
"kernel": "OCCT 7.8",
"triangulationPurpose": "display-and-picking-only",
"linearDeflectionMm": 0.2,
"displayMeshSimplificationPasses": 0,
"faceCount": 6,
"edgeCount": 12,
"faces": [
{
"id": "brep:face:1",
"sourceRef": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7:face:1",
"surfaceType": "plane",
"isPlanar": true,
"normal": [
-1.0,
-0.0,
0.0
],
"planeLocationMm": [
0.0,
0.0,
0.0
],
"xDirection": [
0.0,
0.0,
1.0
],
"pointMm": [
0.0,
10.0,
15.0
],
"areaMm2": 600.0,
"orientation": "reversed",
"adjacentFaceIds": [
"brep:face:3",
"brep:face:4",
"brep:face:5",
"brep:face:6"
],
"triangles": {
"positionsMm": [
0.0,
0.0,
30.0,
0.0,
20.0,
0.0,
0.0,
0.0,
0.0,
0.0,
20.0,
30.0
],
"indices": [
0,
1,
2
]
},
"wires": [
{
"id": "brep:face:1:wire:1",
"sourceRef": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7:face:1:wire:1",
"isOuter": true,
"isCircular": false,
"centerMm": null,
"radiusMm": null,
"axis": null,
"fitResidualMm": null,
"circularityMethod": null,
"edges": [
{
"id": "brep:edge:1",
"sourceRef": "sha256:073b7cf3dbe11a465f34da53b9b5e765a489e970cbb0f6c3c2d8cd01553aedc7:edge:1",
"curveType": "line",
"orientation": "forward",
"firstParameter": 0.0,
"lastParameter": 30.0,
"startMm": [
0.0,
0.0,
0.0
],
"endMm": [
0.0,
0.0,
30.0
],
"samplesMm": [
[
0.0,
0.0,
0.0
],
[
0.0,
0.0,
30.0
]
],
"isExact": true,
"selectableAsBoundary": true,
"direction": [
0.0,
0.0,
1.0
]
}
]
}
]
}
]
},
"requestId": "req-demo-001"
}
| data 字段 | 说明 |
|---|---|
| schemaVersion | 当前为 interface-step-brep/v1 |
| sourceName | 解析器使用的文件名,当前通常为 source.step 或 source.stp,不是前端原文件名 |
| sourceSha256 | 原始 STEP 文件字节的 SHA-256,64 位小写十六进制,无 sha256: 前缀 |
| sourceUnits / scaleToMeters | 输出坐标单位及转换到米的比例,当前 mm / 0.001 |
| kernel | 几何内核版本标识 |
| triangulationPurpose | display-and-picking-only:三角网格仅用于显示和拾取 |
| linearDeflectionMm / displayMeshSimplificationPasses | 显示网格精度和简化次数 |
| faceCount / edgeCount | 原模型面和边数量 |
| faces | 完整面数组,包括曲面类型、法向/轴、面积、线环、边和显示网格 |
| 嵌套字段 | 说明 |
|---|---|
| faces[].id / sourceRef | 精确面的 ID 与源文件引用;后续拾取应保留这些标识 |
| faces[].surfaceType / isPlanar | 曲面类型及是否平面;字段依据类型出现 |
| faces[].normal / planeLocationMm / xDirection | 平面法向、平面位置和面内基准方向,仅平面类型提供 |
| faces[].axis / axisLocationMm / radiusMm | 圆柱轴、轴位置和半径,仅圆柱类型提供 |
| faces[].pointMm / areaMm2 / orientation | 面参考点、面积以及 forward / reversed 方向 |
| faces[].adjacentFaceIds | 相邻面的 ID |
| faces[].triangles.positionsMm | 扁平位置数组 [x0,y0,z0,x1,y1,z1,...],毫米 |
| faces[].triangles.indices | 三角形顶点索引数组,每三个索引组成一个三角形 |
| faces[].wires[] | 线环;含 id / sourceRef / isOuter / isCircular / edges |
| wires[].centerMm / radiusMm / axis | 圆形线环的圆心、半径和轴;非圆环可为 null |
| wires[].fitResidualMm / circularityMethod | 圆形拟合残差和方法;可能为 null |
| edges[].id / sourceRef / curveType | 精确边引用与曲线类型,例如 line / circle / ellipse / bspline |
| edges[].startMm / endMm / samplesMm | 端点及显示用的采样点,单位毫米 |
| edges[].firstParameter / lastParameter / orientation | 底层曲线参数范围和方向,不是统一的毫米长度 |
| edges[].isExact / selectableAsBoundary | 是否原始精确边及能否选作边界 |
| edges[].direction | 直线方向;圆边可返回圆心、半径、axis、xDirection、isFullCircle;椭圆返回长短半径 |
不能从显示三角网格反推并保存精确接口;保存几何时应基于精确平面、孔轴及原始拓扑引用,并转换为米。该接口不记录业务操作日志。
6. 用户管理
用户 ID 为数值型。本阶段仅管理手机号、昵称、类型和状态,不提供密码、登录和角色/菜单权限配置。
| 方法 | 路径 | 功能 |
|---|---|---|
| GET | /admin-api/users |
分页及筛选 |
| GET | /admin-api/users/{id} |
详情 |
| POST | /admin-api/users |
创建 |
| PUT | /admin-api/users/{id} |
修改 |
| DELETE | /admin-api/users/{id} |
逻辑删除 |
6.1 用户保存字段
| Body 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| phone | string | 是 | 大陆手机号,正则 ^1[3-9]\d{9}$;不可与已有或已删除用户重复 |
| nickname | string | 是 | 非空、最多 64 字符 |
| status | string | 否 | ACTIVE 或 DISABLED;创建默认 ACTIVE,修改省略或 null 时保留原值 |
| userType | string | 否 | NORMAL 或 ADMIN;创建默认 NORMAL,修改省略或 null 时保留原值 |
枚举必须使用上述大写值。修改时仍必须提交 phone 和 nickname,不是 PATCH。响应额外提供 id / createdAt / updatedAt;deleted 不暴露给前端。
6.2 查询用户列表
GET /admin-api/users
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 否 | 默认 1,最小 1 |
| size | integer | 否 | 默认 20,最小 1,上限 100 |
| keyword | string | 否 | 手机号或昵称模糊匹配 |
| userType | string | 否 | NORMAL / ADMIN |
| status | string | 否 | ACTIVE / DISABLED |
请求示例
GET /admin-api/users?page=1&size=20&keyword=示例&userType=ADMIN&status=DISABLED HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"items": [
{
"id": 1,
"phone": "13800000001",
"nickname": "示例管理员",
"status": "DISABLED",
"userType": "ADMIN",
"createdAt": "2026-10-09T17:10:24.51",
"updatedAt": "2026-10-09T17:10:24.563"
}
],
"page": 1,
"size": 20,
"total": 1
},
"requestId": "req-demo-001"
}
按更新时间、ID 倒序;已逻辑删除的用户不会出现在列表中。
6.3 查询用户详情
GET /admin-api/users/{id}
路径参数 id:用户数值 ID。
请求示例
GET /admin-api/users/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 1,
"phone": "13800000001",
"nickname": "示例用户",
"status": "ACTIVE",
"userType": "NORMAL",
"createdAt": "2026-10-09T17:10:24.51",
"updatedAt": "2026-10-09T17:10:24.51"
},
"requestId": "req-demo-001"
}
6.4 创建用户
POST /admin-api/users
请求字段见 6.1。
请求示例
POST /admin-api/users HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"phone": "13800000001",
"nickname": "示例用户",
"status": "ACTIVE",
"userType": "NORMAL"
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 1,
"phone": "13800000001",
"nickname": "示例用户",
"status": "ACTIVE",
"userType": "NORMAL",
"createdAt": "2026-10-09T17:10:24.51",
"updatedAt": "2026-10-09T17:10:24.51"
},
"requestId": "req-demo-001"
}
6.5 修改用户
PUT /admin-api/users/{id}
请求字段见 6.1。
请求示例
PUT /admin-api/users/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
{
"phone": "13800000001",
"nickname": "示例管理员",
"status": "DISABLED",
"userType": "ADMIN"
}
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 1,
"phone": "13800000001",
"nickname": "示例管理员",
"status": "DISABLED",
"userType": "ADMIN",
"createdAt": "2026-10-09T17:10:24.51",
"updatedAt": "2026-10-09T17:10:24.563"
},
"requestId": "req-demo-001"
}
6.6 逻辑删除用户
DELETE /admin-api/users/{id}
删除后详情及列表都查不到该用户,但历史数据和手机号唯一约束仍保留;手机号不能分配给新用户。重复删除返回 404 / USER_NOT_FOUND。
请求示例
DELETE /admin-api/users/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"success": true
},
"requestId": "req-demo-001"
}
用户管理操作不写入本文第 7 节的业务操作日志。
7. 操作日志
只读模块,提供列表和详情。记录组件库、接口库写操作的成功与失败;用户管理、查询、下载、STEP 分析、姿态候选及确认不产生该类业务日志。
业务日志保存失败不改变原接口结果;前端不要以“日志列表是否立即出现记录”作为写操作是否成功的判断依据。
| 动作值 | 含义 |
|---|---|
| CREATE | 新增组件或接口 |
| UPDATE | 修改组件或接口 |
| DELETE | 删除组件或接口 |
| PREPARE_UPLOAD | 创建上传会话 |
| PREPARE_UPLOAD_URL | 获取单文件上传地址 |
| UPLOAD | 资源文件上传或接口源文件上传 |
| COMPLETE_UPLOAD | 完成上传会话 |
7.1 查询操作日志列表
GET /admin-api/operation-logs
| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 否 | 默认 1,最小 1 |
| size | integer | 否 | 默认 20,最小 1,上限 100 |
| module | string | 否 | COMPONENT / INTERFACE |
| action | string | 否 | 上表动作值 |
| success | boolean | 否 | true 成功、false 失败;省略查询全部 |
| operatorId | integer | 否 | 操作人 ID;默认测试操作人 0 |
| from | string | 否 | 开始时间,包含该边界;如 2026-10-09T00:00:00 |
| to | string | 否 | 结束时间,包含该边界;如 2026-10-09T23:59:59.999 |
请求示例
GET /admin-api/operation-logs?page=1&size=20&module=INTERFACE&action=UPDATE&success=false&operatorId=0 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"items": [
{
"id": 14,
"module": "INTERFACE",
"action": "UPDATE",
"targetId": "mount-2-hole",
"operatorId": 0,
"operatorName": "TEST_OPERATOR",
"requestPath": "/admin-api/interfaces/mount-2-hole",
"requestMethod": "PUT",
"clientIp": "127.0.0.1",
"requestId": "req-demo-001",
"operatedAt": "2026-10-09T17:10:26.262",
"durationMs": 3,
"success": false,
"httpStatus": 422,
"errorSummary": "接口已修改,请刷新后保存"
}
],
"page": 1,
"size": 20,
"total": 1
},
"requestId": "req-demo-001"
}
时间查询示例:GET /admin-api/operation-logs?page=1&size=20&module=COMPONENT&success=true&operatorId=0&from=2026-10-09T00%3A00%3A00&to=2026-10-09T23%3A59%3A59.999。
开始时间晚于结束时间返回 422 / INVALID_REQUEST。module / action 当前是精确字符串筛选,输入未使用的值通常得到空列表;前端下拉框使用本文列出的值。结果按操作时间、ID 倒序。
成功操作的分页示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"items": [
{
"id": 10,
"module": "COMPONENT",
"action": "CREATE",
"targetId": "1",
"operatorId": 0,
"operatorName": "TEST_OPERATOR",
"requestPath": "/admin-api/components",
"requestMethod": "POST",
"clientIp": "127.0.0.1",
"requestId": "req-demo-001",
"operatedAt": "2026-10-09T17:10:24.908",
"durationMs": 22,
"success": true,
"httpStatus": 200
}
],
"page": 1,
"size": 20,
"total": 1
},
"requestId": "req-demo-001"
}
7.2 查询操作日志详情
GET /admin-api/operation-logs/{id}
路径参数 id:数值型日志 ID。
请求示例
GET /admin-api/operation-logs/14 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
无请求体。
成功返回示例:HTTP 200
{
"code": "OK",
"message": "success",
"data": {
"id": 14,
"module": "INTERFACE",
"action": "UPDATE",
"targetId": "mount-2-hole",
"operatorId": 0,
"operatorName": "TEST_OPERATOR",
"requestPath": "/admin-api/interfaces/mount-2-hole",
"requestMethod": "PUT",
"clientIp": "127.0.0.1",
"requestId": "req-demo-001",
"operatedAt": "2026-10-09T17:10:26.262",
"durationMs": 3,
"success": false,
"httpStatus": 422,
"errorSummary": "接口已修改,请刷新后保存"
},
"requestId": "req-demo-001"
}
| 返回字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 日志 ID |
| module / action | string | 业务模块及动作 |
| targetId | string | 业务对象 ID、对象 Key 或会话前缀;失败发生较早时可能缺省 |
| operatorId / operatorName | integer / string | 操作人 ID 和名称 |
| requestPath / requestMethod | string | 请求路径及 HTTP 方法 |
| clientIp | string | 服务端看到的请求来源 IP |
| requestId | string | 产生该日志的原请求编号;与查询日志接口外层 requestId 含义不同 |
| operatedAt | string | 操作时间,上海时区本地时间 |
| durationMs | integer | 请求处理耗时,毫秒 |
| success | boolean | 成功/失败 |
| httpStatus | integer | 原操作的 HTTP 状态码 |
| errorSummary | string | 失败摘要;成功日志通常缺省 |
不提供日志新增、修改、删除接口;不返回请求体、文件内容、密钥或上传会话令牌。
8. 前端调用流程
8.1 创建或编辑组件
- 通过 URDF/RFS 会话上传模型及资源,完成上传后取得
source。 - 如需封面,通过封面会话上传,完成后取得
coverImageKey / coverImageUrl。 - 前端解析模型并准备
componentJson、assemblyMetadata;需要端口时执行 8.3。 - 调用
POST /admin-api/components或PUT /admin-api/components/{id}。 - 以后展示资源使用详情返回的
sourceUrl / coverImageUrl。
8.2 浏览器上传示例
以下以 URDF/RFS 会话为例;封面流程将会话路径替换为 cover-image-upload-sessions,完成结果字段使用 coverImageKey。
const apiBase = 'http://127.0.0.1:8992';
async function readJsonResponse(response) {
const body = await response.json();
if (!response.ok || body.code !== 'OK') {
throw new Error(body.message || `HTTP ${response.status}`);
}
return body.data;
}
async function postJson(path, body) {
const response = await fetch(`${apiBase}${path}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body)
});
return readJsonResponse(response);
}
// files 是 [{ file: File, objectPath: 'robot.urdf' },
// { file: File, objectPath: 'meshes/base.stl' }, ...]。
// 目录选择时保留模型引用所需的相对目录,主文件只能有一个。
async function uploadModel(files) {
const path = '/admin-api/components/urdf-upload-sessions';
const session = await postJson(path);
const objectKeys = [];
for (const { file, objectPath } of files) {
const contentType = file.type || 'application/octet-stream';
const prepared = await postJson(`${path}/upload-url`, {
uploadSessionToken: session.uploadSessionToken,
objectPath,
contentType
});
const response = await fetch(prepared.uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': contentType },
body: file
});
if (response.status !== 204) {
// 失败通常为 JSON;如网关返回非 JSON,保留 HTTP 状态信息。
const error = await response.json().catch(() => ({}));
throw new Error(error.message || `上传失败,HTTP ${response.status}`);
}
objectKeys.push(prepared.objectKey);
}
return postJson(`${path}/complete`, {
uploadSessionToken: session.uploadSessionToken,
objectKeys
}); // { source: 'components/urdf/...' },随后保存组件
}
当前应用没有统一启用跨域配置。前端开发代理、网关入口或服务端跨域设置需与后端协调;上传 URL 和下载 URL 也应使用实际可访问的统一入口,不只代理列表接口。
8.3 保存带机械端口的组件
- 取得接口模板详情,记录
geometryRevision。 - 保存原始 URDF XML 快照,并为其引用的网格/纹理建立资源清单;资源先通过模型会话上传。
- 用 link 局部坐标中的实际几何调用
/pose-candidates。 - 用户选择候选后,携带候选 ID、对应修订和源哈希调用
/confirm-port。 - 将规范化端口加入
componentJson.interfaces;按照 2.9 处理多目标路径的输入格式。 - 将同一原始快照放入
componentJson.urdfSource,保存组件。接口定义或源文件改变后,重新执行识别和确认。
urdfSource 结构:
{
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
}
上例 URDF 只有一个根 link,没有网格/纹理引用,所以 resources 为空。实际模型每个 mesh/texture 的 filename 引用都必须有对应资源项:
{
"reference": "meshes/base.stl",
"sourceKey": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/meshes/base.stl",
"sha256": "<RESOURCE_BYTES_SHA256_HEX>"
}
哈希算法均为 UTF-8 文本或原始文件字节的 SHA-256,小写 64 位十六进制:
documentHash = SHA256(原始 XML 的 UTF-8 字节)
将 resources 按 reference 升序排序,构建 manifest:
reference + "\t" + sha256
多项之间使用 "\n",最后一项不附加换行
sourceGeometryHash = SHA256(documentHash + "\n" + manifest)
资源为空时仍计算 SHA256(documentHash + "\n")。不要格式化或修改 XML 后继续使用旧哈希。资源 sha256 必须根据真实字节计算,服务端会再次读取已上传对象验证。
urdfSource.xml 必须是合法 URDF:根节点为 robot,link/joint 名称不重复、父子 link 存在、没有环且只有一个根 link。端口 linkName 必须存在于该原始快照;每个端口的 sourceGeometryHash 必须等于 urdfSource.sourceGeometryHash。
注意区分三类哈希:STEP 分析返回 sourceSha256 是 STEP 文件哈希;接口定义的 sourceGeometryHash 是其绑定源文件哈希且通常带 sha256:;组件端口的 sourceGeometryHash 是上述 URDF 文档及资源清单哈希。三者不可直接互换。
9. 错误处理
前端同时检查 HTTP 状态与 JSON code。提示可使用 message,排查时带上 requestId。以下响应示例中的提示文字用于说明,字段结构与业务错误码以实际响应为准。
9.1 常见失败返回
重复手机号失败示例:HTTP 409
{
"code": "USER_PHONE_DUPLICATE",
"message": "手机号已存在,包括已删除的用户",
"requestId": "req-demo-001"
}
接口修订过期失败示例:HTTP 422
{
"code": "INVALID_INTERFACE",
"message": "接口已修改,请刷新后保存",
"requestId": "req-demo-001"
}
查询已删除用户失败示例:HTTP 404
{
"code": "USER_NOT_FOUND",
"message": "用户不存在",
"requestId": "req-demo-001"
}
| HTTP | code | 前端处理建议 |
|---|---|---|
| 422 | INVALID_REQUEST | 必填、字段长度、枚举、JSON 格式、参数类型或几何结构不合法,提示修改输入 |
| 422 | INVALID_INTERFACE | 接口不存在、ID 已占用/归档、修订过期或源文件绑定不合法;注意接口库“对象不存在”当前也可能返回此码 |
| 409 | USER_PHONE_DUPLICATE | 手机号冲突,已删除用户也会占用手机号 |
| 404 | USER_NOT_FOUND | 用户不存在或已删除 |
| 409 | COMPONENT_NAME_DUPLICATE | 组件名称重复 |
| 404 | COMPONENT_NOT_FOUND | 组件不存在 |
| 404 | OPERATION_LOG_NOT_FOUND | 日志不存在 |
| 422 | INVALID_COMPONENT_UPLOAD_SESSION / INVALID_COMPONENT_COVER_UPLOAD_SESSION | 上传会话过期、类型或操作人不匹配;重新创建对应类型会话 |
| 422 | INVALID_COMPONENT_UPLOAD_OBJECT | 对象路径、前缀、长度、重复 Key 或文件列表不合法 |
| 422 | COMPONENT_UPLOAD_OBJECT_MISSING | 文件尚未上传成功;检查 PUT 结果及提交 Key |
| 422 | COMPONENT_COVER_IMAGE_TYPE_INVALID / COMPONENT_COVER_IMAGE_KEY_TOO_LONG | 封面扩展名或 Key 长度不符合要求 |
| 422 | COMPONENT_MAIN_FILE_NOT_FOUND / COMPONENT_MAIN_FILE_NOT_UNIQUE / COMPONENT_MAIN_FILE_TYPE_CONFLICT / COMPONENT_MAIN_FILE_PATH_TOO_LONG | 模型主文件不存在、多个主文件、混合 URDF/RFS 或主文件路径过长 |
| 413 | INVALID_REQUEST | multipart 文件或整个请求超过大小限制 |
| 413 | INTERFACE_BREP_UPLOAD_TOO_LARGE / INTERFACE_BREP_OUTPUT_TOO_LARGE | STEP 输入/输出超过解析限制 |
| 422 | INTERFACE_BREP_INVALID_STEP | STEP 无法解析或精确拓扑不合法 |
| 503 | INTERFACE_BREP_UNAVAILABLE | 解析服务、脚本或 Python/OCP 依赖不可用,联系后端 |
| 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 | 存储连接、权限或读写失败,联系后端 |
| 404 | MINIO_OBJECT_NOT_FOUND | 资源对象不存在 |
| 422 | INVALID_STORAGE_OBJECT_KEY | 存储对象 Key 不合法 |
| 503 | DATABASE_UNAVAILABLE | 数据库连接不可用,联系后端 |
| 500 | INTERNAL_ERROR | 未分类系统异常,反馈 requestId |
| 404 | NOT_FOUND | 路由不存在,检查路径及前缀 |
下载失败或上传失败可能返回 JSON;网关错误也可能返回非 JSON。文件请求的错误处理应兼容这两种情况。
9.2 联调检查要点
- 创建、修改和删除成功是 HTTP 200,文件流上传成功是 HTTP 204;不要统一按 201 或统一解析 JSON。
- 接口库列表是数组,其余三个分页列表是
data.items。 - 保存组件使用 Key,展示模型/封面使用后端生成的 URL。
- 文件流上传使用 PUT 原始二进制;接口源文件及 STEP 分析使用 POST FormData。
- 会话令牌、对象 Key、源几何哈希、模板修订和候选姿态 ID 使用当前实际返回值。
- 用户删除是逻辑删除;组件删除是物理删除;接口删除保留历史且 ID 不能复用。
- 文件与端口保存失败时先展示错误提示,重新确认相关数据后重试,不自行补偿旋转或伪造哈希。