# RC_Legged 项目规范

## 1. 项目概述

RC_Legged 是一个四轮足强化学习（RL）机器狗项目，涵盖机械设计、硬件电路、嵌入式软件和控制算法全栈开发。

### 仓库地址

- **Gitea 远程仓库**: `https://git.zeitvex.com/Robocon/RC_Legged.git`
- **SSH**: `git@git.zeitvex.com:Robocon/RC_Legged.git`

---

## 2. 仓库目录结构规范

```
RC_Legged/
├── 00_reference/           # 参考项目与文档（只读，不改动）
├── 01_doc/                 # 项目文档（设计文档、会议记录、需求文档）
├── 02_mechanical/          # 机械设计（SolidWorks/STL/URDF/STEP）
│   ├── CAD/                # 源文件
│   ├── STL/                # 3D 打印文件
│   └── URDF/               # URDF 描述文件
├── 03_hardware/            # 硬件电路设计（KiCad/Altium）
│   ├── PCB/                # PCB 工程文件
│   ├── BOM/                # 物料清单
│   └── datasheet/          # 芯片/模块数据手册
├── 04_firmware/            # 嵌入式固件（STM32/ESP32 等）
│   ├── motor_driver/       # 电机驱动固件
│   └── sensor_board/       # 传感器板固件
├── 05_software/            # 上层软件
│   ├── rl_training/        # 强化学习训练代码
│   │   ├── configs/        # 训练配置
│   │   ├── envs/           # 环境定义
│   │   └── logs/           # 训练日志（.gitignore）
│   ├── ros_ws/             # ROS 工作空间
│   │   ├── src/
│   │   └── scripts/
│   └── utils/              # 通用工具脚本
├── 06_assets/              # 媒体资源（渲染图、演示视频等）
├── .gitignore
├── .pre-commit-config.yaml # Pre-commit 配置
├── README.md               # 项目总览
└── 项目规范.md              # 本文件
```

---

## 3. 分支管理策略

### 3.1 分支结构

```
main              ─────●────────────●────────────────●── 最稳定，仅里程碑合并
                         \          /                /
main-nightly      ──●────●──●────●─────────●─────────── 每日构建/集成测试
                      \    \  /    \       /
task-<name>       ─────●──●────────●──●──────────●──── 具体任务分支（实验/算法/feature）
                            \                    /
task-<name>-infra  ─────────●────────────────●─────── 核心代码修补分支（紧急修复）
```

### 3.2 分支职责

| 分支 | 角色 | 说明 |
|------|------|------|
| `main` | 项目所有负责人 | 最保守，只合并经过充分验证的里程碑版本。每次合并应为 **no-ff**（保留合并记录）。 |
| `main-nightly` | 主要维护人员 | 日常集成测试目标。任务分支达标后先合入此分支，稳定后再合入 `main`。 |
| `task-<name>` | 具体任务开发者 | 自己维护，主要用于 task 配置和实验记录。**只允许修改对应子目录内的文件**。 |
| `task-<name>-infra` | 任务开发者（极端情况） | 当必须修改 `main-nightly` 核心代码才能跑通当前训练时使用，快速验证后合入 `main-nightly`。 |

### 3.3 分支操作规则

1. **`main` 分支**：禁止直接推送。只能通过 Pull Request 从 `main-nightly` 合并，且必须经过 Code Review。
2. **`main-nightly` 分支**：原则上禁止直接推送。任务分支通过 PR 合入，需经过基本验证。
3. **`task-*` 分支**：从 `main-nightly` 创建，开发者自行推送。
4. **`task-*-infra` 分支**：从 `main-nightly` 创建，只包含核心代码改动，**不允许包含任何 task 配置文件**，合入后立即删除。
5. **配置代码与逻辑代码分离**：训练 config 文件和核心逻辑代码必须在不同的分支维护。只允许 config 分支从 logic 分支 merge。在里程碑之前，logic 分支不吸收任何 config 分支改动。

---

## 4. 提交（Commit）规范

### 4.1 Commit Message 格式

```
[tag] 一句话描述（不超过 72 字符）

（空一行后可补充详细说明，例如改动动机、注意事项等）
```

### 4.2 标签规则

| 标签 | 含义 | 示例 |
|------|------|------|
| `[add]` | 新增功能/文件 | `[add] 四足逆运动学求解器` |
| `[update]` | 修改已有功能 | `[update] 优化步态切换逻辑` |
| `[fix]` | 修复 Bug | `[fix] 电机 CAN 通讯超时处理` |
| `[remove]` | 删除功能/文件 | `[remove] 废弃旧版遥控器协议` |
| `[format]` | 代码格式化/重构 | `[format] 统一命名规范` |
| `[log]` | 实验记录/日志提交 | `[log] 第3轮训练结果，reward 收敛至0.85` |
| `[doc]` | 文档相关 | `[doc] 添加CAN总线协议说明` |
| `[hardware]` | 硬件相关改动 | `[hardware] PCB v1.2 修改电源走线` |
| `[mechanical]` | 机械相关改动 | `[mechanical] 大腿连杆加厚2mm` |

### 4.3 Commit 原则

1. **一个 Commit 只做一件事**。如果一次改动了多个不相关的问题，必须拆分为多个 commit。
2. **Commit Message 必须说清楚改动内容**。只看 message 就能理解改了什么，否则需要修正。
3. **Task 配置文件和核心代码不得混在同一个 commit 中**。
4. **未通过 Pre-commit 检查的代码不允许 commit**。
5. **如果 commit 历史有问题，必须先修复再继续开发**。

---

## 5. 代码质量规范

### 5.1 Pre-commit 自动检查

- 使用 [pre-commit](https://pre-commit.com/) 工具实现提交前自动检查。
- 安装：`pip install pre-commit`
- 启用：在仓库根目录执行 `pre-commit install`
- 手动运行：`pre-commit run --all-files`
- 所有检查项必须全部通过（绿色/蓝色）方可 commit。
- `.pre-commit-config.yaml` 需包含：代码格式化（Clang-Format / Black）、Python 语法检查（Flake8 / Ruff）、YAML 检查、文件末尾换行符检查等。

### 5.2 代码风格

- **C/C++**：遵循 Google C++ Style Guide，使用 `.clang-format` 统一格式。
- **Python**：遵循 PEP 8，使用 Black 格式化。
- **ROS**：遵循 ROS C++/Python 编码规范。
- **命名**：
  - 文件名：小写 + 下划线（`imu_driver.cpp`）
  - 类名：大驼峰（`ImuDriver`）
  - 函数/变量：小写 + 下划线（`read_imu_data()`）
  - 宏/常量：全大写 + 下划线（`IMU_TIMEOUT_MS`）

### 5.3 接口变更流程

1. 首先尝试在现有接口定义下完成需求。
2. 如必须修改接口，向项目负责人 + 所有使用者提交申请。
3. 通过后，使用 **Pull Request** 标记变更过程，关联相关 Issue。

---

## 6. Pull Request 与代码审查（Code Review）

### 6.1 PR 流程

1. 在 `task-*` 或 `task-*-infra` 分支上完成开发并推送。
2. 在 Gitea 上创建 Pull Request：
   - **来源分支**：`task-*` → **目标分支**：`main-nightly`
   - **来源分支**：`main-nightly` → **目标分支**：`main`
3. PR 标题格式：`[tag] 简短描述`（与 commit message 一致）。
4. PR 描述中说明：改动内容、验证方式、影响范围。

### 6.2 审查要求

- 必须由至少 1 名项目成员 Review 后方可合并。
- 审查重点：功能正确性、接口兼容性、代码风格、是否包含无关文件。
- 如有修改意见，PR 作者修改后重新请求 Review。

### 6.3 合并方式

- 合入 `main-nightly`：使用 **Squash Merge**（保持 nightly 历史清晰）。
- 合入 `main`：使用 **Merge Commit (no-ff)**（保留完整分支历史）。

---

## 7. Gitea 配置

### 7.1 仓库设置

- **可见性**：私有（Private）
- **默认分支**：`main`
- **分支保护**（`main` 分支）：
  - 禁止直接推送
  - 要求 PR 审查通过后才能合并
  - 要求 PR 必须基于最新 `main`
  - 禁用强制推送

### 7.2 初始推送

```bash
git init
git checkout -b main
git add .
git commit -m "[init] RC_Legged 项目初始化"
git remote add origin https://git.zeitvex.com/Robocon/RC_Legged.git
git push -u origin main
```

---

## 8. 硬件测试规范

### 8.1 真机测试要求

1. **全程录像**：每次真机测试必须有独立相机全程拍摄视频。
2. **ROS Bag 记录**：完整系统测试时必须用 ROS Bag 记录所有 message 数据。
   - 使用 `ros2 bag record -s mcap -o <bag_name> /topic1 /topic2 ...`
   - 推荐编写 `rosbag.sh` 脚本自动记录所有传感器数据。
   - 所有与项目相关的电脑需安装 [Foxglove Studio](https://foxglove.dev/) 用于查看 bag。
3. **可视化配置**：所有 ROS 系统必须配置 RViz + `robot_state_publisher` + `joint_state_publisher`。

### 8.2 急停方案

所有真机测试脚本必须包含：
- 除 `Ctrl+C` 外的独立急停机制（如遥控器急停按钮）。
- 急停触发后立即进入 **Damping Mode**，无任何等待延迟。
- 推荐方案：控制程序监听遥控器急停信号，触发后立即终止程序。

---

## 9. .gitignore 示例

```gitignore
# 编译产出
build/
devel/
install/
*.o
*.elf
*.hex

# Python
__pycache__/
*.pyc
*.pyo
.venv/
venv/

# IDE
.vscode/
.idea/
*.swp
*.swo

# 训练产出
05_software/rl_training/logs/
05_software/rl_training/checkpoints/
wandb/

# ROS
*.bag
*.mcap

# 系统
.DS_Store
Thumbs.db

# 机械
*.sldprt
*.sldasm
*.step
*.stp
```

---

## 10. 项目里程碑工作流

```
[日常开发]
  task-xxx 分支开发 → 提交 → 推送 → PR → Code Review → 合入 main-nightly

[里程碑发布]
  main-nightly 经过充分测试
    → 创建 PR: main-nightly → main
    → 项目负责人 Review
    → 合入 main
    → 创建 Git Tag: v1.0.0, v1.1.0, ...
```

---

## 11. 参考项目

| 项目 | 类型 | 地址 |
|------|------|------|
| EDULITE_A3 | 四足机器人 | `00_reference/EDULITE_A3/` |
| OpenDog | 四足机器人 | `00_reference/open-dog/` |
| reBot-DevArm | 机械臂 | `00_reference/reBot-DevArm/` |

---

*本规范参考上述开源项目及行业最佳实践编写，随项目推进持续完善。*