# VibeMake CAD 后端实施与接口契约 > 历史方案:当前前端对接以 [CAD 个人工作空间前端对接](workspace-api.md) 为准(2026-11-03 同步)。以下 v1.2 设计保留供参考,不作为当前实现或部署输入;其接口路径、capabilities、complete/状态查询、专用私有 Bucket 和临时下载签名已被新契约替代。 - 文档版本:v1.2,已按最终决定复用 VibeMake 登录弹窗。 - 更新日期:2026-11-03。 - 适用对象:VibeMake 后端开发、使用 Codex 实施的开发者、CAD 前端开发和测试。 - 实施状态:需求与接口契约,尚未据此实现或部署后端。 - 产品范围:基于 SolidCraft 的 VibeMake CAD Web 版本,权威源文件为 `.sc`。 > 本文可单独交给后端同事作为 Codex 实施输入,不依赖之前的聊天。项目现有技术栈、认证组件、数据库和 OSS 封装需要先检查再复用。不得把文档示例当作已经上线的能力或真实环境配置。 ## 1. 已确定的产品决定 1. 产品名为 **VibeMake CAD**,浏览器编辑器基于 SolidCraft/Rust/WASM。 2. CAD 页面未登录时打开 **VibeMake 统一登录弹窗**,登录完成后继续当前 CAD 页面或操作。 3. **CAD 不新增登录页、注册、验证码、账号表、密码管理或 token 签发接口。** 统一账号系统继续负责登录;CAD API 必须复用现有认证并校验资源归属。 4. 推荐 CAD 前端与主站同源部署:`/cad/` 为列表,`/cad/editor/?project=` 为编辑器。API 基址沿用现有业务系统,可以是独立 API 域名或同源反向代理。 5. 一个 CAD 项目对应一个原生 `.sc` 工程。STEP、STL、GLB 等不是云端权威工程格式。 6. CAD 数据独立建模,复用主站用户和基础设施,不直接复用社区/工作区项目记录,不建立隐式 projectCode 映射。 7. 一期手动云保存;本机草稿由前端负责,不等于云保存。 8. 文件直传私有 OSS 临时位置;后端固化、校验并原子提交后,才确认保存成功。 9. 一期保留所有已确认快照,但不提供历史列表/恢复 UI。删除先做逻辑删除。 10. 不自动覆盖并发保存;使用基于云端版本的比较并提交(CAS)。 ### 1.1 一期不包含 - 多人实时协同、团队、分享、社区发布、CAD 管理后台。 - 服务端建模、几何布尔、转换格式、渲染缩略图。 - 工程目录、外部附件集合、任意 ZIP 上传、分片续传、差量同步。 - 历史版本查询界面、历史恢复、物理删除入口。 - 对主站和 PCB 数据模型或登录体系的重构。 缩略图一期允许为空,由列表显示占位图标。以后增加时,缩略图是绑定 revision 的派生资源,不能代替源文件。 ### 1.2 核心不变量 - OSS 上传成功不代表云保存成功;只有 `COMMITTED` 才可显示“已保存到云端”。 - 项目 head 永远只指向已经固化并校验通过的不可变文件。 - 同一保存 operation 无论重试多少次,最多生成一个 revision。 - 客户端提交的 owner、用户 ID、对象 key 不能决定实际权限。 - 文件下载、副本导出、本机草稿都不能推进云端版本。 - 失败、超时、冲突时不能清除用户当前未保存内容。 ## 2. 后端 Codex 开始实施前的检查 先阅读目标后端仓库的 AGENTS.md、README、运行和测试说明,再检查: 1. 当前语言、框架、项目分层和 API 路由习惯。 2. 用户稳定标识、现有鉴权中间件、token/会话验证和账号禁用规则。 3. 数据库、迁移工具、事务隔离和锁使用方式。 4. OSS SDK、私有桶、签名上传下载、当前环境配置与 CORS。 5. 统一 JSON 信封、异常处理、requestId、国际化和限流组件。 6. 是否已经存在 CAD 模块、表、接口或历史工程数据。 7. 后台任务、持久化队列、定时任务及测试基础设施。 实施要求: - 优先扩展现有业务后端,不因本文新建整套账号服务或不必要的微服务。 - 如果 CAD 模块位于同一后端,直接复用认证中间件;如果独立部署,接入现有身份验证机制,不自行设计另一种 token。 - 已有 CAD 功能先核对实际行为,补齐缺口,不重复建表、覆盖数据或删除旧实现。 - 如果已有 OpenCADStudio/DWG/DXF 项目,保留原格式和引擎归属;不能把旧记录改标为 `.sc`。需要兼容时使用明确的 engineKind/格式区分和可回滚迁移。 - 表和类可遵循现有命名习惯,但本文公共 API 字段、状态、错误码和语义需保持一致;必须变更时更新契约和测试,不能静默改动。 - 不假设用户 ID 类型、桶名或 OSS 密钥;登录弹窗复用现有主站接口。优先从现有配置解析,缺少的环境值作为明确配置项交付。 - 不部署正式环境,不执行破坏性数据迁移,不创建/修改生产用户,不把测试写请求发往生产。 ## 3. 架构与职责 | 组件 | 职责 | | --- | --- | | 统一登录弹窗和账号后端 | 登录、凭据签发/失效、账号状态和退出 | | CAD 平台前端 | 登录弹窗、列表、项目名称、上传调度、保存状态、草稿和冲突提示 | | Rust/WASM 编辑器 | 几何、约束、参数、原生工程快照生成与加载 | | CAD 业务模块 | 鉴权、CRUD、快照、上传事务、配额、幂等和提交 | | 文件校验任务 | 固化源文件、检查实际字节与结构、提交或拒绝 | | 数据库 | 项目、不可变 revision、对象引用、事务与幂等结果 | | 私有 OSS | 临时上传、最终不可变文件、短期读取授权 | 标准保存链路: ```text 固定本次工程快照及字节 -> 创建保存事务 -> 直传 OSS 临时位置 -> complete 请求 -> 最终对象固化与校验 -> 数据库原子提交 revision/head/事务回执 -> 返回 COMMITTED ``` 业务后端沿用现有技术栈。结构校验可使用受限的独立组件或复用兼容的原生读取组件,不要求服务端运行桌面 CAD,不执行建模重放或渲染。 ## 4. 统一登录和鉴权边界 ### 4.1 登录弹窗由主站统一系统负责 CAD 复用主站邮箱与图片验证码登录弹窗,继续调用现有 auth 接口,不新增 CAD 专用 captcha/login/register 接口。 前端流程: 1. 用户访问列表或编辑器。 2. 未登录时自动打开主站同款登录弹窗;关闭后停留在登录提示页,不加载私有项目或引擎。 3. 登录成功后继续原 CAD 深链接或待执行操作。 4. CAD 使用统一账号系统已有的凭据请求业务 API。 5. 编辑中凭据失效时,先保护本机草稿,再引导重新登录。 当前主站已有 Bearer 请求方式和 `vm.auth` 前端身份存储。以实际统一账号契约为准复用,不为 CAD 强制迁移 Cookie、OIDC 或另发 token。 一期不新增 `/login/` 路由,不使用 returnTo 跳转登录。弹窗打开时锁定画布输入和键盘焦点;简体中文与英文共享当前 CAD 语言。 同源 `/cad/` 复用主站 `vm.auth` 和已有 Bearer。编辑中明确 401 时保护原账号草稿、锁定输入并打开登录弹窗;同账号续登先查未知事务,不同账号登录后释放原工程并进入新账号列表。跨标签页身份变化必须同步,旧账号回执不得更新新会话。 ### 4.2 CAD 后端仍需验证身份和权限 所有本文业务接口,包括 capabilities,都要求现有认证。当前请求方式: ```http Authorization: Bearer <统一账号系统签发的凭据> ``` - 当前用户来自服务端认证上下文,不能来自请求 body、URL 参数或可伪造身份头。 - 项目、revision、upload、签名授权都验证 owner 及关联关系。 - 不存在和越权统一 `404 NOT_FOUND`,不泄漏他人数据是否存在。 - 当前用户自己的已删除项目通常返回 `410 PROJECT_DELETED`;已确认事务回执查询见第 12 节例外。 - 未登录、失效、被统一认证拒绝时返回 **JSON HTTP 401**,CAD API 不 302 跳转登录页。 - 后端不读取或信任浏览器 `vm.auth` 内容;它只验证请求实际携带的凭据。 - CORS 不是鉴权。知道 UUID、OSS key 或通过前端路由检查,都不构成访问权限。 退出或取消 HTTP 请求不会自动撤销已受理的保存。已受理操作即便最终完成,也只能属于原账号、原项目;前端切账号后不得应用旧回执。 ## 5. 原生文件及版本约定 ### 5.1 权威源文件 | 项目 | 一期约定 | | --- | --- | | 扩展名/sourceFormat | `.sc` / `sc` | | MIME | `application/octet-stream` | | 文件数 | 每次保存一个完整工程 | | 容器 | 支持的 SolidCraft 原生容器,当前为 `solidcraft-container/1` | | 参数化文档 | 容器中的 `document.json`,携带 `solidcraft/N` | | 保存方式 | 原始二进制字节,不重写、不重新压缩、不转换 | 原生容器采用 ZIP 结构,包含 `container.json`、`document.json`、必要的 `blobs/` 以及可选缓存。这不等于允许任意 ZIP、目录包或附加 gzip 封装。 - 旧 JSON、旧扩展名或导入格式由编辑器解析后生成支持的 `.sc` 再上传。 - 内部 `solidcraft/N` 等格式标识不因产品更名改变。 - 后端不生成空工程文件。项目初始可以没有快照。 - 工程特征、约束、参数和必要资源由原生文件承载;不能用 STL/STEP/GLB 或截图替代。 - 工程内缓存不是权威建模结果;是否可编辑由引擎和 round-trip 测试验证。 - Undo/Redo 会话栈不要求上传;云端保存序号也不是操作历史。 ### 5.2 四种版本不能混用 | 字段 | 含义 | | --- | --- | | headVersion | 云项目第几次确认保存,0、1、2…… | | containerFormat | 容器编码版本 | | documentFormat | 实际参数化文档结构版本 `solidcraft/N` | | engineBuild | 生成工程的编辑器构建标识 | `N` 必须取自实际序列化文件及发布的校验器,不能用应用版本号猜测。本文 JSON 中 `solidcraft/` 是示例占位,生产响应必须是真实格式值。 前端支持、后端接受和校验器识别的格式范围需要建立发布清单。新版本不支持时明确拒绝,不能静默丢弃未知内容。 ### 5.3 项目名称与工程内容 项目重命名只修改平台元数据,不改 `.sc` 原始字节、内部文档名、headVersion 或 lastSavedAt。下载名称可由平台安全生成,源文件的内部模型名称不要求与平台名每时每刻相同。 ## 6. 数据模型 下面为逻辑模型,落地按现有 ORM/数据库习惯调整。ID 推荐 UUID;用户字段使用现有稳定用户标识。数值版本通过 JSON 返回时必须处于前端可精确表示的整数范围。 ### 6.1 cad_projects | 字段 | 说明 | | --- | --- | | id | 项目 UUID | | owner_user_code | 服务端身份,类型沿用主站 | | name | 显示名,trim 后 1–120 个 Unicode 码点,UTF-8 不超过 512 字节 | | engine_kind | 一期 `solidcraft` | | source_format | 一期 `sc` | | head_version | 非负整数,初始 0 | | head_revision_id | 最新确认 revision,可空 | | metadata_version | 初始 1;名称修改等元数据变更时递增 | | last_saved_at | 仅确认工程保存时更新,可空 | | created_at / updated_at | 创建/最近元数据或工程更新时间 | | deleted_at | 逻辑删除时间,可空 | 派生状态:EMPTY=head 为空;READY=head 非空;DELETED=deleted_at 非空。不要再维护一份容易漂移的 EMPTY/READY 持久化状态。 约束:headVersion=0 时 revision 为空;大于 0 时指向本项目已确认 revision。允许同用户同名项目。名称拒绝控制字符,作为纯文本展示。 ### 6.2 cad_revisions | 字段 | 说明 | | --- | --- | | id / project_id | revision UUID 和所属项目 | | version | 项目内保存序号 | | blob_id | 已固化并校验通过的对象 | | client_operation_id | 保存幂等键 | | client_snapshot_id | 客户端固定快照标识,不授予权限 | | created_by_user_code | 认证提交者 | | container_format / document_format | 服务端检测值 | | engine_build | 客户端构建标识,仅诊断信息 | | created_at | 服务器确认时间 | 唯一约束:`(project_id, version)`、`(project_id, client_operation_id)`。已确认 revision 不允许原地覆盖源文件。 ### 6.3 cad_blobs | 字段 | 说明 | | --- | --- | | id | UUID | | object_key | 私有最终对象 key,浏览器从无写权限 | | object_version_id | 启用存储版本控制时记录具体版本 | | size_bytes / sha256 | 服务端对最终字节实际校验的结果 | | source_format / container_format / document_format | 检测结果 | | created_at | 固化时间 | 一期不做跨用户去重;不同显式保存可产生不同对象和 revision。同一幂等 operation 重试不能产生第二个 revision。 ### 6.4 cad_uploads | 字段 | 说明 | | --- | --- | | id / project_id / owner_user_code | 事务 UUID 与归属 | | client_operation_id / client_snapshot_id | 固定保存操作与快照 | | request_fingerprint | 规范化后的请求摘要 | | expected_version | 客户端读取并编辑所基于的云 head | | expected_size / expected_sha256 | 声明的完整源字节信息 | | declared_container_format / declared_document_format | 声明格式,不能取代实际检测 | | file_name / engine_build | 固定文件显示名与构建标识 | | temp_object_key | 唯一临时上传位置 | | state | 第 12 节定义的状态 | | error_code / error_details | 固定拒绝原因,不含敏感内部信息 | | verifier_token / lease_until | 校验执行权及租约 | | candidate_object_key | 本次校验尝试使用的独立固化位置 | | committed_revision_id / committed_version / saved_at | 固定确认回执 | | reserved_bytes | 预留配额 | | expires_at / created_at / updated_at | 期限和时间 | 唯一约束:`(project_id, client_operation_id)`。请求摘要至少包括 expectedVersion、snapshotId、文件名、大小、hash、格式和构建标识;规范化方式固定,后端计算,不信任客户端传入摘要。 ### 6.5 创建项目幂等记录与配额 创建项目使用独立记录,键为 `(owner, action, Idempotency-Key)`,保存请求摘要和创建的 projectId。不得因网络重试重复创建项目。一期持久保存结果,若未来清理,需先明确重试期限和旧键拒绝策略。 复用或新增用户配额记录,用事务协调 used/reserved bytes,不能仅在前端计数或每个并发请求各自做无锁检查。 ### 6.6 索引与事务 - 列表至少索引 owner、删除状态、排序时间、ID。 - upload 索引项目/owner、幂等键、state、过期时间、租约。 - revision 和 blob 使用外键或等价完整性检查,防止串项目引用。 - 保存与删除按统一锁顺序协调;对象网络操作不放在持有行锁的长事务内。 - 数据库迁移必须可审查并有回滚/兼容说明,不删除既有业务数据。 ## 7. 通用 API 规则 统一前缀:`/api/cad`。本文示例省略真实域名。 ```json { "code": "OK", "message": "", "data": {}, "requestId": "server-generated-request-id" } ``` - 失败使用真实 HTTP 状态和稳定业务 code。前端不以 message 文本判断逻辑。 - 时间统一 UTC ISO 8601,带 `Z`;大小为字节;SHA-256 为 64 位小写十六进制。 - JSON 接口仅接收元数据,设置合理 body 限制;源文件直接去 OSS。 - API 私有响应 `Cache-Control: no-store`,CDN/SW 不缓存。 - 响应头 `X-Request-Id`,限流时 `Retry-After`。 - 支持 `Accept-Language: zh-CN`/`en`,默认中文;error details 使用机器字段。 - 不返回堆栈、存储密钥、未经脱敏对象地址等内部信息。 - 不接受客户端覆盖 owner、head、revision 关联或对象 key。 成功查询到 REJECTED/EXPIRED 事务仍可是 HTTP 200 + code=OK;仅表示查询成功,前端必须判断 data.status。 ## 8. 接口总览 | 方法 | 路径 | 用途 | | --- | --- | --- | | GET | /capabilities | 格式和限制 | | GET | /projects | 当前用户项目列表 | | POST | /projects | 幂等创建 EMPTY 项目 | | GET | /projects/{projectId} | 项目元数据 | | PATCH | /projects/{projectId} | 带元数据版本的重命名 | | DELETE | /projects/{projectId} | 逻辑删除 | | GET | /projects/{projectId}/snapshot | 确认快照和只读授权 | | POST | /projects/{projectId}/uploads | 幂等初始化保存 | | POST | /projects/{projectId}/uploads/{uploadId}/complete | 开始/继续确认 | | GET | /projects/{projectId}/uploads/{uploadId} | 查询固定事务结果 | 以下成功示例均为信封中的 data,不重复外层 code/message/requestId。 ## 9. 能力和 CRUD 详细契约 ### 9.1 GET /capabilities ```json { "apiVersion": 1, "engineKind": "solidcraft", "sourceFormats": ["sc"], "preferredSourceFormat": "sc", "containerFormats": ["solidcraft-container/1"], "documentFormats": ["solidcraft/"], "formatSupportId": "实际发布格式清单的标识", "maxSourceBytes": 52428800, "maxSourceFiles": 1, "externalAttachments": false, "saveProtocol": "signed-post-cas-v1", "manualSave": true, "cloudAutosave": false, "historyUi": false, "uploadAuthorizationTtlSeconds": 300, "uploadTransactionTtlSeconds": 1800, "downloadAuthorizationTtlSeconds": 300 } ``` `documentFormats` 必须返回校验器实际接受的版本清单,不返回占位 ``。50 MiB 是建议初始配置,不是现有线上能力;完成浏览器和服务端峰值内存/重开测试后确定。不直接复用主站普通文件的 10 MiB 限制。 所有时间和容量由配置产生并与签名、校验实际行为一致。前端使用服务端和编辑器承载能力的较小上限。 ### 9.2 GET /projects 参数:q 可选,最多 200 个 Unicode 码点;page 从 1 开始;pageSize 默认 20,最大 100。名称搜索使用参数化查询并正确处理 LIKE 特殊字符,不拼 SQL。 仅查当前用户、未删除、engineKind=solidcraft 的项目。排序:`COALESCE(last_saved_at, created_at) DESC, id DESC`。重命名不伪装成保存;分页期间新保存可改变顺序,不承诺固定快照分页。 ```json { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "机械臂支架", "engineKind": "solidcraft", "sourceFormat": "sc", "state": "READY", "headVersion": 3, "headRevisionId": "33333333-3333-4333-8333-333333333333", "metadataVersion": 1, "createdAt": "2026-11-03T02:00:00Z", "updatedAt": "2026-11-03T02:20:00Z", "lastSavedAt": "2026-11-03T02:20:00Z", "thumbnail": null } ], "page": 1, "pageSize": 20, "total": 1 } ``` 列表不返回文件字节或签名源文件 URL,不触发渲染。 ### 9.3 POST /projects 必须携带 `Idempotency-Key: `。 ```json { "name": "机械臂支架" } ``` 首次返回 HTTP 201 和项目结构:EMPTY、headVersion=0、headRevisionId=null、metadataVersion=1、lastSavedAt=null。相同 owner/键/请求返回同一项目(HTTP 200);同键异内容 `409 IDEMPOTENCY_KEY_REUSED`。 格式、engineKind、owner 由服务端确定。创建不接工程字节。导入时可先在编辑器确认文件可读,再创建 EMPTY 项目并走标准保存。 ### 9.4 GET /projects/{projectId} 返回与列表条目一致的项目结构。不存在/越权 404;自己的已删除项目 410。 ### 9.5 PATCH /projects/{projectId} ```json { "name": "机械臂支架 V2", "expectedMetadataVersion": 1 } ``` 仅允许修改名称。使用 metadataVersion 条件更新并递增,返回更新后的项目。过期版本 `409 METADATA_CONFLICT`,details 包含 currentMetadataVersion。若响应丢失,前端重读元数据确认,不盲目重复覆盖。 不修改源字节、工程 headVersion 或 lastSavedAt。普通工程保存不修改 metadataVersion;updatedAt 可以更新。 ### 9.6 DELETE /projects/{projectId} ```json { "id": "11111111-1111-4111-8111-111111111111", "deleted": true } ``` 逻辑删除,与保存提交竞争同一项目锁。重复 owner 删除返回同样成功;越权/不存在 404。 删除后禁止新 init、新快照授权和未完成保存提交。已确认 revision 保留,不修改其他产品数据。已签发读取 URL 可能到期前仍可用,不承诺删除时即时撤销;读取授权短期有效。 ## 10. 工程快照与下载 ### 10.1 GET /projects/{projectId}/snapshot EMPTY: ```json { "projectId": "11111111-1111-4111-8111-111111111111", "headVersion": 0, "revisionId": null, "savedAt": null, "file": null } ``` READY: ```json { "projectId": "11111111-1111-4111-8111-111111111111", "headVersion": 3, "revisionId": "33333333-3333-4333-8333-333333333333", "savedAt": "2026-11-03T02:20:00Z", "file": { "name": "design.sc", "sourceFormat": "sc", "containerFormat": "solidcraft-container/1", "documentFormat": "solidcraft/", "size": 123456, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "downloadUrl": "<短期只读、绑定不可变对象的签名 URL>", "downloadExpiresAt": "2026-11-03T02:25:00Z" } } ``` 强制约定: - headVersion/revision/file 来自一次一致性读取,不拼接不同时间的结果。 - URL 固定到该 revision 的不可变对象或具体对象版本,不使用可覆盖的 latest.sc。 - 下载期间云端 head 前进不改变已签发文件。 - 前端校验 size/hash 后交给引擎,保存时使用该快照对应 expectedVersion。 - 不能把新读取的 head 数字套到仍在编辑的旧文件上。 ### 10.2 同一 revision 续签 支持 `GET /projects/{projectId}/snapshot?revisionId=<已知UUID>`。只允许该项目 owner 读取已确认且属于该项目的 revision,返回它自己的版本。用于下载过期续签,不新增历史列表 API。 下载禁止匿名永久地址。浏览器向 OSS 不携带业务 Bearer,使用短期只读授权;后端签名不接受任意外部 URL。 ## 11. 初始化上传及直传 ### 11.1 POST /projects/{projectId}/uploads ```json { "clientOperationId": "44444444-4444-4444-8444-444444444444", "clientSnapshotId": "55555555-5555-4555-8555-555555555555", "expectedVersion": 3, "engineBuild": "实际编辑器构建标识", "file": { "name": "design.sc", "sourceFormat": "sc", "containerFormat": "solidcraft-container/1", "documentFormat": "solidcraft/", "size": 123456, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } ``` 要求: - expectedVersion 为非负整数;文件大小为正且不超过配置。 - 文件名为安全 basename,UTF-8 建议不超过 255 字节,不能含目录、控制字符或被当作对象 key。 - 同一 operationId 固定该次快照、基准版本、字节及请求字段;新内容用新 operationId。 - 先鉴权并查同 operation 幂等记录,再检查新事务的 head;已提交的旧操作重试不能因当前 head 前进而变成冲突。 - 新事务检查 owner、项目未删除、格式、大小、版本、频率、并发和额度;可以提前 409,但 complete 仍再次 CAS。 - 初始化和预留配额原子处理,避免并发超额或重复预留。 ### 11.2 初始化返回 首次新建 HTTP 201;同键重试 HTTP 200,返回原事务当前状态。 ```json { "uploadId": "66666666-6666-4666-8666-666666666666", "projectId": "11111111-1111-4111-8111-111111111111", "clientOperationId": "44444444-4444-4444-8444-444444444444", "clientSnapshotId": "55555555-5555-4555-8555-555555555555", "status": "PENDING_UPLOAD", "expiresAt": "2026-11-03T02:50:00Z", "upload": { "method": "POST", "url": "<当前环境 OSS 上传地址>", "fields": { "key": "<后端生成的精确临时 key>", "policy": "", "<签名相关字段>": "", "success_action_status": "204" }, "fileField": "file", "uploadExpiresAt": "2026-11-03T02:25:00Z" } } ``` fields 为完整不透明表单,由实际 OSS SDK/签名版本生成,不能把示例占位字段或某套旧签名字段写死在前端。策略限制精确 temp key、有效期和大小范围。浏览器不具备 final 目录写权限或列举权限。 已 COMMITTED 的重试返回原确认回执,不再签发上传;VERIFYING/REJECTED/EXPIRED 返回现有状态,不新建或复活事务。仅 PENDING 且未超过事务期限时允许同请求续签同 key。 ### 11.3 浏览器直传 1. 构造 FormData,原样添加 fields。 2. 最后附加 file 字段和完整原始字节。 3. POST 到指定 OSS 地址,不带业务 Bearer,不手动设置 multipart boundary。 4. OSS 成功后请求 complete。 此处 multipart/form-data 是单文件表单上传,不是 OSS 分片协议。不增加 Base64 JSON 工程上传通道。 OSS 响应丢失时可先调用 complete;文件不存在则收到 UPLOAD_NOT_READY 后继续同事务。签名过期但 PENDING 事务未过期,可相同 init 续签。 ## 12. complete、状态查询与幂等回执 ### 12.1 状态机 ```text PENDING_UPLOAD -> VERIFYING -> COMMITTED | | v v EXPIRED REJECTED ``` - COMMITTED/REJECTED/EXPIRED 为不可逆终态。 - PENDING 的 expiresAt 是允许开始确认的截止时间。 - 已受理 VERIFYING 使用独立校验租约、超时和有限重试,不能由普通过期任务改成 EXPIRED。 - 可恢复存储/数据库故障不直接变成永久拒绝;在重试预算内继续 VERIFYING。耗尽后明确终态错误,不无限处理中。 ### 12.2 POST /projects/{projectId}/uploads/{uploadId}/complete 请求 body 为 `{}`。不接受换 key/hash/文件/版本;以初始化记录为准。 PENDING 且对象尚未存在:`409 UPLOAD_NOT_READY`,仍保持 PENDING,可上传后重试。鉴权失败 401;越权事务 404。 已开始异步确认,HTTP 202: ```json { "uploadId": "66666666-6666-4666-8666-666666666666", "projectId": "11111111-1111-4111-8111-111111111111", "clientOperationId": "44444444-4444-4444-8444-444444444444", "clientSnapshotId": "55555555-5555-4555-8555-555555555555", "status": "VERIFYING", "retryAfterMs": 1000 } ``` 已提交,HTTP 200: ```json { "uploadId": "66666666-6666-4666-8666-666666666666", "projectId": "11111111-1111-4111-8111-111111111111", "clientOperationId": "44444444-4444-4444-8444-444444444444", "clientSnapshotId": "55555555-5555-4555-8555-555555555555", "status": "COMMITTED", "revisionId": "77777777-7777-4777-8777-777777777777", "headVersion": 4, "savedAt": "2026-11-03T02:21:00Z", "file": { "size": 123456, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } ``` HTTP 202、OSS 204、单纯 code=OK 或 VERIFYING 均不能显示已保存。 ### 12.3 GET /projects/{projectId}/uploads/{uploadId} 所有状态包含 uploadId/projectId/clientOperationId/clientSnapshotId/status/expiresAt;VERIFYING 可带 retryAfterMs。COMMITTED 返回上述固定确认字段。 终态失败查询 HTTP 200,例如: ```json { "uploadId": "66666666-6666-4666-8666-666666666666", "projectId": "11111111-1111-4111-8111-111111111111", "clientOperationId": "44444444-4444-4444-8444-444444444444", "clientSnapshotId": "55555555-5555-4555-8555-555555555555", "status": "REJECTED", "expiresAt": "2026-11-03T02:50:00Z", "error": { "code": "HEAD_CONFLICT", "details": {"expectedVersion": 3, "currentHeadVersion": 4} } } ``` EXPIRED 同样返回状态及 UPLOAD_EXPIRED。查询成功不等于保存成功。complete 对 REJECTED/EXPIRED 返回对应 HTTP 错误和稳定原因;同 init 重试可以 200 返回原事务终态。 ### 12.4 固定结果与删除例外 - 已 COMMITTED 的 complete/init/status 重试永远返回那笔固定结果,不因当前 head 后来前进变成冲突。 - 项目后来被 owner 删除,仍允许该 owner 查询已发生的 COMMITTED 回执,可附 projectDeleted=true;不签发新的文件读取授权。 - 未确认事务遇项目删除,拒绝为 PROJECT_DELETED;不能复活项目。 - 查询仍需有效身份。其他用户无论项目是否删除都不能查回执。 - 超时/断网/5xx 后先查同笔事务,不盲目换 operationId 重做。轮询按 retryAfterMs 退避并有前台等待上限;暂停轮询不等于后端取消。 ## 13. 固化、校验、CAS 的实现要求 ### 13.1 临时对象不可作为确认文件 临时 POST 授权有效期间可能重复写入。因此禁止“校验 temp 后直接引用 temp”,也禁止“先校验 temp,再假设稍后复制到的内容相同”。 推荐实现: 1. complete 取得事务执行权,转 VERIFYING,持久化任务。 2. 每次校验尝试生成独立 token 和候选 final key,先记录后执行复制。 3. 将 temp 复制到仅后端可写的候选对象;可用源 version/条件复制固定来源。 4. 对候选对象实际字节计算 size/hash,执行结构/版本/依赖校验。 5. 验证执行 token 仍有效,才允许 CAS 提交该候选对象。 候选 key 不跨尝试复用。租约过期的旧任务即使晚到,也不能覆盖当前候选或提交。复制请求结果未知时,先查本次候选对象并验证,不能盲目覆盖已存在候选。 采用存储版本控制时,固定对象 versionId;不能仅依赖一个在目标桶配置下可能不起作用的防覆盖头。ETag 不能当作原始文件 SHA-256。 ### 13.2 数据库原子提交 对象校验完成后,短事务中按统一顺序锁项目再锁 upload: ```text 重新验证 owner / project / upload 关联 若 upload 已 COMMITTED:返回原回执 验证 upload 状态与 verifier token 检查项目未删除 检查 head_version == expected_version 写入 blob 和 revision(version = expected_version + 1) 更新项目 head_revision_id / head_version / last_saved_at / updated_at 将 upload 标记 COMMITTED 并保存固定回执 reserved 配额转为 used 配额 提交 ``` CAS 失败时持久化 HEAD_CONFLICT 终态并释放预留额度,不推进 head。失败处理本身也需事务和幂等;不能依赖已经回滚事务里的错误状态更新。 对象读取、hash、解压和 OSS 复制在数据库长锁之外执行。revision/head/upload/配额必须原子一致。唯一约束是最后防线,不取代权限和版本检查。 ### 13.3 故障恢复 对象存储与数据库不在同一事务: - 固化成功、DB 提交失败:原事务恢复重试,未引用候选可能成为孤儿。 - DB 提交成功、响应丢失:重试返回固定 COMMITTED。 - 校验任务崩溃:租约到期后由恢复任务接管,用新 token/候选,禁止旧任务提交。 - 所有确认对象必须能从 revision 找到;孤儿允许晚回收,丢失已确认对象不可接受。 单体后端可用持久化任务表/现有队列,不要求额外引入消息中间件;只用进程内 Promise/线程而不持久化状态不合格。 ## 14. 文件校验与依赖 校验最终将被引用的对象,而非信任文件名、Content-Type、客户端元数据或 OSS 自定义 metadata。 必须检查: 1. 实际长度与声明相等,且不超过当前限制。 2. 服务端计算 SHA-256 与声明一致。 3. 原生容器签名、container.json、document.json 及真实格式版本。 4. 条目数、压缩后/展开后预算、JSON 深度、解析时间和资源预算。 5. 重复/歧义条目、路径穿越、绝对路径及不支持的归档特性。 6. 必要源 blob 引用、实际长度、CRC/hash 及原生格式所要求的结构约束。 7. 必要外部依赖是否已完整嵌入或被一期明确拒绝。 优先复用安全的原生读取组件或兼容的受限校验器,不自行猜测不完整文件结构。不能把“只读 ZIP 魔数”标为完整验证。校验器应能在资源限制下失败退出,业务服务保持可用。 允许把完整源文件作为受控临时单文件供 seek 读取,但不能按归档内路径解压到业务目录。不得让校验器访问任意服务器文件或主动抓取任意 URL。 ### 14.1 结构校验不等于几何保证 不运行参数化建模、布尔、渲染作为保存前置条件。可选显示/模型缓存按原生读取规则处理:缓存无效可回退不等于必要源数据可损坏;缓存永远不代替权威源数据。 保证持久化的原始字节可重取,不承诺任意外来工程都能无错误求解。编辑续编能力必须通过真实编辑器 round-trip 验收。 ### 14.2 外部依赖策略 - 已完整嵌入 `.sc` 的导入数据和图片等允许。 - 必需但未包含的外部设计/组件文件一期阻断云保存,返回 EXTERNAL_DEPENDENCIES_UNSUPPORTED。 - 按字段真实语义判断,不因任意 path 字段存在就误判必要依赖;仅作来源说明的路径不能与实际未解析依赖混为一谈。 - 不假装已上传附件,不自动下载用户任意 URL。 - 可选字体的回退与几何/必需依赖区分,明确兼容边界,不保证任意本机字体跨设备完全一致。 ## 15. 并发、草稿和前端 ACK ### 15.1 多窗口 A/B 都打开 head=3;A 提交成为 4;B 基于 3 的提交必须 HEAD_CONFLICT,不覆盖 A。不提供隐式 force=true。 冲突后前端保留草稿,可下载副本、另存新项目,或经用户确认重新加载云端。不能只刷新 head 版本号然后上传旧模型覆盖。 ### 15.2 保存过程中继续编辑 快照 S7 上传时用户继续编辑出 S8:确认只属于 S7,S8 仍未保存。服务端回显 snapshotId/operationId/file hash,前端匹配 user/project/document binding 后才能推进对应云基线。 现有引擎本地保存可能直接标记 saved,云适配必须拆分“取得快照”和“服务器确认此快照”。下载副本不能清云 dirty。 ### 15.3 本机恢复与身份 前端将固定快照、原 init 参数、operationId/uploadId 和草稿按用户/项目隔离持久化。刷新后先查询未知事务,再决定是否新建保存。 切账号、切项目或关闭文档,旧请求回执不能写入新 binding。401 后停止新写入并保护草稿;已经受理的原事务可能完成,不能宣称取消浏览器请求就撤销了提交。 ## 16. 错误码 | HTTP | code | 语义/前端处理 | | --- | --- | --- | | 400 | INVALID_ARGUMENT | 参数或受保护字段不合法,显示错误 | | 401 | UNAUTHORIZED | JSON;保护草稿,引导统一登录 | | 403 | QUOTA_EXCEEDED | 当前用户容量/项目额度不足 | | 404 | NOT_FOUND | 不存在或越权,不泄漏资源 | | 409 | HEAD_CONFLICT | 保留草稿,处理工程并发 | | 409 | METADATA_CONFLICT | 重读元数据,由用户决定 | | 409 | IDEMPOTENCY_KEY_REUSED | 同键异内容,协议错误 | | 409 | UPLOAD_NOT_READY | 临时文件尚未就绪,可同事务重试 | | 410 | PROJECT_DELETED | 阻止保存,不自动复活 | | 410 | UPLOAD_EXPIRED | 保留字节,重试需新 operation | | 413 | SOURCE_TOO_LARGE | 返回实际 maxSourceBytes | | 422 | INVALID_SOURCE_FILE | 原生工程结构无效 | | 422 | UNSUPPORTED_FORMAT_VERSION | 部署不支持实际文件版本 | | 422 | CHECKSUM_MISMATCH | 实际大小/hash 不符,本事务拒绝 | | 422 | EXTERNAL_DEPENDENCIES_UNSUPPORTED | 处理必要外部依赖 | | 429 | RATE_LIMITED | 返回 Retry-After,有界退避 | | 503 | SAVE_UNAVAILABLE | 结果可能未知,先查同笔事务 | 失败示例: ```json { "code": "HEAD_CONFLICT", "message": "云端已有更新版本", "data": { "uploadId": "66666666-6666-4666-8666-666666666666", "expectedVersion": 3, "currentHeadVersion": 4 }, "requestId": "server-generated-request-id" } ``` 错误不清除未保存状态。无 upload 的初始化提前拒绝不伪造 uploadId。持久事务拒绝结果必须可查询;5xx 不能让客户端猜测是否已提交。 ## 17. OSS、CORS、配额与清理 ### 17.1 私有存储 示例 key 结构,仅为后端内部约定: ```text cad//tmp////source cad//objects/////source.sc ``` - 环境隔离,私有读写;不为浏览器暴露长期密钥。 - 显示名称不决定 key。 - 最终 key 不覆盖、不跨校验尝试复用;有版本控制时固定版本。 - 临时授权只允许本次精确位置和合理大小/期限。 - 下载短期只读,正确设置附件文件名,不能注入响应头。 - 不记录 token、完整签名 URL 或上传签名表单到普通日志。 ### 17.2 CORS 和缓存 业务 API 精确允许实际开发/生产前端 origin: ```text Methods: GET, POST, PATCH, DELETE, OPTIONS Request headers: Authorization, Content-Type, Accept, Accept-Language, Idempotency-Key Exposed response headers: X-Request-Id, Retry-After ``` OSS 独立配置 POST/GET/HEAD 和实际预检,允许必要请求头并暴露实际读取的 ETag/请求标识。OSS CORS 和业务 API CORS 不能只配其中一处。 私有 API、snapshot、事务状态、身份和源文件不进入公共 CDN/SW 缓存。CAD 静态入口和 WASM 资源策略由前端发布处理,不能让静态 fallback 返回 HTML 冒充 API/文件。 ### 17.3 建议初始参数 | 配置 | 建议起点 | | --- | --- | | 单源文件 | 50 MiB,测试通过后启用 | | 上传授权 | 5 分钟 | | PENDING 事务 | 30 分钟 | | 下载授权 | 5 分钟 | | 每用户同时 PENDING/VERIFYING | 建议 3,按实际容量调整 | | 临时回收宽限 | 建议过期后至少 24 小时,再验证引用/租约 | | 历史确认快照自动清理 | 一期不启用 | 用户项目数、总存储、初始化频率、校验并发/内存/耗时和重试上限必须可配置。对外开放前确定具体值,不能隐式无限制。 ### 17.4 配额一致性 init 原子预留 expected bytes;COMMITTED 转 used;REJECTED/EXPIRED 仅释放一次。校验重试不重复记费/预留。存储容量按保留版本计,软删除且仍留存对象不能假装已释放实际容量。 临时与重复校验候选的物理开销另外受并发/任务/清理限制,不以逻辑 quota 代替存储运维预算。 ### 17.5 回收安全条件 可回收:过期临时对象、被拒绝/失效尝试的候选、无 revision 引用且无有效任务租约的孤儿。 禁止:全前缀无差别生命周期删除、删除 VERIFYING 有效候选、删除已确认引用、项目软删除立即清空历史。 清理与任务接管需防竞争,重新核对引用/状态/租约并使用安全宽限。对象存储中存在但 DB 无记录的异常候选也要能按受控前缀识别回收。 ## 18. 后台恢复、监控和部署 至少三个逻辑任务:校验、租约恢复、过期/孤儿清理。可部署在同一服务,但任务状态必须持久化,进程重启后可继续。 日志关联字段:requestId、userCode、projectId、uploadId、operationId、状态、大小、校验/提交耗时、拒绝码。日志脱敏。 指标:成功保存率、确认耗时、积压、长时间 VERIFYING、校验失败、冲突、存储/DB 错误、额度预留异常和孤儿增长。 部署顺序: 1. 核对/迁移数据库,部署向后兼容的 API 和任务。 2. 配置私有存储、CORS、额度和实际格式校验器。 3. 开发环境联调统一登录、CRUD、直传、确认、跨浏览器重开。 4. 确认编辑器构建与格式支持清单兼容,再切前端入口。 5. 保留回滚能力,不回删已经保存的工程或新版本数据。 备份必须同时考虑数据库引用和不可变对象。上线前完成恢复演练,恢复后的 head 必须能找到正确文件。RPO/RTO 沿用平台既有要求,缺少时由部署方明确,而非文档虚构 SLA。 ## 19. 前后端分工及配套交付 | 工作 | 后端 | 前端/编辑器 | | --- | --- | --- | | 统一登录弹窗 | 复用账号系统,不新增 CAD 登录接口 | 弹窗、继续原操作、过期时保护草稿与锁输入 | | 身份和资源权限 | 每次服务端验证 | 携带现有凭据,不决定 owner | | 项目列表/CRUD | 十接口中的相关 API | 页面、双语、交互 | | 工程字节 | 原样存储、校验 | 生成固定快照、读写原生 `.sc` | | 云保存 | 事务、CAS、幂等、固定回执 | 上传、查询、快照 ACK、dirty | | 恢复 | 任务接管、查询未知提交 | 用户/项目分区本机草稿 | | 格式兼容 | 发布真实校验支持清单 | 提供真实样例及构建/格式信息 | | 并发 | 防覆盖和删除竞争 | 冲突提示、另存、重新加载 | 前端 API 封装需支持 Idempotency-Key 等自定义请求头;OSS 上传使用独立直传逻辑,不强塞进只接受 JSON 成功信封的业务 request 函数。 工程字节使用二进制桥/Uint8Array/Blob,不通过普通 JSON 命令传 Base64。当前编辑器命令桥不等于完整云工程桥;需补齐序列化、打开、文档绑定和快照确认。 ## 20. Codex 实施顺序和交付要求 ### 阶段 A:检查和基础模块 - 识别现有认证、表、OSS、配置和任务设施,记录复用点。 - 提交可审查迁移,接入现有认证和通用错误信封。 - 完成 capabilities、CRUD、创建幂等和权限测试。 ### 阶段 B:源文件和保存协议 - 完成私有读取授权、不可变 snapshot。 - 完成 upload 初始化、预留额度、签名直传契约。 - 完成固化/校验任务、CAS、固定回执和状态查询。 - 完成重启恢复、过期与孤儿清理。 ### 阶段 C:联调和交付 - 先用测试身份、私有测试桶和真实 `.sc` 样例联调,再用真实浏览器编辑器验收。 - 故障/并发测试通过后提供配置、部署和回滚说明。 - 运行目标仓库适当的检查,不靠 mock 通过宣称真实 OSS/账号/数据库已经联通。 - 不将占位格式、无效签名、内存任务或模拟存储作为生产完成实现。 最终交付物: 1. 业务代码、数据库迁移、任务和配置模板。 2. OpenAPI 或等效机器可读接口定义,覆盖状态、错误和 HTTP 202。 3. 单元/集成/并发及故障恢复测试结果。 4. `.sc` 真实样例、校验器格式范围、大小/展开预算说明。 5. 测试环境 API 基址、允许 origin、OSS 实际行为和限制参数。 6. 账号接入说明,明确没有新增 CAD 登录体系。 7. 运维、清理、监控、备份恢复和回滚说明。 8. 实际完成/未完成列表,明确哪些仅模拟验证,哪些真实服务联调。 ## 21. 必须通过的验收矩阵 | 编号 | 场景 | 预期结果 | | --- | --- | --- | | T01 | 未登录调用 CAD API | JSON 401,不返回登录页 HTML 或 302 | | T02 | 登录后访问 CAD | 接受统一凭据,不需要 CAD 再登录 | | T03 | A 访问 B 的项目/事务/revision | 404,不签发任何授权 | | T04 | 同用户创建两个同名项目 | ID/文件独立 | | T05 | create 响应丢失后重试 | 同一项目,无重复创建 | | T06 | 同幂等键换请求内容 | 409,不替换原操作 | | T07 | EMPTY snapshot | head=0,revision/file=null | | T08 | 重命名并发 | 过期 metadataVersion 冲突,不改变工程 head | | T09 | 连续三次保存 | 三份不可变确认记录,head 指向第三次 | | T10 | init/complete 多次重试 | 同操作至多一个 revision | | T11 | COMMITTED 响应丢失 | 查询返回固定原回执 | | T12 | head 前进后重试旧成功操作 | 仍返回旧成功,不误报冲突 | | T13 | 双窗口基于同一 head | 一笔成功,另一笔冲突,不覆盖 | | T14 | S7 上传期间继续编辑 S8 | 仅确认 S7,S8 仍未保存 | | T15 | 未上传就 complete | UPLOAD_NOT_READY,可同事务继续 | | T16 | 签名过期、事务未过期 | 仅 PENDING 可同请求续签 | | T17 | PENDING 过期 | EXPIRED,不能复活或重复释放额度 | | T18 | 校验时覆盖 temp | 只提交已固化并验证的最终字节 | | T19 | 提交后旧临时授权继续写 | 不改变已确认 revision | | T20 | 大小/hash/格式声明不符 | 拒绝,不推进 head | | T21 | 非法 ZIP、路径、超大展开、损坏 blob | 受限安全失败,业务服务不崩溃 | | T22 | 必要外部依赖未嵌入 | 明确拒绝,不假保存 | | T23 | 校验任务退出/租约接管 | 新旧任务不竞争提交,无重复版本 | | T24 | 对象固化后 DB 故障 | 可恢复同操作,孤儿可安全回收 | | T25 | 保存与删除并发 | 不复活项目;已发生提交可查固定回执 | | T26 | 下载授权过期续签 | 仍绑定正确 revision/字节 | | T27 | 换账号/项目后旧回执晚到 | 不串数据、不更新新页面状态 | | T28 | 并发上传和配额释放 | 不超额、不重复扣费/释放 | | T29 | 清理与有效校验并发 | 不删有效候选或已引用对象 | | T30 | 跨浏览器下载 | 原始 size/hash 相同 | | T31 | 真实编辑器跨浏览器重开续编 | 特征/约束/参数可继续修改并再次保存 | | T32 | 备份恢复 | head 可读取正确不可变文件 | | T33 | 主站/PCB 回归 | 原登录和项目功能保持正常 | 完成定义:浏览器 A 登录主站账号,新建 CAD 项目并进行草图/三维编辑,确认云保存后关闭;浏览器 B 同账号从列表打开,修改既有参数后再次保存;A 重新打开获得新结果。失败、并发、删除、重试和换账号时没有假保存、串写或已确认文件被覆盖。真实后端/OSS/编辑器联调未完成前不得宣称线上可用。 ## 22. 可直接交给后端 Codex 的任务说明 ```text 请在当前 VibeMake 业务后端仓库实施《VibeMake CAD 后端实施与接口契约 v1.2》。 先阅读当前仓库规则,检查已有账号鉴权、API 信封、数据库迁移、OSS、任务和测试体系, 然后按文档完成独立 CAD 模块。已有能力优先复用,不覆盖现有 CAD 或其他业务数据。 用户已经决定:CAD 复用主站统一登录弹窗;后端仍须鉴权和 owner 校验,不新增 CAD 登录/注册/验证码/账号/token 签发。 CAD API 复用统一认证,逐请求校验项目、revision 和 upload 的 owner。 源文件是 SolidCraft 原生 .sc,不能套用 DWG/DXF 或将 STEP/STL/GLB 当权威工程。 严格实现不可变快照、受限 OSS 临时直传、最终固化校验、幂等事务、CAS 和固定 COMMITTED 回执。 上传成功、HTTP 202 和本机草稿不能当作云保存成功。 按文档顺序实现数据库、十个 API、任务恢复/清理、额度、错误码和验收测试。 环境差异从现有配置识别;无法确认的登录地址/身份验证/桶权限/格式校验器要列明, 不能编造已联通能力,也不能用 mock/内存存储冒充生产实现。 只在本地和测试环境验证,不部署生产或执行破坏性迁移。 交付机器可读接口定义、配置模板、测试结果、部署回滚说明及真实未完成项。 ```