Files
makeCAD/docs/vibemake/workspace-api.md
T
likang ec622d1088 Web CAD: preserve the existing VibeMake platform integration
Recover the ZIP snapshot baseline at 147b4049cf from 6616 matching files and the archive timestamp. Preserve the existing browser assistant, host workspace bridge, theme, translations, and integration documents before updating upstream.

Generated validation media and logs remain in a local backup. The initial cargo xtask ci run stopped at those local media files lacking attribution; the integrated source tree will be checked after the upstream merge.
2026-11-05 18:26:29 +08:00

13 KiB
Raw Blame History

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 工作空间独立于现有 /api/workspace/projects,不创建 Git 仓库、不自动发布社区。只支持当前用户的单个自包含原生 .sc 设计文件,不管理外部引用的多文件装配。

文件沿用现有 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;
  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 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。列表和详情均包含封面。列表只包含本人未删除项目,按最近更新时间倒序;支持名称包含搜索。page 为 1~100000,size 为 1~100,默认 20,返回 {items,page,size,total}。同名项目允许存在。改名、描述和封面修改不改变文件保存版本或 savedAt。

项目封面

复用 已有封面上传 的 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。

保存和重新打开

  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 分钟,未确认批次同一时刻过期;文件上传完成但确认已过期时,重新申请批次。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 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 与现有资源共用 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 共用,通过部署环境注入
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 和编辑器联调。