Files
community/docs/frontend-pcb-workspace.md
T
2026-11-04 17:35:31 +08:00

10 KiB
Raw Blame History

PCB 个人工作空间前端对接

PCB 工作空间使用独立的 /api/pcb/workspace/projects,与 CAD 共用 /api/auth/login、/api/auth/logout 和 /api/users/me,使用同一个 Authorization: Bearer <平台 token>。个人空间提供独立 PCB 分类;列表只包含本人未删除的 PCB 项目,不创建 Git 仓库、不自动发布社区。本文约定后端接口,PCB 编辑器及宿主网页需另行接入。

每次手动保存上传一个完整工程 ZIP。数据库保存项目元数据、当前文件引用和上传回执,原理图、PCB、工程配置与工程内私有依赖由前端打包和还原。后端不解压 ZIP、不解析 KiCad 文件,也不验证 ZIP 内容是否可编辑;文件名和大小校验不能代替前端格式验证。

文件读取沿用 CAD 的普通 OSS/CDN 地址规则:平台接口按用户隔离,文件直链权限由现有 Bucket/CDN 决定。公开配置下,拿到链接即可下载。逻辑删除不会撤销已有文件链接。

接口与数据

下表前缀为 /api/pcb/workspace/projects。全部需要登录,成功 HTTP 200,响应为 {code,message,data,requestId},响应包含 Cache-Control: no-store。分页、上海业务时间和跨域约定沿用 Vibemake 接入约定。业务编码是不透明字符串,客户端不使用数据库 ID。

方法 相对路径 请求 成功 data
GET 空 page=1&size=20&keyword=名称 {items,page,size,total}
POST 空 {name,description?,coverUrl?} 项目
GET /{pcbProjectCode} 无 项目
PATCH /{pcbProjectCode} {name?,description?,coverUrl?} 项目
DELETE /{pcbProjectCode} 无 null
POST /{pcbProjectCode}/uploads/signature {fileName,sizeBytes,expectedVersion} 上传签名
PUT /{pcbProjectCode}/document {uploadCode} 保存回执
GET /{pcbProjectCode}/document 无 ZIP 文件读取信息

名称去除首尾空白后须为 1~100 字符,描述最多 2000 字符,新建默认空字符串。封面为完整 HTTPS 地址,最多 2048 字符,新建省略、null 或空白表示无封面。PATCH 省略或 null 表示保留;描述或封面传 "" 可清空,至少提供一个非 null 字段。

同名项目允许存在。列表按最近更新时间倒序,同一时间按内部主键倒序稳定分页,主键不对外返回;名称支持包含搜索,关键词最多 100 字符。page 为 1~100000,size 为 1~100,默认 20。

interface PcbProject {
  pcbProjectCode: string;
  name: string;
  description: string;
  coverUrl: string | null;
  hasDocument: boolean;
  version: number;
  fileName: string;
  sizeBytes: number;
  savedAt: string | null;
  createdAt: string;
  updatedAt: string;
}
interface PcbUploadSignature {
  uploadCode: string;
  uploadUrl: string;
  formFields: Record<string, string>;
  expiresAt: string;
}
interface PcbSaveResult {
  pcbProjectCode: string;
  version: number;
  savedAt: string;
}
interface PcbDocument {
  downloadUrl: string;
  expiresAt: null;
  version: number;
  fileName: string;
  sizeBytes: number;
}

空项目 hasDocument=false、version=0、fileName=""、sizeBytes=0、savedAt=null。名称、描述和封面修改只更新元数据,不改变文件版本或 savedAt。

工程 ZIP、保存和重新打开

ZIP 应保留工程原有目录和文件名,包含 .kicad_pro、.kicad_sch、.kicad_pcb 及工程实际使用的私有符号库、封装库、库表、3D 模型、图像等项目文件。文件按原始字节保存,二进制文件不能先解码为文本。全局标准库仍由编辑器提供;工程外的本机绝对路径依赖需由前端迁入工程并处理引用,后端不会自动收集。

PCB 前端现有“归档项目”按扩展名白名单过滤,不能直接作为完整云端保存范围。前端需先刷新所有编辑器的最新序列化结果、等待本地写入完成,再读取完整工程快照打包;不上传浏览器缓存、.git、工具目录和本地历史记录。解压时由前端校验路径及资源限额,完整导入成功后再切换当前工程。

  1. 首次保存先创建项目,保留返回的 pcbProjectCode 和 version=0,后续上传失败复用该项目。
  2. 从完整工程快照生成 ZIP。文件名为不含路径和控制字符的 .zip 名称,最多 255 字符,扩展名不区分大小写;文件非空,默认最大 268435456 字节(256 MiB)。
  3. 申请签名,提交 ZIP 实际字节数及编辑基础版本。sizeBytes 和 expectedVersion 必须是 JSON 整数,不接受字符串、小数、负数或 null,sizeBytes 必须大于零。
  4. 将所有 formFields 原样加入 FormData,最后追加 ZIP 文件,POST 到 uploadUrl。ZIP Blob MIME 使用 application/zip,不手写 multipart Content-Type,不携带平台 Authorization。OSS 成功为 HTTP 200,无需解析 JSON。
  5. 上传后提交原 uploadCode 确认。只有成功回执才能显示云端已保存;同一项目串行保存,打包或上传期间的新修改继续标记为未保存。
  6. 打开先读详情;空项目进入新工程,否则获取 document,fetch downloadUrl 得到 ZIP 并交给编辑器导入。编辑基础版本使用 document.version,不能混用此前详情的版本。

本期为手动云端保存,宿主保存按钮和 Ctrl+S 应接入上述链路。本地自动保存继续作为浏览器内恢复能力,不能显示为云端已保存。iframe 集成由宿主网页和编辑器完成;使用 postMessage 时校验精确 origin 与 source,平台 Token 不放 URL,直传和 OSS 文件读取不携带平台 Token。

签名及未确认批次默认 15 分钟后过期。业务时间采用上海时间、无时区后缀,前端解析时补 +08:00。下载地址为普通 OSS/CDN 地址,expiresAt 固定为 null,不需要下载签名续期。

相同 uploadCode 重复确认返回首次成功的 version 和 savedAt,不重复增加版本;即使已有更新版本,也不会重新绑定旧 ZIP。回执版本可能小于当前版本,需要时重新读项目。确认超时应保留原批次并重试确认;OSS 上传结果不明确时也先尝试确认,缺文件再处理上传,不盲目覆盖或重复创建项目。

两个标签页基于同一版本保存,仅一个成功,另一个收到 PCB_VERSION_CONFLICT。保留本地修改,提供重新打开最新工程、下载本地 ZIP 或另存项目入口,不能自动替换版本号后覆盖。401 时保留本地工程,重新登录后核对账号与归属;离开、切换工程、退出登录前处理未保存修改。

封面与错误处理

封面复用 POST /api/uploads/project-covers/signature,请求 {contentType,fileSize},支持 JPG、PNG、WebP,最大 5 MiB。取得签名后直传图片,将完整 coverUrl 提交至 PCB 创建或 PATCH 接口;无需先创建 Git 项目。封面上传使用已有 OSS_ENABLED 开关,PCB 文件开关不代替它。

平台封面落库为 /project-covers/... 等环境相对路径,接口返回完整 URL;外部 HTTPS 图片沿用已有规则。工程保存保留封面,更新封面不改变工程版本;替换或清空封面、删除项目均保留原 OSS 对象。

HTTP / code 处理
400 BAD_REQUEST / PCB_INVALID_FILE 检查元数据、ZIP 文件名及整数参数
401 UNAUTHORIZED 保留工程,恢复登录后核对账号
404 NOT_FOUND 项目或批次不存在、非本人或已删除,停止保存
404 PCB_DOCUMENT_NOT_FOUND 空项目尚无云端 ZIP
409 PCB_VERSION_CONFLICT 保留本地修改,处理并发冲突
409 PCB_FILE_MISSING 尚无上传对象,检查上传结果再重试确认
409 PCB_FILE_SIZE_MISMATCH 当前文件不变,重新申请并上传正确文件
409 PCB_UPLOAD_EXPIRED 重新申请批次
413 PCB_FILE_TOO_LARGE / REQUEST_TOO_LARGE 文件或 JSON 请求超限
429 RATE_LIMITED 按 Retry-After 等待后重试
502 PCB_OSS_ERROR 保留工程及批次,稍后重试
503 PCB_STORAGE_UNAVAILABLE / PCB_STORAGE_UNSAFE 存储未开启或连接不完整
503 PCB_CODE_BUSY / REDIS_UNAVAILABLE 暂时无法处理,保留输入后重试

部署与联调

先手工执行 PCB 建表 SQL,再部署后端,配置当前环境 pcb-projects/* 的 RAM 权限及 OSS/CDN CORS,最后开启 PCB 存储。应用不自动创建或修改业务表,回滚时保留两张表和已有 OSS 对象。

配置项 默认值 / 要求
PCB_OSS_ENABLED false,配置完成后显式开启
PCB_MAX_FILE_BYTES 268435456;允许 1 字节至 5 GiB,需兼容编辑器读取限额
PCB_UPLOAD_VALIDITY 15m,允许 1 秒至 7 天
RATE_PCB_CREATE_PER_MINUTE / RATE_PCB_SIGN_PER_MINUTE 每用户 5 / 20
RATE_PCB_SAVE_PER_MINUTE / RATE_PCB_READ_PER_MINUTE 每用户 30 / 60,含确认及读取重试
OSS_REGION、OSS_ENDPOINT、OSS_BUCKET、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET 共用现有 OSS 连接,前端不持有 RAM 密钥
OSS_PUBLIC_BASE_URL 共用普通 OSS/CDN 基础地址;为空时使用 Bucket 域名
vibemake.oss.root-directory test 为 vibemake_dev,prod 为 vibemake

PCB 开关独立于 CAD 和公共资源开关;OSS_ENABLED=false 时,只要共用连接完整,PCB 仍可开启。适配器仅本地签名、HEAD 核验大小及生成普通地址,不读取或修改 Bucket ACL、对象 ACL、版本控制或公开策略,不单独设置 private ACL。

数据库仅存 /pcb-projects/{pcbProjectCode}/{uploadCode}/project.zip,真实 OSS key 为环境根目录加此路径。前端原样使用 formFields.key,不自行拼接环境前缀。格式见 OSS 引用规范。

RAM 授权覆盖当前环境 pcb-projects/* 的 oss:PutObject 与 oss:GetObject,用于直传和 HEAD;读取权限按已有普通地址方式配置。CORS 允许实际宿主或编辑器来源的 POST、GET 和 Content-Type,需要时暴露 Content-Length、Content-Disposition。平台 API 使用既有来源白名单。

联调验证创建工程、上传、确认、刷新列表、下载 ZIP、重新打开并继续编辑,以及账号隔离和双标签版本冲突。后端自动化使用模拟 OSS,真实 OSS/CDN 与编辑器联调在部署环境完成。首期不提供历史恢复、对象清理或自动云端保存。