Files
2026-10-27 16:49:51 +08:00

107 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 需求解析后端接入与部署
已按 `/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 或类别目录时,应同步来源版本、规则校验与一致性样例,不能只替换提示词后直接发布。