Files
cadworld/cadworld-api/docs/api.md
T
2026-10-13 16:53:04 +08:00

29 KiB
Raw Blame History

用户端组件匹配与拼装 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. 前端拼装与模型加载

  1. 提交结构化匹配条件,读取 data.status;FALLBACK、PARTIAL 仍可以展示已有模型,同时展示未满足条件和缺件。
  2. 使用 parts[].urdfUrl 加载 URDF,用 componentCode 区分模型实例;需要 STEP 文件时使用 stepUrl。空地址不发起文件请求。
  3. 从 rootCategory 对应模型开始,按 connections 组装。在父组件实例内部查找 parentLink,将子 childRootLink 对齐到给定局部 xyz/rpy。不要假设连接数组已经按装配顺序排列。
  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,但已有公开资源地址不保证立即失效;不要仅凭模型地址可访问就判断组件仍可使用。