a3434d12d5
任一目标失败,保留原方案和有效需求,并保存新版本说明原因。 默认优先同型号配套,明确参数和单侧替换要求优先。 请求体不变,新增 match.change 返回替换结果,无需改表。
888 lines
38 KiB
Markdown
888 lines
38 KiB
Markdown
# 用户端组件匹配与拼装 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` 为根,未列出躯干时自动补入。后续只沿这个躯干的接口路径匹配其他部件,在固定躯干下优先覆盖所需部件,再评价整机条件。选中的躯干不会因为另一个躯干能接更多部件而自动替换。在明确需求和组件齐全优先的前提下,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 个角色的整机请求。组件库提供了躯干、默认右臂和一个兼容的替代右臂。
|
||
|
||
```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,但已有公开资源地址不保证立即失效;不要仅凭模型地址可访问就判断组件仍可使用。
|