Files
vibemake-pcb-studio/docs/vibemake/pcb-integration-plan.md
T
likang 1fde96c05e
CI / typecheck + test + build (push) Has been cancelled
打通vibemake
2026-11-05 16:21:37 +08:00

11 KiB
Raw Blame History

VibeMake PCB 前端实施与交付说明

更新日期:2026-11-05。基于 7e01147 实施。真实接口接入以 当前接入说明 为准。

配套:历史后端接口建议、验证记录与截图。后续已调整主站同源入口和开发启动模式;CAD 与业务后端功能代码未改。本文件描述已经实现的前端和仍需真实服务联调的边界。

1. 独立应用与页面

PCB 保持独立仓库、独立 pnpm/Vite 构建。发布 designer/dist 到主站同源 /pcb/,不合并主站业务代码。主站、CAD、PCB 各自维护项目数据,只共享账号和品牌。

地址 内容
/pcb/ 我的 PCB 项目,搜索、20 项分页、新建、导入、重命名、删除
/pcb/p/{code}/ 当前工程文件管理
/pcb/p/{code}/pcb PCB 编辑
/pcb/p/{code}/schematic 原理图编辑
/pcb/p/{code}/pcb/3d 三维查看
/pcb/p/{code}/symbols 符号编辑
/pcb/p/{code}/footprints 封装编辑
/pcb/p/{code}/tools/{tool} calculator、drawing-sheet、image-converter、gerber

?f= 为经过校验的工程相对路径,禁止绝对路径和目录穿越。刷新和直接访问根据项目编码加载,停用旧最近项目回退。项目名允许重复,重命名只改显示名称,不改文件与引用。新建生成稳定内部名称 project.kicad_pro/.kicad_sch/.kicad_pcb,先建立本机草稿,首次手动保存后才产生云设计。

原生 ZIP、目录、单独板文件和原理图通过导入校验后创建平台项目,多入口工程可选择主文件。模板和示例走同一创建流程。其他格式转换保留在专业 PCB 编辑器的 File > Import > Non-KiCad Board File,转换结果写入当前工程。

首次进入默认 PCB;没有板文件的工程进入原理图。另一浏览器打开只有元数据的项目会提示“此项目尚未保存设计”,由用户选择创建空白或返回列表,不伪装成已恢复设计。

2. 统一视觉与登录

网站外壳采用受控 Logo 副本、Sora、中文系统字体、JetBrains Mono,以及 #07080a 背景、#0f1114/#15181c 面板、#c8ff3e 主色。导航 64px、列表最大宽度 1240px。专业画布、工具栏、图层、坐标遵循已有编辑器规则。弹窗约束焦点,提交时锁定关闭,保留加载、错误、重试、空状态反馈。页面按 ui-ux-pro-max 的焦点和反馈指导检查,视觉以现有网站为准。

新增页面默认中文,可切换英文。专业编辑器继续使用已有翻译系统,语言切换不会重建文档。宽度不超过 820px、手机和平板显示电脑端提示;编辑中缩窄只遮罩与锁定,不卸载文档。

真实模式读取主站 vm.auth={token,user,expiresAt},expiresAt 为毫秒时间戳。PCB 内提供同款邮箱、图片验证码登录弹窗:

接口 前端用途
GET /api/auth/captcha 图片及验证码编码
POST /api/auth/login {email,captchaCode,captchaAnswer}
GET /api/users/me 验证身份后加载工作区
POST /api/auth/logout 退出共享账号

同一用户 token 更新后保留工程并重新验证;过期锁输入、保留文档和草稿。网络与 5xx 显示故障,不清空账号。切换用户取消旧请求、保存原账号草稿、销毁旧工程与私有资源挂载。工程异步响应按 owner、binding、session 和请求代次隔离。

平台入口不启动旧 Supabase 身份、恢复密钥、设置云同步、项目云同步、分享或协作任务。旧匿名/加密工程不自动认领,需从原环境导出再显式导入。

3. 工程文件与快照

主要实现位于 designer/src/platform/:

文件 职责
auth.tsx、api.ts 共享身份、真实接口、签名直传
ProjectList.tsx、PlatformApp.tsx 列表、路由、工作区、离开保护
runtime.ts 唯一工程绑定、revision、保存事务、草稿
filesystem.ts、account-resources.ts 原生工具读写、账号私有资源收集
archive.ts、archive.worker.ts 受限 ZIP、manifest、SHA-256
storage.ts、mock-api.ts 平台 IndexedDB、模拟接口
EditorHost.tsx 懒加载编辑环境与工程挂载

原理图、PCB、符号、封装和图纸注册可等待的快照参与者。快照在安全命令边界暂时锁输入,等待原生序列化、文件写队列和资源收集,复制完整 byte 文件集,随后解锁。工程文件按完整相对路径定位,两个目录下同名子页保持独立。

云格式为原生文件集合加 manifest 的完整 ZIP,根目录不包显示名称:

vibemake-project.json
project.kicad_pro
project.kicad_sch
project.kicad_pcb
project.kicad_dru
sheets/...
symbols/...
footprints/...
models3d/...
images/...

manifest v1 实际字段如下,hash 示例须替换为文件原始字节的真实 SHA-256:

{
  "format": "vibemake-pcb-project",
  "schemaVersion": 1,
  "engineBuild": "build identifier",
  "roots": {"project":"project.kicad_pro","schematic":"project.kicad_sch","board":"project.kicad_pcb"},
  "directories": ["sheets"],
  "files": [{"path":"project.kicad_pcb","sizeBytes":1234,"sha256":"64 lowercase hex characters"}],
  "libraryDependencies": [],
  "unresolvedDependencies": [{"kind":"model3d","sourcePath":"project.kicad_pcb","reference":"missing.step"}]
}

实际清单包含全部设计与资源,排除 manifest 自身、锁、临时文件、旧历史和可再生缓存。二进制保持原字节,不使用扩展名白名单过滤工程。前端导入校验路径、大小、数量、重复、文件目录冲突、符号链接、manifest 版本和 hash,校验原生主文件语法。现有后端仅存储 ZIP 并核验上传对象大小,不解压、解析或校验可编辑性。

已使用的本机私有符号/封装收集到工程并更新库表,私有模型复制到工程相对路径。偏好和用户库按账号留本机,不新增个人云库产品。

4. 保存、草稿与恢复

手动保存、Ctrl/Cmd+S、保存并离开触发完整云保存。自动保存只在空闲 1 秒及安全命令边界写本机 byte 草稿,不打 ZIP、不上传。

保存状态为尚未保存或有修改,进入正在准备、上传、确认,然后显示已保存、仍有新修改、失败或冲突。保存并发触发复用同一任务。上传期间可继续编辑,只确认快照 revision,后续编辑不会被清成已保存。本机序列化成功也不会清除云端脏状态。

流程为捕获快照、worker 打 ZIP 与本地 hash、持久化待确认事务、申请签名、上传、PUT 确认,核对回执项目/version 后更新已确认 revision。服务端不回传操作标识、批次或 hash,原 uploadCode 由本地保存任务绑定。确认响应丢失保持原 ZIP 和批次,重试原确认;明确过期或大小不符才申请替代批次。冲突不覆盖,提供下载、另存新项目、明确放弃后重载。

数据库 vm.pcb 分开保存草稿、已确认缓存、待确认批次、本机用户库和模拟服务数据。草稿按账号、项目、标签页 session 隔离。重开先处理未知确认,再从同一次 document 响应下载并验证完整 ZIP;发现草稿时展示时间和基础版本供选择。

恢复后已有元件、走线、属性仍为原生可编辑对象。旧 Undo/Redo 不跨会话恢复,新操作正常撤销重做。离开有保存并离开、放弃并离开、继续编辑;保存失败停留。浏览器关闭使用原生提示并尽力写草稿,不承诺关闭时云上传完成。存储不可用保留当前内存并提示云保存或下载。

5. 三维资源

缺少外部模型允许保存。模型路径、偏移、旋转、缩放留在原生设计;已有模型 bytes 入 ZIP,缺失项进入 unresolvedDependencies 并持续提示数量。文件管理提供补选,复制到 models3d/、修正引用、标记修改。三维读取支持 bytes,私有缓存按工程挂载和内容 hash 隔离。

缺少主设计文件、损坏归档或不合法路径仍阻止打开或保存。模型缺失提示不能掩盖工程损坏。

6. 本地启动与正式构建

pnpm install
pnpm -C designer dev:mock --host 127.0.0.1

打开 http://127.0.0.1:5173/pcb/。模拟账号 A/B、模拟项目和 ZIP 只在当前浏览器 IndexedDB,持续显示开发标识,身份键为 vm.pcb.mock.auth,不覆盖真实 vm.auth。故障开关包括离线、确认响应丢失、签名过期、版本冲突、容量超限。

pnpm -C designer build
pnpm -C designer preview --host 127.0.0.1

正式构建仅真实接口。VITE_PCB_API_MODE=mock 或 vite build --mode mock 会拒绝构建,真实 API 失败不回退模拟。产物 designer/dist,base /pcb/。VITE_PCB_API_BASE=/api 使用同源代理,其他配置见 designer/.env.example。不要把 secret 放入 VITE 前缀变量。

列表和登录不初始化原生编辑环境;三维、DRC 和其他工具按需加载。PWA 仅预缓存轻量入口及品牌资源,不缓存账号接口、工程 ZIP、签名地址,也不强制刷新编辑页面。

7. 服务器挂载

以下示例假设主站静态根为 /srv/vibemake,将 designer/dist 内容发布到其 pcb/ 子目录。路径按服务器实际情况调整。

root /srv/vibemake;
location = /pcb { return 301 /pcb/; }
location = /pcb/index.html { add_header Cache-Control "no-cache"; }
location = /pcb/sw.js { add_header Cache-Control "no-cache"; }
location ^~ /pcb/assets/ {
    try_files $uri =404;
    add_header Cache-Control "public, max-age=31536000, immutable";
}
location /pcb/ { try_files $uri $uri/ /pcb/index.html; }

保留主站 /api/ 代理,业务 API 失败返回 JSON,不能回退 index.html。字体、公共符号、封装、模板、示例和模型服务需在目标环境验证可达。对象存储放开前端源的 POST/GET CORS;Bearer 仅发业务 API,不送 OSS。使用 HTTPS 提供 secure context 和 SHA-256。旧构建 hash 资源保留一段时间,避免打开中的旧页面找不到懒加载 chunk。

主站入口已接入独立 PCB,同源 /pcb/ 不再使用旧 iframe;开发启动默认使用真实接口,模拟需显式开启。线上仍需发布新产物并联调主站导航、登录共享、刷新、CSP 和对象存储 CORS。不同端口不能作为共享登录验收。

8. 验证边界

新增 qa/unittests/designer/pcb_platform.test.ts 覆盖原生设计与二进制往返、子页同名路径、归档攻击与篡改、缺失模型、账号隔离、幂等确认、并发冲突、保存期间编辑、未知结果恢复和文件写队列。浏览器模拟验收覆盖登录、新建、草稿恢复、保存、确认丢失重试及从列表重开后读取设计属性。

真实账号与跨设备存储需后端完成后验收:浏览器 A 保存,B 同账号打开、继续修改保存,A 再读取新版;不同账号禁止读写。大工程容量、全部第三方格式转换、完整制造输出及各浏览器 GPU 表现需要专门回归,不能由模拟测试推断通过。