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

30 KiB
Raw Blame History

文字 / 图片需求解析与组件匹配(前端联调)

服务地址默认 http://127.0.0.1:8991。本流程接收用户文字、图片,返回可核对的需求;用户确认后再匹配组件。所有 JSON 接口和 SSE 事件数据沿用 {code, message, data, requestId}。

1. 前端调用顺序

  1. 创建会话,保存 conversationId。
  2. 有图片时先上传到该会话,保存 attachmentId;仅文字可跳过。
  3. 发送消息,使用 POST + fetch 接收 SSE。
  4. 收到 analysis.completed:needs_clarification 时展示追问,用户在同一会话发送新消息;ready 时展示摘要、详细需求及来源,请用户确认。
  5. 确认时只提交 analysisId、revision 和 confirmed:true,不回传或修改解析 JSON。
  6. 后端先固定最符合要求的一个躯干,再沿其接口匹配其他组件;前端展示组件、逐项校验和装配诊断。需要降级时让用户主动接受;只有 assembly.status=ready 才能应用后端连接位姿。

浏览器需要保留后端设置的 HttpOnly Cookie,所有调用均设置 credentials:"include"。不需要读写 Cookie 值,也不传 userId、模型 Key 或系统提示词。当前按匿名浏览器访客隔离对话和图片,清除 Cookie 后不能访问之前记录。生产使用 HTTPS;前后端通过同站点 /api 代理接入。开发跨端口需后端配置具体允许域名,并使用一致的主机名(不要混用 localhost 与 127.0.0.1)。

接口清单

方法 路径 请求 返回
POST /api/robot-conversations 无请求体 会话编码、初始版本、有效期
POST /api/robot-conversations/{conversationId}/attachments multipart file 图片编码、预览地址
GET /api/robot-conversations/{conversationId}/attachments/{attachmentId} 无 私有原图,需要 Cookie
POST /api/robot-conversations/{conversationId}/messages 消息 JSON SSE 解析阶段与完整结果
GET /api/robot-analyses/{analysisId} 无 当前解析状态及结果
POST /api/robot-analyses/{analysisId}/retry 无请求体 SSE,仅重试失败或停止的当前版本
DELETE /api/robot-analyses/{analysisId} 无 停止后的解析状态
POST /api/robot-analyses/{analysisId}/confirm 确认 JSON 匹配结果,重复确认返回同一结果
POST /api/robot-analyses/{analysisId}/rematch 确认 JSON 使用保存的需求重新匹配,不重新调用模型
GET /api/robot-demand-matches/{matchId} 无 保存的匹配结果
POST /api/robot-demand-matches/{matchId}/accept-degradation 接受 JSON 原方案及更新后的装配阻塞状态

既有结构化 POST /api/robot-matches 和公开组件详情保留,见 组件接口文档。本流程的状态为小写,与既有接口的 MATCHED/FALLBACK/PARTIAL/NO_MATCH 分开使用。

2. 创建会话与上传图片

POST /api/robot-conversations,无请求体。返回示例:

{
  "code": "OK",
  "message": "success",
  "data": {
    "conversationId": "DC-11111111111111111111111111111111",
    "revision": 0,
    "expiresAt": "2026-10-20T02:00:00Z"
  },
  "requestId": "frontend-demand-001"
}

会话默认最近一条新用户消息后 7 天过期,过期后返回 404。conversationId 等名称中的 Id 都是业务编码,不是数据库主键。

上传:POST /api/robot-conversations/{conversationId}/attachments,multipart/form-data,字段名 file。每次上传一张 PNG/JPEG/WebP,每张最大 8MiB。浏览器传 FormData,不要手动填写 multipart Content-Type。

{
  "code": "OK",
  "message": "success",
  "data": {
    "attachmentId": "DA-44444444444444444444444444444444",
    "mimeType": "image/png",
    "sizeBytes": 12450,
    "previewUrl": "/api/robot-conversations/DC-11111111111111111111111111111111/attachments/DA-44444444444444444444444444444444"
  },
  "requestId": "frontend-demand-001"
}

图片仅能用于所属会话,一个附件只能绑定一条新消息。重复发送同一 messageId 无需重复上传;后续图片消息请重新上传附件。原图可用返回的 previewUrl 展示,仍需携带 Cookie。

3. 发送消息与追问

POST /api/robot-conversations/{conversationId}/messages,请求示例:

{
  "messageId": "m1",
  "text": "我要一个右臂,扭矩至少20N·m",
  "attachmentIds": []
}

图文消息示例:

{
  "messageId": "m2",
  "text": "以草图为参考,右臂扭矩至少20N·m",
  "attachmentIds": [
    "DA-44444444444444444444444444444444"
  ]
}
字段 类型 必填 限制
messageId string 是 1–80 位字母、数字、下划线、短横线;同一会话内保持唯一;网络重发使用原编号
text string 是 最多 20000 字符;仅图片时传空字符串
attachmentIds string[] 否 最多 4 张,不重复;省略/null 表示无图

文字和图片不能同时为空。相同编号但不同内容返回 409。历史由后端保存,不传 role、messages、客户端解析结果。最多 40 条历史消息(含后端追问);图片原始字节总量最多 30MiB,编码后的模型请求最多 40MiB;超限时新建会话。

SSE 事件

事件 data 内容 前端处理
analysis.progress {analysisId, revision, stage, message} 更新阶段提示,记录解析编码和版本
analysis.completed 完整 AnalysisView,见后文 展示追问或用户确认页
analysis.failed code 为错误码,data=null 停止加载,按错误码显示重试入口
心跳注释 无 JSON 数据 忽略

阶段依次为 validating_input、analyzing_requirements、validating_result。阶段提示不是模型逐字输出,不用于计算完成百分比。只有完整结果校验并保存后才发送完成事件。

事件格式示例:

event:analysis.progress
data:{"code":"OK","message":"success","data":{"analysisId":"DN-22222222222222222222222222222222","revision":1,"stage":"analyzing_requirements","message":"正在分析需求"},"requestId":"frontend-demand-001"}

使用 fetch 接收 POST SSE(EventSource 不支持 POST):

async function sendMessage(conversationId, message, onEvent, signal) {
  const response = await fetch(`/api/robot-conversations/${conversationId}/messages`, {
    method: "POST",
    credentials: "include",
    headers: { "Content-Type": "application/json", "Accept": "text/event-stream" },
    body: JSON.stringify(message),
    signal
  });
  if (!response.ok) throw await response.json();
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  function consume() {
    let end;
    while ((end = buffer.indexOf("\n\n")) >= 0) {
      const block = buffer.slice(0, end);
      buffer = buffer.slice(end + 2);
      let event = "message";
      const lines = [];
      for (const line of block.split("\n")) {
        if (line.startsWith("event:")) event = line.slice(6).trim();
        if (line.startsWith("data:")) lines.push(line.slice(5).trimStart());
      }
      if (lines.length) onEvent(event, JSON.parse(lines.join("\n")));
    }
  }
  try {
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      consume();
    }
    buffer += decoder.decode();
    consume();
  } finally {
    reader.releaseLock();
  }
}

后端发送 LF 分隔的事件,网络读取可能把一个事件拆成多块,需保留 buffer。主动停止调用 DELETE;断开全部订阅也会停止尚未完成的解析。连接中断后先 GET 查询状态,再决定 retry,不要凭连接关闭判断成功。SSE 开始前的校验错误使用 HTTP 错误响应;开始后模型失败通过 analysis.failed 通知。

完整解析返回示例

analysis.completed 和 GET /api/robot-analyses/{analysisId} 使用同一数据结构:

{
  "code": "OK",
  "message": "success",
  "data": {
    "analysisId": "DN-22222222222222222222222222222222",
    "conversationId": "DC-11111111111111111111111111111111",
    "revision": 1,
    "status": "ready",
    "canSubmit": true,
    "summary": "右臂扭矩至少20N·m",
    "questions": [],
    "warnings": [
      "整机拼装固定一个躯干,已补入torso_0作为基础组件。"
    ],
    "result": {
      "request": {
        "userInput": "我要一个右臂,扭矩至少20N·m",
        "requirements": [
          "右臂"
        ],
        "requiredParts": [
          "torso_0",
          "arm_r"
        ],
        "robotRequirements": {},
        "partRequirements": [
          {
            "category": "arm_r",
            "torqueNm": 20,
            "operators": {
              "torqueNm": "gte"
            }
          }
        ]
      },
      "analysis": {
        "summary": "右臂扭矩至少20N·m",
        "keywords": [
          {
            "term": "右臂",
            "source": "explicit",
            "reason": "用户指定部件",
            "negated": false,
            "evidence": "我要一个右臂,扭矩至少20N·m"
          }
        ],
        "robotTypes": [],
        "partCategories": [
          {
            "category": "arm_r",
            "source": "explicit",
            "reason": "用户指定部件",
            "evidence": "我要一个右臂,扭矩至少20N·m"
          }
        ],
        "excludedCategories": [],
        "unmodeled": [],
        "constraints": [
          {
            "scope": "part",
            "categories": [
              "arm_r"
            ],
            "field": "torqueNm",
            "value": "20N·m",
            "upperValue": "",
            "operator": "gte",
            "evidence": "我要一个右臂,扭矩至少20N·m"
          }
        ],
        "questions": [],
        "warnings": [
          "整机拼装固定一个躯干,已补入torso_0作为基础组件。"
        ],
        "catalogVersion": "2026-10-13-draft",
        "observations": [
          {
            "id": "e1",
            "messageId": "m1",
            "imageId": "",
            "kind": "user_text",
            "content": "我要一个右臂,扭矩至少20N·m",
            "clarity": "clear",
            "region": []
          }
        ],
        "intentItems": [
          {
            "id": "r1",
            "dimension": "performance",
            "subject": "右臂",
            "requirement": "扭矩至少20N·m",
            "priority": "must",
            "source": "explicit",
            "evidenceIds": [
              "e1"
            ],
            "evidence": "我要一个右臂,扭矩至少20N·m"
          }
        ],
        "images": [],
        "keywordEvidence": [
          {
            "term": "右臂",
            "evidenceIds": [
              "e1"
            ]
          }
        ],
        "schemaVersion": "multimodal-v1.1",
        "canSubmit": true,
        "status": "ready"
      }
    }
  },
  "requestId": "frontend-demand-001"
}
字段 说明
status processing / ready / needs_clarification / failed / cancelled / superseded
canSubmit 为 true 时可展示确认按钮;不表示已匹配、已达标或可装配
questions 本轮最多展示 5 个追问;用户回答作为同一会话的新消息提交
warnings 来源、推断或能力承载方面的说明,供核对
result.request 规范化五字段需求;未提供的约束不会补成 0
result.analysis.intentItems 逐项需求,must 硬要求、prefer 偏好、context 参考;用于确认界面
result.analysis.observations 用户原文 / 图片 OCR / 视觉描述及所属消息、图片
result.analysis.images 图片类型、用途和不确定点;不包含图片数据
evidenceIds 关联 observation 的编码;region=[] 表示无可靠定位框

ready 与 needs_clarification 返回 result;其他状态 result=null、canSubmit=false。图像视觉推断只保留参考,不自动成为确定尺寸、材质、数值或能力。展示整机功能“跑步”等时应标明文本相关性,不能据此展示真实能力已验证。

追问场景:用户说“右臂扭矩至少30”缺单位时,状态为 needs_clarification;前端展示问题并发送新消息 {messageId:"m2", text:"单位是N·m", attachmentIds:[]}。新解析版本递增为 2;旧版本变为 superseded,旧确认按钮失效。禁止直接修改 result.request 后调用旧匹配接口冒充已确认需求。

4. 确认与匹配

POST /api/robot-analyses/{analysisId}/confirm:

{
  "revision": 1,
  "confirmed": true
}

两个字段均必填,revision 必须等于当前解析版本,confirmed 必须为 true。相同版本重复确认返回保存的同一 matchId;新消息使旧确认返回 409。

以下请求只指定右臂,后端补入一个躯干作为装配根。完整返回包含躯干和右臂,编码与资源域名均为演示值:

{
  "code": "OK",
  "message": "success",
  "data": {
    "analysisId": "DN-22222222222222222222222222222222",
    "revision": 1,
    "matchId": "DM-33333333333333333333333333333333",
    "status": "complete",
    "rootCategory": "torso_0",
    "searchLimited": false,
    "degradationAcceptanceRequired": false,
    "degradationAccepted": false,
    "totals": {
      "degreesOfFreedom": 4,
      "massKg": 3.2,
      "knownMassKg": 3.2,
      "massComplete": true
    },
    "unmetRequirements": [],
    "unmatchedKeywords": [],
    "missingParts": [],
    "requirementChecks": [
      {
        "intentId": "r1",
        "priority": "must",
        "status": "satisfied",
        "field": "torqueNm",
        "expected": 20,
        "actual": 25,
        "reason": "所选组件的登记参数满足该条件"
      }
    ],
    "assembly": {
      "status": "ready",
      "rootInstanceId": "DM-33333333333333333333333333333333:torso_0",
      "matrixLayout": "column-major",
      "connections": [
        {
          "parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
          "parentFrame": "J_ARM",
          "parentLink": "BASE",
          "childInstanceId": "DM-33333333333333333333333333333333:arm_r",
          "childFrame": "ARM_ROOT",
          "childRootLink": "ARM_ROOT",
          "parentRootToInterface": [
            1,
            0,
            0,
            0,
            0,
            1,
            0,
            0,
            0,
            0,
            1,
            0,
            0.1,
            0,
            0,
            1
          ],
          "childRootToInterface": [
            1,
            0,
            0,
            0,
            0,
            1,
            0,
            0,
            0,
            0,
            1,
            0,
            0,
            0,
            0,
            1
          ],
          "childRootRelativeToParentRoot": [
            1,
            0,
            0,
            0,
            0,
            1,
            0,
            0,
            0,
            0,
            1,
            0,
            0.1,
            0,
            0,
            1
          ]
        }
      ],
      "issues": []
    },
    "components": [
      {
        "instanceId": "DM-33333333333333333333333333333333:torso_0",
        "component": {
          "componentCode": "CW-TORSO-001",
          "componentName": "铝合金躯干",
          "category": "torso_0",
          "description": "机器人躯干",
          "material": "铝合金",
          "massKg": 2,
          "degreesOfFreedom": 0,
          "functionDescription": "支撑",
          "shape": "宽躯干",
          "size": "中型",
          "torqueNm": 0,
          "bomList": [
            {
              "partCode": "FRAME-01",
              "quantity": 1
            }
          ],
          "urdfInfo": {
            "robotName": "躯干",
            "rootLink": "BASE",
            "frames": [
              {
                "name": "J_ARM",
                "kind": "joint",
                "type": "fixed",
                "parent": "BASE",
                "child": "LINK_arm_r",
                "interfaceType": "arm_r",
                "originExplicit": true,
                "xyz": [
                  0.1,
                  0,
                  0
                ],
                "rpy": [
                  0,
                  0,
                  0
                ],
                "axis": [
                  0,
                  0,
                  0
                ],
                "limits": {}
              }
            ]
          },
          "version": 1,
          "stepUrl": "https://models.example.com/cadworld/components/CW-TORSO-001/step/batch-a/torso.step",
          "urdfUrl": "https://models.example.com/cadworld/components/CW-TORSO-001/urdf/batch-a/robot.urdf"
        },
        "urdfMainPath": "robot.urdf",
        "resources": [
          {
            "relativePath": "robot.urdf",
            "url": "https://models.example.com/cadworld/components/CW-TORSO-001/urdf/batch-a/robot.urdf",
            "version": 1,
            "expiresAt": null
          },
          {
            "relativePath": "meshes/torso.stl",
            "url": "https://models.example.com/cadworld/components/CW-TORSO-001/urdf/batch-a/meshes/torso.stl",
            "version": 1,
            "expiresAt": null
          }
        ],
        "resourceIssues": []
      },
      {
        "instanceId": "DM-33333333333333333333333333333333:arm_r",
        "component": {
          "componentCode": "CW-ARM-001",
          "componentName": "标准右臂",
          "category": "arm_r",
          "description": "机器人右臂",
          "material": "铝合金",
          "massKg": 1.2,
          "degreesOfFreedom": 4,
          "functionDescription": "抓取",
          "shape": "长条",
          "size": "小型",
          "torqueNm": 25,
          "bomList": {
            "parts": [
              {
                "partCode": "MOTOR-01",
                "quantity": 4,
                "specification": {
                  "ratedTorqueNm": 25
                }
              }
            ]
          },
          "urdfInfo": {
            "robotName": "右臂",
            "rootLink": "ARM_ROOT",
            "frames": [],
            "assembly": {
              "mountingFrame": "ARM_ROOT",
              "pairingConvention": "coincident_frames"
            }
          },
          "version": 2,
          "stepUrl": "https://models.example.com/cadworld/components/CW-ARM-001/step/batch-a/arm.step",
          "urdfUrl": "https://models.example.com/cadworld/components/CW-ARM-001/urdf/batch-a/robot.urdf"
        },
        "urdfMainPath": "robot.urdf",
        "resources": [
          {
            "relativePath": "robot.urdf",
            "url": "https://models.example.com/cadworld/components/CW-ARM-001/urdf/batch-a/robot.urdf",
            "version": 2,
            "expiresAt": null
          },
          {
            "relativePath": "meshes/arm.stl",
            "url": "https://models.example.com/cadworld/components/CW-ARM-001/urdf/batch-a/meshes/arm.stl",
            "version": 2,
            "expiresAt": null
          }
        ],
        "resourceIssues": []
      }
    ],
    "alternatives": [
      {
        "category": "torso_0",
        "items": []
      },
      {
        "category": "arm_r",
        "items": []
      }
    ]
  },
  "requestId": "frontend-demand-001"
}
字段 说明
status complete:所需角色齐全且硬要求已验证满足;partial:缺件、硬要求未满足或未验证;no_match:没有可用组件
components[] 稳定实例编码 + 完整公开组件 DTO,保留原始 bomList 和 urdfInfo JSON
alternatives[] 每个已选角色最多 5 个兼容替代项,见下文
requirementChecks[] 对应 intentId,状态 satisfied / unmet / unverified;前端关联解析中的详细需求
unmetRequirements 字段差距,包括偏好差距;硬要求判定以详细校验为准
totals 组件标称参数求和;不重复统计 BOM。质量未知时 massKg=null,knownMassKg 为已知部分
missingParts 缺失角色和原因;没有可用躯干时返回 no_match,其他现存角色可标记 NO_TORSO;仍是 HTTP 200
searchLimited 候选或搜索被截断,本方案不是已证明的全局最优
degradationAcceptanceRequired 硬要求未满足、未验证或缺件时需用户主动接受
assembly.status ready 才可应用完整连接;blocked 展示 issues,不自动拼装

公开组件字段与 组件详情 一致,不包含数据库主键和独立 OSS 对象键。urdfMainPath 与资源清单中的 relativePath 保留目录层级,使用 resources[].url 加载模型和 mesh。公开资源 expiresAt=null,不是临时签名;version 表示组件版本。

躯干优先规则

整机结果始终以 torso_0 为根,默认方案中的躯干只有一个。用户未单独提出躯干时,后端在规范化的 requiredParts 中补入 torso_0 并返回说明;原始对话和提取的用户条目保持其来源。明确要求“不要躯干”或多个同类躯干时会追问,不能直接确认拼装。

躯干先按自身硬条件、数值差距、偏好、整机功能文本与关键词相关性排序;这些条件相同后优先选择能接更多所需角色的接口集合,最后按编码稳定排序。整机自由度和质量目标在后续组合阶段评价,不直接当作躯干单件的数值要求。

选定躯干后不因其他躯干能多接几件或更接近整机总量而自动换根。其他组件须能通过现有接口路径连接到这个躯干;例如右手通过右臂连接,允许沿链匹配,但不自动补入未要求的中间连接件。达标搜索和降级搜索沿用同一个躯干。缺件时返回该躯干及可连接的部分方案;无可用躯干时返回 no_match,不会用头部或手臂代替根。

替代项示例

下面是 alternatives[].items[] 的完整对象示例,仍是同一右臂角色:

{
  "component": {
    "componentCode": "CW-ARM-002",
    "componentName": "大扭矩右臂",
    "category": "arm_r",
    "description": "机器人右臂",
    "material": "铝合金",
    "massKg": 1.5,
    "degreesOfFreedom": 4,
    "functionDescription": "抓取",
    "shape": "长条",
    "size": "小型",
    "torqueNm": 30,
    "bomList": {
      "parts": [
        {
          "partCode": "MOTOR-01",
          "quantity": 4,
          "specification": {
            "ratedTorqueNm": 25
          }
        }
      ]
    },
    "urdfInfo": {
      "robotName": "大扭矩右臂",
      "rootLink": "ARM_V2_ROOT",
      "frames": [],
      "assembly": {
        "mountingFrame": "ARM_V2_ROOT",
        "pairingConvention": "coincident_frames"
      }
    },
    "version": 1,
    "stepUrl": "https://models.example.com/cadworld/components/CW-ARM-002/step/batch-a/arm.step",
    "urdfUrl": "https://models.example.com/cadworld/components/CW-ARM-002/urdf/batch-a/robot.urdf"
  },
  "resources": [
    {
      "relativePath": "robot.urdf",
      "url": "https://models.example.com/cadworld/components/CW-ARM-002/urdf/batch-a/robot.urdf",
      "version": 1,
      "expiresAt": null
    },
    {
      "relativePath": "meshes/arm.stl",
      "url": "https://models.example.com/cadworld/components/CW-ARM-002/urdf/batch-a/meshes/arm.stl",
      "version": 1,
      "expiresAt": null
    }
  ],
  "resourceIssues": [],
  "urdfMainPath": "robot.urdf",
  "totals": {
    "degreesOfFreedom": 4,
    "massKg": 3.5,
    "knownMassKg": 3.5,
    "massComplete": true
  },
  "unmetRequirements": [],
  "unmatchedKeywords": [],
  "requirementChecks": [
    {
      "intentId": "r1",
      "priority": "must",
      "status": "satisfied",
      "field": "torqueNm",
      "expected": 20,
      "actual": 30,
      "reason": "所选组件的登记参数满足该条件"
    }
  ],
  "assembly": {
    "status": "ready",
    "rootInstanceId": "DM-33333333333333333333333333333333:torso_0",
    "matrixLayout": "column-major",
    "connections": [
      {
        "parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
        "parentFrame": "J_ARM",
        "parentLink": "BASE",
        "childInstanceId": "DM-33333333333333333333333333333333:arm_r",
        "childFrame": "ARM_V2_ROOT",
        "childRootLink": "ARM_V2_ROOT",
        "parentRootToInterface": [
          1,
          0,
          0,
          0,
          0,
          1,
          0,
          0,
          0,
          0,
          1,
          0,
          0.1,
          0,
          0,
          1
        ],
        "childRootToInterface": [
          1,
          0,
          0,
          0,
          0,
          1,
          0,
          0,
          0,
          0,
          1,
          0,
          0,
          0,
          0,
          1
        ],
        "childRootRelativeToParentRoot": [
          1,
          0,
          0,
          0,
          0,
          1,
          0,
          0,
          0,
          0,
          1,
          0,
          0.1,
          0,
          0,
          1
        ]
      }
    ],
    "issues": []
  },
  "degradationAcceptanceRequired": false
}

替代结果以当前默认方案为基准,包含重新计算的汇总、校验和装配信息。前端切换时替换对应实例的组件与资源并应用该替代项的连接信息。躯干替代项表示替换当前唯一躯干,不能作为第二个躯干追加。多个替代项同时切换不能直接叠加各自预览;当前没有多项替换后的服务端校验/方案保存接口,降级接受接口仅针对服务器保存的默认方案。

5. 装配连接与加载

assembly.connections[] 示例(属于躯干 + 右臂方案):

{
  "parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
  "parentFrame": "J_ARM",
  "parentLink": "MID",
  "childInstanceId": "DM-33333333333333333333333333333333:arm_r",
  "childFrame": "MOUNT",
  "childRootLink": "ARM_ROOT",
  "parentRootToInterface": [
    1,
    0,
    0,
    0,
    0,
    1,
    0,
    0,
    0,
    0,
    1,
    0,
    0.1,
    0,
    0,
    1
  ],
  "childRootToInterface": [
    1,
    0,
    0,
    0,
    0,
    1,
    0,
    0,
    0,
    0,
    1,
    0,
    0.02,
    0,
    0,
    1
  ],
  "childRootRelativeToParentRoot": [
    1,
    0,
    0,
    0,
    0,
    1,
    0,
    0,
    0,
    0,
    1,
    0,
    0.08,
    0,
    0,
    1
  ]
}

矩阵为 16 个数字,column-major,位移单位 m,角度来源为 rad。childRootRelativeToParentRoot 是子组件 root 相对父组件 root 的变换;父接口可能位于中间 link,后端已累积路径,不能再次叠加帧原始 xyz/rpy。前端世界变换为 父组件世界矩阵 × childRootRelativeToParentRoot。

parentRootToInterface、childRootToInterface 分别是两件组件自身根到安装接口的矩阵;连接计算遵循 父根到接口 × inverse(子根到接口)。childFrame 可以是指定 link 或 joint,childRootLink 保留文件原名。

每件子组件通过 urdfInfo.assembly 明确基准:

{
  "mountingFrame": "ARM_ROOT",
  "pairingConvention": "coincident_frames"
}

此对象嵌在 urdfInfo.assembly 中,安装帧须存在于文件图中。前端不根据草图生成机械坐标。缺少基准、多个同类父接口未配对、连接图异常、活动关节缺状态、资源清单不完整等都会返回 assembly.status=blocked。

加载模型时保留 URDF 相对路径目录;不要只取文件名,否则 meshes/... 引用会失效。OSS/CDN 须允许前端 CORS,组件资源直接加载公开 URL;用户需求图片走私有预览接口,不能复用模型公开域名。

6. 接受降级、重新匹配与错误

POST /api/robot-demand-matches/{matchId}/accept-degradation:

{
  "revision": 1,
  "accepted": true
}

返回同一匹配结构,degradationAccepted=true、degradationAcceptanceRequired=false;只清除 DEGRADATION_NOT_ACCEPTED 阻塞。缺件、安装基准、资源问题和未验证能力仍保留,status 不会因此变成 complete。不要在点击接受后直接将装配状态改为 ready。

部分返回片段示例(仅展示发生变化的字段):

{
  "status": "partial",
  "degradationAccepted": true,
  "degradationAcceptanceRequired": false,
  "assembly": {
    "status": "blocked",
    "issues": [
      {
        "code": "MISSING_MOUNTING_REFERENCE",
        "category": "arm_r",
        "componentCode": "CW-ARM-001",
        "message": "子组件缺少明确安装基准或接口配对约定"
      }
    ]
  }
}

组件版本变化或逻辑删除后,接受旧方案返回 COMPONENT_REVISION_CONFLICT。调用 POST /api/robot-analyses/{analysisId}/rematch 并传 {revision:1,confirmed:true} 使用保存的需求重新匹配;返回新 matchId,旧匹配编码失效。再次解析需求则发送新消息。

错误响应示例:

{
  "code": "DEMAND_REVISION_CONFLICT",
  "message": "需求版本已更新,请确认最新解析结果",
  "data": null,
  "requestId": "frontend-demand-001"
}
HTTP / 错误码 前端处理
422 INVALID_REQUEST / DEMAND_INPUT_TOO_LARGE 修正输入或新建会话
404 DEMAND_NOT_FOUND 无记录、已过期或不属于当前访客;新建会话
409 DEMAND_REVISION_CONFLICT 查询最新解析,重新确认;重复消息编号内容须一致
409 COMPONENT_REVISION_CONFLICT 用当前已确认需求调用 rematch
409 DEMAND_ATTACHMENT_MISSING 原图已失效,重新上传并发送新消息
429 DEMAND_BUSY 暂无解析容量;查询状态后稍后 retry
503 DEMAND_UNAVAILABLE / DEMAND_ATTACHMENT_UNAVAILABLE 暂不可用,稍后 retry 或重传
SSE DEMAND_TIMEOUT / DEMAND_PROVIDER_FAILURE / DEMAND_INCOMPLETE / DEMAND_INVALID_OUTPUT 解析失败且不可确认,可重试或补充说明
SSE DEMAND_CANCELLED 已停止;当前版本可 retry

网关对 SSE 关闭缓冲,超时应长于后端解析超时加 30 秒(默认超过 210 秒)。模型通常不是即时返回,等待期间保留停止入口。GET 解析接口可用于恢复状态;当前未提供整个会话列表与消息历史列表接口。