2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00

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。

后台接口

响应沿用 {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。

S
Description
No description provided
Readme 2.5 MiB