117 lines
7.5 KiB
Markdown
117 lines
7.5 KiB
Markdown
# 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=测试根目录` 覆盖根目录,默认生产目录被禁止使用。清理失败时保留准确对象键记录,常规测试和打包不执行它。
|