KiCad 项目版本管理（包含变体版本管理）v2.0.1

KiCad 项目版本管理（包含变体版本管理）v2.0.1

结合硬件物理特性与软件工程中的语义化版本（Semantic Versioning）思想，本方案采用“硬隔离/强基线控制策略”：将 PCB Layout（物理基板）与变体 BOM（逻辑装配）彻底解耦。

只要物理 Layout（走线、过孔、器件位置、板框）有任何改动，即升级主版本号（MAJOR）；元件参数调整、DNP（不贴片）及变体切换仅通过专属的修订号来管理。

---

1. 语义化版本控制规范

版本号格式统一为：v<MAJOR>-<VARIANT_SLUG>.<VARIANT_PATCH>

• MAJOR（主版本号 / 物理基板）：代表 PCB Gerber 物理版本（如 v1、v2）。
  • 触发条件：任何 Layout 走线微调、过孔移动、板框变更、层叠结构修改。
  • 工程含义：裸板必须重新打样；钢网（Stencil）、测试治具（ICT/FCT）可能需要重新制作；硬件库房废弃/隔离旧主版本裸板。
• VARIANT_SLUG（变体代号）：代表不同的产品应用方向（如 IND 代表工业级，CONS 代表消费级）。
• VARIANT_PATCH（变体修订号）：代表在同一块物理基板生命周期内，特定变体 BOM 的修改演进序号（从 .1 开始递增）。
  • 触发条件：PCB 零改动的前提下，调整阻容参数、更换 Pin-to-Pin 替代料、切换 DNP 变体。
  • 工程含义：裸板完全复用；钢网与治具 100% 复用；仅更新 SMT 贴片程序与领料 BOM。

---

2. 变体 BOM 命名与双重追踪

变体 BOM 采用 “主版本号 + 变体代号 + 变体修订号” 进行唯一标识，并在数据结构中反向绑定源项目版本。

• 版本命名示例：
  • v1-IND.1：基于 v1 版 PCB 的工业级变体 BOM 初版。
  • v1-IND.2：PCB 完全不变，仅替换工业级 BOM 中的 Pin-to-Pin 滤波电容品牌。
  • v1-CONS.1：基于同一块 v1 版 PCB 的消费级变体 BOM 初版。
  • v2-IND.1：PCB 重新走线打样后，工业级变体 BOM 的新基线初版。
• 双重追踪机制：
  • 在导出的变体产物中，除了在文件名和 CSV 表头中标明版本外，强烈建议同步生成同名的 .json 跟踪文件（例如 Project_v1-IND.1_BOM.json），记录其派生的源项目基板版本，确保血缘关系可追溯。

---

3. KiCad 工程实施 SOP

A. 原理图与 PCB 标识规范

1. PCB 丝印层（Silkscreen）：
   • 裸板上仅打印主版本号，如 REV: v1。
   • 原理：同一批打样的 v1 裸板可同时供给 v1-IND.1 与 v1-CONS.1 贴片，避免裸板丝印与具体变体绑定导致的库存浪费。
2. 原理图属性与 DNP 控制：
   • 在元件属性中勾选 Do Not Populate (DNP) 控制变体留空。
   • 添加自定义属性 Variant（值示例：ALL、IND_ONLY、CONS_ONLY）。
   • 原理图 Title Block 的 Revision 填入 v1，Comment 标注变体信息。

B. 自动化导出与产出物规范

通过 KiCad CLI（kicad-cli）与 Python 脚本实现自动化打包，产出物按用途严格隔离：

release/
└── v1-IND.1/                              # 对应的变体发布版本
    ├── Project_v1-IND.1_BOM.csv           # 变体 BOM 表
    ├── Project_v1-IND.1_CPL.csv           # 贴片坐标文件
    ├── Project_v1-IND.1_BOM.json          # 变体跟踪与血缘关系记录
    └── Project_v1-IND.1_Fab.pdf           # 装配图

---

4. 版本变更决策矩阵

变更场景	PCB Layout 改动	原理图 / 属性改动	主硬件版本号 (HW)	变体 BOM 版本号	钢网/治具状态
微调阻容参数 / 变更 DNP 变体	否	仅变体参数	v1	v1-IND.1 升级到 v1-IND.2	100% 复用
主控更换 Pin-to-Pin 替代料	否	修改 MPN (料号)	v1	v1-ALL.1 升级到 v1-ALL.2	100% 复用
优化一处走线 / 调整过孔	是	无/微调	v1 升级到 v2	v2-IND.1	重新制作
新增/删减电路模组（含重新走线）	是	新增/删除电路	v2 升级到 v3	v3-IND.1	重新制作

---

5. Git 仓库管理结构

采用 Git 对 KiCad 工程进行版本追踪与防冲突管理：

Project_Root/
├── .gitignore
├── Project.kicad_pro
├── Project.kicad_sch
├── Project.kicad_pcb
├── scripts/
│   └── export_variants.py                 # KiCad CLI 变体 BOM/CPL 自动导出脚本
└── release/                               # 打包发布归档目录

• Git Tag 规范：
  • 仅 BOM 变体修订打 Tag：git tag -a v1-IND.2 -m "BOM: Replace C102 vendor PN"
  • PCB 重打样打 Tag：git tag -a v2 -m "HW: Layout rerouted for EMC optimization"