653 lines
30 KiB
Markdown
653 lines
30 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` | 创建文字/图片需求会话,后续接口见上述联调文档 |
|
||
|
||
组件匹配和详情无需登录凭证;需求会话使用后端 HttpOnly Cookie 校验访客归属,前端需携带 Cookie。组件使用 `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",
|
||
"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`。不能据此宣布满足质量上限。功能命中表示元数据相关,不代表动力学验证。
|
||
|
||
拼装候选必须同时有非空 `step_object_key` 和已上传的 URDF 主文件(非空 `urdf_main_object_key`),且 `urdfInfo` 是包含非空 `rootLink` 和 `frames` 数组的对象。仅上传 STEP 的组件可以查看详情,但不会进入默认方案或替代候选。父帧的 `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 | 组件标称自由度 |
|
||
| `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"
|
||
},
|
||
{
|
||
"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": []},
|
||
"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, "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": []},
|
||
"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:
|
||
|
||
```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
|
||
}
|
||
```
|
||
|
||
前端可以展示模型,同时提示“已提供可拼装方案,部分要求未满足”,并列出质量、扭矩和功能差异。
|
||
|
||
### 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"}],
|
||
"searchLimited": false
|
||
}
|
||
```
|
||
|
||
前端展示已返回的组件,并提示缺失头部;不能把这份汇总作为完整整机数据。
|
||
|
||
### 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"},
|
||
{"category": "arm_r", "reason": "NO_COMPONENT"}
|
||
],
|
||
"searchLimited": false
|
||
}
|
||
}
|
||
```
|
||
|
||
前端展示“暂无可拼装组件”,结合 `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,用 `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,但已有公开资源地址不保证立即失效;不要仅凭模型地址可访问就判断组件仍可使用。
|