cadworld

Java 21 / Spring Boot 3.4.4 / MyBatis-Plus 多模块项目。管理端提供组件库、用户管理和操作日志,默认端口 8992;用户端提供组件匹配与文字/图片需求解析,默认端口 8991。

项目模块

模块 内容
cadworld-adminapi 后台启动应用、Controller、Web 配置、运行日志和审计
cadworld-service 业务服务、Mapper、阿里云 OSS 签名、资源校验
cadworld-bean 实体、请求和响应 DTO、枚举
cadworld-common 统一响应、异常、JSON 类型处理、请求编号和操作目标上下文
cadworld-api 独立用户端 API:组件详情、匹配、需求会话、图文理解、自动选件与装配
cadworld-security 用户端及管理端 Spring Security、独立登录态、共用图片验证码与 Token 基础实现

用户端支持邮箱与图片验证码登录,首次自动注册,所有业务接口需要 Bearer Token。管理端支持管理员邮箱登录,仅允许已启用的 ADMIN 账号,全部后台业务接口要求管理端 Bearer Token。上传会话和审计使用实际登录管理员。两端 Token 和验证码不能互用。

数据库

管理端访问 component、sys_user、sys_operation_log。用户端登录使用 sys_user,组件匹配复用 component,需求解析流程另外使用五张独立表;新增表的中文注释建表语句见 需求流程建表说明,需要部署时手动执行,应用不自动建表。组件旋转轴字段 rotation_axis 的迁移 SQL 见 管理端字段部署说明,部署两端新代码前须执行。

组件存储基本信息、自由度、旋转轴、功能、形状、大小描述、扭矩、BOM 清单、URDF 信息、两组自定义字段、STEP 对象键、URDF 目录及实际文件清单、version、deleted 删除标记和维护时间。旋转轴通过 rotationAxis 接收和返回,仅接受 X、Y、Z,未设置时为 null。BOM 和 URDF 信息均为 JSON 对象或数组,创建和修改必填 urdfInfo;可选 bomList 缺失或为 null 时写入 []。列表返回旋转轴和描述字段,BOM 和 URDF 信息仅在详情及保存结果中返回。通用日志存储模块、动作、目标快照、操作人、请求元信息和结果,不依赖组件专属列。

用户登录改造发布前需手动执行用户编码迁移 SQL。应用启动不建表、不迁移旧数据。本次未修改 .sql 文件;仓库中历史 SQL 不代表当前组件和日志结构,请使用已经建好的表。MySQL 需支持现有建表语句中的 JSON / TEXT 表达式默认值。

组件名称允许重复,编码唯一且不可修改。新增编码为 CW- 加 16 位随机数字或大写字母(排除 I/L/O/U),总长 19,例如 CW-7K3M9Q2R6V8X4T5N;使用 80 位密码学安全随机空间,数据库唯一索引约束重复。旧版 35 字符编码和已有上传会话继续兼容,无需修改表结构或迁移已有编码。组件逻辑删除;用户删除入口改为禁用账号,可重新启用,邮箱仍被占用。已删除组件的编码仍被占用。组件替换资源或逻辑删除均不自动删除 OSS 文件。

现有 component 表包含 deleted TINYINT UNSIGNED NOT NULL DEFAULT 0 字段,中文注释为“删除标记:0-未删除,1-已删除”。运行代码通过 MyBatis-Plus 自动过滤已删除组件,列表、详情、修改和编辑上传签名均只处理未删除记录。

配置与启动

cp .env.example .env
# 填写数据库、OSS 参数和上传会话密钥。
set -a
source .env
set +a
mvn -pl cadworld-adminapi -am -DskipTests package
java -jar cadworld-adminapi/target/cadworld-adminapi-0.0.1-SNAPSHOT.jar

Spring Boot 不自动读取 .env,需要通过 shell 导入。默认 profile 为 test;生产使用 SPRING_PROFILES_ACTIVE=prod,提供数据库连接变量。生产 Swagger 默认关闭。

Maven 命令在仓库根目录执行。首次构建或共享模块新增 DTO、方法后,使用 mvn install 将所有模块的最新产物安装到本地仓库。只构建管理端或用户端时,分别使用 mvn -pl cadworld-adminapi -am install、mvn -pl cadworld-api -am install,-am 会同时构建它们依赖的模块。

在子模块目录直接执行 mvn install 不会重建兄弟模块,可能引用本地旧包并出现程序包不存在或“找不到合适的方法”等错误。可用 -f 指定根 POM,从任意目录构建;将下方路径替换为实际仓库路径:

mvn -f /path/to/cadworld/pom.xml -pl cadworld-api -am install
环境变量 用途
APP_DB_URL / APP_DB_USERNAME / APP_DB_PASSWORD MySQL 连接配置
SERVER_PORT 后台端口,默认 8992
APP_ADMIN_ALLOWED_ORIGINS 管理端 /admin-api/** 跨域白名单;test 默认 https://dev-cadworld-admin.robotquan.com,prod 默认 https://cadworld-admin.robotquan.com;可用逗号分隔的完整 origin 覆盖,显式留空关闭跨域,禁止通配符
OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET 阿里云 OSS 凭证,通过环境变量或被 Git 忽略的 .env 提供
OSS_REGION / OSS_BUCKET 默认 oss-cn-beijing / linkerbot,签名地域使用 cn-beijing
OSS_ROOT_PREFIX 桶内环境根目录;test 默认 cadworld_dev,prod 默认 cadworld
APP_STORAGE_PUBLIC_BASE_URL 返回资源访问地址所用的前缀,默认指向 /admin-api/component-assets
APP_STORAGE_MAX_UPLOAD_BYTES 每个 OSS 文件的大小上限,默认 104857600 字节(100 MiB),签名策略与保存检查一致
OSS_UPLOAD_SESSION_TTL 上传会话有效期,默认 PT30M;续签不延长会话
OSS_UPLOAD_SIGNATURE_TTL OSS 签名有效期,默认 PT5M,不超过会话剩余时间
APP_UPLOAD_SESSION_SECRET 至少 32 个 UTF-8 字节;留空使用进程随机密钥,重启后原会话失效;多实例需配置相同密钥
APP_ADMIN_AUTH_CAPTCHA_TTL / APP_ADMIN_AUTH_TOKEN_TTL 管理端验证码与登录态有效期,默认 PT2M / PT24H;未设置时沿用通用 APP_AUTH_* 配置
LOG_PATH 运行日志目录,默认 logs

运行时使用已有 OSS 桶,不自动创建桶。前端通过 OSS V4 表单签名直接上传,后端通过 HEAD 检查文件,资源下载仍由后台代理。OSS 需配置前端站点的 CORS,允许表单 POST;上传字段原样使用,file 放在表单最后。凭证需有目标目录上传和读取权限。

对象路径:

{环境根目录}/components/{组件编码}/step/{上传批次}/{文件名}
{环境根目录}/components/{组件编码}/urdf/{上传批次}/{相对路径}

数据库只保存对象键,不保存完整 URL。返回 URL 对每段路径编码,访问路径区分大小写;根目录不要填写 URL。跨环境、越界、非法路径会被拒绝。更改环境根目录后,原目录资源不能由该部署访问。

实例连接规则

先选定最符合需求的唯一躯干,再沿接口逐层选件。interfaceType 优先确定目标类型,缺失/无效时从 child 的 LINK_ 后解析现有类别;双方 frames[].child 严格一致才连接,name 不参与匹配。每个数组元素独立占用,同款组件可复用为多个实例;明确 quantity 优先,省略时填满所需类型的可匹配接口,单次最多24个实例。汇总和替代均按实例处理。

后端只返回实例及接口下标的连接关系,不再计算装配矩阵;原始 urdfInfo 保留,由前端决定摆放。组件类型统一使用完整16类大写编码,足部为 LEG_L/LEG_R/LEG_0;旧小写及 pedal_l/pedal_r 兼容输入。默认人形按实际接口选择 L/R/0,臂、手、足、脚各合计至少两个;六足需求使用 hexapod 模板,只要求躯干和 LEG/FOOT 各至少六个实例。接口仍为 0 接 0、L 接 L、R 接 R;其他未配置形态保留差异。历史结果通过新消息重新生成,无需数据库迁移。

上传与接口

上传只使用 POST /admin-api/storage/upload-signature。新增首次传 {},获得后端编码、一个上传会话令牌和 STEP / URDF 两组授权;编辑传 componentId;续签传原 uploadSessionToken。申请签名不创建组件记录。

前端流程为:获取编码和签名 → STEP 文件和 URDF 文件夹直传 OSS → POST / PUT 保存组件。URDF 去掉选中文件夹最外层目录,保留内部结构。保存提交对象键,后端校验归属、实际存在性、大小及主文件后才写数据库。PUT 必须带详情中的 version,并发修改返回 409。

完整请求、响应及浏览器上传代码见 后台接口文档。

用户端接口入参、返回和公开模型加载见 组件匹配文档;文字/图片理解、SSE 与自动生成装配方案见 前端需求联调文档。用户端部署变量、私有附件目录与接口连接约定见 后端接入说明。需求解析需配置后端 ARK_API_KEY;普通用户组件接口不需要管理员身份、上传令牌或 OSS 凭证。

AI 对话流程为:文字/图片 → 理解需求 → 自动选件与装配校验 → 返回机器人方案。发送消息后无需追问、确认或接受降级,analysis.completed 与状态查询直接返回 match。信息不足时使用默认双足模板或可辨认的部位,缺单位、冲突和不支持的要求作为未验证项保留;组件仍须有STEP和URDF主文件引用;安装基准、位姿和资源清单问题作为提示,不阻塞已有组合。SSE 意外断开后任务继续执行,可查询恢复。此次流程优化复用已有五张需求表,无需调整表结构。对话拼装已收敛为 7 个接口,旧确认、重新匹配、按匹配编码查询及接受降级接口已删除;结果统一由消息事件和任务查询返回,需要刷新时发送新消息。

路径 方法
/admin-api/storage/upload-signature POST,新增签名、编辑签名、续签
/admin-api/components GET 分页列表,POST 新增
/admin-api/components/{id} GET 详情,PUT 全量表单修改,DELETE 逻辑删除
/admin-api/component-assets/{objectKey} GET 下载资源
/admin-api/users GET 分页列表,POST 新增
/admin-api/users/{id} GET 详情,PUT 修改,DELETE 逻辑删除
/admin-api/operation-logs GET 分页列表,支持通用目标与模块筛选
/admin-api/operation-logs/{id} GET 详情

统一响应为 {code, message, data, requestId},成功 code=OK。分页为 {items, page, size, total},页码从 1 开始,默认每页 20,上限 100。下载成功直接返回文件流。

接口库、端口、姿态和 BREP 路由已移除,Python 工具不再需要。旧上传会话、上传确认、封面和后台文件流上传路由均返回 404。

日志

当前业务操作日志仅持久化组件 CREATE / UPDATE / DELETE 的成功和失败。资源校验及替换结果归入对应保存事件。日志表、审计基础设施和查询仍支持其他业务模块。

日志保留目标主键、编码和名称快照,删除后仍可追溯;写入使用独立事务,失败不改变业务结果。签名、续签、查询、下载和用户管理只输出运行日志。日志不保存请求体、表单值、令牌、签名或敏感信息,定位使用请求编号、路由模板和安全的异常信息。

运行日志配置集中在 cadworld-common,输出 cadworld-adminapi.log 与 cadworld-adminapi-error.log,按时间和大小归档。Mapper 日志保持 INFO,避免输出 SQL 参数。

测试环境 Swagger:http://127.0.0.1:8992/swagger-ui.html;OpenAPI:/api-docs。

验证

mvn -pl cadworld-api,cadworld-adminapi -am test
mvn -pl cadworld-api,cadworld-adminapi -am -DskipTests package

自动测试通过 Java 在 H2 创建临时表,使用内存 OSS,不连接业务 MySQL、不执行业务数据库 DDL。覆盖签名与续签、资源校验及替换、默认值、自定义字段、版本冲突、审计、逻辑删除及目标快照、旧路由 404 和用户管理回归,并校验 OSS V4 签名策略。

真实 OSS 的独立测试需显式配置凭证并启用 oss-integration profile:

mvn -pl cadworld-adminapi -am -Poss-integration verify

该测试默认写入 cadworld_dev/verification/{UUID} 目录,完成后清理测试对象;可通过 -Dcadworld.it.oss-root-prefix=测试根目录 覆盖根目录,默认生产目录被禁止使用。清理失败时保留准确对象键记录,常规测试和打包不执行它。

S
Description
No description provided
Readme 2.5 MiB