Files
community/docs/frontend-cad-workspace.md
T
2026-11-03 17:50:46 +08:00

10 KiB
Raw Blame History

CAD 个人工作空间前端对接

CAD 与 Vibemake 共用 /api/auth/login、/api/auth/logout 和 /api/users/me,使用同一个 Authorization: Bearer <平台 token>。CAD 工作空间独立于现有 /api/workspace/projects,不创建 Git 仓库、不自动发布社区。只支持当前用户的单个自包含原生 .sc 设计文件,不管理外部引用的多文件装配。

通用响应、上海时间格式、分页和跨域规则沿用 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?} 项目
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 字段。

项目:

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 与现有资源共用 vibemake.oss 的 Bucket、地域、Endpoint、AccessKey 和各环境根目录;vibemake.cad.oss 仅保留独立的 enabled 开关,文件存储默认关闭。

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 共用,通过部署环境注入
vibemake.oss.root-directory CAD 直接使用各环境根目录: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,保存确认和下载签名尝试次数

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 移除。

共用 Bucket 可以是 private 或 public-read,CAD 对象必须显式为 private,不能继承 Bucket 权限;不允许 public-read-write Bucket 或公共 Bucket Policy。当前对公共 Policy 采用保守检查,任何公共 Policy 都会使 CAD 返回 CAD_STORAGE_UNSAFE,包括仅用于其他资源目录的公共 Policy。若现有公开资源依赖此类 Policy,需在部署时调整访问方案,应用不会自动修改整个 Bucket 的 ACL 或 Policy。

Bucket 必须从未开启版本控制(Off,Suspended 也不允许)。共用 RAM 凭据需要根目录 cad-projects/* 的 oss:PutObject、oss:PutObjectAcl、oss:GetObject、oss:GetObjectAcl,以及 Bucket 的 oss:GetBucketAcl、oss:GetBucketPolicyStatus、oss:GetBucketVersioning。后端只读取这些配置,不修改 Bucket。不要给前端 RAM 密钥。

上传策略精确绑定对象键、大小、MIME、Content-Disposition、private ACL 和禁止覆盖;后端签发凭据时检查 Bucket ACL、策略及版本控制,确认保存和签发下载时额外核验对象 ACL 必须为 private。对象 ACL 优先于 Bucket ACL,依据 OSS 权限控制说明。OSS PostObject 官方文档说明版本控制开启或暂停时会忽略禁止覆盖参数,因此部署要求 Off。

若此前已经使用独立 CAD Bucket 保存过文件,切换前需将文件按原对象键复制到 OSS_BUCKET 并设置 private ACL;应用只保存对象键,不记录历史 Bucket,不会自动迁移旧对象。

OSS CORS 允许真实编辑器来源的 POST、GET,允许 Content-Type;需要时暴露 Content-Length 和 Content-Disposition。直传和文件下载不携带平台 Token。生产联调须验证:匿名 GET 原对象被拒绝、有效签名能读取、过期签名不能读取、同对象二次上传被拒绝,以及完整原生设计保存后能恢复编辑。API 自动化使用存储替身,不能替代真实 Bucket 的这些验证。