11 KiB
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 表现需要专门回归,不能由模拟测试推断通过。