企业官网建设流程全解析

1. 背景与痛点

硬件团队（尤其 3~20 人）的元件库管理普遍存在以下问题：

• 个人库与团队库脱节，协作靠网盘/U 盘，版本管理混乱；
• 符号、封装、3D 模型三者分离，绘制原理图时经常对不上；
• 新建料号需手工绘制符号/封装并搜索 3D 模型，效率低下；
• BOM 整理依赖 Excel 手工处理，位号/料号/价格/库存易出错。

云端元件库（如官方 KiCad 在线库、商城云库）可部分解决上述问题，但数据不出内网的硬性要求限制了多数团队采用。基于此，我们在华秋 KiCad 10.0.3 发行版（GPL-3.0）基础上 fork 并自建了一套云端元件库系统。

2. 整体架构

方案整体分为客户端与服务端两部分：

WEB 后台元件库管理页（左侧导航 + 共享/私有筛选 + 真实物料数据）：

3. 核心链路：画布选中 → 保存到服务器

3.1 操作步骤

在已有原理图中选中元件符号，右键菜单选择「保存到服务器库」：

完整链路如下：

1. 符号序列化：将选中符号序列化为裸(symbol ...)S-Expr 文本，无需手动导出文件；

2. 跨模块取封装与 3D：原理图侧经 Kiway 跨模块调用 pcbnew 的GetFootprintBundle(位号)，自动带上.kicad_mod封装与 STEP 3D 模型。3D 传输前经 zlib 压缩（单件 6~9MB → 约 1MB）；

3. 信息填写：库类型（共享/私有）、分类、物料编码、MPN、厂商；

4. 数据落库：写入components与manufacturer_parts，保存前自动查重（含软删记录），已存在则提示，避免重复建库。

保存后可通过器件库面板按共享/私有、分类、关键词检索，点「放置」自动落回画布：

4. 共享库与私有库：两级隔离与三角色权限

权限模型为三角色 RBAC：

• 总管理员（super_admin）：全部权限，维护共享库，管理用户与分类；
• 库管理员（library_admin）：维护共享库，可将他人私有库元件复制进共享库（沉淀团队资产）；
• 普通用户（regular_user）：使用共享库并维护自己的私有库。
  

5. 进阶玩法

以下功能均已实现：

1. 批量建库：多选符号 → 右键「批量保存」，200 个以内一次提交，已有编码自动跳过（幂等）；

2. 模块电路共享：将子图（Sheet）完整保存为复用模块（符号+连线+标签），可一键插入工程；

3. 参数化建族：选择 E 系列（E24/E96）+ 封装，一键生成整个阻值/容值家族；

4. Excel 导入导出：支持模板批量导入老库数据；

5. WEB 后台：浏览器全图形化管理，元件编辑支持符号/封装/3D 资产文件直接上传：
   

6. BOM 生成（进行中）：服务端已支持 join 料号库补全 MPN/厂商/单价/库存/交期并导出 Excel，正在开发「原理图内直接生成 + 主料/替代料自动选」功能，后续将单独成文介绍。

6. 踩坑实录

以下为开发过程中遇到的真实问题，供想复刻的朋友参考：

1. KiCad 右键菜单按工具分：「保存模块电路」仅注册在选择工具菜单时，用户处于绘图工具激活态右键子图会看不到菜单项，需双注册（drawMenu + selToolMenu）；
2. 跨模块取 PCB 数据：eeschema 不直接链接 pcbnew，需通过KIWAY_PLAYER基类虚函数（GetFootprintBundle模式），由 PCB 侧 override，原理图侧经Kiway().Player()获取基类指针调用；
3. 3D 路径解析：KiCad 的${KICAD*_3DMODEL_DIR}为内部环境变量（由 FILENAME_RESOLVER 管理），std::getenv无法读取，需使用PROJECT_PCB::Get3DFilenameResolver()；
4. material_code 幂等：全局唯一约束 + 软删不释放编码，存在性判定需全量匹配（含软删记录），否则重存同编码会触发 500；
5. 大请求体：批量携带 3D 模型时 JSON 体积可达 90MB+，需调整 nginxclient_max_body_size，并在前端增加体积预检提示；
6. 渲染规则：解析 KiCad S-Expr 必须按 layer 过滤（fp_line 分 Fab/SilkS/CrtYd），否则 courtyard 红色边框会污染预览图。

7. 后续计划

• BOM 生成进阶（原理图内直接生成、主料/替代料自动选）；
• 对接第三方目录库（华秋商城 / 立创商城 API）自动拉取料号、价格、库存；
• PCB 封装库独立成库；
• 3D PCB 库。

如果本文对你有帮助，欢迎点赞、收藏、关注。后续会更新源码拆解（右键菜单挂载机制、面板与客户端 postMessage 协议、跨模块取封装实现）以及 BOM / 第三方库对接实战。

预告：后面会考虑出视频（真实操作演示：画布右键保存、批量建库、模块电路插入、BOM 生成），想看的可以关注蹲一下，也欢迎评论区告诉我你最想看哪部分。

本系统为业余空闲时间独立开发，持续迭代中，肯定有考虑不周之处，欢迎评论区交流讨论。