Files
community/docs/frontend-cad-workspace.md

195 lines
17 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.
# 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 和编辑器联调。