# Git 协作规范（2-3 人团队）

## 一、分支管理策略：main + feature 短分支

```
main ──────●──────●────────●──→  始终可编译可运行
            \    / \      /
feature/h264  ●──   \    /
feature/linux-agent ─●──
```

| 分支 | 用途 | 生命周期 |
|---|---|---|
| `main` | 唯一稳定分支，随时可构建交付 | 永久，受保护 |
| `feature/<模块>-<内容>` | 一个功能一个分支 | ≤1 周，完成即合入删除 |

规则（2-3 人小团队，够用且不添乱）：

1. **main 受保护**：禁止直接 push，一律走 PR/MR 合入（哪怕自己合自己，留个审查记录）；
2. **feature 分支从最新 main 切出**：`git switch -c feature/agent-nvenc main`；
3. **小步提交 + 每天至少 rebase 一次 main**，避免长分支大冲突；
4. **协议（common/）改动**必须先合入，其他分支跟随——协议是三端共享契约；
5. 发版时打 tag：`git tag v0.2.0 && git push --tags`。

### 常用命令速查

```bash
git switch -c feature/agent-nvenc main   # 切新分支
git add -p && git commit -m "feat(agent): ..."   # 交互式暂存提交
git fetch && git rebase origin/main      # 同步 main
git push -u origin feature/agent-nvenc   # 推送并建立跟踪
```

### 提交信息格式

```
<类型>(<模块>): <一句话说明>

类型：feat / fix / refactor / docs / perf / chore
模块：agent / viewer / common / build
示例：perf(agent): 采集限速 30fps 降低带宽需求
```

## 二、两人分工方案（定稿）

按"被控侧 / 主控侧"纵向切分，crate 边界即人的边界，避免合并冲突：

### 成员 A —— 被控侧（agent/）
| 项 | 内容 |
|---|---|
| 主责 crate | `agent/`（以及未来的 `linux-agent/`） |
| 当前任务 | ① 双机复测 H.264 版拿实测数据；② NVENC/QSV 硬编（60fps 目标）；③ Windows 服务化 + 守护进程；④ Linux 被控端（差异化卖点，UU 不做） |
| 技术域 | DXGI 采集、编码器、SendInput、Windows 服务 |

### 成员 B —— 主控侧 + 协议（viewer/ + common/）
| 项 | 内容 |
|---|---|
| 主责 crate | `viewer/`、`common/` |
| 当前任务 | ① 配合 A 双机联调（负责启动/读 HUD 数据）；② 码率自适应（接收端统计 → 反馈编码端）；③ P2P 打洞 + coturn 中继 + 信令服务器；④ 多屏支持、文件传输 |
| 技术域 | 渲染/HUD、QUIC 调优、网络穿透、协议设计 |

### 共同规则

1. **`common/` 改动双人过审**：协议是两端契约，A 动了采集侧消息、B 动了解码侧消息都要对方看一眼；
2. **交叉 review**：A 的 PR 由 B 批准，B 的 PR 由 A 批准——两人都要懂全链路；
3. **联调接口**：新消息类型先在 `common/` 合入 main，再各自动两端，避免协议漂移；
4. **共享基础设施**（信令服务器、coturn 部署脚本）由 B 主建，A 参与；
5. **联调日**：每周固定一次双机联调（A 带被控机，B 带主控机），过完再合 main。

## 三、协作流程（一个功能的完整生命周期）

```
1. 领任务   → 在 issue/任务清单认领，切 feature 分支
2. 开发     → 小步提交（一事一提交）
3. 自测     → cargo build --release 通过 + 回环冒烟测试
4. 提 PR    → 描述改动 + 测试方法，指定另一人 review
5. Review   → 至少 1 人批准；协议改动需全员看过
6. 合入     → squash merge 进 main，删 feature 分支
7. 联调     → main 上跑双机测试，通过后打 tag
```

## 四、代码合并规范

1. **合并方式**：统一 squash merge（`git merge --squash` 或平台按钮），main 历史保持一功能一提交；
2. **冲突处理**：谁的功能分支谁 rebase，禁止在 main 上直接改冲突；
3. **必须过审的改动**：
   - `common/` 任何改动（协议兼容性，三端都受影响）
   - 加密/认证相关代码
   - `Cargo.toml` 新增依赖（确认许可证 + 维护活跃度）
4. **不合并的代码**：编译不过的不合、回环冒烟不过的不合、带 `dbg!`/注释代码块的不合；
5. **Cargo.lock 提交入库**（已提交），依赖变更必须连 lock 一起提。

## 五、当前仓库注意事项

- `target/`（1.4G）、`*.exe`、`*.dll` 已在 .gitignore 排除；**构建产物不入库**，部署用 exe 各自按《构建运行手册.md》编译，或后续用 GitHub Releases/内部网盘分发；
- mingw 运行库 3 个 DLL（libstdc++-6 等）不入库，发布时手动附带；
- 本仓库当前为本地仓库，需要远端托管时：`git remote add origin <url> && git push -u origin main`。