pcb项目接口
This commit is contained in:
@@ -0,0 +1,128 @@
|
||||
# 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 与编辑器联调在部署环境完成。首期不提供历史恢复、对象清理或自动云端保存。
|
||||
@@ -5,7 +5,8 @@
|
||||
| 位置 | 数据库存储示例 | 实际 OSS key 示例 |
|
||||
| --- | --- | --- |
|
||||
| CAD 当前设计及上传批次 | `/cad-projects/{项目编码}/{批次编码}/design.sc` | `vibemake_dev/cad-projects/{项目编码}/{批次编码}/design.sc` |
|
||||
| 平台托管封面(含 CAD 的 cover_url) | `/project-covers/{用户编码}/{日期}/{文件名}` | `vibemake_dev/project-covers/{用户编码}/{日期}/{文件名}` |
|
||||
| PCB 当前工程及上传批次 | `/pcb-projects/{项目编码}/{批次编码}/project.zip` | `vibemake_dev/pcb-projects/{项目编码}/{批次编码}/project.zip` |
|
||||
| 平台托管封面(含 CAD、PCB 的 cover_url) | `/project-covers/{用户编码}/{日期}/{文件名}` | `vibemake_dev/project-covers/{用户编码}/{日期}/{文件名}` |
|
||||
| URDF 主文件及目录 | `/urdf/{项目编码}/{批次编码}/...` | `vibemake_dev/urdf/{项目编码}/{批次编码}/...` |
|
||||
| STEP、GLB、零件、拼装步骤、行走资源 | `/project-resources/{项目编码}/{类型}/{批次编码}/...` | `vibemake_dev/project-resources/{项目编码}/{类型}/{批次编码}/...` |
|
||||
|
||||
@@ -15,6 +16,8 @@
|
||||
|
||||
## 现有数据手工转换 SQL
|
||||
|
||||
PCB 两张新表直接采用环境相对路径,建表见 [PCB 工作空间 SQL](pcb-database.md),无需执行下列 CAD 与社区资源的历史转换。
|
||||
|
||||
无需修改字段结构。先升级所有在线写入进程与导入工具,再暂停资源写入并备份业务库。在对应环境的业务数据库连接中执行;test 使用 `vibemake_dev`,prod 将 `@oss_root` 改为 `vibemake`。不会移动、复制或删除 OSS 对象,也不修改项目版本、保存时间、上传回执和业务更新时间。
|
||||
|
||||
仅当字段精确以当前环境和对应资源目录开头时转换,使用二进制前缀比较避免大小写或下划线通配符误匹配,不使用全局 REPLACE。已经是相对路径的记录、空值和其他环境路径不变;本转换可重复执行。
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# PCB 工作空间建表 SQL
|
||||
|
||||
在启用 PCB 接口前,由运维在现有 `vibemake` 数据库手工执行以下 SQL(MySQL 8.0.13+)。应用不自动建表,不修改现有项目表。所有业务时间按上海时间写入。
|
||||
|
||||
`id` 和归属外键仅供服务内部使用,对外使用 `pcb_project_code` 和 `upload_code`。两张表与 Git 项目无关联。上线顺序:执行 SQL → 部署后端 → 验证共用 OSS 配置及文件读取 → 开放前端入口。回滚代码时保留两张表和 OSS 对象。
|
||||
|
||||
```sql
|
||||
CREATE TABLE pcb_project (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对外返回',
|
||||
pcb_project_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT 'PCB项目唯一业务编码',
|
||||
owner_user_id BIGINT NOT NULL COMMENT '所属用户内部主键,关联sys_user.id',
|
||||
name VARCHAR(100) NOT NULL COMMENT 'PCB项目名称',
|
||||
description VARCHAR(2000) NOT NULL DEFAULT '' COMMENT 'PCB项目描述',
|
||||
cover_url VARCHAR(2048) NULL COMMENT 'PCB项目封面,平台OSS资源存无环境前缀的相对路径',
|
||||
document_object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '' COMMENT '当前工程ZIP文件环境相对路径,以斜杠开头,不含域名和环境根目录',
|
||||
file_name VARCHAR(255) NOT NULL DEFAULT '' COMMENT '当前工程ZIP文件名称',
|
||||
size_bytes BIGINT NOT NULL DEFAULT 0 COMMENT '当前工程ZIP文件大小,单位字节',
|
||||
version BIGINT NOT NULL DEFAULT 0 COMMENT '当前保存版本,空项目为0,每次成功保存递增',
|
||||
saved_at DATETIME(3) NULL COMMENT '最近成功保存工程ZIP文件的上海时间',
|
||||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除标记,0未删除,1已删除',
|
||||
created_at DATETIME(3) NOT NULL COMMENT '项目创建上海时间',
|
||||
updated_at DATETIME(3) NOT NULL COMMENT '项目信息最近更新上海时间',
|
||||
PRIMARY KEY (id),
|
||||
UNIQUE KEY uk_pcb_project_code (pcb_project_code),
|
||||
KEY idx_pcb_project_owner_list (owner_user_id, deleted, updated_at, id)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='PCB个人工作空间项目';
|
||||
|
||||
CREATE TABLE pcb_project_upload (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对外返回',
|
||||
upload_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '上传批次唯一业务编码',
|
||||
pcb_project_id BIGINT NOT NULL COMMENT '所属PCB项目内部主键,关联pcb_project.id',
|
||||
expected_version BIGINT NOT NULL COMMENT '签发上传时的项目基础版本,用于并发保存校验',
|
||||
object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '本批次工程ZIP文件环境相对路径,以斜杠开头,不含域名和环境根目录',
|
||||
file_name VARCHAR(255) NOT NULL COMMENT '本批次工程ZIP文件名称',
|
||||
size_bytes BIGINT NOT NULL COMMENT '本批次声明的文件大小,单位字节',
|
||||
expires_at DATETIME(3) NOT NULL COMMENT '未确认批次的截止上海时间,与上传签名一致',
|
||||
saved_version BIGINT NULL COMMENT '确认成功的版本号,空值表示尚未确认',
|
||||
saved_at DATETIME(3) NULL COMMENT '首次确认成功上海时间,重复确认返回原值',
|
||||
created_at DATETIME(3) NOT NULL COMMENT '批次创建上海时间',
|
||||
updated_at DATETIME(3) NOT NULL COMMENT '批次最近更新上海时间',
|
||||
PRIMARY KEY (id),
|
||||
UNIQUE KEY uk_pcb_upload_code (upload_code),
|
||||
KEY idx_pcb_upload_project (pcb_project_id, created_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='PCB工程ZIP文件上传与保存确认批次';
|
||||
```
|
||||
|
||||
保存事务锁定当前用户的未删除项目和对应批次,按 `expected_version` 条件更新当前对象键和版本,同时写入批次回执。失败整体回滚。重放已确认批次只返回首次确认的版本和时间,不重新绑定旧对象;项目删除后仍拒绝重放。首期不清理上传批次或旧 OSS 对象,不提供历史恢复接口。
|
||||
|
||||
`document_object_key` 和 `object_key` 均保存 `/pcb-projects/{项目编码}/{批次编码}/project.zip`,不保存 `vibemake_dev/` 或 `vibemake/`。真实上传和读取在运行时补当前环境根目录。PCB 新建表直接采用该格式,无需执行 CAD 的历史路径转换 SQL。
|
||||
|
||||
@@ -10,6 +10,8 @@ ZIP、TAR.GZ 下载和 HTTPS Git 本地开发的独立前端交付文档见 [仓
|
||||
|
||||
CAD 个人工作空间使用独立的 `/api/cad/workspace/projects`,共用登录,但不创建 Git 仓库、不混入现有项目列表。接口、保存续编流程和共用 OSS 配置见 [CAD 工作空间前端对接](frontend-cad-workspace.md),上线前执行 [CAD 建表 SQL](cad-database.md)。
|
||||
|
||||
PCB 个人工作空间使用独立的 `/api/pcb/workspace/projects`,共用登录,通过完整工程 ZIP 直传 OSS 保存与续编,个人空间按独立 PCB 分类查询。接口、版本冲突、重试和部署配置见 [PCB 工作空间前端对接](frontend-pcb-workspace.md),上线前手工执行 [PCB 建表 SQL](pcb-database.md)。
|
||||
|
||||
CAD 网页 AI Agent 使用 `/api/cad/ai/capabilities` 和 `/api/cad/ai/chat`,支持流式回复及浏览器执行的 CAD 工具调用,复用豆包连接配置。功能默认关闭,聊天不落库;完整协议及 SolidCraft 网页适配要求见 [CAD AI Agent 前端对接](frontend-cad-ai-agent.md)。
|
||||
|
||||
## 阅读导航
|
||||
|
||||
Reference in New Issue
Block a user