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

91 KiB
Raw Blame History

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. 通用约定
  2. 接口库管理
  3. 组件库管理及上传会话
  4. 资源上传与下载
  5. STEP 精确解析
  6. 用户管理
  7. 操作日志
  8. 前端调用流程
  9. 错误处理

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 创建或编辑组件

  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。

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 结构:

{
  "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 不能复用。
  • 文件与端口保存失败时先展示错误提示,重新确认相关数据后重试,不自行补偿旋转或伪造哈希。