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-10 14:13:23 +08:00
2026-10-09 16:49:06 +08:00
2026-10-10 14:13:23 +08:00
2026-10-10 14:13:23 +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、阿里云 OSS、几何与资源校验
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

原有两个脚本保留不变。执行初始化或增量脚本后,还需执行下面的接口重构补充 SQL。当前业务使用五张表:sys_user、component、interface_definition_v2、interface_definition_revision、sys_operation_log;组件资源索引代码已移除。

用户删除保留数据及手机号唯一索引,已删除用户的手机号不能重新注册。组件删除沿用物理删除;接口删除保留历史修订,原接口 ID 不能再次创建。删除操作不会清理 OSS 中的资源对象。

接口重构补充 SQL

按项目约定,不改动 .sql 文件,新增结构单独提供。下面 SQL 需手动在目标数据库执行,可重复执行;应用不会自动迁移。先检查重复组件名,存在重复记录时需先整理,否则唯一索引无法建立。

-- 检查已有组件名称是否重复。
SELECT component_name, COUNT(*) AS duplicate_count
FROM component
GROUP BY component_name
HAVING COUNT(*) > 1;

SET @cadworld_edit_revision_ddl = IF(
    EXISTS (SELECT 1 FROM information_schema.COLUMNS
            WHERE TABLE_SCHEMA = DATABASE()
              AND TABLE_NAME = 'interface_definition_v2' AND COLUMN_NAME = 'edit_revision'),
    'SELECT 1',
    'ALTER TABLE interface_definition_v2 ADD COLUMN edit_revision BIGINT NOT NULL DEFAULT 1 COMMENT ''编辑版本号,每次修改或源文件绑定变化时递增,用于防止旧数据覆盖''');
PREPARE cadworld_edit_revision_statement FROM @cadworld_edit_revision_ddl;
EXECUTE cadworld_edit_revision_statement;
DEALLOCATE PREPARE cadworld_edit_revision_statement;

SET @cadworld_component_name_ddl = IF(
    EXISTS (SELECT 1 FROM information_schema.STATISTICS
            WHERE TABLE_SCHEMA = DATABASE()
              AND TABLE_NAME = 'component' AND INDEX_NAME = 'uk_component_name'),
    'SELECT 1',
    'ALTER TABLE component ADD UNIQUE KEY uk_component_name (component_name) COMMENT ''组件名称唯一索引,防止并发创建同名组件''');
PREPARE cadworld_component_name_statement FROM @cadworld_component_name_ddl;
EXECUTE cadworld_component_name_statement;
DEALLOCATE PREPARE cadworld_component_name_statement;

-- 该表只重复登记模型和封面对象键,业务代码已不依赖它。
DROP TABLE IF EXISTS component_asset;

前端联调变更见 后台接口文档:接口修改携带 editRevision 和 geometryRevision;组件修改携带 componentJson.componentRevision;原始文件 PUT 发送上传地址响应中的 uploadHeaders。版本冲突返回 HTTP 409,不覆盖其他人的修改。

配置与启动

cp .env.example .env
# 填写 .env 中的数据库和阿里云 OSS 参数。
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
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_API_BASE_URL 生成上传地址所用的后台外部地址
APP_STORAGE_PUBLIC_BASE_URL 生成下载地址的资源前缀,默认 /admin-api/component-assets
APP_STORAGE_MAX_UPLOAD_BYTES 文件上传大小限制,默认 104857600 字节;原始 PUT 流同样检查
APP_UPLOAD_SESSION_SECRET 至少 32 个 UTF-8 字节的上传签名密钥;留空时生成进程内随机密钥,重启后原上传会话失效
APP_ADMIN_OPERATOR_ID / APP_ADMIN_OPERATOR_NAME 测试操作人,默认 0 / TEST_OPERATOR
LOG_PATH 运行日志目录,默认 logs

运行时只使用阿里云 OSS,通过 HTTPS 和 V4 签名访问已有存储桶,不自动创建桶。账号需要对应目录下的上传、读取和删除权限。资源继续通过后台上传和读取,无需客户端直连 OSS;线上地址配置应包含实际域名及反向代理路径,上传和下载地址均使用 /admin-api 前缀。

数据库资源字段及 URDF 资源清单只保存桶内相对对象键,例如 cadworld_dev/components/urdf/.../robot.urdf;访问 URL 由后台生成,不入库。所有上传、入库和存储读写都校验当前环境根目录,完整 URL、跨环境路径或目录越界返回 422 / INVALID_STORAGE_OBJECT_KEY。根目录不要配置成完整 URL。新增路径包含根目录后的总长度仍受原字段限制。

本次切换不迁移历史 MinIO 文件或数据库记录,旧资源需要重新上传;切换后旧上传会话也需要重新创建。更改根目录会使原目录对象不能被当前环境访问。

接口文档: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 测试使用 SDK Mock、H2 和仅存在于测试代码中的内存资源替身,不连接共享数据库或真实 OSS。Python 测试包含程序生成的真实 STEP 文件及无效文件解析;缺少外部原始模型时,对应回归用例跳过。

MySQL 集成测试使用可清空的专用 cadworld_verification 数据库,验证初始化、升级、重复执行及数据保留,并运行业务接口用例。资源仍使用内存替身。准备独立 MySQL(默认 127.0.0.1:13306,root 空密码)后执行:

mvn -P integration verify

可通过 -Dcadworld.it.db-url=...、-Dcadworld.it.db-user=...、-Dcadworld.it.db-password=... 覆盖配置。测试会重建专用数据库中的业务表,并拒绝使用其他数据库名称。

真实 OSS 测试使用独立 Spring 上下文,不加载数据库,只通过以下入口显式启用:

# 先按启动说明加载 .env 中的 OSS 凭证。
mvn -P oss-integration verify

默认仅访问 cadworld_dev/verification/<本次UUID>/,可通过 -Dcadworld.it.oss-root-prefix=... 设置其他测试根目录;禁止使用默认生产目录 cadworld。测试验证上传、元数据、下载、未知长度超限保护及删除,仅清理本次创建的对象,不创建或删除存储桶。

若真实测试清理失败,未清理对象键会记录到 cadworld-adminapi/logs/oss-verification-pending/,供后续清理且不会被 mvn clean 删除。删除返回 AccessDenied 时,请检查当前凭证是否具有该目录的 oss:DeleteObject 权限,以及桶策略或保留策略是否限制删除;补齐权限后按记录清理。

S
Description
No description provided
Readme 2.5 MiB