Files
cadworld/README.md
T
2026-10-10 18:03:05 +08:00

117 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 和维护时间。通用日志存储模块、动作、目标快照、操作人、请求元信息和结果,不依赖组件专属列。
应用启动不建表、不迁移旧数据。本次未修改 `.sql` 文件;仓库中历史 SQL 不代表当前组件和日志结构,请使用已经建好的表。MySQL 需支持现有建表语句中的 JSON / TEXT 表达式默认值。
组件名称允许重复,编码唯一且不可修改。组件物理删除,用户逻辑删除;已删除用户的手机号仍被占用。组件替换资源或删除记录均不自动删除 OSS 文件。
## 配置与启动
```bash
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` 放在表单最后。凭证需有目标目录上传和读取权限。
对象路径:
```text
{环境根目录}/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。
完整请求、响应及浏览器上传代码见 [后台接口文档](cadworld-adminapi/docs/admin-api.md)。
| 路径 | 方法 |
| --- | --- |
| /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`。
## 验证
```bash
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:
```bash
mvn -pl cadworld-adminapi -am -Poss-integration verify
```
该测试默认写入 `cadworld_dev/verification/{UUID}` 目录,完成后清理测试对象;可通过 `-Dcadworld.it.oss-root-prefix=测试根目录` 覆盖根目录,默认生产目录被禁止使用。清理失败时保留准确对象键记录,常规测试和打包不执行它。