17 KiB
CAD 个人工作空间前端对接
网页 AI 助手使用独立的 /api/cad/ai 接口,复用平台登录,工具由浏览器执行;接口、工具循环、停止及撤销适配见 CAD Web AI Agent 对接。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 引用规范。
通用响应、上海时间格式、分页和跨域规则沿用 Vibemake 接入约定。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 字段。
项目:
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 请求头:
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 工作空间进入的情况:
- 读取
GET /api/cad/workspace/projects/{cadProjectCode}的最新详情。 hasDocument=true时使用GET .../{cadProjectCode}/document下载.sc并打开,以document.version作为编辑基础版本。读取失败显示错误并允许重试,不自动退回 STEP,避免用户误以为已有编辑丢失。hasDocument=false且initialStep非空时,fetchinitialStep.downloadUrl,将原始文件字节和fileName交给编辑器的 STEP/STP 导入能力。导入失败保留同一个关联,提供重试;不创建新 CAD。- 导入成功后视为尚未云端保存,首次保存由前端导出完整
.sc,使用expectedVersion=0走原有上传签名与确认流程。后端不解析或转换 STEP,不把 STEP 当作已保存的原生文档,原生上传接口仍只接受.sc。 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 编码继续不可访问,不提供恢复。
项目封面
复用 已有封面上传 的 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}:
{"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。
保存和重新打开
- 独立新设计首次保存先创建项目,保留返回的
cadProjectCode和version=0;从工作区进入的关联 CAD 直接复用返回的项目编码,不再创建空项目。 - 使用 SolidCraft 原生序列化生成完整
.sc,不能仅上传 STL、STEP、GLB 或显示网格;原生文件保留参数及可编辑设计。需要由前端接通原生文件导出和导入桥接,当前本机/浏览器保存不等于云端保存。 - 文件名须为不含路径和控制字符的
.sc名称,最多 255 字符。文件非空,默认上限 268435456 字节(256 MiB)。sizeBytes和expectedVersion必须是 JSON 整数,不接受字符串或小数。 - 申请签名,将
formFields全部原样写入 FormData,最后追加file,POST 到uploadUrl。不携带平台 Authorization,不手写 multipart Content-Type。OSS 成功为 HTTP 200,无需解析 JSON。 - 上传完成后提交原
uploadCode确认。后端核验对象大小、批次归属、截止时间和基础版本,成功才更新当前设计引用,并返回新版本。 - 只有确认成功才显示云端已保存;序列化期间及上传期间又产生的修改仍应标为未保存。每个项目前端串行执行云端保存。
- 打开项目先读详情;
hasDocument=true时 GETdocument,fetchdownloadUrl得到原始文件字节并交给 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,已有表先执行工作区项目关联与初始 STEP 增量 SQL,再部署后端并接入前端。CAD 与现有资源共用 vibemake.oss 的 Bucket、地域、Endpoint、AccessKey 和各环境根目录;vibemake.cad.oss 仅保留独立的 enabled 开关,文件存储默认关闭。关联创建及初始 STEP 地址生成不访问 OSS,不依赖 .sc 上传开关;云端保存仍需启用 CAD 存储。
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 和编辑器联调。