195 lines
17 KiB
Markdown
195 lines
17 KiB
Markdown
# CAD 个人工作空间前端对接
|
||
|
||
网页 AI 助手使用独立的 `/api/cad/ai` 接口,复用平台登录,工具由浏览器执行;接口、工具循环、停止及撤销适配见 [CAD Web AI Agent 对接](frontend-cad-ai-agent.md)。AI 修改仍通过本文的原生 `.sc` 流程手动保存。
|
||
|
||
CAD 与 Vibemake 共用 `/api/auth/login`、`/api/auth/logout` 和 `/api/users/me`,使用同一个 `Authorization: Bearer <平台 token>`。CAD 工作空间使用独立的列表和保存接口,不创建 Git 仓库、不自动发布社区;可独立创建,也可从 `/api/workspace/projects` 中带 STEP 的本人项目创建关联。云端保存只支持当前用户的单个自包含原生 `.sc` 设计文件,不管理外部引用的多文件装配;STEP 仅作为前端首次导入来源。
|
||
|
||
文件沿用现有 OSS 资源规则:上传继承 Bucket 权限,读取使用 `OSS_PUBLIC_BASE_URL` 对应的普通 OSS/CDN 地址。工作空间和平台接口按用户隔离,文件直链的访问权限由现有 Bucket/CDN 配置决定;公开配置下,拿到直链即可读取文件。
|
||
|
||
数据库的当前文件和上传批次只保存 `/cad-projects/{项目编码}/{批次编码}/design.sc`,不含环境前缀;上传签名的 `formFields.key` 和实际访问地址仍包含当前环境根目录,前端原样使用。所有资源的存储规范及历史数据转换 SQL 见 [OSS 引用规范](oss-storage-paths.md)。
|
||
|
||
通用响应、上海时间格式、分页和跨域规则沿用 [Vibemake 接入约定](vibemake-api.md#接入约定)。CAD 所有接口返回 `Cache-Control: no-store`。业务编码为不透明字符串,不使用数据库 ID。
|
||
|
||
## 接口与数据
|
||
|
||
下表前缀为 `/api/cad/workspace/projects`。全部需要登录,成功均为 HTTP 200,JSON 为 `{code,message,data,requestId}`。
|
||
|
||
| 方法 | 相对路径 | 请求 | 成功 data |
|
||
| --- | --- | --- | --- |
|
||
| GET | 空 | `page=1&size=20&keyword=名称` | 项目分页 |
|
||
| POST | 空 | `{name,description?,coverUrl?}` | 项目 |
|
||
| GET | `/{cadProjectCode}` | 无 | 项目 |
|
||
| PATCH | `/{cadProjectCode}` | `{name?,description?,coverUrl?}` | 项目 |
|
||
| DELETE | `/{cadProjectCode}` | 无 | null |
|
||
| POST | `/{cadProjectCode}/uploads/signature` | `{fileName,sizeBytes,expectedVersion}` | 上传签名 |
|
||
| PUT | `/{cadProjectCode}/document` | `{uploadCode}` | 保存回执 |
|
||
| GET | `/{cadProjectCode}/document` | 无 | 文件读取信息 |
|
||
|
||
名称必填,去除首尾空白后 1~100 字符;描述最多 2000 字符,新建时默认空字符串。`coverUrl` 可选,传完整 HTTPS 地址,最多 2048 字符;新建省略、null 或空白表示没有封面。PATCH 省略或 null 表示保留,描述或封面传 `""` 可清空,至少提供一个非 null 字段。
|
||
|
||
项目:
|
||
|
||
```ts
|
||
interface CadProject {
|
||
cadProjectCode: string;
|
||
workspaceProjectCode: string | null; // 关联的当前工作区项目编码,独立项目为 null
|
||
initialStep: CadInitialStep | null; // 创建关联时固定的 STEP 来源,保存 .sc 后仍保留
|
||
name: string;
|
||
description: string;
|
||
coverUrl: string | null; // 完整 OSS/CDN 地址,无封面为 null
|
||
hasDocument: boolean;
|
||
version: number;
|
||
fileName: string;
|
||
sizeBytes: number;
|
||
savedAt: string | null;
|
||
createdAt: string;
|
||
updatedAt: string;
|
||
}
|
||
interface CadInitialStep {
|
||
downloadUrl: string; // 普通 OSS/CDN 地址,无临时签名
|
||
fileName: string; // 保留原始 STEP/STP 文件名、中文和大小写
|
||
sizeBytes: number;
|
||
}
|
||
interface CadUploadSignature {
|
||
uploadCode: string;
|
||
uploadUrl: string;
|
||
formFields: Record<string, string>;
|
||
expiresAt: string;
|
||
}
|
||
interface CadSaveResult {
|
||
cadProjectCode: string;
|
||
version: number;
|
||
savedAt: string;
|
||
}
|
||
interface CadDocument {
|
||
downloadUrl: string;
|
||
expiresAt: null;
|
||
version: number;
|
||
fileName: string;
|
||
sizeBytes: number;
|
||
}
|
||
```
|
||
|
||
新项目 `hasDocument=false、version=0、fileName=""、sizeBytes=0、savedAt=null`,未提供封面时 `coverUrl=null`。独立创建的项目 `workspaceProjectCode=null、initialStep=null`;有关联的 STEP 不代表已经保存了 `.sc`。列表、详情、创建及修改结果均包含相同的封面、关联编码和初始 STEP 字段。列表只包含本人未删除项目,按最近更新时间倒序;支持名称包含搜索。`page` 为 1~100000,`size` 为 1~100,默认 20,返回 `{items,page,size,total}`。同名项目允许存在。改名、描述和封面修改不改变文件保存版本或 savedAt。
|
||
|
||
## 从个人空间 STEP 项目进入编辑器
|
||
|
||
本人工作区项目详情中,`repoStatus === 'READY'` 且 `stepMainUrl` 非空时显示“编辑”。Fork 已复制 STEP 路径、文件名和大小,因此使用 Fork 后当前用户的 `projectCode`,不使用上游来源项目编码。
|
||
|
||
点击后调用以下接口,无请求体,平台 Token 放在 Authorization 请求头:
|
||
|
||
```http
|
||
POST /api/workspace/projects/{projectCode}/cad-project
|
||
```
|
||
|
||
成功 HTTP 200,`data` 为上述 `CadProject`,响应 `Cache-Control: no-store`。前端使用返回的 `cadProjectCode` 进入现有 CAD 编辑器路由,不把 Token 放 URL。首次创建继承当前项目的名称、描述、封面及 STEP 引用;重复点击、请求超时重试或多标签页并发均复用同一个有效关联,不自动重复创建。不同用户的 Fork 各自创建关联 CAD。请求使用 `cad-read` 限流,实际创建额外使用 `cad-create`,复用不消耗创建额度。
|
||
|
||
编辑器按以下顺序打开,包括直接从 CAD 工作空间进入的情况:
|
||
|
||
1. 读取 `GET /api/cad/workspace/projects/{cadProjectCode}` 的最新详情。
|
||
2. `hasDocument=true` 时使用 `GET .../{cadProjectCode}/document` 下载 `.sc` 并打开,以 `document.version` 作为编辑基础版本。读取失败显示错误并允许重试,不自动退回 STEP,避免用户误以为已有编辑丢失。
|
||
3. `hasDocument=false` 且 `initialStep` 非空时,fetch `initialStep.downloadUrl`,将原始文件字节和 `fileName` 交给编辑器的 STEP/STP 导入能力。导入失败保留同一个关联,提供重试;不创建新 CAD。
|
||
4. 导入成功后视为尚未云端保存,首次保存由前端导出完整 `.sc`,使用 `expectedVersion=0` 走原有上传签名与确认流程。后端不解析或转换 STEP,不把 STEP 当作已保存的原生文档,原生上传接口仍只接受 `.sc`。
|
||
5. `hasDocument=false` 且 `initialStep=null` 时进入普通空设计。
|
||
|
||
`initialStep` 固定为创建关联时的引用;工作区 STEP 替换或移除、名称描述封面变更均不覆盖已有关联 CAD,也不回写原工作区项目。后续保存的 `.sc` 是重新打开时的首选。STEP 的默认资源上限为 500 MiB,原始文件名最多 1024 字符;不套用 `.sc` 的 256 MiB 和 255 字符限制,前端需按编辑器实际能力处理导入错误,导出 `.sc` 后仍受 CAD 保存大小限制。
|
||
|
||
无关联且当前项目无 STEP 返回 `409 PROJECT_STEP_NOT_FOUND`;仓库未 READY 返回 `409 CONFLICT`;项目非本人、不存在或已删除返回 `404 NOT_FOUND`。已有关联时,即使 STEP 已移除,直接调用关联接口仍返回原 CAD;页面不再显示该“编辑”入口,用户仍可从 CAD 工作空间进入。
|
||
|
||
删除工作区项目不删除 CAD,已有 CAD 可独立打开和继续保存;删除 CAD 会释放关联,工作区仍有 STEP 时再次“编辑”创建新 CAD。删除前的 CAD 编码继续不可访问,不提供恢复。
|
||
|
||
## 项目封面
|
||
|
||
复用 [已有封面上传](vibemake-api.md#项目封面与-oss-直传) 的 `POST /api/uploads/project-covers/signature`,无需 CAD 项目编码,也不会创建 Git 项目。请求 `{contentType,fileSize}`,支持 JPG、PNG、WebP,最大 5 MiB;使用同一平台 Token 申请签名,取得 `uploadUrl、formFields、coverUrl`。
|
||
|
||
将全部 formFields 和图片通过 FormData 直传 OSS,不携带平台 Token。上传成功后,将签名返回的完整 `coverUrl` 放入新建请求,或提交 `PATCH /api/cad/workspace/projects/{cadProjectCode}`:
|
||
|
||
```json
|
||
{"coverUrl":"https://你的OSS或CDN域名/vibemake_dev/project-covers/用户编码/日期/文件名.png"}
|
||
```
|
||
|
||
封面上传遵循现有 `OSS_ENABLED` 开关和 OSS 规则;CAD 的 `.sc` 独立存储开关不代替封面上传开关。可以由前端截取 CAD 画布生成图片,后台不自动生成或更新封面。
|
||
|
||
平台托管封面在数据库 `cad_project.cover_url` 中保存 `/project-covers/...` 等无环境前缀的未编码路径;列表、详情和创建/修改结果中的 coverUrl 自动补当前环境前缀及 OSS/CDN 地址。沿用现有封面规则接受外部 HTTPS 图片链接并原样保存,不接受直接提交数据库相对路径。
|
||
|
||
只修改封面不更新 `.sc` 文件或版本,保存 `.sc` 也不会清空封面。换图、清空封面和删除 CAD 项目均不删除旧 OSS 图片。已有数据库部署前先执行 [CAD 封面增量 SQL](cad-database.md#已有数据库增加-cad-项目封面)。
|
||
|
||
## 保存和重新打开
|
||
|
||
1. 独立新设计首次保存先创建项目,保留返回的 `cadProjectCode` 和 `version=0`;从工作区进入的关联 CAD 直接复用返回的项目编码,不再创建空项目。
|
||
2. 使用 SolidCraft 原生序列化生成完整 `.sc`,不能仅上传 STL、STEP、GLB 或显示网格;原生文件保留参数及可编辑设计。需要由前端接通原生文件导出和导入桥接,当前本机/浏览器保存不等于云端保存。
|
||
3. 文件名须为不含路径和控制字符的 `.sc` 名称,最多 255 字符。文件非空,默认上限 268435456 字节(256 MiB)。`sizeBytes` 和 `expectedVersion` 必须是 JSON 整数,不接受字符串或小数。
|
||
4. 申请签名,将 `formFields` 全部原样写入 FormData,最后追加 `file`,POST 到 `uploadUrl`。不携带平台 Authorization,不手写 multipart Content-Type。OSS 成功为 HTTP 200,无需解析 JSON。
|
||
5. 上传完成后提交原 `uploadCode` 确认。后端核验对象大小、批次归属、截止时间和基础版本,成功才更新当前设计引用,并返回新版本。
|
||
6. 只有确认成功才显示云端已保存;序列化期间及上传期间又产生的修改仍应标为未保存。每个项目前端串行执行云端保存。
|
||
7. 打开项目先读详情;`hasDocument=true` 时 GET `document`,fetch `downloadUrl` 得到原始文件字节并交给 SolidCraft 打开;未保存且有 `initialStep` 时按上节导入 STEP,普通空项目进入新设计。**本次编辑基础版本使用 `document.version`**,文件与版本来自同一快照,不混用先前详情中的版本。
|
||
|
||
上传签名默认 15 分钟,未确认批次同一时刻过期;文件上传完成但确认已过期时,重新申请批次。`downloadUrl` 为普通 OSS/CDN 文件地址,不附加临时下载签名,`expiresAt` 为兼容前端保留且固定返回 null;前端直接读取地址,不做下载签名续期。业务时间为上海时间字符串,无时区后缀,解析时补 `+08:00`。
|
||
|
||
相同 `uploadCode` 重复确认返回首次保存回执,不重复增加版本。即使之后已有更新版本,重试旧批次也不会恢复旧文件;回执版本可能小于最新项目版本,需要时重新读取详情。网络超时先保留原批次并重试确认,不直接创建新项目或新批次。上传使用现有 `signObject` 策略及其禁止覆盖参数,每次申请使用新的批次对象键;OSS 上传超时先尝试确认,缺文件再处理上传,不无条件重复上传。
|
||
|
||
两个标签页使用相同基础版本保存时,只有一个成功,另一个收到 `CAD_VERSION_CONFLICT`。保留本地修改并提供重新打开最新设计、下载本地副本或另存新项目的处理入口;不能只换成最新版本号后自动覆盖。
|
||
|
||
离开、切换项目、退出登录前提示未保存修改。401 后保留设计并引导重新登录,重新登录后核对当前账号和项目归属再继续保存。推荐部署同源的可编辑 SolidCraft 构建;iframe 跨源集成如使用 postMessage,须校验 source 和精确 origin,平台 Token 不放 URL。现有 `?embed` 会关闭浏览器持久化等能力,不能直接充当云端保存桥接。
|
||
|
||
## 错误处理
|
||
|
||
| HTTP / code | 处理 |
|
||
| --- | --- |
|
||
| 400 `BAD_REQUEST` / `CAD_INVALID_FILE` | 校验名称、描述、文件和整数参数 |
|
||
| 401 `UNAUTHORIZED` | 保留本地修改,恢复登录 |
|
||
| 404 `NOT_FOUND` | 非本人、不存在或已删除的项目/批次,停止对此项目保存 |
|
||
| 404 `CAD_DOCUMENT_NOT_FOUND` | 空项目尚未保存文件 |
|
||
| 409 `PROJECT_STEP_NOT_FOUND` | 工作区项目无 STEP 且无有效关联,刷新项目详情 |
|
||
| 409 `CONFLICT` | 工作区项目仓库未就绪,核对创建或 Fork 状态 |
|
||
| 409 `CAD_VERSION_CONFLICT` | 保留修改,处理并发冲突 |
|
||
| 409 `CAD_FILE_MISSING` | 尚未上传完整,检查 OSS 上传结果后重试确认 |
|
||
| 409 `CAD_FILE_SIZE_MISMATCH` | 当前文件不变,重新申请并上传正确文件 |
|
||
| 409 `CAD_UPLOAD_EXPIRED` | 重新申请上传批次 |
|
||
| 413 `CAD_FILE_TOO_LARGE` / `REQUEST_TOO_LARGE` | 文件超限或 JSON 超限,调整请求 |
|
||
| 429 `RATE_LIMITED` | 按 Retry-After 等待后重试 |
|
||
| 502 `CAD_OSS_ERROR` | 保留当前设计及批次,稍后重试 |
|
||
| 503 `CAD_STORAGE_UNAVAILABLE` / `CAD_STORAGE_UNSAFE` | 存储未开启或本地 OSS 连接参数不完整,联系管理员 |
|
||
| 503 `CAD_CODE_BUSY` / `REDIS_UNAVAILABLE` | 暂时无法处理,保留输入后重试 |
|
||
|
||
删除为逻辑删除,之后列表、详情、文件地址获取、编辑及保存确认均不可访问,不提供恢复。上传失败、替换、删除均保留旧 OSS 对象,已有文件直链仍按 Bucket/CDN 规则访问,删除项目不会撤销已有直链。首期没有历史恢复和对象自动清理。
|
||
|
||
## 部署配置
|
||
|
||
先手工执行 [CAD 建表 SQL](cad-database.md),已有表先执行[工作区项目关联与初始 STEP 增量 SQL](cad-database.md#已有数据库增加工作区项目关联与初始-step),再部署后端并接入前端。CAD 与现有资源共用 `vibemake.oss` 的 Bucket、地域、Endpoint、AccessKey 和各环境根目录;`vibemake.cad.oss` 仅保留独立的 `enabled` 开关,文件存储默认关闭。关联创建及初始 STEP 地址生成不访问 OSS,不依赖 `.sc` 上传开关;云端保存仍需启用 CAD 存储。
|
||
|
||
```yaml
|
||
vibemake:
|
||
cad:
|
||
oss:
|
||
enabled: ${CAD_OSS_ENABLED:false}
|
||
```
|
||
|
||
| 配置项 | 默认值 / 要求 |
|
||
| --- | --- |
|
||
| `CAD_OSS_ENABLED` | false,配置齐全后设为 true |
|
||
| `OSS_REGION` | 与现有 OSS 共用,默认 cn-beijing |
|
||
| `OSS_ENDPOINT` | 与现有 OSS 共用,可选 HTTPS Endpoint;不填写时按地域生成 |
|
||
| `OSS_BUCKET` | 与现有资源共用同一个 Bucket |
|
||
| `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` | 与现有 OSS 共用,通过部署环境注入 |
|
||
| `OSS_PUBLIC_BASE_URL` | 与现有资源共用普通 OSS/CDN 访问基础地址,配置为空时使用 Bucket 域名 |
|
||
| `vibemake.oss.root-directory` | CAD 直接使用各环境根目录:test 为 vibemake_dev,prod 为 vibemake |
|
||
| `CAD_MAX_FILE_BYTES` | 268435456;配置范围为 1 字节至 OSS 表单上限 5 GiB,需同时兼容编辑器读取上限 |
|
||
| `CAD_UPLOAD_VALIDITY` | 默认 15m;范围 1 秒至 7 天 |
|
||
| `RATE_CAD_CREATE_PER_MINUTE` / `RATE_CAD_SIGN_PER_MINUTE` | 5 / 20,按当前用户独立限流 |
|
||
| `RATE_CAD_SAVE_PER_MINUTE` / `RATE_CAD_READ_PER_MINUTE` | 30 / 60,保存确认和文件地址读取尝试次数 |
|
||
|
||
CAD 独立开关与 `OSS_ENABLED` 分开控制:公共资源上传关闭时,只要共用连接参数完整,CAD 仍可独立开启。只有 `CAD_OSS_ENABLED` 继续生效;旧的 `CAD_OSS_BUCKET`、`CAD_OSS_REGION`、`CAD_OSS_ENDPOINT`、`CAD_OSS_ACCESS_KEY_ID`、`CAD_OSS_ACCESS_KEY_SECRET` 和 `CAD_OSS_ROOT_DIRECTORY` 均不再读取,可从 `.env` 移除。
|
||
|
||
上传签名仅在本地生成,保存确认只通过 HEAD 核验对象存在和大小;文件地址沿用现有 `OssResourcePaths.publicUrl` 规则生成。后端不查询 Bucket ACL、公共访问策略、版本控制状态或对象 ACL,不修改 Bucket 配置,也不为 CAD 单独强制 private ACL。
|
||
|
||
共用 RAM 凭据只需覆盖当前环境 `cad-projects/*` 的 `oss:PutObject`、`oss:GetObject`,分别用于普通文件上传和 HEAD 元数据读取。不额外要求 CAD 的 ACL 或 Bucket 配置读取/修改权限。不要给前端 RAM 密钥。
|
||
|
||
上传策略与原有 STEP 等资源相同,精确绑定对象键、大小、MIME、Content-Disposition 和禁止覆盖参数,不设置 `x-oss-object-acl`。文件是否公开、CDN 是否需要鉴权、同名对象覆盖行为均遵循已有 OSS/CDN 配置,应用不增加 CAD 专属限制;数据库仍校验归属、基础版本、批次截止时间和幂等回执。
|
||
|
||
旧的 `CAD_DOWNLOAD_VALIDITY` 不再读取。前端如曾按下载签名过期时间续期,需调整为直接读取普通地址,允许 `expiresAt=null`。
|
||
|
||
若此前使用独立 CAD Bucket 保存过文件,切换前需按原对象键复制到 `OSS_BUCKET`。若旧文件曾单独设为 private,且现有普通地址无法读取,需按已有资源访问方式调整为继承 Bucket(default)或配置相应的 CDN 回源授权;代码不会自动迁移文件或修改历史对象 ACL。
|
||
|
||
OSS/CDN 沿用现有 CORS 规则,允许真实编辑器来源的 POST、GET 和 Content-Type;需要时暴露 Content-Length 和 Content-Disposition。直传和文件读取不携带平台 Token。联调验证上传、确认保存、通过配置的普通 OSS/CDN 地址读取,以及原生设计重新打开后可继续编辑。API 自动化使用存储替身,不替代真实 OSS/CDN 和编辑器联调。
|