3、源码管理基础：Git版本控制、仓库结构设计、分支策略、提交规范与标签管理

智能门锁项目交付物中，源码是最核心的资产之一。无论是嵌入式固件、移动端App、云端服务端还是测试脚本，若缺乏系统化的版本管理，交付时极易出现“代码版本对不上”“功能回退困难”“多人协作冲突频发”等问题。本章围绕Git版本控制展开，重点讲解仓库结构设计、分支策略、提交规范与标签管理，帮助项目团队建立一套可追溯、可复现、可协作的源码管理体系。

3.1 Git版本控制核心原理与仓库结构设计

核心原理：Git采用分布式版本控制模型，每个开发者的本地仓库都包含完整的提交历史。智能门锁项目涉及多模块协同（固件、App、服务端），仓库结构设计直接影响团队协作效率。常见的结构方案有单仓库（Monorepo）和多仓库（Multi-repo）两种。对于中小型智能门锁项目，推荐采用单仓库+模块目录的方式，便于统一管理依赖版本和进行跨模块的原子提交。

推荐仓库目录结构：

smart-lock-project/
├── firmware/          # 嵌入式固件源码（C/STM32）
│   ├── src/
│   ├── inc/
│   └── Makefile
├── mobile-app/        # 移动端App（Android/iOS）
│   ├── android/
│   └── ios/
├── cloud-service/     # 云端服务（Node.js/Python）
│   ├── api/
│   └── worker/
├── test/              # 测试脚本与测试固件
│   ├── unit/
│   └── integration/
├── docs/              # 设计文档、API文档
├── tools/             # 构建脚本、烧录工具
└── README.md

3.2 分支策略：从开发到发布的标准化流程

核心原理：分支策略决定了代码如何从开发走向发布。智能门锁项目建议采用Git Flow的简化变体，既保留足够的流程控制，又不至于过度复杂。核心分支包括：main（生产分支）、develop（集成分支）、feature/*（功能分支）、release/*（发布分支）、hotfix/*（热修复分支）。

操作流程：

1. 功能开发：从develop检出feature/xxx分支，开发完成后合并回develop。
2. 发布准备：从develop检出release/1.2.0分支，仅允许bug修复和文档更新，禁止新功能。
3. 正式发布：将release/1.2.0合并到main，并打上标签v1.2.0。
4. 紧急修复：从main检出hotfix/1.2.1，修复后同时合并回main和develop。

3.3 提交规范：让历史记录可读、可追溯

核心原理：规范的提交信息是项目文档的一部分。采用Conventional Commits规范，格式为<type>(<scope>): <subject>。对于智能门锁项目，scope建议使用模块名（firmware、app、server、test）。

提交粒度建议：每次提交应保持逻辑独立，一个提交只解决一个问题。避免将“修复bug”和“添加新功能”混在一个提交中。对于涉及多个模块的变更，应拆分为多个提交，但可在PR描述中关联。

3.4 标签管理与版本发布

核心原理：标签（Tag）是Git中不可变的版本快照，用于标记发布点。推荐使用语义化版本号（SemVer）：主版本号.次版本号.修订号。对于智能门锁项目，建议在main分支的每个发布提交上打标签，并附注说明（Annotated Tag）。

标签操作流程：

# 创建附注标签
git tag -a v1.2.0 -m "Release v1.2.0: 支持指纹+蓝牙双解锁"

# 推送标签到远程
git push origin v1.2.0

# 查看标签列表
git tag -l "v1.*"

# 从标签创建修复分支
git checkout -b hotfix/1.2.1 v1.2.0

版本发布检查清单：

• 确认CHANGELOG.md已更新，记录本次版本的功能变更、修复项和已知问题。
• 确认所有测试（单元测试、集成测试、硬件在环测试）通过。
• 确认固件编译产物（.hex/.bin）已归档到发布附件或制品库。
• 确认App安装包已签名并上传至分发平台。
• 在标签附注中写明关键变更和兼容性说明。

3.5 常见误区与总结复盘

常见误区：

• 误区一：直接在main分支上开发。这会导致主干不稳定，无法随时发布。
• 误区二：提交信息随意填写，如“update”“fix bug”。这会让历史追溯变得极其困难。
• 误区三：忽略标签管理，仅依赖分支名记录版本。分支会移动，标签才是不可变锚点。
• 误区四：将编译产物（.bin、.apk）提交到Git仓库。应使用制品库（如Nexus、Artifactory）管理二进制文件。

总结复盘：有效的源码管理是智能门锁项目交付质量的基石。通过合理的仓库结构、清晰的分支策略、规范的提交信息和严格的标签管理，团队可以实现：任何历史版本可复现、任何变更可追溯、多人协作无冲突。建议在项目启动初期就建立这些规范，并在每次迭代回顾中检查执行情况，逐步形成团队共识。