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

14 KiB
Raw Blame History

需求解析后端接入与部署

已按 /Users/edy/Downloads/robot-demand-parser-v1 的 README、backend-handoff、protocol,以及 index.mjs / mechanical-rules.mjs 移植 Java 程序校验。自动拼装输出版本为 multimodal-v1.2-auto-assembly,目录版本为 2026-10-14-auto-assembly。原始来源作为参考保留,当前提示词与 Java 规则已调整为无追问的自动生成流程。来源文件夹保持不变,运行时不依赖 Node、React 或前端解析脚本。

业务标准化另外落实躯干优先规则:整机必须且只能有一个躯干,解析时可自动补入基础躯干;明确排除躯干时保留排除项并返回无匹配方案,不追问或偷偷补入。匹配先固定最符合需求的躯干,再搜索与其连通的其他组件。

前端完整调用说明与示例见 robot-demand-api.md。下面说明部署条件和后端边界。

启动条件

  1. 使用已有 component 表,部署前按 管理端旋转轴字段部署说明 添加 rotation_axis。在用户端服务使用的数据库中执行 demand-schema.md 的五张表建表语句。代码不自动建表或迁移,不修改或执行仓库 .sql 文件。
  2. 配置 MySQL、公开模型域名与 ARK_API_KEY。Key 仅提供给后端,缺失时其他组件接口仍可使用,需求解析返回不可用状态。
  3. 为需求图片配置私有可写的持久化目录;不能映射为静态资源或挂载到公开模型目录。
  4. 前端通过同站点 HTTPS 代理 /api;开发跨端口时配置具体前端 origin。生产 Cookie 设置 Secure。
  5. 机械在组件 urdfInfo.assembly 登记安装基准和配对约定;缺失时匹配仍返回组件,但装配阻塞。
mvn -pl cadworld-api,cadworld-adminapi -am test
mvn -pl cadworld-api,cadworld-adminapi -am -DskipTests package
java -jar cadworld-api/target/cadworld-api-0.0.1-SNAPSHOT.jar

默认端口 8991、profile test;生产指定 SPRING_PROFILES_ACTIVE=prod。Spring Boot 不自动加载 .env,由启动环境注入变量。此服务不需要管理员身份、上传签名密钥或 OSS AccessKey。

环境变量 默认 / 说明
APP_DB_URL / APP_DB_USERNAME / APP_DB_PASSWORD 生产必填,MySQL 连接
APP_STORAGE_PUBLIC_BASE_URL 生产必填,公开 OSS/CDN 域名,不能填管理端代理
OSS_ROOT_PREFIX 测试默认 cadworld_dev,生产默认 cadworld
ARK_API_KEY 无默认,仅后端环境变量或密钥服务提供
ARK_MODEL doubao-seed-2-1-lite-260915,可替换为账号开通的多模态结构化输出模型
ARK_ENDPOINT https://ark.cn-beijing.volces.com/api/v3/responses
APP_DEMAND_TIMEOUT PT3M,允许 1 秒至 5 分钟
APP_DEMAND_ATTACHMENT_DIRECTORY data/demand-attachments,私有附件目录
APP_DEMAND_RETENTION P7D,允许 1 小时至 30 天
APP_DEMAND_CONCURRENT_ANALYSES 4,允许 1–16;当前进程并发上限,无等待队列
APP_DEMAND_ALLOWED_ORIGINS /api/** 跨域白名单;test 默认 https://dev-cadworld.robotquan.com,prod 默认 https://cadworld.robotquan.com;可用逗号分隔的完整 origin 覆盖,显式留空关闭跨域,禁止通配符
APP_DEMAND_ROOT_IS_MOUNTING_FRAME false;本项目尚未统一根节点安装约定,保持 false

用户端跨域支持凭证,允许 GET / POST / DELETE / OPTIONS,请求头允许 Content-Type / X-Request-Id,向前端暴露 X-Request-Id,预检缓存 3600 秒。浏览器请求需要携带访客 Cookie 时,使用 credentials: 'include'(Axios 使用 withCredentials: true)。公开 OSS/CDN 资源的跨域需在对应资源服务单独配置。

模型调用使用严格 JSON Schema、深度思考、stream:false、store:false,不启用联网工具。SSE 为后端阶段和已校验业务结果,不透传模型推理内容。接收上游响应最多 2MiB,提取的中间 JSON 最多 150000 字符。

原始提示词、模型中间 Schema、类别目录放在 cadworld-service/src/main/resources/robot-demand/,不作为公开静态资源。Schema 拒绝缺少字段、未知字段、非法枚举、超长值和无效证据编号。来源文字必须是所属用户消息的原文子串;历史助手消息不能作为用户数值证据。每张上传图片都需出现在模型图片分析中,图片与观察归属需一致。

持久化与运行方式

五张表分别保存会话归属和版本、私有附件元信息、服务端历史、完整解析结果、自动生成的匹配快照。对外均使用编码;原始访客 Cookie 只在浏览器,数据库保存其 SHA-256。没有账号系统时暂按浏览器访客隔离;以后接入登录,应将归属替换为服务端认证主体,不能改成信任客户端 userId。

新用户消息在事务中锁定会话、递增版本并使旧方案失效;相同消息编号和内容不重复创建版本、调用模型或选件。消息任务在需求规范化后立即执行自动选件和装配校验,需求结果与匹配快照在同一事务内提交,随后才发布 ready 和 analysis.completed;完成事件及 GET 查询同时返回公开的 match,内部 snapshot 始终移除。选件在会话锁外执行,提交时再次核对版本和取消状态,防止旧任务覆盖新方案。新流程不写入助手追问。

对话拼装仅保留 7 个接口:创建会话、上传图片、预览图片、发送消息、查询任务、重试和停止。确认、重新匹配、按匹配编码查询和接受降级接口及相关 DTO/业务实现已删除,旧路径返回 404。结果统一由消息完成事件和任务查询返回;调整需求或刷新组件库结果时,发送新的用户消息,重新调用模型并生成新方案。重发相同消息编号只恢复原任务或原结果。

当前解析执行器与 SSE 订阅在进程内,建议单实例部署;多实例须共享数据库和私有文件卷,并按会话路由到同一实例。此版本未实现分布式任务租约或跨实例取消通知。进程重启后的 processing 记录会在超时后标为失败,当前版本可重试,不会将未完成结果视为可装配。SSE 意外断开只移除订阅,任务仍继续执行,前端可查询或重新订阅同一消息恢复;显式 DELETE、超时和新版本才停止任务。模型调用受解析超时限制,整个生成任务的截止时间为该超时加 30 秒。

上传附件只接受本服务生成的编码,不支持客户端任意路径、URL 或预签名外链。默认每小时清理至多 100 个过期会话及其私有图片、消息、解析、匹配;删除失败保留元信息,下轮重试。会话访问过期即返回 404,不等待清理任务。上传到会话而未发送的附件同样随会话过期清理。组件公开 OSS 资源不受此任务影响。

网关应允许 8MiB 文件上传、POST SSE 和至少 210 秒的请求等待时间(默认解析超时 180 秒加 30 秒)。关闭 SSE 缓冲。所有需求相关运行日志只记录请求编号、业务编码、版本、数量、状态、错误码和耗时,不记录完整输入、图片、BOM/URDF JSON、模型 Key。

需求与匹配判定

规范化五字段 request 继续兼容原结构化匹配,自动生成使用完整 analysis。详细 intentItems 保留 must/prefer/context、证据和来源。硬要求优先排序,偏好在硬要求之后评价;不能映射为登记字段或缺少能力证据的硬要求返回 unverified。功能文本相关性不证明跑步、巡检、飞行、续航等物理能力。

数值约束统一到 kg、N·m,支持明确单位换算与中文数字;自由度必须是 int32 非负整数,质量和扭矩遵循 decimal(18,6)。单位缺失、范围无法表示、相互冲突、对象不清楚等保留原要求和未验证说明,不用于硬条件筛选、不阻塞生成,也不自动选一个值或默认单位。lt/gt/neq 与非退化双边范围当前不投影为 eq/gte/lte。未指定属性不会填 0。未指定可匹配类型或部位时,按 part-catalog.json 的 defaultTemplate=biped 生成参考方案并说明;可识别的图片或部位推断可用于选件,但不升级为硬数值或已验证能力。图片视觉推断、模糊信息和反例不能投影成硬数值条件。

组件组合仍为 MySQL + 同义词词典 + Java 有界搜索。候选查询只扫描同时具有非空 step_object_key 和 urdf_main_object_key 的组件,只有 STEP 的组件不参与默认方案或替代候选;新增时可先仅上传 STEP,再通过管理端修改补齐 URDF 和元数据。先按躯干单件硬要求、数值差距、偏好及功能/关键词相关性固定唯一躯干;评分相同后比较所需接口覆盖及编码。整机自由度和质量在后续组合求和评价。固定躯干后优先覆盖所需角色;在同等覆盖下,硬要求差距优先于偏好。先搜索其他部件硬条件满足的候选,再提供明确说明的降级结果,两轮共用同一个躯干;不以整机总量或覆盖率更换根。

没有可用躯干时返回无匹配结果,不再尝试其他角色为根。一个角色只对应一个实例,躯干的中英文别名也归一化到同一个角色。除作为基础部件自动补入的躯干外,不补入其他未要求的中间连接件;一个实例的数量可验证,同角色多个实例的数量要求作为未验证项保留,不追问,也不会静默去重冒充数量达标。躯干替代项只用于替换当前唯一躯干。

complete/partial/no_match 描述需求匹配,assembly.ready/blocked 只描述已有组件的安装与资源是否有效。缺件通过 missingParts 和 partial 提示,不进入 assembly.issues;缺件、性能不足或未验证能力不要求先接受降级,degradationAcceptanceRequired 固定为 false,因此 partial 可同时返回 assembly.ready 并直接显示已有有效组合。没有可用组件、躯干根不合法、安装基准缺失、坐标图或资源异常仍阻塞。仅有有效躯干时可以显示躯干,连接数组为空。

默认组合和替代候选使用相同装配判定。兼容响应中的降级接受标记保留为 false,不提供单独接受流程;缺件、未验证能力和机械/资源问题继续保留。新生成结果不再保存只供接受流程使用的内部 snapshot,查询历史数据时仍移除旧快照。升级规则或组件库更新后,发送新消息生成新版本;原消息重放和状态查询不会重算。替代项是相对默认方案的一次替换预览,当前未实现多项替换的服务端验证或装配方案保存。

机械安装数据

每件子组件须显式填写:

{
  "robotName": "右臂",
  "rootLink": "ARM_ROOT",
  "frames": [],
  "assembly": {
    "mountingFrame": "ARM_ROOT",
    "pairingConvention": "coincident_frames"
  }
}

这是 urdfInfo 的示例;真实帧数组保留完整文件结构。mountingFrame 可为 root、可达 link 或 joint,含义是文件内真正的安装坐标系;coincident_frames 表示与父接口坐标系直接重合。管理员组件表单仍接受 JSON 对象/数组,不要求所有旧数据立刻补齐;装配校验会诊断缺失项。

父接口优先使用 interfaceType;缺少时按 LINK_ 子 link 的已知角色名推导。文件中的 xyz/rpy 是相对父 link 的局部原始位姿,后端沿固定关节链累积根到接口的变换。子组件根到安装帧的变换必须取逆,公式为:

T_parentRoot_childRoot = T_parentRoot_parentInterface × inverse(T_childRoot_childInterface)

矩阵为 column-major,长度单位 m,RPY 为 rad。多个同类父接口未指定配对、循环/不可达图、缺失位姿、活动关节没有状态均阻塞,不猜测翻转角或安装位置。originExplicit:false 且位姿缺失时按 URDF 隐式零位姿处理。

公开组件同时返回完整 BOM、URDF 信息及 STEP/URDF URL,资源清单保留相对目录和版本。不存在独立用户资源代理。公开资源更新使用新上传批次路径;逻辑删除不撤销之前已发出的公开直链。图片附件为另一套私有资源,不使用公开模型地址。

验证范围

自动测试使用 Java H2 表、模拟模型客户端、本地模拟 Responses HTTP 服务与测试资源域名,不调用真实付费模型、不访问业务 MySQL 或 OSS。

保留规则包原始 Node 样例,验证四组样例的机械条件投影及证据不变。覆盖新流程无追问、证据和图片归属、单位补充、数值与冲突边界、模型拒绝/超时/异常、SSE、取消和重试、版本和幂等、硬要求/偏好、7 个接口路由及旧路由 404、历史内部快照不暴露、资源版本变化后通过新消息刷新、私有附件过期清理,以及消息自动返回装配、默认模板、图文冲突和缺单位生成、断流查询恢复、选件失败不发布结果、匹配快照保存失败时回滚解析结果、新消息使正在选件的旧任务失效、坐标累积、子安装基准取逆、端口歧义与活动关节阻塞。验证缺件时默认组件与替代候选可直接预览、仅有躯干可显示,同时保留缺件和整机总量未验证提示;机械或资源异常仍阻塞。既有管理端上传、版本控制、逻辑删除与审计测试也参加回归。

真实图片 OCR 和多模态识别质量仍需配置实际模型后使用机械样本验收。修改提示词、Schema 或类别目录时,应同步来源版本、规则校验与一致性样例,不能只替换提示词后直接发布。