任一目标失败,保留原方案和有效需求,并保存新版本说明原因。 默认优先同型号配套,明确参数和单侧替换要求优先。 请求体不变,新增 match.change 返回替换结果,无需改表。
38 KiB
用户端组件匹配与拼装 API(前端联调文档)
本文说明前端如何提交拼装需求、展示匹配结果、切换替代组件及加载模型。示例编码和模型域名仅用于说明,实际结果取决于组件库。
文字、图片需求的自动理解、选件及装配流程见 自动生成机器人联调文档,消息完成事件直接返回 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,包括组件匹配和详情;先完成邮箱与图片验证码登录,请求头携带 Authorization: Bearer <token>。需求会话按登录用户隔离。组件使用 componentCode 标识,不返回数据库 ID。模型通过响应中的公开 OSS/CDN 地址加载。
新增组件编码格式为 CW- 加 16 位随机数字或大写字母(排除 I/L/O/U),总长 19,例如 CW-7K3M9Q2R6V8X4T5N。旧版 35 字符编码继续有效,以下部分示例保留旧编码。前端将编码视为不透明字符串,直接使用返回值查询和加载,不按固定长度截取或重组。
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",
"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 为根,未列出躯干时自动补入。后续只沿这个躯干的接口路径匹配其他部件,在固定躯干下优先覆盖所需部件,再评价整机条件。选中的躯干不会因为另一个躯干能接更多部件而自动替换。在明确需求和组件齐全优先的前提下,ARM/HAND/LEG/FOOT 同族实例优先选择名称可识别的同型号组件,型号一致性优先于普通关键词相关性;用户明确指定的参数和型号仍优先。参数与材质可降级,角色和连接规则始终保持匹配;不自动加入其他未要求的中间连接件。
无法覆盖所有角色时返回躯干及可拼的连通部分;选中的躯干没有所需端口时可只返回躯干。没有可用躯干则返回 NO_MATCH,不会用其他角色作为根。躯干替代候选用于替换当前躯干,不追加第二个躯干。
整机自由度和质量按选中实例字段求和,同款组件的每个实例分别计入,不重复累加BOM,不从URDF再次计算。质量为0视为未填写;只要一个组件质量未知,totals.massKg=null、massComplete=false,已知部分保存在 knownMassKg。不能据此宣布满足质量上限。功能命中表示元数据相关,不代表动力学验证。
拼装候选必须同时有非空 STEP 和 URDF 主文件引用,仅上传 STEP 的组件仍只支持详情查询。接口以合法 interfaceType 决定目标 category,缺失/无效时从 child 的 LINK_ 后解析现有类别;双方 frames[].child 须非空并符合上述单向兼容规则,name 不参与判断。每个数组元素为独立接口,同child的多个接口不合并,连接双方各自只能占用一次。固定躯干后优先处理最近层级的接口,先满足所需类型和明确数量,再填充其余可匹配接口,不引入未要求的类型。自动增补不应破坏本可满足的硬要求;例如质量上限或指定总自由度会约束自动填充数量。坐标、安装基准、关节类型和rootLink不作为连接资格的阻塞条件,缺失接口则返回已有连通部分。
候选还必须处于启用状态(status=ENABLED);禁用组件不会进入新拼装方案或替代候选。禁用不影响用户端按编码查看组件详情、历史生成结果或已保存项目。生成结果加载阶段发现组件已禁用时,沿用 409 / COMPONENT_REVISION_CONFLICT,需要重新匹配。
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 个角色的整机请求。组件库提供了躯干、默认右臂和一个兼容的替代右臂。
{
"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:
{
"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,
"missingPartGroups": []
}
前端可以展示模型,同时提示“已提供可拼装方案,部分要求未满足”,并列出质量、扭矩和功能差异。
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",
"expectedQuantity": 1,
"actualQuantity": 0,
"missingQuantity": 1
}
],
"searchLimited": false,
"missingPartGroups": []
}
前端展示已返回的组件,并提示缺失头部;不能把这份汇总作为完整整机数据。
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",
"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 字符;使用匹配结果中的编码 |
请求示例:
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,
"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:
{
"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,用parts[].instanceId区分模型实例,组件编码可重复;需要 STEP 文件时使用stepUrl。空地址不发起文件请求。 - 从
rootCategory对应模型开始,按connections组装。按双方 instanceId 与 frame 下标读取各自原始接口数据,由前端决定摆放。不要假设连接数组已经按装配顺序排列。 - 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,但已有公开资源地址不保证立即失效;不要仅凭模型地址可访问就判断组件仍可使用。