Files
vibemake-pcb-studio/docs/vibemake/pcb-backend-requirements.md
T
likang 1fde96c05e
CI / typecheck + test + build (push) Has been cancelled
打通vibemake
2026-11-05 16:21:37 +08:00

17 KiB
Raw Blame History

VibeMake PCB 项目工作空间:后端实施要求

日期:2026-11-04。

状态:历史接口建议,已由 2026-11-05 提供的 frontend-pcb-workspace(1).md 替代。当前前端接入以 实际接口接入说明 为准。下文 capabilities、服务端 hash/manifest 校验、创建幂等字段及私有签名下载均为当时建议,不是现有后端能力,也不是当前前端的接口要求。本轮未修改或部署业务后端。

1. 业务边界与复用范围

PCB 与主站、CAD 使用同一平台账号和 Bearer 身份。PCB 内提供同款邮箱和图片验证码弹窗,调用 GET /api/auth/captcha、POST /api/auth/login、POST /api/auth/logout、GET /api/users/me。登录请求为 {email,captchaCode,captchaAnswer},响应为 {token,user,expiresIn};共享 vm.auth={token,user,expiresAt},expiresAt 为毫秒。账号服务继续由平台维护,不新增 PCB 用户表、密码、Supabase 账号、恢复密钥或跨项目映射。

PCB 项目独立建模和独立接口,不复用 /api/workspace/projects 或 CAD 项目记录。PCB 原理图、子页、板文件、设置、自定义库和工程资源组成一个工程;保存时一次确认整个工程。

本期不提供团队、邀请、发布社区、历史列表/版本恢复、回收站或管理后台接口。version 仅用于保存并发检查;它不是新增的历史管理产品。

接口命名参考当前 CAD /api/cad/workspace/projects。PCB 文件采用原生 KiCad 工程 ZIP,不使用 CAD 的 .sc 或早期 OpenCAD 的 DWG/DXF。

2. 通用约定

  • API 前缀:/api/pcb/workspace。核心项目路径为 /projects。
  • 所有接口必须平台鉴权。ownerUserCode 从已验证身份取得,不接受请求体指定归属。
  • pcbProjectCode、uploadCode 为不透明业务字符串;项目编码使用 1 至 120 个字母、数字、下划线或连字符,客户端 encodeURIComponent。不暴露数据库 ID,不强制为 UUID。
  • 前端为创建和上传分别生成稳定 clientRequestId / clientOperationId;后端需按本文实现幂等,不能只忽略这些字段。
  • 成功 HTTP 200,使用当前主站信封 {code:"OK",message:"",data:...,requestId:"..."};失败同时保留对应 HTTP 状态与稳定业务 code。
  • 分页参数 page、size、keyword;默认 size=20,最大 100。名称 trim 后 1~100 个 Unicode 字符,描述最多 2000 字符,同名允许。
  • 文件大小为原始字节整数,hash 为 64 位小写 SHA-256。时间必须采用 ISO 8601,包含 Z 或明确的 +08:00 等时区,不返回无时区字符串。
  • 账号/项目/签名/下载信息响应 Cache-Control:no-store。业务 API 支持主站前端域名的 CORS;错误不通过泄漏他人项目存在性区分权限。

3. 接口清单

核心八个接口与当前 CAD 风格一致;另提供一个能力端点,避免归档上限和格式版本仅写死在前端:

方法 路径 用途
GET /api/pcb/workspace/capabilities 归档格式、大小和文件数限制、读取模式
GET /api/pcb/workspace/projects 个人 PCB 项目分页
POST /api/pcb/workspace/projects 新建项目元数据,支持创建幂等
GET /api/pcb/workspace/projects/{pcbProjectCode} 工程元数据
PATCH /api/pcb/workspace/projects/{pcbProjectCode} 改名称/描述
DELETE /api/pcb/workspace/projects/{pcbProjectCode} 删除,阻止一切后续写入
POST /api/pcb/workspace/projects/{pcbProjectCode}/uploads/signature 为不可变 ZIP 申请上传批次
PUT /api/pcb/workspace/projects/{pcbProjectCode}/document 校验并原子提交同一批次;重复确认查询原回执
GET /api/pcb/workspace/projects/{pcbProjectCode}/document 当前已确认文件及其同一快照版本

本方案没有另设 complete/status 接口。确认超时重试同一 PUT document;如果后端采用异步校验,则必须另行明确 VERIFYING、状态查询和客户端轮询协议,不能保持当前成功回执形状却提前返回“保存成功”。

3.1 capabilities

建议的初始限制如下,属于待压测的配置起点,不能据此声称现有浏览器或服务器已经通过大工程验收:

{
  "archiveFormat": "vibemake-pcb-project+zip",
  "manifestVersions": [1],
  "maxArchiveBytes": 52428800,
  "maxUnpackedBytes": 209715200,
  "maxFileBytes": 52428800,
  "maxFileCount": 2000,
  "maxPathDepth": 16,
  "downloadMode": "signed"
}

ZIP 50 MiB、解压总量 200 MiB 只是初始建议;服务端和前端共同限额。后续上调需要测量峰值内存、worker 拷贝、ZIP 解析和上传时长,不直接沿用 CAD 256 MiB 的单文件上限。

3.2 项目 CRUD

POST 请求:

{
  "name": "控制板",
  "description": "",
  "clientRequestId": "<客户端创建请求标识>"
}

同一 owner + clientRequestId 重试返回同一个项目;若请求标识相同但名称/描述不一致,返回幂等参数冲突。标识与响应应跨短期网络重试保留。PATCH 不修改文件版本,不改 ZIP 内部名称,不触发项目文件重新上传。

项目对象:

{
  "pcbProjectCode": "<不透明项目编码>",
  "name": "控制板",
  "description": "",
  "hasDocument": false,
  "version": 0,
  "fileName": "",
  "sizeBytes": 0,
  "sha256": null,
  "savedAt": null,
  "createdAt": "2026-11-04T10:00:00+08:00",
  "updatedAt": "2026-11-04T10:00:00+08:00"
}

新项目没有云文件,hasDocument=false、version=0;前端据此在浏览器创建原生工程,首次确认保存才产生 document。创建成功后页面退出导致空项目遗留允许保留,不伪造文件已保存。

GET 列表返回 {items,page,size,total},只含本人未删除工程,按 updatedAt 倒序并以稳定主键作为相同时间的次序。GET 详情与 PATCH 返回项目对象,DELETE 返回 null。

3.3 上传签名

POST 请求:

{
  "fileName": "project.zip",
  "sizeBytes": 123456,
  "sha256": "<整个ZIP的SHA-256>",
  "expectedVersion": 0,
  "clientOperationId": "<当前不可变快照的上传操作标识>",
  "archiveFormat": "vibemake-pcb-project+zip",
  "manifestVersion": 1
}

expectedVersion 必须是 JSON 非负整数;sizeBytes 必须非零且不超限。上传前也验证 owner、工程未删除和基础版本,但最终以确认时的事务校验为准。

相同 owner/project/clientOperationId 与相同请求指纹,重复签名返回同一 uploadCode 和有效的授权信息;参数不一致返回 PCB_IDEMPOTENCY_CONFLICT。不能把“超时重试签名”解释为多个独立文件版本。

签名响应:

{
  "uploadCode": "<批次编码>",
  "clientOperationId": "<原操作标识>",
  "uploadUrl": "<OSS签名POST地址>",
  "formFields": {
    "<签名字段>": "<值>"
  },
  "expiresAt": "<明确截止时间>"
}

表单字段按现有 OSS 签名机制返回,前端原样加入 FormData,最后 append file。POST 不带平台 Authorization、Cookie,不手设 multipart Content-Type,也不自行覆盖 ACL、key、policy。

签名建议有效 15 分钟,服务端校验批次截止时间。临时对象键由服务端生成,包含环境/用户/工程/批次的不透明标识;文件名不参与决定路径。每个批次禁止覆盖,确保验证期间和确认后不能被签名再次改写。

3.4 确认保存与幂等

PUT 请求:{uploadCode:"<批次编码>"}。

成功回执:

{
  "pcbProjectCode": "<项目编码>",
  "uploadCode": "<已确认批次>",
  "clientOperationId": "<原操作标识>",
  "version": 1,
  "sha256": "<已验证ZIP的SHA-256>",
  "savedAt": "<服务器确认时间>"
}

处理要求:

  1. 根据鉴权身份定位批次及项目,校验归属、期限、文件元数据和项目状态。
  2. 已 COMMITTED 的同一批次返回首次回执,不重复增加 version;即使项目后来有新版,也返回原批次回执而不是覆盖成最新版。
  3. 对象未完整上传时返回 PCB_FILE_MISSING,不更新项目指针。OSS 上传响应丢失时,已存在正确对象应允许正常确认。
  4. 服务端读取并实际校验对象大小、SHA-256、ZIP/manifest 结构、条目边界和引用入口,不信任客户端提交的 hash 或扩展名。
  5. 对暂存对象做不可变固化,或使用已确保禁止覆盖的不可变对象;数据库最终引用的字节必须就是已校验的字节。不能先验后允许同 key 再上传。
  6. 事务内锁定或 CAS 更新工程:当前 version 必须等于 expectedVersion,且没有 deleted。成功后 version+1、替换当前 document 指针、记录 savedAt 和批次 COMMITTED 回执。
  7. 两个同时使用同一 expectedVersion 的保存只有一个成功。另一个返回 PCB_VERSION_CONFLICT;不得按客户端时间戳决定覆盖。
  8. 数据库提交失败时不返回成功;已上传的孤立对象稍后清理。确认成功但 HTTP 响应丢失时,重试同一 uploadCode 找回同一回执。

客户端仅在明确收到缺文件、大小不符或过期这类终态后,才可退役原批次,为同一快照生成新的 clientOperationId 申请替代批次;未知结果一直查询原批次。旧批次替代后也不可绕过 version CAS 再提交。

同一 uploadCode 已确认且项目仍存在时重复确认不受原上传有效期影响。幂等回执不能随着签名过期立即丢失。项目删除后统一拒绝继续写入,旧页面不可借已确认批次恢复工程。

3.5 当前 document 读取

返回:

{
  "pcbProjectCode": "<项目编码>",
  "version": 1,
  "fileName": "project.zip",
  "sizeBytes": 123456,
  "sha256": "<整个ZIP的SHA-256>",
  "archiveFormat": "vibemake-pcb-project+zip",
  "manifestVersion": 1,
  "downloadUrl": "<短期读取地址>",
  "expiresAt": "<签名到期时间>",
  "savedAt": "<服务器确认时间>"
}

version、文件引用、hash 必须来自同一个已确认快照;前端不能把先前 GET 项目详情的版本拼到后来下载的文件上。尚未保存返回 PCB_DOCUMENT_NOT_FOUND;详情明确为空工程时,前端提示“此项目尚未保存设计”,用户选择创建空白或返回列表,不能自动把空板当作恢复成功。

推荐 downloadMode=signed:工程对象私有,GET document 验证 owner 后签发短期单对象 GET。下载过期可重新取 document;若 version/hash 已变化则重新处理新云版本,不能混用地址与版本。

当前 CAD 的实际约定是普通 OSS/CDN 地址和 expiresAt=null。若 PCB 采用 public 模式复用现有基础设施,capabilities 必须返回 public、expiresAt=null,并明确持有直链可访问、删除项目不能撤销直链。平台接口的 owner 校验不会自动改变 Bucket/CDN 的读权限。本方案推荐 PCB 私有读取;不把该能力假设为现有 CAD 已具备。

4. 归档内容和校验

归档是 ZIP,根目录唯一的 vibemake-project.json:

  • format=vibemake-pcb-project,schemaVersion=1,engineBuild 为编辑器构建标识。
  • roots 为 {project,schematic,board},各值为相对路径或 null,至少有一个支持的原生设计入口。
  • files 为所有原生/资源条目的 path、原始 sizeBytes、原始 SHA-256,不包含 manifest 自身。
  • directories 为必要空目录;libraryDependencies 为明确的公共库标识/版本,不包含用户 token 或绝对凭据 URL。
  • unresolvedDependencies 为 [{kind:"model3d",sourcePath:"project.kicad_pcb",reference:"missing.step"}]。缺失外部模型允许保存,后端不得因该列表非空拒绝已有设计;缺少主设计、非法路径或 hash 不匹配仍然拒绝。
  • 每个被列出的文件必须存在,ZIP 实际设计/资源条目必须在 manifest 中;不接受偷偷附带不在索引中的其他文件。

服务器应限制实际解压量和实际文件数,不能只相信 ZIP central directory 的 size。限制单文件、路径深度和处理时长,按配置防止异常膨胀。前端也做相同校验,但不替代服务端。

路径以 / 分隔,拒绝绝对路径、盘符、..、空段、NUL、控制字符、规范化后重复路径、文件目录冲突和符号链接;跨平台兼容时还需处理大小写折叠冲突。不要把条目按不可信名称直接解压到服务器任意目录。

不执行 ZIP 内脚本、制造文件或库内容;后端不解析并重写 KiCad 几何,不更新网络、不自动布线、不转 STL/STEP/GLB。检查归档结构和存储完整性不等于保证第三方 CAD 特性无损。

嵌入的原生文件保持原字节,禁止把所有文件都当 UTF-8 文本重编码。自定义模型、图片等二进制必须保留。不要将整个 ZIP 再转 base64 放进 JSON。

5. 建议存储模型

可按现有框架/数据库调整命名,不要求为本期增加完整的版本管理模块:

表 主要字段与约束
pcb_workspace_projects 内部 id、pcb_project_code、owner_user_code、name、description、version、当前 object key/size/hash、archive/manifest 版本、saved_at、created_at、updated_at、deleted_at;业务编码唯一
pcb_workspace_uploads upload_code、project_id、owner、client_operation_id、expected_version、请求指纹、临时/最终 key、size/hash、expires_at、state、确认 version/saved_at/receipt;owner/project/operation 唯一
创建幂等记录 owner/client_request_id 唯一、请求指纹与 project_id;可复用现有幂等基础设施

确认后工程只暴露当前版本;旧对象保留/回收与幂等事务分开,不增加历史查询页面。删除使用 tombstone 或等价状态,阻止未完成上传之后把项目重新写回来;默认不做离线排队删除。

对象路径前缀独立,例如环境根下 pcb-workspace/,不混入社区公开资源或 CAD 工程目录。可复用同一 OSS 连接和现有签名服务,不要求另建云厂商账户。

临时/失败对象允许后台过期清理;必须排除当前工程引用、已确认批次所需对象和验证中的对象。历史对象保留策略另行配置,不在本期默默删除旧文件或提供恢复承诺。

6. 错误码

HTTP / code 前端处理
400 BAD_REQUEST / PCB_INVALID_ARCHIVE / PCB_INVALID_MANIFEST / PCB_UNSAFE_PATH 保留工程,指出包/路径/参数问题
401 UNAUTHORIZED 锁住当前工程、保留草稿,重新登录并重新核对身份
404 NOT_FOUND 不存在/非本人/已删除,停止该项目写入;不显示他人信息
404 PCB_DOCUMENT_NOT_FOUND 仅空项目进入新建原生工程流程
409 PCB_VERSION_CONFLICT 保留修改;下载、另存或用户确认后重开;不自动覆盖
409 PCB_FILE_MISSING / PCB_FILE_SIZE_MISMATCH / PCB_UPLOAD_EXPIRED 根据明确结果保留原 bytes 后重试对应阶段
409 PCB_IDEMPOTENCY_CONFLICT 停止自动重试,检查相同请求标识是否被不同内容复用
422 PCB_HASH_MISMATCH / PCB_UNSUPPORTED_MANIFEST 不提交,保留设计和副本
413 PCB_FILE_TOO_LARGE / PCB_UNPACKED_TOO_LARGE / PCB_TOO_MANY_FILES 前端显示实际限制,保持设计
429 RATE_LIMITED 保留快照,按 Retry-After 延后重试
502 PCB_OSS_ERROR 保留批次,重试确认或读取
503 PCB_STORAGE_UNAVAILABLE 提示存储未配置,不回退成本机模拟成功

下载对象存储返回 403 与平台 401 不混淆:前者可能为签名过期/CORS/对象访问配置问题,不清平台登录态。真实离线、5xx 和普通超时均不当作退出登录。

7. 部署与联调责任

后端:数据库迁移、PCB 模块、权限/CAS/幂等、OSS 配置与 ZIP 校验;不部署前端编辑器运行服务。PCB_MAX_ARCHIVE_BYTES 等归档限制和独立存储开关通过环境配置,名称按后端约定统一。

前端:独立 designer 构建、同源 /pcb/、身份适配、快照/归档、签名直传、确认/恢复。所有大小/hash 在原生 bytes 和最终 ZIP 上按约定计算。

OSS:允许 VibeMake dev/prod 域名 POST/GET/HEAD/OPTIONS 所需 CORS;签名表单条件匹配实际大小/类型/禁止覆盖要求;私有读取模式下确保可签名读取。公共符号/封装/模型库单独配置,不把用户 ZIP 放进公共库分发路径。

验收必须使用真实账号和对象存储,至少验证:A 保存、B 同账号打开续编、A 读取 B 新版;另一账号不得读写;保存确认断网重试不多一个版本;并发只有一个提交;删除后旧保存不能复活;ZIP/manifest/hash 不匹配不推进版本。

本机 mock 只用于前端开发,必须有醒目标识且显式启用,不作为 dev/prod 的默认 API 回退。不把模拟服务成功当作真实服务器已完成。