10 KiB
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、工具目录和本地历史记录。解压时由前端校验路径及资源限额,完整导入成功后再切换当前工程。
- 首次保存先创建项目,保留返回的
pcbProjectCode和version=0,后续上传失败复用该项目。 - 从完整工程快照生成 ZIP。文件名为不含路径和控制字符的
.zip名称,最多 255 字符,扩展名不区分大小写;文件非空,默认最大 268435456 字节(256 MiB)。 - 申请签名,提交 ZIP 实际字节数及编辑基础版本。
sizeBytes和expectedVersion必须是 JSON 整数,不接受字符串、小数、负数或 null,sizeBytes 必须大于零。 - 将所有
formFields原样加入 FormData,最后追加 ZIP 文件,POST 到uploadUrl。ZIP Blob MIME 使用application/zip,不手写 multipart Content-Type,不携带平台 Authorization。OSS 成功为 HTTP 200,无需解析 JSON。 - 上传后提交原
uploadCode确认。只有成功回执才能显示云端已保存;同一项目串行保存,打包或上传期间的新修改继续标记为未保存。 - 打开先读详情;空项目进入新工程,否则获取
document,fetchdownloadUrl得到 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 与编辑器联调在部署环境完成。首期不提供历史恢复、对象清理或自动云端保存。