Files
cadworld/cadworld-api/docs/robot-demand-api.md
T

34 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,直接读取 data.match。当 match.assembly.status=ready 时,使用 match.components 的资源及 match.assembly.connections 加载并拼装;partial 也可直接显示有效的已有组合。
  5. 简短展示 warnings、缺件及未满足/未验证项;不弹出追问、确认或必须接受降级的页面。assembly.status=blocked 或 status=no_match 时展示具体原因,不伪造连接位姿。
  6. 用户需要调整时,在同一会话发送新消息,例如“改成右臂扭矩至少30N·m”,后端生成新版本并返回新方案。

浏览器需要保留后端设置的 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} 无 停止后的解析状态

AI 对话拼装仅保留以上 7 个接口。原 confirm、rematch、按 matchId 查询和 accept-degradation 接口已删除,访问返回 HTTP 404;前端不再调用这些接口。生成结果统一从消息完成事件或 GET /api/robot-analyses/{analysisId} 的 data.match 获取。

既有结构化 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,包含 match 直接加载可装配机器人并展示说明
analysis.failed code 为错误码,data=null 停止加载,按错误码显示重试入口
心跳注释 无 JSON 数据 忽略

阶段依次为 validating_input、analyzing_requirements、validating_result、assembling_robot;最后一阶段包含自动选件和装配校验。阶段提示不是模型逐字输出,不用于计算完成百分比。只有需求与匹配快照一起保存成功后才发送完成事件;自动选件期间 GET 仍返回 processing,result 和 match 均为空。

事件格式示例:

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;SSE 意外断开不会取消任务,后端继续生成至完成或超时。连接中断后先 GET 查询状态,processing 时可间隔 1.5–2 秒查询;ready 时直接使用返回的 match;failed/cancelled 才提供 retry。不要重发新消息或把查询成功称为 SSE 连接恢复。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-14-auto-assembly",
        "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.2-auto-assembly",
        "canSubmit": true,
        "status": "ready",
        "defaultTemplate": ""
      }
    },
    "match": {
      "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,
            "rotationAxis": null,
            "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,
            "rotationAxis": null,
            "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 新流程为 processing / ready / failed / cancelled / superseded;ready 表示本次方案已生成,具体能否装配看 match.assembly.status。needs_clarification 仅可能存在于旧记录
canSubmit 旧客户端兼容字段,新流程 ready 时为 true;无需展示确认按钮,不代表所有要求达标
questions 新生成结果固定为 [],不发起追问
warnings 来源、推断或能力承载方面的说明,供核对
result.request 规范化五字段需求;未提供的约束不会补成 0
result.analysis.intentItems 逐项需求,must 硬要求、prefer 偏好、context 参考;用于结果说明和逐项核对
result.analysis.defaultTemplate 没有可匹配类型或部位时使用的默认模板编码,目前为 biped;没有采用默认模板时为空字符串
match 已保存的完整机器人方案,包含组件资源、装配连接、缺件和逐项校验;处理未完成或已失效时为空
result.analysis.observations 用户原文 / 图片 OCR / 视觉描述及所属消息、图片
result.analysis.images 图片类型、用途和不确定点;不包含图片数据
evidenceIds 关联 observation 的编码;region=[] 表示无可靠定位框

新流程 ready 同时返回 result 和 match;其他状态两者为空、canSubmit=false。旧版记录可能仍含 needs_clarification,发送新消息即可按新流程生成;旧版 ready 若没有 match,发送新消息生成方案;不再提供补确认入口。图像视觉推断只保留参考,不自动成为确定尺寸、材质、数值或能力。展示整机功能“跑步”等时应标明文本相关性,不能据此展示真实能力已验证。

自动生成示例:用户说“右臂扭矩至少30”但缺单位时,后端直接选取躯干和右臂,忽略无法验证的数值筛选条件,并把原要求保留为 unverified,不会默认单位或追问。用户后来主动补充“单位是N·m”时,结合真实用户历史生成版本 2;旧版本变为 superseded,旧方案不再应用。未提供机器人形态或部位时按默认双足模板生成参考方案并说明;不支持的四足、飞行等要求仍保留差异,不宣称默认方案已满足。

4. 机器人方案

消息完成事件及状态查询的 data.match 包含同一份已保存方案。第 3 节示例只指定右臂,后端补入一个躯干作为装配根,同时返回两件组件的资源和连接位姿。示例编码与资源域名均为演示值。

字段 说明
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 新生成方案及替代候选固定为 false;缺件和未满足/未验证项作为结果说明,不要求先接受
assembly.status ready:已有组件的安装与资源校验通过,可应用返回的连接位姿;blocked:展示 issues,不自动拼装。与需求是否完整达标分别判断

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

躯干优先规则

拼装仅检索同时具备非空 step_object_key 和已上传 URDF 主文件(非空 urdf_main_object_key)的组件;消息自动生成和替代候选使用同一筛选规则。仅上传 STEP 的组件不会参与拼装。候选仍须满足 urdfInfo.rootLink、frames 及现有连接元数据规则,装配阶段继续校验安装基准和资源清单。

整机结果始终以 torso_0 为根,默认方案中的躯干只有一个。用户未单独提出躯干时,后端在规范化的 requiredParts 中补入 torso_0 并返回说明;原始对话和提取的用户条目保持其来源。明确要求“不要躯干”时保留排除项,返回 no_match、missingParts.reason=EXCLUDED_TORSO,不会偷偷补入躯干;多个同类实例要求保留为未验证项,不追问。

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

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

缺件时展示已有组合

status=partial 可以同时有 assembly.status=ready。例如需要躯干、右臂和头部,库存只有能连接的躯干与右臂,且两件资源和安装基准有效,返回如下片段:

{
  "status": "partial",
  "rootCategory": "torso_0",
  "degradationAcceptanceRequired": false,
  "degradationAccepted": false,
  "missingParts": [
    {
      "category": "head_0",
      "reason": "NO_COMPONENT"
    }
  ],
  "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, 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, 1, 0, 0, 1]
      }
    ],
    "issues": []
  }
}

前端加载 components[] 中已有的模型并应用上述连接,提示“缺少头部”,同时保留降级接受入口。展示模型无需先接受降级,展示不等于用户已经接受。仅有有效躯干时也可返回 ready,此时 connections=[],前端显示躯干本身。

缺失角色不返回占位组件或伪造连接。totals 仍是已有组件的标称参数之和;所需组件未齐全时,整机总量要求仍可能为 unverified。替代候选遵循同一规则。没有可用躯干、安装基准缺失、连接图异常或资源清单不完整仍返回 blocked;新结果的 assembly.issues 不再包含 MISSING_PARTS 或 DEGRADATION_NOT_ACCEPTED。

替代项示例

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

{
  "component": {
    "componentCode": "CW-ARM-002",
    "componentName": "大扭矩右臂",
    "category": "arm_r",
    "description": "机器人右臂",
    "material": "铝合金",
    "massKg": 1.5,
    "degreesOfFreedom": 4,
    "rotationAxis": null,
    "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. 结果刷新与错误

已保存方案是本次生成时的快照。调整需求、组件版本变化、补齐资源或需要重新选件时,在同一会话发送新的 messageId,例如“按原需求重新生成”,后端重新理解当前有效需求并生成新方案。旧版本查询返回 superseded,不会继续返回旧 match。重发原消息编号仅恢复原任务或结果,不触发刷新。

retry 只用于失败或已停止的当前任务;processing 时查询或重订阅原消息,ready 时直接显示结果。部分方案无需接受降级;degradationAcceptanceRequired、degradationAccepted 为兼容字段,新生成结果均为 false。安装基准、坐标或资源异常仍通过 assembly.issues 返回,不把未满足或未验证的需求标成已达标。

错误响应示例:

{
  "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 组件已变化,发送新消息重新生成
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 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。