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 不会重建兄弟模块,可能引用本地旧包并出现 com.linkerbot.cadworld.dto.auth 等程序包不存在的错误。
| 环境变量 | 用途 |
|---|---|
| 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=测试根目录 覆盖根目录,默认生产目录被禁止使用。清理失败时保留准确对象键记录,常规测试和打包不执行它。