29 KiB
用户端组件匹配与拼装 API(前端联调文档)
本文说明前端如何提交拼装需求、展示匹配结果、切换替代组件及加载模型。示例编码和模型域名仅用于说明,实际结果取决于组件库。
文字、图片需求的解析、追问、用户确认和匹配流程见 需求解析与匹配联调文档,包含完整入参、SSE、确认和返回示例。本文中的 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 |
创建文字/图片需求会话,后续接口见上述联调文档 |
组件匹配和详情无需登录凭证;需求会话使用后端 HttpOnly Cookie 校验访客归属,前端需携带 Cookie。组件使用 componentCode 标识,不返回数据库 ID。模型通过响应中的公开 OSS/CDN 地址加载。
2. 请求与通用返回
POST 请求头:
Content-Type: application/json
X-Request-Id: frontend-match-001
X-Request-Id 可选,用于联调排查;省略时后端生成。响应头和响应体均返回请求编号。
{
"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 请求示例
只指定所需角色即可匹配:
{
"requiredParts": ["torso_0", "arm_r"]
}
包含关键词、整机条件和部件条件的请求:
{
"userInput": "我要一个双足跑步机器人,整体20自由度,质量不超过10kg,躯干用铝合金,右臂扭矩至少20N·m",
"requirements": ["双足", "机器人", "跑步"],
"requiredParts": [
"torso_0", "head_0", "waist_0", "arm_l", "arm_r", "hand_l", "hand_r",
"pedal_l", "pedal_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[] | 否 | 最多 12 项;每项对应一个角色的条件,字段见下表 |
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 字符;仅表示文本相关性 |
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 |
| 臂_l、臂_r | arm_l、arm_r |
| 手_l、手_r | hand_l、hand_r |
| 足_l、足_r | pedal_l、pedal_r |
| 脚_l、脚_r | foot_l、foot_r |
| 尾_0 | tail_0 |
输入接受中英文别名和英文大小写,响应返回标准编码。左右侧独立;pedal 对应足,foot 对应脚。
3.7 匹配结果的业务约定
先按角色查询未删除组件,再评价参数、材质和关键词。默认同义词包括跑步/奔跑/跑动/running、机器人/robot、双足/两足/biped/bipedal、铝合金/aluminum alloy/aluminium alloy。材质采用同义词归一化后的等值匹配,功能、形状和大小采用扩展后的包含匹配。名称、分类、功能、说明、材质、形状和大小参与关键词评价。
先选定需求评分最高的一个躯干:按躯干自身条件的未满足数量、数值差距、功能文本和关键词相关性评价;需求评分相同时优先所需接口覆盖,最后按编码稳定排序。整机自由度、质量总量在选定躯干后的组合中评价,不直接作为躯干单件目标。
默认方案始终只有一个躯干且以 torso_0 为根,未列出躯干时自动补入。后续只沿这个躯干的接口路径匹配其他部件,在固定躯干下优先覆盖所需部件,再评价整机条件。选中的躯干不会因为另一个躯干能接更多部件而自动替换。参数与材质可降级,角色和连接规则始终保持匹配;不自动加入其他未要求的中间连接件。
无法覆盖所有角色时返回躯干及可拼的连通部分;选中的躯干没有所需端口时可只返回躯干。没有可用躯干则返回 NO_MATCH,不会用其他角色作为根。躯干替代候选用于替换当前躯干,不追加第二个躯干。
整机自由度和质量按选中组件字段求和,不重复累加BOM,不从URDF再次计算。质量为0视为未填写;只要一个组件质量未知,totals.massKg=null、massComplete=false,已知部分保存在 knownMassKg。不能据此宣布满足质量上限。功能命中表示元数据相关,不代表动力学验证。
拼装候选必须有 URDF 主文件,且 urdfInfo 是包含非空 rootLink 和 frames 数组的对象。父帧的 interfaceType 对应子角色,连接到子组件的 rootLink。结果为无环连通组合,每个端口最多使用一次。异常端口会被忽略,前端应使用返回的 connections 完成拼装。
bomList 和 urdfInfo 始终作为原始 JSON 返回,保留嵌套内容;详情里的 urdfInfo 也可能是其他对象或数组。接口匹配只评价元数据和连接类型,不验证机械承载或运动性能。
4. 匹配结果
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 |
searchLimited |
boolean | 搜索是否达到候选/搜索限制;true 时仍可展示当前方案,但不代表已找到最优方案或证明组件库无解 |
| status | 含义 |
|---|---|
MATCHED |
所需角色完整,所有提供条件和关键词均满足 |
FALLBACK |
角色完整,部分条件或关键词不满足 |
PARTIAL |
返回连通部分,存在缺失角色;也可能有参数不满足 |
NO_MATCH |
没有可用装配候选,parts和connections为空;HTTP仍为200 |
searchLimited 与 status 独立,例如 MATCHED 也可能同时返回 searchLimited=true。数组无内容时返回 []。parts 的顺序不保证与请求一致,前端使用 category 和 componentCode 定位组件。
4.2 公开组件字段
parts[]、alternatives[].items[].component 和详情接口的 data 使用同一结构。
| 字段 | 类型 | 说明 |
|---|---|---|
componentCode |
string | 组件唯一编码,用于获取详情和区分组件 |
componentName |
string | 组件名称 |
category |
string | 组件角色;匹配结果使用标准英文编码 |
description |
string | 组件说明 |
material |
string | 材质 |
massKg |
number | 组件质量,单位 kg;0 表示未填写 |
degreesOfFreedom |
integer | 组件标称自由度 |
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 个角色的整机请求。组件库提供了躯干、默认右臂和一个兼容的替代右臂。
{
"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,
"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"
},
{
"componentCode": "CW-00000000000000000000000000000002",
"componentName": "右臂", "category": "arm_r", "description": "机器人右臂",
"material": "铝合金", "massKg": 1, "degreesOfFreedom": 4,
"functionDescription": "摆臂", "shape": "", "size": "", "torqueNm": 20,
"bomList": [{"code": "ACTUATOR", "quantity": 4}],
"urdfInfo": {"robotName": "arm", "rootLink": "ARM_BASE", "frames": []},
"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"
}
],
"connections": [{
"parentCategory": "torso_0", "parentComponentCode": "CW-00000000000000000000000000000001",
"parentLink": "BASE", "frameName": "J1", "childCategory": "arm_r",
"childComponentCode": "CW-00000000000000000000000000000002", "childRootLink": "ARM_BASE",
"xyz": [-0.1, 0.01, 0], "rpy": [0, -1.5707963267949, 0]
}],
"alternatives": [
{"category": "torso_0", "items": []},
{
"category": "arm_r",
"items": [
{
"component": {
"componentCode": "CW-00000000000000000000000000000003",
"componentName": "高扭矩右臂", "category": "arm_r", "description": "机器人右臂",
"material": "铝合金", "massKg": 1.2, "degreesOfFreedom": 4,
"functionDescription": "摆臂", "shape": "", "size": "", "torqueNm": 25,
"bomList": [{"code": "ACTUATOR-25", "quantity": 4, "spec": {"torqueNm": 25}}],
"urdfInfo": {"robotName": "arm_v2", "rootLink": "ARM_V2_BASE", "frames": []},
"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"
},
"connections": [{
"parentCategory": "torso_0", "parentComponentCode": "CW-00000000000000000000000000000001",
"parentLink": "BASE", "frameName": "J1", "childCategory": "arm_r",
"childComponentCode": "CW-00000000000000000000000000000003", "childRootLink": "ARM_V2_BASE",
"xyz": [-0.1, 0.01, 0], "rpy": [0, -1.5707963267949, 0]
}],
"totals": {"degreesOfFreedom": 4, "massKg": 3.2, "knownMassKg": 3.2, "massComplete": true},
"unmetRequirements": [],
"unmatchedKeywords": []
}
]
}
],
"totals": {"degreesOfFreedom": 4, "massKg": 3, "knownMassKg": 3, "massComplete": true},
"unmetRequirements": [], "unmatchedKeywords": [], "missingParts": [], "searchLimited": false
}
}
4.4 连接字段 connections[]
| 字段 | 类型 | 说明 |
|---|---|---|
parentCategory |
string | 父组件角色 |
parentComponentCode |
string | 父组件编码 |
parentLink |
string | 父组件模型内部的连接基准 link |
frameName |
string | 父组件用于安装的帧名称 |
childCategory |
string | 子组件角色 |
childComponentCode |
string | 子组件编码 |
childRootLink |
string | 子组件模型根 link |
xyz |
number[3] | 相对于父 parentLink 的平移 [x,y,z],单位米 |
rpy |
number[3] | 相对于父 parentLink 的旋转 [roll,pitch,yaw],单位弧度 |
位姿不是世界坐标。示例中将右臂的 ARM_BASE 对齐到躯干 BASE 下的给定位姿。不同组件的 link 名称可能相同,应在对应组件实例内查找。
4.5 替代候选 alternatives[]
| 字段 | 类型 | 说明 |
|---|---|---|
category |
string | 当前可替换的角色 |
items |
object[] | 0 至 5 个兼容替代项,空数组表示没有提供替代组件 |
items[].component |
object | 替代组件的完整公开数据,包括 BOM 和 URDF 信息 |
items[].connections |
object[] | 替换后的整套连接,不只是该部件的局部连接 |
items[].totals |
object | 替换后的整机汇总 |
items[].unmetRequirements |
object[] | 替换后的未满足条件 |
items[].unmatchedKeywords |
string[] | 替换后的未命中关键词 |
替代组件兼容当前父组件和全部当前子组件,保持当前父子拓扑;仍可能不满足用户的材质、数值或文本要求。替换父组件时连接位姿可能改变,替换子组件时根 link 可能改变。
前端选择一个替代项后,应按角色替换 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 |
有该角色的组件,但 URDF 文件或拼装信息不完整 |
NO_TORSO |
有该角色的可用候选,但没有可用躯干,不能形成整机方案 |
NO_COMPATIBLE_CONNECTION |
有候选组件,但未找到与当前组合兼容的连接 |
SEARCH_LIMIT |
达到搜索限制,本次未找到可加入的组件 |
4.8 降级示例:FALLBACK
请求要求能跑步、质量不超过 2 kg、右臂扭矩至少 30 N·m:
{
"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:
{
"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
}
前端可以展示模型,同时提示“已提供可拼装方案,部分要求未满足”,并列出质量、扭矩和功能差异。
4.9 缺件示例:PARTIAL
请求:
{
"requiredParts": ["torso_0", "head_0", "arm_r"]
}
例如仅返回躯干和右臂的连通组合,组件库没有头部。HTTP 200、code=OK,以下为 data 的状态字段片段,实际响应的 parts 包含这两个组件:
{
"status": "PARTIAL",
"rootCategory": "torso_0",
"totals": {"degreesOfFreedom": 4, "massKg": 3, "knownMassKg": 3, "massComplete": true},
"unmetRequirements": [],
"unmatchedKeywords": [],
"missingParts": [{"category": "head_0", "reason": "NO_COMPONENT"}],
"searchLimited": false
}
前端展示已返回的组件,并提示缺失头部;不能把这份汇总作为完整整机数据。
4.10 无可用组件示例:NO_MATCH
请求:
{
"requirements": ["跑步"],
"requiredParts": ["torso_0", "arm_r"]
}
例如这两个角色都没有可用组件,返回 HTTP 200。完整响应:
{
"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"},
{"category": "arm_r", "reason": "NO_COMPONENT"}
],
"searchLimited": false
}
}
前端展示“暂无可拼装组件”,结合 missingParts 提示原因。数据库故障属于接口错误,会返回 HTTP 503,不会返回此状态。
5. 组件详情
GET /api/components/{componentCode},无请求体。
| 路径参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
componentCode |
string | 是 | 组件编码,非空且最多 64 字符;使用匹配结果中的编码 |
请求示例:
GET /api/components/CW-00000000000000000000000000000001
X-Request-Id: frontend-detail-001
HTTP 200,完整响应示例:
{
"code": "OK",
"message": "success",
"requestId": "frontend-detail-001",
"data": {
"componentCode": "CW-00000000000000000000000000000001",
"componentName": "铝合金躯干",
"category": "torso_0",
"description": "机器人躯干",
"material": "铝合金",
"massKg": 2,
"degreesOfFreedom": 0,
"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:
{
"requiredParts": ["unknown_part"]
}
响应:
{
"code": "INVALID_MATCH_REQUEST",
"message": "不支持的组件角色",
"data": null,
"requestId": "frontend-invalid-001"
}
6.2 自由度类型错误:HTTP 422
请求中的自由度使用了字符串:
{
"requiredParts": ["arm_r"],
"robotRequirements": {"degreesOfFreedom": "20"}
}
响应:
{
"code": "INVALID_REQUEST",
"message": "请求体格式不合法,请检查字段类型和JSON结构",
"data": null,
"requestId": "frontend-invalid-002"
}
6.3 组件不存在:HTTP 404
请求 GET /api/components/CW-NOT-FOUND,响应:
{
"code": "COMPONENT_NOT_FOUND",
"message": "组件不存在",
"data": null,
"requestId": "frontend-detail-002"
}
6.4 数据库不可用:HTTP 503
{
"code": "DATABASE_UNAVAILABLE",
"message": "数据库暂不可用,请检查数据库连接配置后重试",
"data": null,
"requestId": "frontend-match-005"
}
错误时按 HTTP 状态和 code 判断,message 用于提示,不作为固定业务分支条件。排查时提供 requestId。
7. 前端拼装与模型加载
- 提交结构化匹配条件,读取
data.status;FALLBACK、PARTIAL仍可以展示已有模型,同时展示未满足条件和缺件。 - 使用
parts[].urdfUrl加载 URDF,用componentCode区分模型实例;需要 STEP 文件时使用stepUrl。空地址不发起文件请求。 - 从
rootCategory对应模型开始,按connections组装。在父组件实例内部查找parentLink,将子childRootLink对齐到给定局部xyz/rpy。不要假设连接数组已经按装配顺序排列。 - BOM 展示读取
bomList;关节、轴、限位等读取原始urdfInfo或已加载模型。不要重复累加 BOM 的质量和自由度。 - 选择替代组件后,按 4.5 同时更新组件、连接、汇总及未满足项。
模型资源由前端直接请求公开 OSS/CDN 地址,无需拼接 /api/components/{componentCode}/assets/... 路径,也不需要给模型地址附加管理员凭证。资源域名需允许前端源跨域读取 URDF 及 meshes,联调时由部署人员配置 OSS/CDN 的 GET/HEAD CORS。
URDF 相对 mesh 路径以主文件目录解析,保留服务器返回的完整目录。若文件使用 package://,前端 URDF 加载器需要配置对应 package 路径映射。STEP 格式解析和模型展示由前端加载器负责。
组件资源替换后应使用最新响应中的 URL。组件已删除时详情返回 404,但已有公开资源地址不保证立即失效;不要仅凭模型地址可访问就判断组件仍可使用。