Git 仓库架构设计：团队协作中的 Git 设置

在明确了团队角色与职责划分之后，接下来需要为团队建立一套高效的 Git 协作基础设施。本节聚焦于与团队组织架构直接相关的 Git 配置与实践——即如何通过子仓库设计、分支策略、权限模型和规范约束，让市场、技术、财务三个角色在同⼀个版本控制体系中有序协作。

团队仓库架构总览

IoT 项目涉及多种类型资产，每种资产有不同的访问权限和更新节奏：

资产类型	内容	维护者	权限要求
固件源码	C/C++ 代码、CMakeLists	固件工程师	技术团队读写
硬件设计	KiCAD 工程、Gerber 文件	硬件工程师	技术团队读写
测试脚本	Python 脚本、测试固件	测试/固件工程师	技术团队读写
需求文档	客户需求、功能规格	售前工程师	售前+管理读写
商务资料	合同、报价、沟通记录	售前工程师	仅售前/管理可读
项目决策	立项评审、财务评估	委员会	全体可读，管理可写

使用 Git 子仓库（submodule），可以将不同权限、不同节奏的资产统一组织在一个主仓库下，同时各子仓库保持独立的访问控制。

基于子仓库的目录结构

iot-project/                    # 主仓库（仅含索引和文档）
├── .gitmodules                 # 子仓库声明
├── README.md                   # 项目概览、当前状态、联系人
├── docs/                       # 项目级通用文档
│   └── project-overview.md
├── firmware/                   # 子仓库：固件
│   └── (独立的 git 仓库，技术团队维护)
├── hardware/                   # 子仓库：硬件
│   └── (独立的 git 仓库，技术团队维护)
├── test/                       # 子仓库：自动化测试
│   └── (独立的 git 仓库，测试团队维护)
└── business/                   # 子仓库：商务资料（私有）
    └── (独立的 git 仓库，售前/管理维护)

子仓库初始化与配置

创建主仓库

# 创建组织级主仓库
mkdir iot-project && cd iot-project
git init

# 创建文档目录
mkdir docs
echo "# IoT Project" > README.md
git add README.md docs/
git commit -m "chore: 初始化项目主仓库"

添加子仓库

# 技术子仓库（团队内开源）
git submodule add https://github.com/your-org/iot-firmware.git firmware
git submodule add https://github.com/your-org/iot-hardware.git hardware
git submodule add https://github.com/your-org/iot-test.git test

# 商务子仓库（私有，仅售前和管理可访问）
git submodule add https://github.com/your-org/iot-business.git business

# 提交子仓库配置
git add .gitmodules
git commit -m "chore: 添加所有子仓库"

设置分支保护规则（团队维度）

主仓库和各子仓库都应设置以下保护规则：

main 分支：禁止直接 push，必须通过 Pull Request
PR 要求：至少 1 人 Code Review 通过
状态检查：CI 自动化测试必须通过

基于角色的协作流程

不同角色的 Git 工作边界

角色	主要操作子仓库	协作方式
固件工程师	`firmware/`	feature 分支 → PR → Code Review
硬件工程师	`hardware/`	feature 分支 → PR → Code Review
售前工程师	`business/`	直接 commit 或简单 PR
测试工程师	`test/`	feature 分支 → PR → Code Review
委员会成员	主仓库 `README`	查看状态，不直接写代码

项目立项后的 Git 协作序列

1. 委员会立项通过 → 更新主仓库 README 项目状态
2. 技术负责人从 firmware/hardware 子仓库 main 切出 feature 分支
3. 开发完成 → 子仓库内发起 PR → Code Review
4. 合并到子仓库 main → CI 自动触发集成测试
5. 更新主仓库的子仓库引用指针

# 步骤 2：技术负责人创建功能分支
cd firmware
git checkout -b feature/mqtt-reconnect

# 步骤 3：开发完成后在 GitHub/GitLab 创建 PR

# 步骤 4：合并后更新主仓库引用
cd ..
git add firmware
git commit -m "chore: 更新 firmware 子仓库引用至 mqtt-reconnect 功能"

商务同事的 Git 使用方式

商务（售前）同事的工作主要在 business/ 子仓库中：

# 克隆（首次）
git clone --recursive https://github.com/your-org/iot-project.git

# 日常：只需关注 business 子仓库
cd iot-project/business

# 查看当前状态
git status

# 添加需求文档
git add requirements/v2-customer-needs.md

# 提交
git commit -m "docs: 添加客户二期需求文档"

# 推送到远程
git push origin main

商务同事不需要进入 firmware/ 或 hardware/ 子仓库，主仓库的 README.md 提供了项目状态概览，方便市场和技术对齐信息。

委员会立项后的仓库操作

委员会制决策流程与 Git 仓库的对应关系：

决策阶段	Git 操作	涉及子仓库
售前收集需求	`business/` 中撰写需求文档	`business/`
技术评估	`firmware/`、`hardware/` 中产出 BOM 和周期评估	`firmware/`、`hardware/`
财务评估	财务意见文档入 `business/`	`business/`
委员会评审	主仓库 README 更新立项状态	主仓库
立项通过	从子仓库 `main` 切出 `feature/` 分支	各技术子仓库

团队 Git 规范

规范项	推荐做法
分支命名	`feature/功能名`、`fix/问题描述`、`docs/文档名`
提交信息	Conventional Commits 格式（`feat:`、`fix:`、`docs:`、`chore:`）
合并方式	技术子仓库通过 PR + Code Review；商务子仓库可简化
主分支保护	技术子仓库 main 禁止直接 push
子仓库指针	子仓库合并后，主仓库需 commit 更新指针引用
.gitignore	各子仓库各自维护，排除编译产物、IDE 配置、密钥
跨角色可见性	主仓库 README 定期更新项目状态，方便市场与财务了解进展

下一步：Git 仓库架构搭建完成后，下一节将介绍售前工程师如何使用 business/ 子仓库中的模板收集客户需求并撰写正式的需求文档。

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →