cadworld
Java 21 / Spring Boot 3.4.4 / MyBatis-Plus 后台多模块项目。包名统一为 com.linkerbot.cadworld,Maven groupId 为 com.linkerbot。当前包含接口库、组件库、用户管理和操作日志,默认端口 8992。
模块
| 模块 | 内容 |
|---|---|
| cadworld-adminapi | 后台启动应用、Controller、Web 配置、操作日志拦截 |
| cadworld-service | 业务服务、Mapper、MinIO/本地存储、几何与资源校验 |
| cadworld-bean | 实体、DTO、枚举 |
| cadworld-common | 响应、异常、JSON 类型处理、请求编号、进程执行工具 |
| cadworld-api | 预留前台 API 模块 |
| cadworld-security | 预留 admin/api/common 三个安全子模块 |
本阶段后台接口不鉴权,没有登录、角色或菜单权限接口。日志和上传流程统一使用配置的测试操作人,默认 0 / TEST_OPERATOR,不要求 sys_user 中存在该用户。上传会话签名用于限制会话类型、对象目录及有效期,与账号登录认证独立。
数据库准备
默认测试库为 39.105.93.138:3306/cadworld,账号和密码必须自行通过环境变量提供。应用启动不执行建表或迁移。
已有库包含所给 cadworld.sql 中的 sys_user 和 component 表时,执行增量脚本:
mysql -h 39.105.93.138 -P 3306 -u YOUR_USER -p cadworld < db/upgrade.sql
对于已经创建好的空数据库,执行初始化脚本:
mysql -h 39.105.93.138 -P 3306 -u YOUR_USER -p cadworld < db/init.sql
两个脚本均可重复执行,不包含删表语句、数据改写或 Flyway 历史处理。增量脚本新增接口定义、历史修订、组件资源索引、操作日志表,并为 sys_user 增加 deleted。仅初始化本次业务需要的六张表;原系统其他业务表无需迁移。
用户删除保留数据及手机号唯一索引,已删除用户的手机号不能重新注册。组件删除沿用物理删除及资源索引级联清理;接口删除保留历史修订,原接口 ID 不能再次创建。删除操作不会清理 MinIO 中的资源对象。
配置与启动
cp .env.example .env
# 填写 .env 中的数据库和 MinIO 参数。
set -a
source .env
set +a
mvn clean verify
java -jar cadworld-adminapi/target/cadworld-adminapi-0.0.1-SNAPSHOT.jar
.env 通过 shell 导入,Spring Boot 不自动读取该文件。默认 profile 为 test;使用 prod 时必须设置 APP_DB_URL、APP_DB_USERNAME、APP_DB_PASSWORD,Swagger 默认关闭。
| 环境变量 | 用途 |
|---|---|
| APP_DB_URL / APP_DB_USERNAME / APP_DB_PASSWORD | MySQL 连接配置 |
| SERVER_PORT | 后台端口,默认 8992 |
| APP_STORAGE_PROVIDER | 默认 minio;支持 local 用于本地开发和测试 |
| APP_MINIO_ENDPOINT / APP_MINIO_ACCESS_KEY / APP_MINIO_SECRET_KEY / APP_MINIO_BUCKET | MinIO 连接及 bucket,均需配置 |
| APP_STORAGE_PUBLIC_API_BASE_URL | 生成上传地址所用的后台外部地址 |
| APP_STORAGE_PUBLIC_BASE_URL | 生成下载地址的资源前缀,默认 /admin-api/component-assets |
| APP_STORAGE_LOCAL_ROOT | 本地存储目录,默认 ./data/assets |
| APP_UPLOAD_SESSION_SECRET | 至少 32 个 UTF-8 字节的上传签名密钥;留空时生成进程内随机密钥,重启后原上传会话失效 |
| APP_ADMIN_OPERATOR_ID / APP_ADMIN_OPERATOR_NAME | 测试操作人,默认 0 / TEST_OPERATOR |
| LOG_PATH | 运行日志目录,默认 logs |
资源通过后台上传和读取,无需客户端直连 MinIO。MinIO 实现首次使用时检查 bucket,不存在时尝试创建,因此账号需有对应权限。线上地址配置应包含实际域名及反向代理路径,上传和下载地址均使用 /admin-api 前缀。
接口文档:http://127.0.0.1:8992/swagger-ui.html;OpenAPI:/api-docs。日志配置集中在 cadworld-common,按应用名输出 cadworld-adminapi.log 和独立的 cadworld-adminapi-error.log,并携带请求编号。普通日志按天及 100 MB 滚动,保留 30 天、最多 10 GB;ERROR 日志按天及 50 MB 滚动,保留 60 天、最多 5 GB。归档文件保存在 logs/archive(支持 LOG_PATH 覆盖)。测试环境项目包日志为 DEBUG,生产环境为 INFO;Mapper 日志保持 INFO,避免 SQL 参数输出敏感数据。
全部后台业务接口通过 @ApiRequestLog 提供中文说明,统一输出请求开始与结束日志,包含路由模板、请求编号、结果、HTTP 状态、业务错误码及耗时。成功记录 INFO,业务或参数失败记录 WARN,服务异常记录 ERROR。文件流上传、下载以及 MVC 之前的 multipart 超限也覆盖;不输出请求体、查询参数、文件内容或完整对象路径。接口运行日志写入运行日志文件;数据库操作日志继续按组件库和接口库写操作的既有范围记录。
后台接口
前端联调文档:后台接口文档,按模块列出全部业务接口、入参及返回示例、上传流程和错误处理。
响应沿用 {code, message, data, requestId},分页数据为 {items, page, size, total}。新建用户和操作日志列表的页码从 1 开始,默认每页 20,最多 100。
| 路径 | 方法及行为 |
|---|---|
| /admin-api/interfaces | GET 列表(keyword),POST 创建 |
| /admin-api/interfaces/{id} | GET 详情,PUT 修改,DELETE 删除 |
| /admin-api/interfaces/{id}/assets | POST 源文件上传,参数 geometryRevision、file |
| /admin-api/interfaces/{id}/pose-candidates | POST 计算姿态候选 |
| /admin-api/interfaces/{id}/confirm-port | POST 校验并确认端口 |
| /admin-api/interface-brep/analyze | POST multipart STEP/STP 精确解析 |
| /admin-api/components | GET 分页列表(page、size、keyword),POST 创建 |
| /admin-api/components/{id} | GET 详情,PUT 修改,DELETE 删除 |
| /admin-api/components/cover-image-upload-sessions | POST 创建封面上传会话;子路径 /upload-url、/complete 均为 POST |
| /admin-api/components/urdf-upload-sessions | POST 创建 URDF/RFS 上传会话;子路径 /upload-url、/complete 均为 POST |
| /admin-api/component-assets/upload | PUT 文件流上传,参数 objectKey |
| /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 日志详情 |
用户创建及修改请求示例:
{"phone":"13812345678","nickname":"测试用户","status":"ACTIVE","userType":"NORMAL"}
手机号为大陆手机号,昵称必填且最多 64 字符;状态为 ACTIVE/DISABLED,用户类型为 NORMAL/ADMIN。创建时省略状态和类型默认为 ACTIVE/NORMAL,修改时省略则保留原值。用户列表支持 keyword(手机号/昵称)、userType、status 筛选,查询排除已逻辑删除用户。
操作日志列表支持 module(COMPONENT/INTERFACE)、action、success、operatorId、from、to。时间使用上海时区的 ISO 本地时间,例如 2026-10-09T16:00:00。
日志动作:CREATE、UPDATE、DELETE、PREPARE_UPLOAD、PREPARE_UPLOAD_URL、UPLOAD、COMPLETE_UPLOAD。成功及失败的写操作均记录;查询、下载、STEP 分析、姿态计算及用户管理不记录业务操作日志。日志只保存操作元信息和标识,不保存请求体、文件或上传令牌;日志持久化使用独立事务,失败时输出运行错误日志并保留原请求结果。
STEP 解析运行环境
建议使用 Python 3.12,OCCT 依赖锁定为 cadquery-ocp==7.8.1.1:
python3.12 -m venv cadworld-adminapi/.venv
cadworld-adminapi/.venv/bin/pip install -r cadworld-adminapi/requirements-interface-brep.txt
export APP_INTERFACE_BREP_PYTHON="$PWD/cadworld-adminapi/.venv/bin/python"
解析脚本包含在后台 JAR 中,每次分析提取到临时目录并在完成后清理。APP_INTERFACE_BREP_SCRIPT 可覆盖为外部脚本路径。默认超时 120 秒、上传及输出限制各 100 MB,可使用 APP_INTERFACE_BREP_TIMEOUT_SECONDS、APP_INTERFACE_BREP_MAX_UPLOAD_BYTES、APP_INTERFACE_BREP_MAX_OUTPUT_BYTES 调整;上传体积还受 Spring multipart 限制。
接口解析仅使用 OCCT 原生 STEP B-Rep。缺少运行库、解析失败、超时及输出过大返回明确错误,不回退到三角网格拟合。
验证
mvn clean verify
cadworld-adminapi/.venv/bin/python -m unittest discover -s cadworld-adminapi/scripts/tests
默认 Java 测试使用 Mock/H2 和本地临时资源目录,不连接共享数据库或 MinIO。可选集成测试使用专用可清空的 cadworld_verification 数据库,并执行初始化、升级、重复执行及数据保留检查,再将相同的用户/组件/接口/日志/上传用例运行于 MySQL 和 MinIO。
Python 测试包含程序生成的真实 STEP 文件及无效文件解析;另有一个依赖外部原始模型的回归用例,缺少该模型时跳过,不会复制来源项目的业务资源。
准备独立 MySQL(默认 127.0.0.1:13306,数据库 cadworld_verification,root 空密码)及独立 MinIO(默认 127.0.0.1:19000,账号 cadworld-test,密码 cadworld-test-secret),执行:
mvn -P integration verify
可通过 -Dcadworld.it.db-url=...、-Dcadworld.it.db-user=...、-Dcadworld.it.db-password=...、-Dcadworld.it.minio-endpoint=...、-Dcadworld.it.minio-user=...、-Dcadworld.it.minio-password=... 覆盖测试服务配置。集成测试会重建该专用数据库中的业务表,并拒绝使用其他数据库名称;MinIO 使用专用 cadworld-verification bucket。