Files

138 lines
13 KiB
Markdown
Raw Permalink 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`;用户端提供组件匹配与文字/图片需求解析,默认端口 `8991`。
## 项目模块
| 模块 | 内容 |
| --- | --- |
| cadworld-adminapi | 后台启动应用、Controller、Web 配置、运行日志和审计 |
| cadworld-service | 业务服务、Mapper、阿里云 OSS 签名、资源校验 |
| cadworld-bean | 实体、请求和响应 DTO、枚举 |
| cadworld-common | 统一响应、异常、JSON 类型处理、请求编号和操作目标上下文 |
| cadworld-api | 独立用户端 API:组件详情、匹配、需求会话、图文理解、自动选件与装配 |
| cadworld-security | 用户端及管理端 Spring Security、独立登录态、共用图片验证码与 Token 基础实现 |
用户端支持[邮箱与图片验证码登录](cadworld-api/docs/auth-api.md),首次自动注册,所有业务接口需要 Bearer Token。管理端支持[管理员邮箱登录](cadworld-adminapi/docs/auth-api.md),仅允许已启用的 ADMIN 账号,全部后台业务接口要求管理端 Bearer Token。上传会话和审计使用实际登录管理员。两端 Token 和验证码不能互用。
## 数据库
管理端访问 `component`、`sys_user`、`sys_operation_log`。用户端登录使用 `sys_user`,组件匹配复用 `component`,需求解析流程另外使用五张独立表;新增表的中文注释建表语句见 [需求流程建表说明](cadworld-api/docs/demand-schema.md),需要部署时手动执行,应用不自动建表。组件旋转轴字段 `rotation_axis` 的迁移 SQL 见 [管理端字段部署说明](cadworld-adminapi/docs/admin-api.md#43-旋转轴字段部署),部署两端新代码前须执行。
组件存储基本信息、自由度、旋转轴、功能、形状、大小描述、扭矩、BOM 清单、URDF 信息、两组自定义字段、STEP 对象键、URDF 目录及实际文件清单、`version`、`deleted` 删除标记和维护时间。旋转轴通过 `rotationAxis` 接收和返回,仅接受 `X`、`Y`、`Z`,未设置时为 null。BOM 和 URDF 信息均为 JSON 对象或数组,创建和修改必填 `urdfInfo`;可选 `bomList` 缺失或为 null 时写入 `[]`。列表返回旋转轴和描述字段,BOM 和 URDF 信息仅在详情及保存结果中返回。通用日志存储模块、动作、目标快照、操作人、请求元信息和结果,不依赖组件专属列。
用户登录改造发布前需手动执行[用户编码迁移 SQL](cadworld-api/docs/auth-api.md#4-发布前手动执行的迁移-sql)。应用启动不建表、不迁移旧数据。本次未修改 `.sql` 文件;仓库中历史 SQL 不代表当前组件和日志结构,请使用已经建好的表。MySQL 需支持现有建表语句中的 JSON / TEXT 表达式默认值。
组件名称允许重复,编码唯一且不可修改。新增编码为 `CW-` 加 16 位随机数字或大写字母(排除 `I/L/O/U`),总长 19,例如 `CW-7K3M9Q2R6V8X4T5N`;使用 80 位密码学安全随机空间,数据库唯一索引约束重复。旧版 35 字符编码和已有上传会话继续兼容,无需修改表结构或迁移已有编码。组件逻辑删除;用户删除入口改为禁用账号,可重新启用,邮箱仍被占用。已删除组件的编码仍被占用。组件替换资源或逻辑删除均不自动删除 OSS 文件。
现有 `component` 表包含 `deleted TINYINT UNSIGNED NOT NULL DEFAULT 0` 字段,中文注释为“删除标记:0-未删除,1-已删除”。运行代码通过 MyBatis-Plus 自动过滤已删除组件,列表、详情、修改和编辑上传签名均只处理未删除记录。
## 配置与启动
```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 默认关闭。
Maven 命令在仓库根目录执行。首次构建或共享模块新增 DTO、方法后,使用 `mvn install` 将所有模块的最新产物安装到本地仓库。只构建管理端或用户端时,分别使用 `mvn -pl cadworld-adminapi -am install`、`mvn -pl cadworld-api -am install`,`-am` 会同时构建它们依赖的模块。
在子模块目录直接执行 `mvn install` 不会重建兄弟模块,可能引用本地旧包并出现程序包不存在或“找不到合适的方法”等错误。可用 `-f` 指定根 POM,从任意目录构建;将下方路径替换为实际仓库路径:
```bash
mvn -f /path/to/cadworld/pom.xml -pl cadworld-api -am install
```
| 环境变量 | 用途 |
| --- | --- |
| APP_DB_URL / APP_DB_USERNAME / APP_DB_PASSWORD | MySQL 连接配置 |
| SERVER_PORT | 后台端口,默认 8992 |
| APP_ADMIN_ALLOWED_ORIGINS | 管理端 `/admin-api/**` 跨域白名单;`test` 默认 `https://dev-cadworld-admin.robotquan.com`,`prod` 默认 `https://cadworld-admin.robotquan.com`;可用逗号分隔的完整 origin 覆盖,显式留空关闭跨域,禁止通配符 |
| 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_AUTH_CAPTCHA_TTL / APP_ADMIN_AUTH_TOKEN_TTL | 管理端验证码与登录态有效期,默认 `PT2M / PT24H`;未设置时沿用通用 APP_AUTH_* 配置 |
| LOG_PATH | 运行日志目录,默认 `logs` |
运行时使用已有 OSS 桶,不自动创建桶。前端通过 OSS V4 表单签名直接上传,后端通过 HEAD 检查文件,资源下载仍由后台代理。OSS 需配置前端站点的 CORS,允许表单 POST;上传字段原样使用,`file` 放在表单最后。凭证需有目标目录上传和读取权限。
对象路径:
```text
{环境根目录}/components/{组件编码}/step/{上传批次}/{文件名}
{环境根目录}/components/{组件编码}/urdf/{上传批次}/{相对路径}
```
组件数据库中的文件键和目录前缀仅保存从 `components/` 开始的相对路径,不包含环境根目录或完整 URL;旧记录在再次成功保存时转换。上传授权、保存请求和详情响应仍使用带环境根目录的完整对象键,访问 URL 在响应时根据当前环境补全根目录并逐段编码。访问路径区分大小写;根目录不要填写 URL。跨环境上传、越界、非法路径会被拒绝。更改环境根目录不会移动 OSS 中的文件,新根目录须具备对应资源。
## 实例连接规则
先选定最符合需求的唯一躯干,再沿接口逐层选件。interfaceType 优先确定目标类型,缺失/无效时从 child 的 LINK_ 后解析现有类别;双方 frames[].child 严格一致才连接,name 不参与匹配。每个数组元素独立占用,同款组件可复用为多个实例;明确 quantity 优先,省略时填满所需类型的可匹配接口,单次最多24个实例。汇总和替代均按实例处理。
后端只返回实例及接口下标的连接关系,不再计算装配矩阵;原始 urdfInfo 保留,由前端决定摆放。组件类型统一使用[完整16类大写编码](cadworld-api/docs/api.md#36-角色映射),足部为 LEG_L/LEG_R/LEG_0;旧小写及 pedal_l/pedal_r 兼容输入。默认人形按实际接口选择 L/R/0,臂、手、足、脚各合计至少两个;六足需求使用 hexapod 模板,只要求躯干和 LEG/FOOT 各至少六个实例。接口仍为 0 接 0、L 接 L、R 接 R;其他未配置形态保留差异。历史结果通过新消息重新生成,无需数据库迁移。
## 上传与接口
上传只使用 `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)。
用户端接口入参、返回和公开模型加载见 [组件匹配文档](cadworld-api/docs/api.md);文字/图片理解、SSE 与自动生成装配方案见 [前端需求联调文档](cadworld-api/docs/robot-demand-api.md)。用户端部署变量、私有附件目录与接口连接约定见 [后端接入说明](cadworld-api/docs/demand-integration.md)。需求解析需配置后端 `ARK_API_KEY`;普通用户组件接口不需要管理员身份、上传令牌或 OSS 凭证。
AI 对话流程为:**文字/图片 → 理解需求 → 自动选件与装配校验 → 返回机器人方案**。发送消息后无需追问、确认或接受降级,`analysis.completed` 与状态查询直接返回 `match`。信息不足时使用默认双足模板或可辨认的部位,缺单位、冲突和不支持的要求作为未验证项保留;组件仍须有STEP和URDF主文件引用;安装基准、位姿和资源清单问题作为提示,不阻塞已有组合。SSE 意外断开后任务继续执行,可查询恢复。此次流程优化复用已有五张需求表,无需调整表结构。对话拼装已收敛为 7 个接口,旧确认、重新匹配、按匹配编码查询及接受降级接口已删除;结果统一由消息事件和任务查询返回,需要刷新时发送新消息。
| 路径 | 方法 |
| --- | --- |
| /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-api,cadworld-adminapi -am test
mvn -pl cadworld-api,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=测试根目录` 覆盖根目录,默认生产目录被禁止使用。清理失败时保留准确对象键记录,常规测试和打包不执行它。