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

129 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 接入约定](vibemake-api.md#接入约定)。业务编码是不透明字符串,客户端不使用数据库 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。
```ts
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-database.md),再部署后端,配置当前环境 `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 引用规范](oss-storage-paths.md)。
RAM 授权覆盖当前环境 `pcb-projects/*` 的 `oss:PutObject` 与 `oss:GetObject`,用于直传和 HEAD;读取权限按已有普通地址方式配置。CORS 允许实际宿主或编辑器来源的 POST、GET 和 Content-Type,需要时暴露 Content-Length、Content-Disposition。平台 API 使用既有来源白名单。
联调验证创建工程、上传、确认、刷新列表、下载 ZIP、重新打开并继续编辑,以及账号隔离和双标签版本冲突。后端自动化使用模拟 OSS,真实 OSS/CDN 与编辑器联调在部署环境完成。首期不提供历史恢复、对象清理或自动云端保存。