2026-10-12 13:09:12 +08:00
2026-10-12 13:09:12 +08:00
2026-10-09 16:49:06 +08:00
2026-10-12 13:09:12 +08:00
2026-10-12 11:43:36 +08:00
2026-10-09 16:49:06 +08:00
2026-10-12 13:09:12 +08:00
2026-10-09 16:49:06 +08:00
2026-10-09 16:49:06 +08:00
2026-10-10 18:03:05 +08:00
2026-10-09 16:49:06 +08:00
2026-10-12 11:43:36 +08:00
2026-10-10 14:13:23 +08:00
2026-10-12 13:09:12 +08:00

cadworld

Java 21 / Spring Boot 3.4.4 / MyBatis-Plus 后台多模块项目。后台只保留组件库、用户管理和操作日志,默认端口 8992。

项目模块

模块 内容
cadworld-adminapi 后台启动应用、Controller、Web 配置、运行日志和审计
cadworld-service 业务服务、Mapper、阿里云 OSS 签名、资源校验
cadworld-bean 实体、请求和响应 DTO、枚举
cadworld-common 统一响应、异常、JSON 类型处理、请求编号和操作目标上下文
cadworld-api 预留前台 API 模块
cadworld-security 预留安全子模块

当前没有登录和权限接口。上传和审计使用配置操作人,默认 0 / TEST_OPERATOR,无需在 sys_user 中创建对应记录。上传会话令牌绑定操作人、组件、上传批次和资源目录。

数据库

运行代码只访问 component、sys_user、sys_operation_log 三张业务表。使用已重建的组件表和通用操作日志表;sys_user 结构和用户管理行为保持不变。

组件存储基本信息、零件参数、两组自定义字段、STEP 对象键、URDF 目录及实际文件清单、version、deleted 删除标记和维护时间。通用日志存储模块、动作、目标快照、操作人、请求元信息和结果,不依赖组件专属列。

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

组件名称允许重复,编码唯一且不可修改。组件和用户均逻辑删除;已删除组件的编码和已删除用户的手机号仍被占用。组件替换资源或逻辑删除均不自动删除 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 默认关闭。

环境变量 用途
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_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_OPERATOR_ID / APP_ADMIN_OPERATOR_NAME 当前配置操作人,默认 0 / TEST_OPERATOR
LOG_PATH 运行日志目录,默认 logs

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

对象路径:

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

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

上传与接口

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

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

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

路径 方法
/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-adminapi -am clean test
mvn -pl 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