Files
community/docs/frontend-cad-workspace.md
T
2026-11-03 15:11:51 +08:00

121 lines
9.0 KiB
Markdown
Raw 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 个人工作空间前端对接
CAD 与 Vibemake 共用 `/api/auth/login`、`/api/auth/logout` 和 `/api/users/me`,使用同一个 `Authorization: Bearer <平台 token>`。CAD 工作空间独立于现有 `/api/workspace/projects`,不创建 Git 仓库、不自动发布社区。只支持当前用户的单个自包含原生 `.sc` 设计文件,不管理外部引用的多文件装配。
通用响应、上海时间格式、分页和跨域规则沿用 [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?}` | 项目 |
| GET | `/{cadProjectCode}` | 无 | 项目 |
| PATCH | `/{cadProjectCode}` | `{name?,description?}` | 项目 |
| DELETE | `/{cadProjectCode}` | 无 | null |
| POST | `/{cadProjectCode}/uploads/signature` | `{fileName,sizeBytes,expectedVersion}` | 上传签名 |
| PUT | `/{cadProjectCode}/document` | `{uploadCode}` | 保存回执 |
| GET | `/{cadProjectCode}/document` | 无 | 文件读取信息 |
名称必填,去除首尾空白后 1~100 字符;描述最多 2000 字符,新建时默认空字符串。PATCH 省略或 null 表示保留,描述传 `""` 可清空,至少提供一个非 null 字段。
项目:
```ts
interface CadProject {
cadProjectCode: string;
name: string;
description: string;
hasDocument: boolean;
version: number;
fileName: string;
sizeBytes: number;
savedAt: string | null;
createdAt: string;
updatedAt: string;
}
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: string;
version: number;
fileName: string;
sizeBytes: number;
}
```
新项目 `hasDocument=false、version=0、fileName=""、sizeBytes=0、savedAt=null`。列表只包含本人未删除项目,按最近更新时间倒序;支持名称包含搜索。`page` 为 1~100000,`size` 为 1~100,默认 20,返回 `{items,page,size,total}`。同名项目允许存在。改名不改变文件保存版本。
## 保存和重新打开
1. 新设计首次保存先创建项目,保留返回的 `cadProjectCode` 和 `version=0`。
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. 打开项目先读详情;空项目进入新设计,否则 GET `document`,fetch `downloadUrl` 得到原始文件字节并交给 SolidCraft 打开。**本次编辑基础版本使用 `document.version`**,文件与版本来自同一快照,不混用先前详情中的版本。
上传签名默认 15 分钟,未确认批次同一时刻过期;文件上传完成但确认已过期时,重新申请批次。下载地址默认 5 分钟,用完即丢弃,不存为永久地址;过期时重新调用 API 获取。业务时间为上海时间字符串,无时区后缀,解析时补 `+08:00`。
相同 `uploadCode` 重复确认返回首次保存回执,不重复增加版本。即使之后已有更新版本,重试旧批次也不会恢复旧文件;回执版本可能小于最新项目版本,需要时重新读取详情。网络超时先保留原批次并重试确认,不直接创建新项目或新批次。OSS 同一对象禁止覆盖,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 `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` | 存储未开启或配置不符合要求,联系管理员 |
| 503 `CAD_CODE_BUSY` / `REDIS_UNAVAILABLE` | 暂时无法处理,保留输入后重试 |
删除为逻辑删除,之后列表、详情、读取、编辑及保存确认均不可访问,不提供恢复;已签发的 OSS 下载链接在到期前仍可能使用。上传失败、替换、删除均保留旧 OSS 对象,首期没有历史恢复和对象自动清理。
## 部署配置
先手工执行 [CAD 建表 SQL](cad-database.md),再部署后端。CAD 业务接口随应用部署可用,文件存储默认关闭;配置以下变量后开启。
| 变量 | 默认值 / 要求 |
| --- | --- |
| `CAD_OSS_ENABLED` | false,配置齐全后设为 true |
| `CAD_OSS_REGION` | cn-beijing |
| `CAD_OSS_ENDPOINT` | 可选,HTTPS OSS Endpoint;不填写时按地域生成 |
| `CAD_OSS_BUCKET` | 必填,必须独立于现有公开资源 Bucket |
| `CAD_OSS_ACCESS_KEY_ID` / `CAD_OSS_ACCESS_KEY_SECRET` | 专用 RAM 凭据,通过部署环境注入 |
| `CAD_OSS_ROOT_DIRECTORY` | 沿用本环境资源根目录(test 为 vibemake_dev,prod 为 vibemake) |
| `CAD_MAX_FILE_BYTES` | 268435456;配置范围为 1 字节至 OSS 表单上限 5 GiB,需同时兼容编辑器读取上限 |
| `CAD_UPLOAD_VALIDITY` / `CAD_DOWNLOAD_VALIDITY` | 15m / 5m;范围 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,保存确认和下载签名尝试次数 |
Bucket ACL 必须 private,不能存在公共读取策略,建议开启阻止公共访问;必须从未开启版本控制(Off,Suspended 也不允许)。RAM 需要根目录 `cad-projects/*` 的 `oss:PutObject`、`oss:PutObjectAcl`、`oss:GetObject`,以及 Bucket 的 `oss:GetBucketAcl`、`oss:GetBucketPolicyStatus`、`oss:GetBucketVersioning`。后端只读取这些配置,不修改 Bucket。不要给前端 RAM 密钥。
上传策略精确绑定对象键、大小、MIME、Content-Disposition、private ACL 和禁止覆盖;后端在签发上传/下载时检查 Bucket ACL、策略及版本控制。相关行为依据 [OSS PostObject 官方文档](https://www.alibabacloud.com/help/en/oss/developer-reference/postobject);版本控制开启或暂停时,OSS 会忽略禁止覆盖参数,因此部署要求 Off。
OSS CORS 允许真实编辑器来源的 POST、GET,允许 Content-Type;需要时暴露 Content-Length 和 Content-Disposition。直传和文件下载不携带平台 Token。生产联调须验证:匿名 GET 原对象被拒绝、有效签名能读取、过期签名不能读取、同对象二次上传被拒绝,以及完整原生设计保存后能恢复编辑。API 自动化使用存储替身,不能替代真实 Bucket 的这些验证。