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.
46 KiB
VibeMake CAD 后端实施与接口契约
历史方案:当前前端对接以 CAD 个人工作空间前端对接 为准(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. 已确定的产品决定
- 产品名为 VibeMake CAD,浏览器编辑器基于 SolidCraft/Rust/WASM。
- CAD 页面未登录时打开 VibeMake 统一登录弹窗,登录完成后继续当前 CAD 页面或操作。
- CAD 不新增登录页、注册、验证码、账号表、密码管理或 token 签发接口。 统一账号系统继续负责登录;CAD API 必须复用现有认证并校验资源归属。
- 推荐 CAD 前端与主站同源部署:
/cad/为列表,/cad/editor/?project=<UUID>为编辑器。API 基址沿用现有业务系统,可以是独立 API 域名或同源反向代理。 - 一个 CAD 项目对应一个原生
.sc工程。STEP、STL、GLB 等不是云端权威工程格式。 - CAD 数据独立建模,复用主站用户和基础设施,不直接复用社区/工作区项目记录,不建立隐式 projectCode 映射。
- 一期手动云保存;本机草稿由前端负责,不等于云保存。
- 文件直传私有 OSS 临时位置;后端固化、校验并原子提交后,才确认保存成功。
- 一期保留所有已确认快照,但不提供历史列表/恢复 UI。删除先做逻辑删除。
- 不自动覆盖并发保存;使用基于云端版本的比较并提交(CAS)。
1.1 一期不包含
- 多人实时协同、团队、分享、社区发布、CAD 管理后台。
- 服务端建模、几何布尔、转换格式、渲染缩略图。
- 工程目录、外部附件集合、任意 ZIP 上传、分片续传、差量同步。
- 历史版本查询界面、历史恢复、物理删除入口。
- 对主站和 PCB 数据模型或登录体系的重构。
缩略图一期允许为空,由列表显示占位图标。以后增加时,缩略图是绑定 revision 的派生资源,不能代替源文件。
1.2 核心不变量
- OSS 上传成功不代表云保存成功;只有
COMMITTED才可显示“已保存到云端”。 - 项目 head 永远只指向已经固化并校验通过的不可变文件。
- 同一保存 operation 无论重试多少次,最多生成一个 revision。
- 客户端提交的 owner、用户 ID、对象 key 不能决定实际权限。
- 文件下载、副本导出、本机草稿都不能推进云端版本。
- 失败、超时、冲突时不能清除用户当前未保存内容。
2. 后端 Codex 开始实施前的检查
先阅读目标后端仓库的 AGENTS.md、README、运行和测试说明,再检查:
- 当前语言、框架、项目分层和 API 路由习惯。
- 用户稳定标识、现有鉴权中间件、token/会话验证和账号禁用规则。
- 数据库、迁移工具、事务隔离和锁使用方式。
- OSS SDK、私有桶、签名上传下载、当前环境配置与 CORS。
- 统一 JSON 信封、异常处理、requestId、国际化和限流组件。
- 是否已经存在 CAD 模块、表、接口或历史工程数据。
- 后台任务、持久化队列、定时任务及测试基础设施。
实施要求:
- 优先扩展现有业务后端,不因本文新建整套账号服务或不必要的微服务。
- 如果 CAD 模块位于同一后端,直接复用认证中间件;如果独立部署,接入现有身份验证机制,不自行设计另一种 token。
- 已有 CAD 功能先核对实际行为,补齐缺口,不重复建表、覆盖数据或删除旧实现。
- 如果已有 OpenCADStudio/DWG/DXF 项目,保留原格式和引擎归属;不能把旧记录改标为
.sc。需要兼容时使用明确的 engineKind/格式区分和可回滚迁移。 - 表和类可遵循现有命名习惯,但本文公共 API 字段、状态、错误码和语义需保持一致;必须变更时更新契约和测试,不能静默改动。
- 不假设用户 ID 类型、桶名或 OSS 密钥;登录弹窗复用现有主站接口。优先从现有配置解析,缺少的环境值作为明确配置项交付。
- 不部署正式环境,不执行破坏性数据迁移,不创建/修改生产用户,不把测试写请求发往生产。
3. 架构与职责
| 组件 | 职责 |
|---|---|
| 统一登录弹窗和账号后端 | 登录、凭据签发/失效、账号状态和退出 |
| CAD 平台前端 | 登录弹窗、列表、项目名称、上传调度、保存状态、草稿和冲突提示 |
| Rust/WASM 编辑器 | 几何、约束、参数、原生工程快照生成与加载 |
| CAD 业务模块 | 鉴权、CRUD、快照、上传事务、配额、幂等和提交 |
| 文件校验任务 | 固化源文件、检查实际字节与结构、提交或拒绝 |
| 数据库 | 项目、不可变 revision、对象引用、事务与幂等结果 |
| 私有 OSS | 临时上传、最终不可变文件、短期读取授权 |
标准保存链路:
固定本次工程快照及字节
-> 创建保存事务
-> 直传 OSS 临时位置
-> complete 请求
-> 最终对象固化与校验
-> 数据库原子提交 revision/head/事务回执
-> 返回 COMMITTED
业务后端沿用现有技术栈。结构校验可使用受限的独立组件或复用兼容的原生读取组件,不要求服务端运行桌面 CAD,不执行建模重放或渲染。
4. 统一登录和鉴权边界
4.1 登录弹窗由主站统一系统负责
CAD 复用主站邮箱与图片验证码登录弹窗,继续调用现有 auth 接口,不新增 CAD 专用 captcha/login/register 接口。
前端流程:
- 用户访问列表或编辑器。
- 未登录时自动打开主站同款登录弹窗;关闭后停留在登录提示页,不加载私有项目或引擎。
- 登录成功后继续原 CAD 深链接或待执行操作。
- CAD 使用统一账号系统已有的凭据请求业务 API。
- 编辑中凭据失效时,先保护本机草稿,再引导重新登录。
当前主站已有 Bearer 请求方式和 vm.auth 前端身份存储。以实际统一账号契约为准复用,不为 CAD 强制迁移 Cookie、OIDC 或另发 token。
一期不新增 /login/ 路由,不使用 returnTo 跳转登录。弹窗打开时锁定画布输入和键盘焦点;简体中文与英文共享当前 CAD 语言。
同源 /cad/ 复用主站 vm.auth 和已有 Bearer。编辑中明确 401 时保护原账号草稿、锁定输入并打开登录弹窗;同账号续登先查未知事务,不同账号登录后释放原工程并进入新账号列表。跨标签页身份变化必须同步,旧账号回执不得更新新会话。
4.2 CAD 后端仍需验证身份和权限
所有本文业务接口,包括 capabilities,都要求现有认证。当前请求方式:
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/<N> 是示例占位,生产响应必须是真实格式值。
前端支持、后端接受和校验器识别的格式范围需要建立发布清单。新版本不支持时明确拒绝,不能静默丢弃未知内容。
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。本文示例省略真实域名。
{
"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
{
"apiVersion": 1,
"engineKind": "solidcraft",
"sourceFormats": ["sc"],
"preferredSourceFormat": "sc",
"containerFormats": ["solidcraft-container/1"],
"documentFormats": ["solidcraft/<N>"],
"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 必须返回校验器实际接受的版本清单,不返回占位 <N>。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。重命名不伪装成保存;分页期间新保存可改变顺序,不承诺固定快照分页。
{
"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: <UUID>。
{
"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}
{
"name": "机械臂支架 V2",
"expectedMetadataVersion": 1
}
仅允许修改名称。使用 metadataVersion 条件更新并递增,返回更新后的项目。过期版本 409 METADATA_CONFLICT,details 包含 currentMetadataVersion。若响应丢失,前端重读元数据确认,不盲目重复覆盖。
不修改源字节、工程 headVersion 或 lastSavedAt。普通工程保存不修改 metadataVersion;updatedAt 可以更新。
9.6 DELETE /projects/{projectId}
{
"id": "11111111-1111-4111-8111-111111111111",
"deleted": true
}
逻辑删除,与保存提交竞争同一项目锁。重复 owner 删除返回同样成功;越权/不存在 404。
删除后禁止新 init、新快照授权和未完成保存提交。已确认 revision 保留,不修改其他产品数据。已签发读取 URL 可能到期前仍可用,不承诺删除时即时撤销;读取授权短期有效。
10. 工程快照与下载
10.1 GET /projects/{projectId}/snapshot
EMPTY:
{
"projectId": "11111111-1111-4111-8111-111111111111",
"headVersion": 0,
"revisionId": null,
"savedAt": null,
"file": null
}
READY:
{
"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/<N>",
"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
{
"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/<N>",
"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,返回原事务当前状态。
{
"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": "<SDK 生成的策略>",
"<签名相关字段>": "<SDK 生成的值>",
"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 浏览器直传
- 构造 FormData,原样添加 fields。
- 最后附加 file 字段和完整原始字节。
- POST 到指定 OSS 地址,不带业务 Bearer,不手动设置 multipart boundary。
- OSS 成功后请求 complete。
此处 multipart/form-data 是单文件表单上传,不是 OSS 分片协议。不增加 Base64 JSON 工程上传通道。
OSS 响应丢失时可先调用 complete;文件不存在则收到 UPLOAD_NOT_READY 后继续同事务。签名过期但 PENDING 事务未过期,可相同 init 续签。
12. complete、状态查询与幂等回执
12.1 状态机
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:
{
"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:
{
"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,例如:
{
"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,再假设稍后复制到的内容相同”。
推荐实现:
- complete 取得事务执行权,转 VERIFYING,持久化任务。
- 每次校验尝试生成独立 token 和候选 final key,先记录后执行复制。
- 将 temp 复制到仅后端可写的候选对象;可用源 version/条件复制固定来源。
- 对候选对象实际字节计算 size/hash,执行结构/版本/依赖校验。
- 验证执行 token 仍有效,才允许 CAS 提交该候选对象。
候选 key 不跨尝试复用。租约过期的旧任务即使晚到,也不能覆盖当前候选或提交。复制请求结果未知时,先查本次候选对象并验证,不能盲目覆盖已存在候选。
采用存储版本控制时,固定对象 versionId;不能仅依赖一个在目标桶配置下可能不起作用的防覆盖头。ETag 不能当作原始文件 SHA-256。
13.2 数据库原子提交
对象校验完成后,短事务中按统一顺序锁项目再锁 upload:
重新验证 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。
必须检查:
- 实际长度与声明相等,且不超过当前限制。
- 服务端计算 SHA-256 与声明一致。
- 原生容器签名、container.json、document.json 及真实格式版本。
- 条目数、压缩后/展开后预算、JSON 深度、解析时间和资源预算。
- 重复/歧义条目、路径穿越、绝对路径及不支持的归档特性。
- 必要源 blob 引用、实际长度、CRC/hash 及原生格式所要求的结构约束。
- 必要外部依赖是否已完整嵌入或被一期明确拒绝。
优先复用安全的原生读取组件或兼容的受限校验器,不自行猜测不完整文件结构。不能把“只读 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 | 结果可能未知,先查同笔事务 |
失败示例:
{
"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 结构,仅为后端内部约定:
cad/<env>/tmp/<owner>/<project>/<upload>/source
cad/<env>/objects/<owner>/<project>/<upload>/<attempt>/source.sc
- 环境隔离,私有读写;不为浏览器暴露长期密钥。
- 显示名称不决定 key。
- 最终 key 不覆盖、不跨校验尝试复用;有版本控制时固定版本。
- 临时授权只允许本次精确位置和合理大小/期限。
- 下载短期只读,正确设置附件文件名,不能注入响应头。
- 不记录 token、完整签名 URL 或上传签名表单到普通日志。
17.2 CORS 和缓存
业务 API 精确允许实际开发/生产前端 origin:
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 错误、额度预留异常和孤儿增长。
部署顺序:
- 核对/迁移数据库,部署向后兼容的 API 和任务。
- 配置私有存储、CORS、额度和实际格式校验器。
- 开发环境联调统一登录、CRUD、直传、确认、跨浏览器重开。
- 确认编辑器构建与格式支持清单兼容,再切前端入口。
- 保留回滚能力,不回删已经保存的工程或新版本数据。
备份必须同时考虑数据库引用和不可变对象。上线前完成恢复演练,恢复后的 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/账号/数据库已经联通。
- 不将占位格式、无效签名、内存任务或模拟存储作为生产完成实现。
最终交付物:
- 业务代码、数据库迁移、任务和配置模板。
- OpenAPI 或等效机器可读接口定义,覆盖状态、错误和 HTTP 202。
- 单元/集成/并发及故障恢复测试结果。
.sc真实样例、校验器格式范围、大小/展开预算说明。- 测试环境 API 基址、允许 origin、OSS 实际行为和限制参数。
- 账号接入说明,明确没有新增 CAD 登录体系。
- 运维、清理、监控、备份恢复和回滚说明。
- 实际完成/未完成列表,明确哪些仅模拟验证,哪些真实服务联调。
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 的任务说明
请在当前 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/内存存储冒充生产实现。
只在本地和测试环境验证,不部署生产或执行破坏性迁移。
交付机器可读接口定义、配置模板、测试结果、部署回滚说明及真实未完成项。