Files
vibemake-pcb-studio/docs/vibemake/pcb-api-integration.md
T

7.8 KiB
Raw Blame History

PCB 后端接口接入说明

更新日期:2026-11-05。接口依据为本次提供的 frontend-pcb-workspace(1).md。本文描述前端接入实现;旧的后端实施建议不再作为接口契约。

本地运行与环境

在相邻的 vibemake 目录运行 node scripts/server.mjs,通过 http://127.0.0.1:8091/pcb/ 访问。启动脚本默认以真实接口模式启动独立 PCB Vite 服务,/api 沿用主站的 dev 后端代理。更换后端使用 API_TARGET=https://后端域名 node scripts/server.mjs。

单独开发 PCB 时运行 pnpm -C designer dev;其 /api 也代理至 dev 后端,可通过 API_TARGET 覆盖。不同端口的 localStorage 不共享,所以统一登录必须在同一个主站源地址下验收,不能混用 localhost 与 127.0.0.1。

只有显式运行 PCB_API_MODE=mock node scripts/server.mjs 或 pnpm -C designer dev:mock 才启用本机模拟。模拟账号使用独立键,不覆盖主站 vm.auth。生产构建禁止模拟模式,接口故障不会回退模拟。

VITE_PCB_API_BASE 留空时按主站域名选择 dev/prod API;自建环境可显式设为 /api 并配置反向代理。此变量是公开的构建配置,不是服务端运行时配置。前端不存储 OSS RAM 密钥。

已对齐的接口

统一登录复用 /auth/captcha、/auth/login、/auth/logout、/users/me。存储格式仍为 vm.auth={token,user,expiresAt};有身份时先验证 /users/me。业务请求携带 Bearer;直传、下载均不携带平台 Token 或 Cookie。401 保留当前工程并要求重新验证账号,超时、断网和 5xx 不清空身份。

工作空间前缀为 /api/pcb/workspace/projects:

操作 方法和路径 请求或返回
分页搜索 GET 空路径 page,size=20,keyword,关键词最多 100 字符
创建 POST 空路径 {name,description:""}
详情 GET /{code} 项目对象,保留 coverUrl
重命名 PATCH /{code} {name},不改内部文件名与文件版本
删除 DELETE /{code} data 为 null
签名 POST /{code}/uploads/signature 仅 {fileName,sizeBytes,expectedVersion}
确认 PUT /{code}/document 仅 {uploadCode};回执仅要求项目编码、version、savedAt
打开 GET /{code}/document 普通 downloadUrl、expiresAt=null、version、fileName、sizeBytes

所有业务响应解析 {code,message,data,requestId},不缓存。无时区的业务时间按 +08:00 解析。项目编码按不透明字符串处理,不依赖数据库 ID 或显示名称。

不请求 /pcb/workspace/capabilities,因为后端契约没有该接口。不向服务器发送 clientRequestId、clientOperationId、sha256、archiveFormat 或 manifestVersion,也不要求这些字段出现在签名、回执或 document 中。本地事务仍保留操作标识和 ZIP hash,用于草稿、缓存和恢复,与后端字段分开。

现有页面保留新建、导入、搜索、重命名、删除。封面在工程保存确认后自动生成,不增加手工封面编辑器。重命名不改变封面。

自动项目封面

  • 从本次确认的原生 ZIP 重新解析并导出,不截取当前屏幕。PCB 有内容时使用完整二维顶视图;空板回退根原理图;两者都为空则恢复默认占位图。板外元件计入边界,默认不使用三维视角。
  • 在独立 worker 使用原生绘图导出,固定图层、配色、完整内容边界和约 10% 留白;排除界面、网格、选中态、临时工具和图框。输出 800×450 WebP(浏览器不支持 WebP 编码时允许 PNG),保留嵌入位图,列表等比完整展示并延迟加载。编辑器缩放与用户设置不变。
  • 使用 POST /api/uploads/project-covers/signature,仅发送 {contentType,fileSize};最大 5 MiB。OSS 表单原样加入签名字段,图片文件最后追加,不携带平台 token、cookie 或手动 multipart Content-Type,HTTP 200 即成功。将返回的完整 coverUrl 用 PATCH /api/pcb/workspace/projects/{code} 绑定;空工程使用 coverUrl: "" 清除旧图。
  • 工程确认成功后立即记为已保存,再显示“正在更新封面”。生成最长 12 秒,整个封面步骤最长 30 秒。封面失败不改变工程版本或保存结果,保留原图并显示可重试提示。重试使用同一 ZIP,不重新增加设计版本;未知确认恢复后也使用原批次 ZIP。保存期间的新修改继续保持未保存状态。
  • 写入前核对云版本,账号/会话切换中止任务,已知过期版本不更新封面。现有 PATCH 没有版本条件,因此“检查后、PATCH 前”仍存在跨标签页竞态;严格保证封面与工程版本原子对应需要后端提供带版本条件的绑定。前端没有发送未文档化字段,也没有修改后端。

开发模拟模式把图片 data URL 保存在本机数据库,刷新仍可显示;不会创建真实 OSS 对象。真实封面签名、OSS CORS 和跨设备显示需后端联调。

保存、失败和重开

  1. 在安全操作边界刷新各编辑器、等待文件写队列、捕获不可变快照。
  2. 原始字节与原生目录整体打包,加入前端 manifest。第一次保存前已有项目编码,上传失败不重建项目。
  3. 申请签名,FormData 原样加入所有 formFields,最后追加 application/zip 文件;不手动设置 multipart Content-Type。
  4. OSS POST 成功要求 HTTP 200,不解析 JSON。随后用原 uploadCode 确认,收到合法回执才更新已保存 revision。上传期间的新修改继续显示未保存。
  5. 确认超时或上传结果不明,保留原 ZIP 和批次,下次先确认原批次;仅明确缺文件时重传。明确过期或大小不符时为原快照重新申请。发生版本冲突保留本地工程,不自动更换基础版本覆盖。
  6. 重开先处理待确认批次,再读取 document、下载、校验大小、受限解压、校验 manifest 和全部文件 hash,成功后才挂载。编辑基础版本取 document.version,不能使用此前详情的 version。普通下载地址 403 按故障处理,不当作临时签名过期无限重取。

服务器不解析 ZIP,也不返回 ZIP SHA-256;工程可编辑性、归档路径和条目完整性由前端验证。manifest 是前端归档格式,不是额外的服务端契约。缺少外部模型仍可保存,缺少原生设计或内部 hash 不一致则不能加载。重开可继续编辑,跨会话不恢复旧 Undo/Redo 栈。

浏览器当前限制:ZIP 256 MiB(与文档默认一致)、单文件 256 MiB、解压总量 512 MiB、2000 文件、路径深度 16。后端可独立返回更低限额的 413;上调后端配置不会自动提高浏览器限制。这些限额不代表所有大小的工程均已完成性能验收。

429 读取 Retry-After 并阻止冷却期内再次请求,不自动重放写操作;其他文档错误码保留 requestId 并显示可操作的错误提示。文档未提供创建幂等键,创建响应不明时要求先刷新列表核对,不把再次 POST 宣称为幂等重试。

验证与部署

接口测试见 qa/unittests/designer/pcb_http_api.test.ts,认证测试见 pcb_platform_auth.test.tsx,原生往返和模拟事务测试见 pcb_platform.test.ts。HTTP 测试使用与文档一致的最小服务端响应,覆盖 Bearer 隔离、multipart、上海时间、无服务端 hash 的下载、document 基础版本、未知确认恢复、并发冲突、限流与账号切换。

构建仍为 pnpm -C designer build,产物独立挂载到主站 /pcb/;主站打包脚本可收录该目录。服务器保留 /pcb/p/... 的 SPA 回退及正确的 API 环境、OSS/CDN POST/GET CORS。此次不修改业务后端、数据库、Bucket ACL 或服务器部署配置。

真实账号、真实 OSS 和跨设备往返需单独联调;本地契约测试不能代替这些验收。