129 lines
10 KiB
Markdown
129 lines
10 KiB
Markdown
# 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 与编辑器联调在部署环境完成。首期不提供历史恢复、对象清理或自动云端保存。
|