107 lines
16 KiB
Markdown
107 lines
16 KiB
Markdown
# 需求解析后端接入与部署
|
||
|
||
已按 `/Users/edy/Downloads/robot-demand-parser-v1` 的 README、backend-handoff、protocol,以及 `index.mjs` / `mechanical-rules.mjs` 移植 Java 程序校验。自动拼装输出版本为 `multimodal-v1.6-component-replacement`,目录版本为 `2026-10-27-hexapod-connectors`。原始来源作为参考保留,当前提示词与 Java 规则已调整为无追问的自动生成流程。来源文件夹保持不变,运行时不依赖 Node、React 或前端解析脚本。
|
||
|
||
业务标准化另外落实躯干优先规则:整机必须且只能有一个躯干,解析时可自动补入基础躯干;明确排除躯干时保留排除项并返回无匹配方案,不追问或偷偷补入。匹配先固定最符合需求的躯干,再搜索与其连通的其他组件。
|
||
|
||
前端完整调用说明与示例见 [robot-demand-api.md](robot-demand-api.md)。下面说明部署条件和后端边界。
|
||
|
||
## 启动条件
|
||
|
||
1. 使用已有 `component` 表,部署前按 [管理端旋转轴字段部署说明](../../cadworld-adminapi/docs/admin-api.md#43-旋转轴字段部署) 添加 `rotation_axis`。在用户端服务使用的数据库中执行 [demand-schema.md](demand-schema.md) 的五张表建表语句。代码不自动建表或迁移,不修改或执行仓库 `.sql` 文件。
|
||
2. 配置 MySQL、公开模型域名与 `ARK_API_KEY`。Key 仅提供给后端,缺失时其他组件接口仍可使用,需求解析返回不可用状态。
|
||
3. 为需求图片配置私有可写的持久化目录;不能映射为静态资源或挂载到公开模型目录。
|
||
4. 前端通过同站点 HTTPS 代理 `/api`;开发跨端口时配置具体前端 origin。先完成[邮箱登录及用户编码迁移](auth-api.md),全部业务请求携带 Bearer Token。
|
||
5. 对接组件实际接口:interfaceType 优先确定现有 category,双方 frames[].child 非空并按单向兼容规则连接(同部位父 L/R 可接同侧或 0,父 0 只接 0);每个 frames 元素是独立接口。无需填写 urdfInfo.assembly,模型摆放由前端处理。
|
||
|
||
```bash
|
||
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 覆盖,显式留空关闭跨域,禁止通配符 |
|
||
|
||
用户端跨域支持凭证,允许 `GET / POST / DELETE / OPTIONS`,请求头允许 `Content-Type / X-Request-Id / Authorization`,向前端暴露 `X-Request-Id`,预检缓存 3600 秒。浏览器统一发送 `Authorization: Bearer <token>`,不再依赖匿名 Cookie。公开 OSS/CDN 资源的跨域需在对应资源服务单独配置。
|
||
|
||
模型调用使用严格 JSON Schema、深度思考、`stream:false`、`store:false`,不启用联网工具。SSE 为后端阶段和已校验业务结果,不透传模型推理内容。接收上游响应最多 2MiB,提取的中间 JSON 最多 150000 字符。
|
||
|
||
原始提示词、模型中间 Schema、类别目录放在 `cadworld-service/src/main/resources/robot-demand/`,不作为公开静态资源。Schema 拒绝缺少字段、未知字段、非法枚举、超长值和无效证据编号。来源文字必须是所属用户消息的原文子串;历史助手消息不能作为用户数值证据。每张上传图片都需出现在模型图片分析中,图片与观察归属需一致。
|
||
|
||
## 持久化与运行方式
|
||
|
||
五张表分别保存会话归属和版本、私有附件元信息、服务端历史、完整解析结果、自动生成的匹配快照。对外均使用编码;会话归属使用服务端认证主体的 `SHA-256("user:" + userCode)`,不信任客户端 `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 和元数据。先按躯干单件硬要求、数值差距、偏好及功能/关键词相关性固定唯一躯干;评分相同后比较所需接口覆盖及编码。整机自由度和质量在后续组合求和评价。固定躯干后优先覆盖所需角色;在同等覆盖下,硬要求差距优先于偏好。先搜索其他部件硬条件满足的候选,再提供明确说明的降级结果,两轮共用同一个躯干;不以整机总量或覆盖率更换根。
|
||
|
||
没有可用躯干时返回无匹配结果,不再尝试其他角色为根。同一组件编码可生成多个独立实例,躯干仍固定一个,中英文类别别名先归一化。除作为基础部件自动补入的躯干外,不补入其他未要求的中间连接件;明确部位数量投影到 partRequirements.quantity(1–24);省略时先覆盖所需类型,再填充其可匹配剩余接口。实例标识、接口占用、替代和参数汇总均以实例为单位,不能按类别或组件编码去重。组件类型仍为16类,新增 hexapod 六足模板,未配置的其他形态继续保留差异。躯干替代项只用于替换当前唯一躯干。
|
||
|
||
`complete/partial/no_match` 描述需求匹配,`assembly.ready/blocked` 只描述是否有可展示组合和已生成的逻辑连接关系。缺件通过 `missingParts` 和 `partial` 提示,不进入 `assembly.issues`;缺件、性能不足或未验证能力不要求先接受降级,`degradationAcceptanceRequired` 固定为 false,因此 `partial` 可同时返回 `assembly.ready` 并直接显示已有有效组合。只有没有可用躯干/组件时才没有可展示组合;安装基准、位姿、活动关节和资源清单问题只返回提示,不阻塞已有组合。仅有有效躯干时可以显示躯干,连接数组为空。
|
||
|
||
默认组合和替代候选使用相同装配判定。兼容响应中的降级接受标记保留为 false,不提供单独接受流程;缺件、未验证能力和机械/资源问题继续保留。新生成结果不再保存只供接受流程使用的内部 `snapshot`,查询历史数据时仍移除旧快照。升级规则或组件库更新后,发送新消息生成新版本;原消息重放和状态查询不会重算。替代项仍是相对当前服务端方案的一次替换预览,不能直接叠加任意前端候选。消息流程支持基于历史成功快照进行多目标联合替换,任一失败则保留原组合和有效需求并保存新版本;`match.change` 返回 applied/unchanged 及原因,详见接口文档的“对话局部替换”。默认选件和替代排序新增同型号软偏好,优先于普通关键词但不覆盖明确需求。新解析协议为 `multimodal-v1.6-component-replacement`;不改表,旧快照不回填。
|
||
|
||
## 接口数据与实例
|
||
|
||
组件类型扩展为16类,新增 ARM_0/HAND_0/LEG_0/FOOT_0。默认人形使用臂、手、足、脚四组各至少两个实例的要求,根据实际接口选择 L/R/0。明确六足需求使用 hexapod 模板,只要求躯干及 LEG/FOOT 各至少六个实例,不沿用人形部位要求。接口以合法 interfaceType 确定要查找的 category,缺失或无效时从 child 的 LINK_ 后解析已有类型编码/别名;无法确定类型时不从此接口向外扩展。装配角色必须属于需求;L/R 角色的候选扫描同时纳入同部位的 0 类组件,并按该侧需求评价条件、数量。child 完全相等时继续可连接;新增兼容只允许 ARM/HAND/LEG/FOOT 标准 LINK 编码末尾方向位 L/R(含小写 l/r)连接 0,其余字符保持区分大小写一致。frame 的 name、kind、type、坐标和安装基准不参与连接资格判断。
|
||
|
||
四类部位统一按父到子方向处理:L 接 L/0,R 接 R/0,0 只接 0,L/R 不互接;0 组件的其他接口不根据安装侧改写。真实 component.category 保留 0,实例标识、连接类别及替代分组使用装配角色;需求检查按装配角色统计,每个实例只计一次。显式排除同时约束真实类别和装配角色。候选在明确需求之后优先保持同型号,替代项重新验证全部相邻连接,接口不重复占用。interfaceChild 为父接口原始 child,前端须用双方实例和 frame 下标定位,不能再假设双方 child 相等。默认模板的候选类型通过后端生成的 `result.request.templatePartGroups` 扩展,具体类别和分组合计缺口分别返回 `missingParts`、`missingPartGroups`。部署时同步读取 `multimodal-v1.6-component-replacement`;消息请求参数不变,无需数据库迁移,原始 URDF 与历史方案均不回写。
|
||
|
||
```json
|
||
{
|
||
"rootLink": "ARM_ROOT",
|
||
"frames": [
|
||
{
|
||
"name": "incoming",
|
||
"child": "LINK_arm_r",
|
||
"interfaceType": "ARM_R"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
父接口也有 child=LINK_arm_r、目标类型为 ARM_R 时,可以连接这件右臂。多个同 child 的 frames 元素为多个独立接口,原始数组不重排;连接双方以实例标识及 frameIndex 占用接口。先处理固定躯干的接口,再逐层扩展,先覆盖需求类型和明确数量,再在尽量满足硬要求的前提下填充其他兼容接口,避免自动增补破坏本可满足的整机参数。
|
||
|
||
结构化结果的实例标识为 category:序号;AI 外层实例标识为 matchId:category:序号,序号从1开始。connection 返回 interfaceChild 和双方 parentFrameIndex/childFrameIndex;不再返回 matrixLayout、装配矩阵或连接摆放用 xyz/rpy。完整 urdfInfo 仍返回原始 JSON,由前端解析各实例模型并定位。资源URL可缓存共享,模型实例必须独立。
|
||
|
||
每次最多24个实例;达到实例、候选或搜索上限时返回已有组合、searchLimited=true和提示。资源清单仍检查路径安全,非法相对路径跳过;清单不完整只提示。部署前端时须同步切换到实例连接协议。历史快照不会迁移或重算,旧矩阵格式通过新messageId生成新方案。
|
||
|
||
公开组件继续返回 BOM、URDF 信息及 STEP/URDF URL,资源清单保留相对目录和版本。公开资源更新使用新上传批次路径;图片附件继续使用另一套私有资源。原 APP_DEMAND_ROOT_IS_MOUNTING_FRAME 配置已移除,后台不再需要根节点安装基准开关。
|
||
|
||
## 验证范围
|
||
|
||
自动测试使用 Java H2 表、模拟模型客户端、本地模拟 Responses HTTP 服务与测试资源域名,不调用真实付费模型、不访问业务 MySQL 或 OSS。
|
||
|
||
保留规则包原始 Node 样例,验证四组样例的机械条件投影及证据不变。覆盖新流程无追问、证据和图片归属、单位补充、数值与冲突边界、模型拒绝/超时/异常、SSE、取消和重试、版本和幂等、硬要求/偏好、7 个接口路由及旧路由 404、历史内部快照不暴露、资源版本变化后通过新消息刷新、私有附件过期清理,以及消息自动返回装配、默认模板、图文冲突和缺单位生成、断流查询恢复、选件失败不发布结果、匹配快照保存失败时回滚解析结果、新消息使正在选件的旧任务失效、child单向兼容矩阵、真实类别与装配角色分离、显式排除、中性替代候选、接口独立占用、类型优先与兜底、多个同child接口、四/六个同款实例、数量不足和上限、逐层覆盖需求、单实例替代及按实例汇总。验证缺件时默认组件与替代候选可直接预览、仅有躯干可显示,同时保留缺件和整机总量未验证提示;位姿或资源清单问题只提示,不阻塞已有组合。既有管理端上传、版本控制、逻辑删除与审计测试也参加回归。
|
||
|
||
真实图片 OCR 和多模态识别质量仍需配置实际模型后使用机械样本验收。修改提示词、Schema 或类别目录时,应同步来源版本、规则校验与一致性样例,不能只替换提示词后直接发布。
|