admin/cadannotation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

跨域配置和接口文档

Browse Source
This commit is contained in:
lxp
2026-07-08 17:00:08 +08:00
parent bc18930b7a
commit 82255a6feb
2 changed files with 719 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cad-model-annotation-api.md
+657
View File
@@ -0,0 +1,657 @@
# CAD 模型与标注接口文档
面向前端联调使用，覆盖 `CadModelController` 与 `CadAnnotationController` 暴露的接口。
## 1. 通用约定
### 1.1 基础信息
| 项 | 说明 |
| --- | --- |
| 默认服务地址 | `http://localhost:8891` |
| 接口前缀 | `/api/cad-models` |
| 请求/响应格式 | `application/json` |
| 时间格式 | `yyyy-MM-dd HH:mm:ss`，时区 `Asia/Shanghai` |
| 字段命名 | JSON 使用小驼峰，如 `modelName` |
| 空字段 | 后端全局配置为 `non_null`，响应中的 `null` 字段默认不返回 |
### 1.2 统一响应结构
成功响应：
```json
{
"code": "OK",
"message": "success",
"data": {},
"requestId": "b3f8..."
}
```
失败响应：
```json
{
"code": "INVALID_REQUEST",
"message": "page 必须大于等于 1",
"requestId": "b3f8..."
}
```
### 1.3 常见状态码与错误码
| HTTP 状态码 | code | 说明 |
| --- | --- | --- |
| 200 | `OK` | 请求成功 |
| 404 | `NOT_FOUND` | 模型、建模历史、结构、功能或请求路径不存在 |
| 409 | `CAD_MODEL_DUPLICATE` | 修改模型时，同分类下源 SolidWorks 文件名已存在 |
| 422 | `INVALID_REQUEST` | 参数校验失败、请求体不合法、方法/媒体类型不支持 |
| 500 | `INTERNAL_ERROR` | 系统异常或数据库异常 |
### 1.4 分页响应结构
```json
{
"items": [],
"page": 1,
"size": 10,
"total": 0
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items` | array | 当前页数据 |
| `page` | number | 当前页码，从 1 开始 |
| `size` | number | 每页条数 |
| `total` | number | 总记录数 |
## 2. 模型接口
### 2.1 分页查询 CAD 模型列表
`GET /api/cad-models`
按创建时间倒序、ID 倒序返回模型列表。
#### Query 参数
| 参数 | 类型 | 必填 | 默认值 | 约束 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `page` | number | 否 | `1` | `>= 1` | 页码 |
| `size` | number | 否 | `10` | `1-100` | 每页条数 |
| `categoryId` | number | 否 | - | 正整数 | 分类 ID |
| `convertStatus` | string | 否 | - | `pending` / `success` / `failed` / `partial_failed` | 转换状态 |
| `keyword` | string | 否 | - | - | 关键字，匹配 `modelName` 或 `sourceSwFilename` |
#### 响应 data
`PageResponse<CadModel>`
```json
{
"code": "OK",
"message": "success",
"data": {
"items": [
{
"id": 1,
"categoryId": 10,
"modelName": "支架模型",
"sourceSwFilename": "bracket.SLDPRT",
"sourceSwPath": "uploads/bracket.SLDPRT",
"featureTreeJsonPath": "uploads/bracket-feature-tree.json",
"viewPath": "uploads/bracket.glb",
"applicationScenario": "机械装配",
"material": "铝合金",
"manufacturingMethod": "CNC",
"unit": "mm",
"userRequirement": "减重并保证强度",
"designDescription": "含多个孔位和倒角",
"convertStatus": "success",
"createdAt": "2026-07-08 16:20:00",
"updatedAt": "2026-07-08 16:20:00"
}
],
"page": 1,
"size": 10,
"total": 1
},
"requestId": "b3f8..."
}
```
### 2.2 查询 CAD 模型详情
`GET /api/cad-models/{id}`
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | number | 是 | 正整数 | 模型 ID |
#### 响应 data
`CadModel`
### 2.3 修改 CAD 模型基础信息
`POST /api/cad-models/{id}`
支持部分字段更新。请求体可为空；为空或所有字段均未传时不更新，直接返回当前模型详情。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | number | 是 | 正整数 | 模型 ID |
#### 请求体
| 字段 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `categoryId` | number | 否 | 正整数 | 分类 ID |
| `modelName` | string | 否 | 最大 255 字符 | 模型名称 |
| `sourceSwFilename` | string | 否 | 最大 255 字符 | 源 SolidWorks 文件名 |
| `sourceSwPath` | string | 否 | 最大 1024 字符 | 源文件路径 |
| `featureTreeJsonPath` | string | 否 | 最大 1024 字符 | 特征树 JSON 路径 |
| `viewPath` | string | 否 | 最大 1024 字符 | 预览文件路径 |
| `applicationScenario` | string | 否 | 最大 255 字符 | 应用场景 |
| `material` | string | 否 | 最大 255 字符 | 材料 |
| `manufacturingMethod` | string | 否 | 最大 255 字符 | 制造方式 |
| `unit` | string | 否 | 最大 64 字符 | 单位 |
| `userRequirement` | string | 否 | - | 用户需求 |
| `designDescription` | string | 否 | - | 设计说明 |
| `convertStatus` | string | 否 | `pending` / `success` / `failed` / `partial_failed`，最大 32 字符 | 转换状态 |
| `errorMessage` | string | 否 | - | 转换错误信息 |
同一 `categoryId` 下 `sourceSwFilename` 不能重复；当更新 `categoryId` 或 `sourceSwFilename` 时会触发唯一性校验。
#### 请求示例
```json
{
"modelName": "支架模型 V2",
"material": "6061 铝合金",
"unit": "mm"
}
```
#### 响应 data
`CadModel`
### 2.4 查询模型建模历史列表
`GET /api/cad-models/{modelId}/histories`
按 `historyIndex` 升序、ID 升序返回。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
#### 响应 data
`CadModelHistory[]`
```json
{
"code": "OK",
"message": "success",
"data": [
{
"id": 101,
"modelId": 1,
"sourceFeatureId": "Feat-Extrude1",
"historyIndex": 0,
"historyName": "拉伸",
"operationType": "Extrude",
"stepPath": "uploads/history/101.step",
"glbPath": "uploads/history/101.glb",
"convertStatus": "success",
"createdAt": "2026-07-08 16:20:00",
"updatedAt": "2026-07-08 16:20:00"
}
],
"requestId": "b3f8..."
}
```
## 3. 建模历史标注接口
### 3.1 保存建模历史步骤标注
`POST /api/cad-models/{modelId}/histories/{historyId}/annotation`
同一个建模历史只能有一条标注。重复保存时按 `historyId` 覆盖原有标注内容。请求体可为空；为空时三个文本字段均按 `null` 保存或覆盖。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
| `historyId` | number | 是 | 正整数 | 建模历史 ID，必须归属当前模型 |
#### 请求体
| 字段 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelingDescription` | string | 否 | - | 建模描述 |
| `supplementDescription` | string | 否 | - | 补充描述 |
| `remark` | string | 否 | - | 备注 |
#### 请求示例
```json
{
"modelingDescription": "通过草图轮廓进行基体拉伸",
"supplementDescription": "该步骤决定主体厚度",
"remark": "前端可作为历史步骤说明展示"
}
```
#### 响应 data
`CadModelHistoryAnnotation`
```json
{
"id": 201,
"modelId": 1,
"historyId": 101,
"modelingDescription": "通过草图轮廓进行基体拉伸",
"supplementDescription": "该步骤决定主体厚度",
"remark": "前端可作为历史步骤说明展示",
"createdAt": "2026-07-08 16:20:00",
"updatedAt": "2026-07-08 16:20:00"
}
```
## 4. 结构接口
### 4.1 创建 CAD 结构
`POST /api/cad-models/{modelId}/structures`
创建结构时必须选择至少一个建模历史步骤。结构与历史的关系按 `historyIds` 请求数组顺序保存，`sortOrder` 从 `0` 开始。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
#### 请求体
| 字段 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `structureName` | string | 是 | 非空，最大 255 字符 | 结构名称 |
| `structureType` | string | 否 | 最大 64 字符 | 结构类型，未传时保存为空字符串 |
| `purpose` | string | 否 | 最大 1024 字符 | 结构用途，未传时保存为空字符串 |
| `solution` | string | 否 | 最大 1024 字符 | 结构方案，未传时保存为空字符串 |
| `reason` | string | 否 | - | 结构原因 |
| `remark` | string | 否 | - | 备注 |
| `historyIds` | number[] | 是 | 非空、元素为正整数、不能重复、必须都归属当前模型 | 关联建模历史 ID 列表 |
#### 请求示例
```json
{
"structureName": "主体支撑结构",
"structureType": "支撑件",
"purpose": "承载上方组件并定位",
"solution": "基体拉伸后增加加强筋",
"reason": "提升抗弯能力",
"remark": "与历史步骤 101、102 关联",
"historyIds": [101, 102]
}
```
#### 响应 data
`CadStructure`
### 4.2 修改 CAD 结构
`POST /api/cad-models/{modelId}/structures/{structureId}`
普通字段支持部分更新，请求未传字段保持原值。请求体可为空；为空时不更新，返回当前结构详情。传入 `historyIds` 时，会按最终数组全量替换结构下的建模历史关系。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
| `structureId` | number | 是 | 正整数 | 结构 ID，必须归属当前模型且未逻辑删除 |
#### 请求体
| 字段 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `structureName` | string | 否 | 非空，最大 255 字符 | 结构名称 |
| `structureType` | string | 否 | 最大 64 字符 | 结构类型 |
| `purpose` | string | 否 | 最大 1024 字符 | 结构用途 |
| `solution` | string | 否 | 最大 1024 字符 | 结构方案 |
| `reason` | string | 否 | - | 结构原因 |
| `remark` | string | 否 | - | 备注 |
| `historyIds` | number[] | 否 | 非空、元素为正整数、不能重复、必须都归属当前模型 | 传入时全量替换关系；不传时关系不变 |
#### 请求示例
```json
{
"purpose": "承载上方组件并提供装配定位",
"historyIds": [101, 103, 104]
}
```
#### 响应 data
`CadStructure`
### 4.3 查询模型下结构列表
`GET /api/cad-models/{modelId}/structures`
只返回未逻辑删除的结构，按结构 ID 升序返回，并携带已关联的建模历史步骤。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
#### 响应 data
`CadStructure[]`
### 4.4 查询结构详情
`GET /api/cad-models/{modelId}/structures/{structureId}`
用于结构编辑回显，返回结构基础信息和已关联的建模历史步骤。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
| `structureId` | number | 是 | 正整数 | 结构 ID，必须归属当前模型且未逻辑删除 |
#### 响应 data
`CadStructure`
### 4.5 CadStructure 响应字段
```json
{
"id": 301,
"modelId": 1,
"structureName": "主体支撑结构",
"structureType": "支撑件",
"purpose": "承载上方组件并定位",
"solution": "基体拉伸后增加加强筋",
"reason": "提升抗弯能力",
"remark": "与历史步骤 101、102 关联",
"historyItems": [
{
"relationId": 401,
"historyId": 101,
"historyIndex": 0,
"historyName": "拉伸",
"operationType": "Extrude",
"sortOrder": 0
}
],
"createdAt": "2026-07-08 16:20:00",
"updatedAt": "2026-07-08 16:20:00"
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 结构 ID |
| `modelId` | number | 模型 ID |
| `structureName` | string | 结构名称 |
| `structureType` | string | 结构类型 |
| `purpose` | string | 结构用途 |
| `solution` | string | 结构方案 |
| `reason` | string | 结构原因 |
| `remark` | string | 备注 |
| `historyItems` | array | 关联建模历史步骤，按 `sortOrder` 升序 |
| `createdAt` | string | 创建时间 |
| `updatedAt` | string | 更新时间 |
`historyItems` 字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `relationId` | number | 结构-历史关系 ID |
| `historyId` | number | 建模历史 ID |
| `historyIndex` | number | 建模历史顺序号 |
| `historyName` | string | 建模历史名称 |
| `operationType` | string | 操作类型 |
| `sortOrder` | number | 关系排序，按请求数组顺序生成 |
## 5. 功能接口
### 5.1 创建 CAD 功能
`POST /api/cad-models/{modelId}/functions`
创建功能时必须选择至少一个结构。功能与结构的关系按 `structureIds` 请求数组顺序保存，`sortOrder` 从 `0` 开始。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
#### 请求体
| 字段 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `functionName` | string | 是 | 非空，最大 255 字符 | 功能名称 |
| `functionType` | string | 否 | 最大 64 字符 | 功能类型，未传时保存为空字符串 |
| `goalDescription` | string | 否 | - | 功能目标描述 |
| `remark` | string | 否 | - | 备注 |
| `structureIds` | number[] | 是 | 非空、元素为正整数、不能重复、必须都归属当前模型且未逻辑删除 | 关联结构 ID 列表 |
#### 请求示例
```json
{
"functionName": "承载与定位",
"functionType": "机械功能",
"goalDescription": "支撑外部载荷并限制装配自由度",
"remark": "由主体支撑结构和定位孔结构共同实现",
"structureIds": [301, 302]
}
```
#### 响应 data
`CadFunction`
### 5.2 修改 CAD 功能
`POST /api/cad-models/{modelId}/functions/{functionId}`
普通字段支持部分更新，请求未传字段保持原值。请求体可为空；为空时不更新，返回当前功能详情。传入 `structureIds` 时，会按最终数组全量替换功能下的结构关系。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
| `functionId` | number | 是 | 正整数 | 功能 ID，必须归属当前模型且未逻辑删除 |
#### 请求体
| 字段 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `functionName` | string | 否 | 非空，最大 255 字符 | 功能名称 |
| `functionType` | string | 否 | 最大 64 字符 | 功能类型 |
| `goalDescription` | string | 否 | - | 功能目标描述 |
| `remark` | string | 否 | - | 备注 |
| `structureIds` | number[] | 否 | 非空、元素为正整数、不能重复、必须都归属当前模型且未逻辑删除 | 传入时全量替换关系；不传时关系不变 |
#### 请求示例
```json
{
"goalDescription": "支撑外部载荷、定位并辅助装配",
"structureIds": [302, 301]
}
```
#### 响应 data
`CadFunction`
### 5.3 查询模型下功能列表
`GET /api/cad-models/{modelId}/functions`
只返回未逻辑删除的功能，按功能 ID 升序返回，并携带已关联的结构。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
#### 响应 data
`CadFunction[]`
### 5.4 查询功能详情
`GET /api/cad-models/{modelId}/functions/{functionId}`
用于功能编辑回显，返回功能基础信息和已关联的结构。
#### Path 参数
| 参数 | 类型 | 必填 | 约束 | 说明 |
| --- | --- | --- | --- | --- |
| `modelId` | number | 是 | 正整数 | 模型 ID |
| `functionId` | number | 是 | 正整数 | 功能 ID，必须归属当前模型且未逻辑删除 |
#### 响应 data
`CadFunction`
### 5.5 CadFunction 响应字段
```json
{
"id": 501,
"modelId": 1,
"functionName": "承载与定位",
"functionType": "机械功能",
"goalDescription": "支撑外部载荷并限制装配自由度",
"remark": "由主体支撑结构和定位孔结构共同实现",
"structureItems": [
{
"relationId": 601,
"structureId": 301,
"structureName": "主体支撑结构",
"structureType": "支撑件",
"sortOrder": 0
}
],
"createdAt": "2026-07-08 16:20:00",
"updatedAt": "2026-07-08 16:20:00"
}
```
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 功能 ID |
| `modelId` | number | 模型 ID |
| `functionName` | string | 功能名称 |
| `functionType` | string | 功能类型 |
| `goalDescription` | string | 功能目标描述 |
| `remark` | string | 备注 |
| `structureItems` | array | 关联结构，按 `sortOrder` 升序 |
| `createdAt` | string | 创建时间 |
| `updatedAt` | string | 更新时间 |
`structureItems` 字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `relationId` | number | 功能-结构关系 ID |
| `structureId` | number | 结构 ID |
| `structureName` | string | 结构名称 |
| `structureType` | string | 结构类型 |
| `sortOrder` | number | 关系排序，按请求数组顺序生成 |
## 6. 公共数据结构
### 6.1 CadModel
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 模型 ID |
| `categoryId` | number | 分类 ID |
| `modelName` | string | 模型名称 |
| `sourceSwFilename` | string | 源 SolidWorks 文件名 |
| `sourceSwPath` | string | 源文件路径 |
| `featureTreeJsonPath` | string | 特征树 JSON 路径 |
| `viewPath` | string | 预览文件路径 |
| `applicationScenario` | string | 应用场景 |
| `material` | string | 材料 |
| `manufacturingMethod` | string | 制造方式 |
| `unit` | string | 单位 |
| `userRequirement` | string | 用户需求 |
| `designDescription` | string | 设计说明 |
| `convertStatus` | string | 转换状态：`pending` / `success` / `failed` / `partial_failed` |
| `errorMessage` | string | 转换错误信息 |
| `createdAt` | string | 创建时间 |
| `updatedAt` | string | 更新时间 |
### 6.2 CadModelHistory
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 建模历史 ID |
| `modelId` | number | 模型 ID |
| `sourceFeatureId` | string | 源特征 ID |
| `historyIndex` | number | 历史步骤顺序号 |
| `historyName` | string | 历史步骤名称 |
| `operationType` | string | 操作类型 |
| `stepPath` | string | STEP 文件路径 |
| `glbPath` | string | GLB 文件路径 |
| `convertStatus` | string | 转换状态 |
| `errorMessage` | string | 转换错误信息 |
| `createdAt` | string | 创建时间 |
| `updatedAt` | string | 更新时间 |
### 6.3 CadModelHistoryAnnotation
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 标注 ID |
| `modelId` | number | 模型 ID |
| `historyId` | number | 建模历史 ID |
| `modelingDescription` | string | 建模描述 |
| `supplementDescription` | string | 补充描述 |
| `remark` | string | 备注 |
| `createdAt` | string | 创建时间 |
| `updatedAt` | string | 更新时间 |
## 7. 前端联调注意事项
1. 所有 Path ID 都必须是正整数。
2. `POST` 更新类接口采用部分更新语义；字段未传表示不修改，字段传空字符串表示按空字符串更新。
3. 创建结构/功能时，关联 ID 数组必传且不能为空；更新结构/功能时，只有传入关联 ID 数组才会全量替换关系。
4. `historyIds` 和 `structureIds` 不能包含重复值；数组顺序会影响响应中的 `sortOrder`。
5. 结构、功能列表接口只返回未逻辑删除的数据。
6. 前端排查问题时可记录响应中的 `requestId`，便于后端按请求链路定位日志。
src/main/java/com/cadlabel/config/CorsConfig.java
+62
View File
@@ -0,0 +1,62 @@
package com.cadlabel.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* 跨域配置类
*
* @author robotquan
*/
@Configuration
public class CorsConfig implements WebMvcConfigurer {
/**
* 跨域配置
*/
@Override
public void addCorsMappings(CorsRegistry registry) {
// 设置允许跨域的路径
registry.addMapping("/**")
// 设置允许跨域请求的域名
.allowedOriginPatterns("*")
// 是否允许cookie
.allowCredentials(true)
// 设置允许的请求方式
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
// 设置允许的header属性
.allowedHeaders("*")
// 跨域允许时间
.maxAge(3600);
}
/**
* 跨域过滤器
*/
@Bean
public CorsFilter corsFilter() {
CorsConfiguration config = new CorsConfiguration();
// 允许所有域名进行跨域调用
config.addAllowedOriginPattern("*");
// 允许所有请求头
config.addAllowedHeader("*");
// 允许所有请求方法
config.addAllowedMethod("*");
// 允许发送Cookie信息
config.setAllowCredentials(true);
// 预检请求的缓存时间（秒）
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
// 对所有路径应用跨域配置
source.registerCorsConfiguration("/**", config);
return new CorsFilter(source);
}
}