Files
cadworld/cadworld-adminapi/docs/admin-api.md
T
2026-10-09 18:34:00 +08:00

3215 lines
91 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. [通用约定](#common)
2. [接口库管理](#interfaces)
3. [组件库管理及上传会话](#components)
4. [资源上传与下载](#assets)
5. [STEP 精确解析](#step)
6. [用户管理](#users)
7. [操作日志](#operation-logs)
8. [前端调用流程](#flows)
9. [错误处理](#errors)
<a id="common"></a>
## 1. 通用约定
### 1.1 请求及响应
JSON 请求使用 `Content-Type: application/json`。文件接口分别使用 multipart 或原始文件流,详见对应接口。除文件接口外,所有成功返回均为 HTTP `200`,创建也不使用 `201`。
请求可以携带 `X-Request-Id`。服务端会将其放入响应头及 JSON 的 `requestId`;不传时自动生成。建议用于排查联调错误。
```json
{
"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 分页与时间
```json
{
"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 节数据库操作日志的记录范围仍按原规则执行。
```text
接口开始 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`,用于关联运行日志和业务操作日志。
<a id="interfaces"></a>
## 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 查询接口列表
<!-- endpoint: GET /admin-api/interfaces -->
`GET /admin-api/interfaces`
| Query 参数 | 必填 | 说明 |
| --- | --- | --- |
| keyword | 否 | 按名称或描述模糊搜索;省略时返回全部,按更新时间倒序 |
**请求示例**
```http
GET /admin-api/interfaces?keyword=双孔 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 查询接口详情
<!-- endpoint: GET /admin-api/interfaces/{id} -->
`GET /admin-api/interfaces/{id}`
路径参数 `id`:接口定义字符串 ID。
**请求示例**
```http
GET /admin-api/interfaces/mount-2-hole HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 新增接口
<!-- endpoint: POST /admin-api/interfaces -->
`POST /admin-api/interfaces`
请求字段见 2.1。ID 不可与已有定义或已删除定义的历史 ID 重复。
**请求示例**
```http
POST /admin-api/interfaces HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
```
```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**
```json
{
"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 修改接口
<!-- endpoint: PUT /admin-api/interfaces/{id} -->
`PUT /admin-api/interfaces/{id}`
请求字段见 2.1,必须携带当前 `geometryRevision`,并提交完整定义。省略描述、目标或展示方向可能将其恢复为空值/默认值。
**请求示例**
```http
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
```
```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**
```json
{
"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 删除接口
<!-- endpoint: DELETE /admin-api/interfaces/{id} -->
`DELETE /admin-api/interfaces/{id}`
删除当前定义,保留历史快照。删除后的 ID 不可重新创建;删除接口不会清理存储中的源文件。
**请求示例**
```http
DELETE /admin-api/interfaces/mount-2-hole HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"code": "OK",
"message": "success",
"data": {
"success": true
},
"requestId": "req-demo-001"
}
```
### 2.7 上传并绑定接口源文件
<!-- endpoint: POST /admin-api/interfaces/{id}/assets -->
`POST /admin-api/interfaces/{id}/assets`
| 位置 | 字段 | 必填 | 说明 |
| --- | --- | --- | --- |
| Path | id | 是 | 已创建的接口定义 ID |
| Query | geometryRevision | 是 | 当前修订号 |
| multipart | file | 是 | 非空原始文件;通常为 STEP/STP |
先保存接口定义,再上传源文件。后端校验修订号,计算文件 SHA-256,并更新当前修订的源文件绑定。该接口本身不执行 STEP 解析或校验文件拓扑;需要精确解析时先调用第 5 节接口。
单个文件和整个 multipart 请求默认均限制 100 MB;边界开销也占请求大小。当前修订已有不同内容的源文件时,绑定会被拒绝,应按源文件变更流程先保存新修订。
**请求示例**
```bash
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**
```json
{
"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**
```json
{
"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 计算姿态候选
<!-- endpoint: POST /admin-api/interfaces/{id}/pose-candidates -->
`POST /admin-api/interfaces/{id}/pose-candidates`
| Body 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| definitionRevision | integer | 是 | 使用的模板修订号 |
| linkName | string | 是 | 端口所属原始 URDF link |
| geometryInLink | object | 是 | 实测安装面和完整孔组;与 `geometry` 结构一致,坐标位于该 link 的局部坐标系 |
| sourceGeometryHash | string | 是 | 原始 URDF 和资源清单形成的源几何哈希,算法见 8.3 |
**请求示例**
```http
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
```
```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**
```json
{
"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**
```json
{
"code": "OK",
"message": "success",
"data": {
"solverVersion": "mount-geometry-3",
"candidates": [],
"reasons": [
"孔 h1 的孔距组合与模板不符,请核对该孔及完整孔组",
"孔 h2 的孔距组合与模板不符,请核对该孔及完整孔组"
]
},
"requestId": "req-demo-001"
}
```
### 2.9 确认端口姿态
<!-- endpoint: POST /admin-api/interfaces/{id}/confirm-port -->
`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 | 否 | 不传或为空时使用模板目标;多目标建议采用二维路径数组,见下文 |
**请求示例**
```http
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
```
```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**
```json
{
"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` 会把一维字符串数组视为“一条级联路径”,例如 `["机械臂", "末端工具"]` 被合并为 `"机械臂/末端工具"`。多个目标请提交二维数组,例如 `[["机械臂", "末端工具"], ["移动底盘", "附件"]]`。返回统一为一维路径字符串数组。将确认结果用于保存组件时,多目标应先转换为二维数组,避免被合并为一条路径。
<a id="components"></a>
## 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 查询组件列表
<!-- endpoint: GET /admin-api/components -->
`GET /admin-api/components`
| Query 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| page | integer | 否 | 默认 1,请传正整数 |
| size | integer | 否 | 默认 20,上限 100,请传正整数 |
| keyword | string | 否 | 搜索组件名称、分类、标签和能力;当前不搜索厂商及型号 |
**请求示例**
```http
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**
```json
{
"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 查询组件详情
<!-- endpoint: GET /admin-api/components/{id} -->
`GET /admin-api/components/{id}`
路径参数 `id`:数值型组件 ID。
**请求示例**
```http
GET /admin-api/components/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 新增组件
<!-- endpoint: POST /admin-api/components -->
`POST /admin-api/components`
请求字段见 3.1。示例展示带已确认端口的完整保存结构;没有端口时可以将 `componentJson` 简化为 `{ "interfaces": [] }`。
**请求示例**
```http
POST /admin-api/components HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
```
```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**
```json
{
"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 修改组件
<!-- endpoint: PUT /admin-api/components/{id} -->
`PUT /admin-api/components/{id}`
请求字段同新增。使用完整必填字段;省略分类、封面和描述会将这些可选文本重置为空。
**请求示例**
```http
PUT /admin-api/components/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
```
```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**
```json
{
"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 删除组件
<!-- endpoint: DELETE /admin-api/components/{id} -->
`DELETE /admin-api/components/{id}`
物理删除组件及关联资源索引,不删除 MinIO 中已经上传的对象。
**请求示例**
```http
DELETE /admin-api/components/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 创建封面上传会话
<!-- endpoint: POST /admin-api/components/cover-image-upload-sessions -->
`POST /admin-api/components/cover-image-upload-sessions`
**请求示例**
```http
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**
```json
{
"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 获取封面文件上传地址
<!-- endpoint: POST /admin-api/components/cover-image-upload-sessions/upload-url -->
`POST /admin-api/components/cover-image-upload-sessions/upload-url`
| Body 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uploadSessionToken | string | 是 | 本类型创建会话的返回值 |
| objectPath | string | 是 | 当前会话中的相对文件路径 |
| contentType | string | 否 | 文件 MIME 类型,建议与实际 PUT 请求保持一致 |
**请求示例**
```http
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
```
```json
{
"uploadSessionToken": "<COVER_IMAGE_UPLOAD_SESSION_TOKEN>",
"objectPath": "cover.png",
"contentType": "image/png"
}
```
**成功返回示例:HTTP 200**
```json
{
"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 完成封面上传
<!-- endpoint: POST /admin-api/components/cover-image-upload-sessions/complete -->
`POST /admin-api/components/cover-image-upload-sessions/complete`
| Body 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uploadSessionToken | string | 是 | 创建会话返回值 |
| objectKeys | string[] | 是 | 已上传的完整对象 Key;必须恰好 1 个 |
封面扩展名支持 `.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`,不区分大小写。完成后将 `coverImageKey` 用于保存组件,`coverImageUrl` 用于预览。
**请求示例**
```http
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
```
```json
{
"uploadSessionToken": "<COVER_IMAGE_UPLOAD_SESSION_TOKEN>",
"objectKeys": [
"components/cover-images/0/20261009/22222222-2222-4222-8222-222222222222/cover.png"
]
}
```
**成功返回示例:HTTP 200**
```json
{
"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 上传会话
<!-- endpoint: POST /admin-api/components/urdf-upload-sessions -->
`POST /admin-api/components/urdf-upload-sessions`
**请求示例**
```http
POST /admin-api/components/urdf-upload-sessions HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 文件上传地址
<!-- endpoint: POST /admin-api/components/urdf-upload-sessions/upload-url -->
`POST /admin-api/components/urdf-upload-sessions/upload-url`
| Body 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uploadSessionToken | string | 是 | 本类型创建会话的返回值 |
| objectPath | string | 是 | 当前会话中的相对文件路径 |
| contentType | string | 否 | 文件 MIME 类型,建议与实际 PUT 请求保持一致 |
**请求示例**
```http
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
```
```json
{
"uploadSessionToken": "<URDF_UPLOAD_SESSION_TOKEN>",
"objectPath": "robot.urdf",
"contentType": "application/xml"
}
```
**成功返回示例:HTTP 200**
```json
{
"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 上传
<!-- endpoint: POST /admin-api/components/urdf-upload-sessions/complete -->
`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`,前端仍需根据模型准备保存数据。
**请求示例**
```http
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
```
```json
{
"uploadSessionToken": "<URDF_UPLOAD_SESSION_TOKEN>",
"objectKeys": [
"components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf"
]
}
```
**成功返回示例:HTTP 200**
```json
{
"code": "OK",
"message": "success",
"data": {
"source": "components/urdf/0/20261009/11111111-1111-4111-8111-111111111111/robot.urdf"
},
"requestId": "req-demo-001"
}
```
<a id="assets"></a>
## 4. 资源上传与下载
这些接口通过后台读写 MinIO,前端不需要 MinIO Access Key、Secret Key 或直连存储桶。
### 4.1 上传原始文件流
<!-- endpoint: PUT /admin-api/component-assets/upload -->
`PUT /admin-api/component-assets/upload`
| 位置 | 字段 | 必填 | 说明 |
| --- | --- | --- | --- |
| Query | objectKey | 是 | 获取上传地址返回的完整对象 Key;应直接使用返回的 `uploadUrl` |
| Header | Content-Type | 否 | 真实文件 MIME 类型;省略时按通用二进制类型处理 |
| Body | 文件二进制 | 是 | 直接发送 File/Blob/ArrayBuffer;不用 FormData,不做 JSON 或 Base64 包装 |
**请求示例**
```bash
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
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 下载或读取资源
<!-- endpoint: GET /admin-api/component-assets/{objectKey} -->
`GET /admin-api/component-assets/{objectKey}`
`objectKey` 表示包含多级 `/` 的完整对象路径,不只是最后一个文件名。通常直接使用组件详情返回的 `sourceUrl / coverImageUrl`。
**请求示例**
```http
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
HTTP/1.1 200 OK
Content-Type: application/xml
Cache-Control: public, max-age=3600
X-Request-Id: req-demo-001
```
图片等文件返回对应 MIME 类型和二进制内容,服务端在知道大小时返回 `Content-Length`。读取时使用 `text()`、`blob()` 或 `arrayBuffer()`,不要统一按 JSON 解析。资源不存在时返回 JSON 错误响应,例如 `404 / MINIO_OBJECT_NOT_FOUND`。
如需从 Key 手动拼路径,对每个路径段编码后用 `/` 连接;不要把整个带斜杠的路径当作一个普通路径段。
<a id="step"></a>
## 5. STEP 精确解析
### 5.1 分析 STEP/STP
<!-- endpoint: POST /admin-api/interface-brep/analyze -->
`POST /admin-api/interface-brep/analyze`
| 位置 | 字段 | 必填 | 说明 |
| --- | --- | --- | --- |
| multipart | file | 是 | 非空 `.step` 或 `.stp` 文件,扩展名不区分大小写;不接受 STL |
默认单文件及整个 multipart 请求上限均为 100 MB;默认解析超时 120 秒、输出上限 100 MB。该接口只返回解析数据,不创建接口定义,也不绑定或永久保存上传文件。
**请求示例**
```bash
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**
```json
{
"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;椭圆返回长短半径 |
不能从显示三角网格反推并保存精确接口;保存几何时应基于精确平面、孔轴及原始拓扑引用,并转换为米。该接口不记录业务操作日志。
<a id="users"></a>
## 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 查询用户列表
<!-- endpoint: GET /admin-api/users -->
`GET /admin-api/users`
| Query 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| page | integer | 否 | 默认 1,最小 1 |
| size | integer | 否 | 默认 20,最小 1,上限 100 |
| keyword | string | 否 | 手机号或昵称模糊匹配 |
| userType | string | 否 | NORMAL / ADMIN |
| status | string | 否 | ACTIVE / DISABLED |
**请求示例**
```http
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**
```json
{
"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 查询用户详情
<!-- endpoint: GET /admin-api/users/{id} -->
`GET /admin-api/users/{id}`
路径参数 `id`:用户数值 ID。
**请求示例**
```http
GET /admin-api/users/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 创建用户
<!-- endpoint: POST /admin-api/users -->
`POST /admin-api/users`
请求字段见 6.1。
**请求示例**
```http
POST /admin-api/users HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
```
```json
{
"phone": "13800000001",
"nickname": "示例用户",
"status": "ACTIVE",
"userType": "NORMAL"
}
```
**成功返回示例:HTTP 200**
```json
{
"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 修改用户
<!-- endpoint: PUT /admin-api/users/{id} -->
`PUT /admin-api/users/{id}`
请求字段见 6.1。
**请求示例**
```http
PUT /admin-api/users/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
Content-Type: application/json
```
```json
{
"phone": "13800000001",
"nickname": "示例管理员",
"status": "DISABLED",
"userType": "ADMIN"
}
```
**成功返回示例:HTTP 200**
```json
{
"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 逻辑删除用户
<!-- endpoint: DELETE /admin-api/users/{id} -->
`DELETE /admin-api/users/{id}`
删除后详情及列表都查不到该用户,但历史数据和手机号唯一约束仍保留;手机号不能分配给新用户。重复删除返回 `404 / USER_NOT_FOUND`。
**请求示例**
```http
DELETE /admin-api/users/1 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"code": "OK",
"message": "success",
"data": {
"success": true
},
"requestId": "req-demo-001"
}
```
用户管理操作不写入本文第 7 节的业务操作日志。
<a id="operation-logs"></a>
## 7. 操作日志
只读模块,提供列表和详情。记录组件库、接口库写操作的成功与失败;用户管理、查询、下载、STEP 分析、姿态候选及确认不产生该类业务日志。
业务日志保存失败不改变原接口结果;前端不要以“日志列表是否立即出现记录”作为写操作是否成功的判断依据。
| 动作值 | 含义 |
| --- | --- |
| CREATE | 新增组件或接口 |
| UPDATE | 修改组件或接口 |
| DELETE | 删除组件或接口 |
| PREPARE_UPLOAD | 创建上传会话 |
| PREPARE_UPLOAD_URL | 获取单文件上传地址 |
| UPLOAD | 资源文件上传或接口源文件上传 |
| COMPLETE_UPLOAD | 完成上传会话 |
### 7.1 查询操作日志列表
<!-- endpoint: GET /admin-api/operation-logs -->
`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` |
**请求示例**
```http
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**
```json
{
"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**
```json
{
"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 查询操作日志详情
<!-- endpoint: GET /admin-api/operation-logs/{id} -->
`GET /admin-api/operation-logs/{id}`
路径参数 `id`:数值型日志 ID。
**请求示例**
```http
GET /admin-api/operation-logs/14 HTTP/1.1
Host: 127.0.0.1:8992
X-Request-Id: req-demo-001
```
无请求体。
**成功返回示例:HTTP 200**
```json
{
"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 | 失败摘要;成功日志通常缺省 |
不提供日志新增、修改、删除接口;不返回请求体、文件内容、密钥或上传会话令牌。
<a id="flows"></a>
## 8. 前端调用流程
### 8.1 创建或编辑组件
1. 通过 URDF/RFS 会话上传模型及资源,完成上传后取得 `source`。
2. 如需封面,通过封面会话上传,完成后取得 `coverImageKey / coverImageUrl`。
3. 前端解析模型并准备 `componentJson`、`assemblyMetadata`;需要端口时执行 8.3。
4. 调用 `POST /admin-api/components` 或 `PUT /admin-api/components/{id}`。
5. 以后展示资源使用详情返回的 `sourceUrl / coverImageUrl`。
### 8.2 浏览器上传示例
以下以 URDF/RFS 会话为例;封面流程将会话路径替换为 `cover-image-upload-sessions`,完成结果字段使用 `coverImageKey`。
```javascript
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 保存带机械端口的组件
1. 取得接口模板详情,记录 `geometryRevision`。
2. 保存原始 URDF XML 快照,并为其引用的网格/纹理建立资源清单;资源先通过模型会话上传。
3. 用 link 局部坐标中的实际几何调用 `/pose-candidates`。
4. 用户选择候选后,携带候选 ID、对应修订和源哈希调用 `/confirm-port`。
5. 将规范化端口加入 `componentJson.interfaces`;按照 2.9 处理多目标路径的输入格式。
6. 将同一原始快照放入 `componentJson.urdfSource`,保存组件。接口定义或源文件改变后,重新执行识别和确认。
`urdfSource` 结构:
```json
{
"xml": "<robot name=\"demo\"><link name=\"base_link\"/></robot>",
"documentHash": "7fa86878484ac25bb466ba4f49e095caf6df3f3ab1a4234ee423a6aba6277a7a",
"resources": [],
"sourceGeometryHash": "d16fa71567b7e89283c4870161ba4be526a67622217f1c515d36a0573a20dc5f"
}
```
上例 URDF 只有一个根 link,没有网格/纹理引用,所以 `resources` 为空。实际模型每个 mesh/texture 的 `filename` 引用都必须有对应资源项:
```json
{
"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 位十六进制:
```text
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 文档及资源清单哈希。三者不可直接互换。
<a id="errors"></a>
## 9. 错误处理
前端同时检查 HTTP 状态与 JSON `code`。提示可使用 `message`,排查时带上 `requestId`。以下响应示例中的提示文字用于说明,字段结构与业务错误码以实际响应为准。
### 9.1 常见失败返回
**重复手机号失败示例:HTTP 409**
```json
{
"code": "USER_PHONE_DUPLICATE",
"message": "手机号已存在,包括已删除的用户",
"requestId": "req-demo-001"
}
```
**接口修订过期失败示例:HTTP 422**
```json
{
"code": "INVALID_INTERFACE",
"message": "接口已修改,请刷新后保存",
"requestId": "req-demo-001"
}
```
**查询已删除用户失败示例:HTTP 404**
```json
{
"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 不能复用。
- 文件与端口保存失败时先展示错误提示,重新确认相关数据后重试,不自行补偿旋转或伪造哈希。