# 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; 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 和编辑器联调。