Files
cadworld/cadworld-api/docs/api.md
T

886 lines
37 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.
# 用户端组件匹配与拼装 API(前端联调文档)
本文说明前端如何提交拼装需求、展示匹配结果、切换替代组件及加载模型。示例编码和模型域名仅用于说明,实际结果取决于组件库。
文字、图片需求的自动理解、选件及装配流程见 [自动生成机器人联调文档](robot-demand-api.md),消息完成事件直接返回 `match`,无需追问或确认。本文中的 `POST /api/robot-matches` 保留为直接提交结构化需求的接口,不调用模型;对话流程使用保存的完整分析,自动返回逐项校验及 `assembly.ready/blocked` 状态。
## 1. 接口总览
本地默认服务地址:`http://127.0.0.1:8991`。线上地址由部署环境提供。
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/robot-matches` | 按需求匹配组件,返回默认拼装方案和兼容替代组件 |
| GET | `/api/components/{componentCode}` | 按组件编码获取详情,包括 BOM、URDF 信息和模型地址 |
| POST | `/api/robot-conversations` | 创建文字/图片需求会话,后续接口见上述联调文档 |
所有 `/api/**` 业务接口均需要 Bearer Token,包括组件匹配和详情;先完成[邮箱与图片验证码登录](auth-api.md),请求头携带 `Authorization: Bearer <token>`。需求会话按登录用户隔离。组件使用 `componentCode` 标识,不返回数据库 ID。模型通过响应中的公开 OSS/CDN 地址加载。
新增组件编码格式为 `CW-` 加 16 位随机数字或大写字母(排除 `I/L/O/U`),总长 19,例如 `CW-7K3M9Q2R6V8X4T5N`。旧版 35 字符编码继续有效,以下部分示例保留旧编码。前端将编码视为不透明字符串,直接使用返回值查询和加载,不按固定长度截取或重组。
## 2. 请求与通用返回
POST 请求头:
```http
Content-Type: application/json
X-Request-Id: frontend-match-001
```
`X-Request-Id` 可选,用于联调排查;省略时后端生成。响应头和响应体均返回请求编号。
```json
{
"code": "OK",
"message": "success",
"data": {},
"requestId": "frontend-match-001"
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | `OK` 表示接口执行成功;其他值为错误编码 |
| `message` | string | 成功时为 `success`,失败时为错误说明 |
| `data` | object / null | 成功时为接口数据,失败时为 null |
| `requestId` | string | 请求编号,反馈问题时一并提供 |
**HTTP 200 和 `code=OK` 表示请求执行成功,拼装是否达标需要继续检查 `data.status`。** 没有匹配组件时也返回 HTTP 200;请求参数错误返回 422,详情组件不存在或已删除返回 404,数据库不可用返回 503。
## 3. 匹配接口
`POST /api/robot-matches`
### 3.1 请求示例
只指定所需角色即可匹配:
```json
{
"requiredParts": ["TORSO_0", "ARM_R"]
}
```
包含关键词、整机条件和部件条件的请求:
```json
{
"userInput": "我要一个双足跑步机器人,整体20自由度,质量不超过10kg,躯干用铝合金,右臂扭矩至少20N·m",
"requirements": ["双足", "机器人", "跑步"],
"requiredParts": [
"TORSO_0", "HEAD_0", "WAIST_0", "ARM_L", "ARM_R", "HAND_L", "HAND_R",
"LEG_L", "LEG_R", "FOOT_L", "FOOT_R"
],
"robotRequirements": {
"degreesOfFreedom": 20,
"functionDescription": "跑步",
"massKg": 10,
"operators": {"massKg": "lte"}
},
"partRequirements": [
{"category": "TORSO_0", "material": "铝合金"},
{"category": "ARM_R", "torqueNm": 20, "operators": {"torqueNm": "gte"}}
]
}
```
### 3.2 顶层入参
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userInput` | string | 否 | 最多 4000 字符,仅作上下文;后端不解析、不存储,也不覆盖结构化条件 |
| `requirements` | string[] | 否 | 最多 32 个关键词,每个非空且最多 128 字符;省略/null 表示无关键词要求 |
| `requiredParts` | string[] | 是 | 非空,最多 24 项;中英文别名归一化后去重,组件类型去重但支持同类型多个实例;未列出躯干时自动补入唯一 `TORSO_0` |
| `robotRequirements` | object | 否 | 整机条件,字段见下表 |
| `partRequirements` | object[] | 否 | 最多 16 项;每项对应一个角色的条件,字段见下表 |
`userInput` 中写出的条件不会自动生效,前端必须同时提供相应结构化字段。例如“质量不超过 10kg”需要传 `massKg: 10` 和 `operators.massKg: "lte"`。
### 3.3 整机条件 `robotRequirements`
所有字段均可选。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `degreesOfFreedom` | integer | 标称总自由度,非负整数 |
| `massKg` | number | 整机质量目标,单位 kg,非负 |
| `functionDescription` | string | 整机功能要求,最多 512 字符,例如“跑步” |
| `operators` | object | 数值比较方式,只支持已提供的 `degreesOfFreedom`、`massKg` |
### 3.4 部件条件 `partRequirements[]`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `category` | string | 是 | 组件角色,必须包含在 `requiredParts` 中(躯干固定补入);同一角色不能重复定义条件 |
| `componentName` | string | 否 | 组件名称,最多 128 字符;按名称及配置同义词匹配 |
| `description` | string | 否 | 描述关键词,最多 20000 字符;仅表示文本相关性 |
| `quantity` | integer | 否 | 1–24;仅接受JSON整数,省略/null表示按可匹配接口填充。躯干固定一个 |
| `material` | string | 否 | 材质,最多 128 字符,例如“铝合金” |
| `degreesOfFreedom` | integer | 否 | 该部件自由度,非负整数 |
| `massKg` | number | 否 | 该部件质量目标,单位 kg,非负 |
| `torqueNm` | number | 否 | 该部件扭矩目标,单位 N·m,非负 |
| `functionDescription` | string | 否 | 功能要求,最多 512 字符 |
| `shape` | string | 否 | 形状要求,最多 128 字符 |
| `size` | string | 否 | 大小描述要求,最多 128 字符,例如“中型”;不是数值尺寸比较 |
| `operators` | object | 否 | 数值比较方式,只支持已提供的 `degreesOfFreedom`、`massKg`、`torqueNm` |
### 3.5 数值、空值与运算符
可选条件省略或传 null 表示不约束该字段。字符串裁剪首尾空白,空字符串也表示不约束。显式传 `0` 表示要求数值为 0,与不传条件不同。
自由度只接受 0 至 2147483647 的 JSON 整数;`1.0`、`"1"`、布尔值和越界值均不合法。质量与扭矩使用 JSON 数值,最多 12 位整数、6 位小数。
| 运算符 | 含义 | 示例 |
| --- | --- | --- |
| `eq` | 等于,省略时的默认值 | `degreesOfFreedom: 20` 表示总自由度等于 20 |
| `gte` | 大于或等于 | `torqueNm: 20` 配合 `operators.torqueNm: "gte"` 表示至少 20 N·m |
| `lte` | 小于或等于 | `massKg: 10` 配合 `operators.massKg: "lte"` 表示不超过 10 kg |
`operators` 不能对应未提供目标值的字段,也不能用于文本字段。未知请求字段、非法角色、重复部件条件、负数和非法运算符均返回 HTTP 422。
材质按同义词归一化后的等值匹配;功能、形状、大小按文本包含关系匹配。这些条件都可能因找不到合适组件而放宽,实际差异见 `unmetRequirements`。
### 3.6 角色映射
| 中文类型 | 标准编码 |
| --- | --- |
| 躯干_0 | TORSO_0 |
| 头_0 | HEAD_0 |
| 腰_0 | WAIST_0 |
| 左臂 | ARM_L |
| 右臂 | ARM_R |
| 不分左右的臂 | ARM_0 |
| 左手 | HAND_L |
| 右手 | HAND_R |
| 不分左右的手 | HAND_0 |
| 左足(腿部) | LEG_L |
| 右足(腿部) | LEG_R |
| 不分左右的足(腿部) | LEG_0 |
| 左脚 | FOOT_L |
| 右脚 | FOOT_R |
| 不分左右的脚 | FOOT_0 |
| 尾_0 | TAIL_0 |
以上16类为完整组件类型,公开响应统一使用大写标准编码。输入兼容英文大小写和原有中文别名;旧 `pedal_l/pedal_r` 兼容为 `LEG_L/LEG_R`。左右侧、足与脚独立;L/R 互不替代,同部位的 0 类组件可承担 L/R 装配角色。
ARM、HAND、LEG、FOOT 的父接口采用单向兼容:L 可接 L/0,R 可接 R/0,0 只接 0,L/R 不能互接。除原始 child 完全相等外,仅允许上述标准 `LINK_部位_L/R`(方向位也支持小写 l/r)连接同前缀的 `_0`;其余字符须区分大小写完全一致,不放宽自定义接口编码或跨部位连接。
组件库分类及 URDF `interfaceType` 均按上述类型识别,候选查询兼容已有大小写分类和旧足部编码;`interfaceType` 缺失时也可从 `LINK_LEG_L/LINK_LEG_R` 等 child 识别目标类型。原始 `urdfInfo` 保持不变,连接按上述单向规则判断。实例编码使用大写装配角色,例如 `LEG_L:1` 的真实组件类别可以是 `LEG_0`。
### 3.7 匹配结果的业务约定
先按角色查询未删除组件,再评价参数、材质和关键词。默认同义词包括跑步/奔跑/跑动/running、机器人/robot、双足/两足/biped/bipedal、六足/六足机器人/六腿/六条腿/hexapod/hexapod robot、铝合金/aluminum alloy/aluminium alloy。材质采用同义词归一化后的等值匹配,功能、形状和大小采用扩展后的包含匹配。名称、分类、功能、说明、材质、形状和大小参与关键词评价;例如“六足机器人”可以命中说明“六足蜘蛛机器人躯干”。
先选定需求评分最高的一个躯干:按躯干自身条件的未满足数量、数值差距、功能文本和关键词相关性评价。关键词先比较命中的不同需求数量,再比较字段权重,避免名称中的泛称“机器人”压过说明中的“六足”等具体要求;需求评分相同时优先所需接口覆盖,最后按编码稳定排序。整机自由度、质量总量在选定躯干后的组合中评价,不直接作为躯干单件目标。组合在既有完整性、参数和整体关键词评分相同后,继续比较各实例的关键词相关性,使带有六足说明的足部候选优先于无相关说明的同接口候选。
默认方案始终只有一个躯干且以 `TORSO_0` 为根,未列出躯干时自动补入。后续只沿这个躯干的接口路径匹配其他部件,在固定躯干下优先覆盖所需部件,再评价整机条件。选中的躯干不会因为另一个躯干能接更多部件而自动替换。参数与材质可降级,角色和连接规则始终保持匹配;不自动加入其他未要求的中间连接件。
无法覆盖所有角色时返回躯干及可拼的连通部分;选中的躯干没有所需端口时可只返回躯干。没有可用躯干则返回 `NO_MATCH`,不会用其他角色作为根。躯干替代候选用于替换当前躯干,不追加第二个躯干。
整机自由度和质量按选中实例字段求和,同款组件的每个实例分别计入,**不重复累加BOM,不从URDF再次计算**。质量为0视为未填写;只要一个组件质量未知,`totals.massKg=null`、`massComplete=false`,已知部分保存在 `knownMassKg`。不能据此宣布满足质量上限。功能命中表示元数据相关,不代表动力学验证。
拼装候选必须同时有非空 STEP 和 URDF 主文件引用,仅上传 STEP 的组件仍只支持详情查询。接口以合法 interfaceType 决定目标 category,缺失/无效时从 child 的 LINK_ 后解析现有类别;双方 frames[].child 须非空并符合上述单向兼容规则,name 不参与判断。每个数组元素为独立接口,同child的多个接口不合并,连接双方各自只能占用一次。固定躯干后优先处理最近层级的接口,先满足所需类型和明确数量,再填充其余可匹配接口,不引入未要求的类型。自动增补不应破坏本可满足的硬要求;例如质量上限或指定总自由度会约束自动填充数量。坐标、安装基准、关节类型和rootLink不作为连接资格的阻塞条件,缺失接口则返回已有连通部分。
`bomList` 和 `urdfInfo` 始终作为原始 JSON 返回,保留嵌套内容;详情里的 `urdfInfo` 也可能是其他对象或数组。接口匹配只评价元数据和连接类型,不验证机械承载或运动性能。
## 4. 匹配结果
响应新增 `missingPartGroups`,每项为 `{family, categories, reason, expectedQuantity, actualQuantity, missingQuantity}`。它用于 AI 默认人形的部位合计缺口,例如 ARM 组允许 `ARM_L/ARM_R/ARM_0`、期望2个、实际1个、缺少1个;具体类别缺口仍放 `missingParts`。任一类缺口存在时为 `PARTIAL`,没有组件仍为 `NO_MATCH`。直接结构化请求不启用模板分组,`missingPartGroups` 返回 `[]`,也不接受 `templatePartGroups` 入参。
### 4.1 `data` 字段
| 字段 | 类型 | 内容 |
| --- | --- | --- |
| `status` | string | 匹配状态,见下表 |
| `rootCategory` | string / null | 有结果时固定为 `TORSO_0`;无结果时为 null |
| `parts` | object[] | 默认选中组件,字段见 4.2 |
| `connections` | object[] | 默认方案的整套父子连接,字段见 4.4 |
| `alternatives` | object[] | 每个已选角色一个分组,每组最多 5 个兼容替代组件,字段见 4.5 |
| `totals` | object | 默认方案的整机汇总,字段见 4.6 |
| `unmetRequirements` | object[] | 未满足的整机或部件条件,字段见 4.7 |
| `unmatchedKeywords` | string[] | 没有任何选中组件元数据命中的关键词 |
| `missingParts` | object[] | 未加入组合的角色和原因,字段见 4.7 |
| `missingPartGroups` | object[] | 后端模板部位合计缺口;直接结构化请求为 `[]` |
| `searchLimited` | boolean | 搜索是否达到候选/搜索限制;true 时仍可展示当前方案,但不代表已找到最优方案或证明组件库无解 |
| status | 含义 |
| --- | --- |
| `MATCHED` | 所需角色完整,所有提供条件和关键词均满足 |
| `FALLBACK` | 角色完整,部分条件或关键词不满足 |
| `PARTIAL` | 返回连通部分,存在缺失角色或模板部位合计数量不足;也可能有参数不满足 |
| `NO_MATCH` | 没有可用装配候选,parts和connections为空;HTTP仍为200 |
`searchLimited` 与 `status` 独立,例如 `MATCHED` 也可能同时返回 `searchLimited=true`。数组无内容时返回 `[]`。`parts` 的顺序不保证与请求一致,前端使用 `instanceId` 定位实例;`componentCode` 标识组件,`category` 是组件真实类别。
### 4.2 公开组件字段
`parts[]`、`alternatives[].items[].component` 和详情接口的 `data` 使用同一结构。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `componentCode` | string | 组件唯一编码,用于获取详情和区分组件 |
| `componentName` | string | 组件名称 |
| `category` | string | 组件真实类别,使用标准英文编码;可能与本次装配角色不同 |
| `description` | string | 组件说明 |
| `material` | string | 材质 |
| `massKg` | number | 组件质量,单位 kg;0 表示未填写 |
| `degreesOfFreedom` | integer | 组件标称自由度 |
| `rotationAxis` | string / null | 组件旋转轴,仅为 `X`、`Y`、`Z`;未设置时为 null,不替代 URDF 关节的 axis |
| `functionDescription` | string | 功能描述 |
| `shape` | string | 形状描述 |
| `size` | string | 大小描述 |
| `torqueNm` | number | 扭矩,单位 N·m |
| `bomList` | object / array | 原始 BOM JSON,内部结构由组件数据决定;允许 `{}`、`[]` 和嵌套内容 |
| `urdfInfo` | object / array | 原始 URDF 信息 JSON,保留完整 frames、axis、limits 等;匹配结果中为带 `rootLink`、`frames` 的对象 |
| `version` | integer | 组件数据版本号 |
| `stepUrl` | string | 公开 STEP 文件地址;没有文件时为空字符串 |
| `urdfUrl` | string | 公开 URDF 主文件地址;详情没有文件时为空字符串 |
两个 JSON 字段均直接作为对象或数组使用,无需再执行 `JSON.parse`。组件未填写的描述字段可能为空字符串。响应不包含数据库 ID、独立 OSS 对象键、目录前缀、内部文件清单或上传令牌。
### 4.3 完整成功响应示例
以下响应对应 3.1 的最小请求 `{"requiredParts":["TORSO_0","ARM_R"]}`,不是包含 11 个角色的整机请求。组件库提供了躯干、默认右臂和一个兼容的替代右臂。
```json
{
"code": "OK",
"message": "success",
"requestId": "example-request",
"data": {
"status": "MATCHED",
"rootCategory": "TORSO_0",
"parts": [
{
"componentCode": "CW-00000000000000000000000000000001",
"componentName": "铝合金躯干",
"category": "TORSO_0",
"description": "机器人躯干",
"material": "铝合金",
"massKg": 2,
"degreesOfFreedom": 0,
"rotationAxis": null,
"functionDescription": "支撑",
"shape": "宽躯干",
"size": "中型",
"torqueNm": 0,
"bomList": {
"items": [
{
"code": "BOLT-M4",
"quantity": 4
}
]
},
"urdfInfo": {
"robotName": "torso",
"rootLink": "BASE",
"frames": [
{
"name": "J1",
"kind": "joint",
"type": "fixed",
"parent": "BASE",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"originExplicit": true,
"xyz": [
-0.1,
0.01,
0
],
"rpy": [
0,
-1.5707963267949,
0
],
"axis": [
0,
0,
0
],
"limits": {}
}
]
},
"version": 1,
"stepUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000001/step/batch/model.STEP",
"urdfUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000001/urdf/batch/robot.urdf",
"instanceId": "TORSO_0:1"
},
{
"componentCode": "CW-00000000000000000000000000000002",
"componentName": "右臂",
"category": "ARM_R",
"description": "机器人右臂",
"material": "铝合金",
"massKg": 1,
"degreesOfFreedom": 4,
"rotationAxis": null,
"functionDescription": "摆臂",
"shape": "",
"size": "",
"torqueNm": 20,
"bomList": [
{
"code": "ACTUATOR",
"quantity": 4
}
],
"urdfInfo": {
"robotName": "arm",
"rootLink": "ARM_BASE",
"frames": [
{
"name": "INCOMING_arm_r",
"kind": "joint",
"type": "fixed",
"parent": "ARM_BASE",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"xyz": [
0,
0,
0
],
"rpy": [
0,
0,
0
]
}
]
},
"version": 1,
"stepUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000002/step/batch/model.STEP",
"urdfUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000002/urdf/batch/robot.urdf",
"instanceId": "ARM_R:1"
}
],
"connections": [
{
"parentCategory": "TORSO_0",
"parentComponentCode": "CW-00000000000000000000000000000001",
"parentLink": "BASE",
"frameName": "J1",
"childCategory": "ARM_R",
"childComponentCode": "CW-00000000000000000000000000000002",
"childRootLink": "ARM_BASE",
"parentInstanceId": "TORSO_0:1",
"childInstanceId": "ARM_R:1",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 0,
"childFrameIndex": 0
}
],
"alternatives": [
{
"category": "TORSO_0",
"items": [],
"instanceId": "TORSO_0:1"
},
{
"category": "ARM_R",
"items": [
{
"component": {
"componentCode": "CW-00000000000000000000000000000003",
"componentName": "高扭矩右臂",
"category": "ARM_R",
"description": "机器人右臂",
"material": "铝合金",
"massKg": 1.2,
"degreesOfFreedom": 4,
"rotationAxis": null,
"functionDescription": "摆臂",
"shape": "",
"size": "",
"torqueNm": 25,
"bomList": [
{
"code": "ACTUATOR-25",
"quantity": 4,
"spec": {
"torqueNm": 25
}
}
],
"urdfInfo": {
"robotName": "arm_v2",
"rootLink": "ARM_V2_BASE",
"frames": [
{
"name": "INCOMING_arm_r",
"kind": "joint",
"type": "fixed",
"parent": "ARM_V2_BASE",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"xyz": [
0,
0,
0
],
"rpy": [
0,
0,
0
]
}
]
},
"version": 1,
"stepUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000003/step/batch/model.STEP",
"urdfUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000003/urdf/batch/robot.urdf",
"instanceId": "ARM_R:1"
},
"connections": [
{
"parentCategory": "TORSO_0",
"parentComponentCode": "CW-00000000000000000000000000000001",
"parentLink": "BASE",
"frameName": "J1",
"childCategory": "ARM_R",
"childComponentCode": "CW-00000000000000000000000000000003",
"childRootLink": "ARM_V2_BASE",
"parentInstanceId": "TORSO_0:1",
"childInstanceId": "ARM_R:1",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 0,
"childFrameIndex": 0
}
],
"totals": {
"degreesOfFreedom": 4,
"massKg": 3.2,
"knownMassKg": 3.2,
"massComplete": true
},
"unmetRequirements": [],
"unmatchedKeywords": []
}
],
"instanceId": "ARM_R:1"
}
],
"totals": {
"degreesOfFreedom": 4,
"massKg": 3,
"knownMassKg": 3,
"massComplete": true
},
"unmetRequirements": [],
"unmatchedKeywords": [],
"missingParts": [],
"searchLimited": false,
"missingPartGroups": []
}
}
```
同款组件可重复出现在 parts 中,新增的 instanceId 在结果内唯一,例如 ARM_R:1、ARM_R:2。单次最多24个实例;数量或搜索达到上限时 searchLimited=true,仍返回已有组合。missingParts 增加 expectedQuantity、actualQuantity 和 missingQuantity,明确数量未达到时返回缺少的数量。默认方案及替代项均按实例累计质量和自由度。
0 组件承担指定侧时,按该侧需求评价参数和数量,每个实例只归属一个装配角色;部位分组和整机汇总均只计一次。`parts[].category` 和替代组件的 `category` 始终返回真实类别。候选继续按现有评分和编码排序,不额外优先同侧或中性组件。
### 4.4 连接字段 `connections[]`
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `parentInstanceId` / `childInstanceId` | string | 连接双方实例标识,格式为 装配角色:序号,序号从1开始 |
| `parentCategory` / `childCategory` | string | 双方本次装配角色,可能与组件真实 category 不同 |
| `parentComponentCode` / `childComponentCode` | string | 双方组件编码,同款可以在多个实例重复使用 |
| `interfaceChild` | string | 父接口原始 frames[].child;子接口 child 可以是同部位的 0 |
| `parentFrameIndex` / `childFrameIndex` | integer | 双方各自原始 frames 数组的零起始下标 |
| `frameName` | string | 父接口原始 name,仅用于辅助定位 |
| `parentLink` / `childRootLink` | string | 原始模型信息,缺失时可为空 |
本接口只返回连接关系,已移除连接摆放用 xyz/rpy,不计算矩阵。前端以双方实例标识和 frame 下标读取原始 urdfInfo,自行决定模型位置;不能假设双方 child 相等。同一 child 的多个接口以数组下标区分,前端不能按 child 或 componentCode 去重。
### 4.5 替代候选 `alternatives[]`
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `category` | string | 当前可替换实例的装配角色,替代组件真实类别可为同部位的 0 |
| `instanceId` | string | 当前可替换的单个实例 |
| `items` | object[] | 0 至 5 个兼容替代项,空数组表示没有提供替代组件 |
| `items[].component` | object | 替代组件的完整公开数据,包括 BOM 和 URDF 信息 |
| `items[].connections` | object[] | 替换后的**整套**连接,不只是该部件的局部连接 |
| `items[].totals` | object | 替换后的整机汇总 |
| `items[].unmetRequirements` | object[] | 替换后的未满足条件 |
| `items[].unmatchedKeywords` | string[] | 替换后的未命中关键词 |
替代组件兼容当前父组件和全部当前子组件,保持当前父子拓扑;仍可能不满足用户的材质、数值或文本要求。替换时重新匹配该实例关联的全部接口,双方 frame 下标或原始模型信息可能改变。
前端选择一个替代项后,应按 instanceId 替换 `parts` 中的单个实例,并整体采用该项的 `connections`、`totals`、`unmetRequirements` 和 `unmatchedKeywords`。上例替换右臂后,编码变为 `CW-00000000000000000000000000000003`,根 link 变为 `ARM_V2_BASE`,整机质量变为 3.2 kg。
替代项没有独立 `status`,可根据当前 `missingParts` 和替代项的未满足条件/关键词重新展示状态。这些替代项针对本次默认方案计算;多个角色的替代项不能直接任意组合。重新请求会生成新的默认方案,当前接口没有锁定已选编码或校验多部件替换的入参。
### 4.6 汇总 `totals`
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `degreesOfFreedom` | integer | 所选组件标称自由度之和 |
| `massKg` | number / null | 全部已选组件质量已知时的总质量;有未知质量时为 null |
| `knownMassKg` | number | 仅已知质量部分的合计 |
| `massComplete` | boolean | 是否所有已选组件质量均已填写;无组件时为 false |
`PARTIAL` 的汇总只覆盖已返回的组件。`massComplete=true` 表示这些组件的质量已知,不表示所需角色齐全。不要把组件 `massKg=0` 或汇总 `massKg=null` 展示成真实的零质量。
### 4.7 未满足条件和缺件
`unmetRequirements[]` 字段:
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `scope` | string | `PART` 表示部件条件,`ROBOT` 表示整机条件 |
| `category` | string / null | 部件标准角色;整机条件为 null |
| `field` | string | 未满足的请求字段,如 `torqueNm`、`massKg`、`material` |
| `operator` | string | 数值为 `eq/gte/lte`,材质为 `eq`,功能/形状/大小为 `contains` |
| `expected` | number / string | 用户要求的目标值 |
| `actual` | number / string / null | 实际值;未知质量或未命中的整机功能可为 null |
| `reason` | string | 原因,见下表 |
| `unmetRequirements.reason` | 展示含义 |
| --- | --- |
| `VALUE_MISMATCH` | 数值不满足目标 |
| `UNKNOWN_MASS` | 质量未填写,无法确认是否满足质量要求 |
| `NO_TEXT_MATCH` | 材质、功能、形状或大小未命中 |
`missingParts[]` 每项包含 `category`(缺失角色)和 `reason`(原因):
| `missingParts.reason` | 展示含义 |
| --- | --- |
| `NO_COMPONENT` | 组件库没有该角色的可用组件 |
| `INVALID_ASSEMBLY_METADATA` | 历史结果兼容原因;新流程不因位姿或安装基准缺失排除组件,缺少匹配接口使用 NO_COMPATIBLE_CONNECTION |
| `NO_TORSO` | 有该角色的可用候选,但没有可用躯干,不能形成整机方案 |
| `NO_COMPATIBLE_CONNECTION` | 有候选组件,但未找到与当前组合兼容的连接 |
| `SEARCH_LIMIT` | 达到搜索限制,本次未找到可加入的组件 |
### 4.8 降级示例:`FALLBACK`
请求要求能跑步、质量不超过 2 kg、右臂扭矩至少 30 N·m:
```json
{
"requirements": ["跑步"],
"requiredParts": ["TORSO_0", "ARM_R"],
"robotRequirements": {
"massKg": 2,
"functionDescription": "跑步",
"operators": {"massKg": "lte"}
},
"partRequirements": [
{"category": "ARM_R", "torqueNm": 30, "operators": {"torqueNm": "gte"}}
]
}
```
例如找到可拼装的完整组合,但合计 3.2 kg、右臂扭矩 25 N·m,且未命中跑步功能。HTTP 200、`code=OK`,下面仅展示 **`data` 的状态字段片段**;实际响应仍包含完整 `parts`、`connections` 和 `alternatives`:
```json
{
"status": "FALLBACK",
"rootCategory": "TORSO_0",
"totals": {
"degreesOfFreedom": 4,
"massKg": 3.2,
"knownMassKg": 3.2,
"massComplete": true
},
"unmetRequirements": [
{
"scope": "PART",
"category": "ARM_R",
"field": "torqueNm",
"operator": "gte",
"expected": 30,
"actual": 25,
"reason": "VALUE_MISMATCH"
},
{
"scope": "ROBOT",
"category": null,
"field": "massKg",
"operator": "lte",
"expected": 2,
"actual": 3.2,
"reason": "VALUE_MISMATCH"
},
{
"scope": "ROBOT",
"category": null,
"field": "functionDescription",
"operator": "contains",
"expected": "跑步",
"actual": null,
"reason": "NO_TEXT_MATCH"
}
],
"unmatchedKeywords": [
"跑步"
],
"missingParts": [],
"searchLimited": false,
"missingPartGroups": []
}
```
前端可以展示模型,同时提示“已提供可拼装方案,部分要求未满足”,并列出质量、扭矩和功能差异。
### 4.9 缺件示例:`PARTIAL`
请求:
```json
{
"requiredParts": ["TORSO_0", "HEAD_0", "ARM_R"]
}
```
例如仅返回躯干和右臂的连通组合,组件库没有头部。HTTP 200、`code=OK`,以下为 **`data` 的状态字段片段**,实际响应的 `parts` 包含这两个组件:
```json
{
"status": "PARTIAL",
"rootCategory": "TORSO_0",
"totals": {
"degreesOfFreedom": 4,
"massKg": 3,
"knownMassKg": 3,
"massComplete": true
},
"unmetRequirements": [],
"unmatchedKeywords": [],
"missingParts": [
{
"category": "HEAD_0",
"reason": "NO_COMPONENT",
"expectedQuantity": 1,
"actualQuantity": 0,
"missingQuantity": 1
}
],
"searchLimited": false,
"missingPartGroups": []
}
```
前端展示已返回的组件,并提示缺失头部;不能把这份汇总作为完整整机数据。
### 4.10 无可用组件示例:`NO_MATCH`
请求:
```json
{
"requirements": ["跑步"],
"requiredParts": ["TORSO_0", "ARM_R"]
}
```
例如这两个角色都没有可用组件,返回 HTTP 200。**完整响应**:
```json
{
"code": "OK",
"message": "success",
"requestId": "frontend-match-004",
"data": {
"status": "NO_MATCH",
"rootCategory": null,
"parts": [],
"connections": [],
"alternatives": [],
"totals": {
"degreesOfFreedom": 0,
"massKg": null,
"knownMassKg": 0,
"massComplete": false
},
"unmetRequirements": [],
"unmatchedKeywords": [
"跑步"
],
"missingParts": [
{
"category": "TORSO_0",
"reason": "NO_COMPONENT",
"expectedQuantity": 1,
"actualQuantity": 0,
"missingQuantity": 1
},
{
"category": "ARM_R",
"reason": "NO_COMPONENT",
"expectedQuantity": 1,
"actualQuantity": 0,
"missingQuantity": 1
}
],
"searchLimited": false,
"missingPartGroups": []
}
}
```
前端展示“暂无可拼装组件”,结合 `missingParts` 提示原因。数据库故障属于接口错误,会返回 HTTP 503,不会返回此状态。
## 5. 组件详情
`GET /api/components/{componentCode}`,无请求体。
| 路径参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `componentCode` | string | 是 | 组件编码,非空且最多 64 字符;使用匹配结果中的编码 |
请求示例:
```http
GET /api/components/CW-00000000000000000000000000000001
X-Request-Id: frontend-detail-001
```
HTTP 200,完整响应示例:
```json
{
"code": "OK",
"message": "success",
"requestId": "frontend-detail-001",
"data": {
"componentCode": "CW-00000000000000000000000000000001",
"componentName": "铝合金躯干",
"category": "TORSO_0",
"description": "机器人躯干",
"material": "铝合金",
"massKg": 2,
"degreesOfFreedom": 0,
"rotationAxis": null,
"functionDescription": "支撑",
"shape": "宽躯干",
"size": "中型",
"torqueNm": 0,
"bomList": {
"items": [{"code": "BOLT-M4", "quantity": 4}]
},
"urdfInfo": {
"robotName": "torso",
"rootLink": "BASE",
"frames": [
{
"name": "J1",
"kind": "joint",
"type": "fixed",
"parent": "BASE",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"originExplicit": true,
"xyz": [-0.1, 0.01, 0],
"rpy": [0, -1.5707963267949, 0],
"axis": [0, 0, 0],
"limits": {}
}
]
},
"version": 1,
"stepUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000001/step/batch/model.STEP",
"urdfUrl": "https://models.example.com/cadworld/components/CW-00000000000000000000000000000001/urdf/batch/robot.urdf"
}
}
```
返回字段见 4.2。详情可能返回不满足拼装要求的原始 `urdfInfo`,查看详情不表示该组件一定可以参与匹配。
## 6. 错误响应
| HTTP 状态 | `code` | 常见原因 |
| --- | --- | --- |
| 422 | `INVALID_REQUEST` | 必填项缺失、JSON 类型错误、未知字段、超长文本、负数、自由度小数或数值越界 |
| 422 | `INVALID_MATCH_REQUEST` | 不支持的角色、部件条件不属于所需角色、重复角色条件、非法运算符 |
| 404 | `COMPONENT_NOT_FOUND` | 详情编码不存在或组件已删除 |
| 503 | `DATABASE_UNAVAILABLE` | 数据库暂不可用 |
| 500 | `INTERNAL_ERROR` | 服务内部异常 |
### 6.1 非法角色:HTTP 422
请求 `POST /api/robot-matches`:
```json
{
"requiredParts": ["unknown_part"]
}
```
响应:
```json
{
"code": "INVALID_MATCH_REQUEST",
"message": "不支持的组件角色",
"data": null,
"requestId": "frontend-invalid-001"
}
```
### 6.2 自由度类型错误:HTTP 422
请求中的自由度使用了字符串:
```json
{
"requiredParts": ["ARM_R"],
"robotRequirements": {"degreesOfFreedom": "20"}
}
```
响应:
```json
{
"code": "INVALID_REQUEST",
"message": "请求体格式不合法,请检查字段类型和JSON结构",
"data": null,
"requestId": "frontend-invalid-002"
}
```
### 6.3 组件不存在:HTTP 404
请求 `GET /api/components/CW-NOT-FOUND`,响应:
```json
{
"code": "COMPONENT_NOT_FOUND",
"message": "组件不存在",
"data": null,
"requestId": "frontend-detail-002"
}
```
### 6.4 数据库不可用:HTTP 503
```json
{
"code": "DATABASE_UNAVAILABLE",
"message": "数据库暂不可用,请检查数据库连接配置后重试",
"data": null,
"requestId": "frontend-match-005"
}
```
错误时按 HTTP 状态和 `code` 判断,`message` 用于提示,不作为固定业务分支条件。排查时提供 `requestId`。
## 7. 前端拼装与模型加载
1. 提交结构化匹配条件,读取 `data.status`;`FALLBACK`、`PARTIAL` 仍可以展示已有模型,同时展示未满足条件和缺件。
2. 使用 `parts[].urdfUrl` 加载 URDF,用 `parts[].instanceId` 区分模型实例,组件编码可重复;需要 STEP 文件时使用 `stepUrl`。空地址不发起文件请求。
3. 从 `rootCategory` 对应模型开始,按 `connections` 组装。按双方 instanceId 与 frame 下标读取各自原始接口数据,由前端决定摆放。不要假设连接数组已经按装配顺序排列。
4. BOM 展示读取 `bomList`;关节、轴、限位等读取原始 `urdfInfo` 或已加载模型。不要重复累加 BOM 的质量和自由度。
5. 选择替代组件后,按 4.5 同时更新组件、连接、汇总及未满足项。
模型资源由前端直接请求公开 OSS/CDN 地址,无需拼接 `/api/components/{componentCode}/assets/...` 路径,也不需要给模型地址附加管理员凭证。资源域名需允许前端源跨域读取 URDF 及 meshes,联调时由部署人员配置 OSS/CDN 的 GET/HEAD CORS。
URDF 相对 mesh 路径以主文件目录解析,保留服务器返回的完整目录。若文件使用 `package://`,前端 URDF 加载器需要配置对应 package 路径映射。STEP 格式解析和模型展示由前端加载器负责。
组件资源替换后应使用最新响应中的 URL。组件已删除时详情返回 404,但已有公开资源地址不保证立即失效;不要仅凭模型地址可访问就判断组件仍可使用。