# 文件组织规范

本文档定义了AGV路径跟踪项目的文件组织规范，用于管理bug修复、程序更新和版本归档。

## 目录结构

```
agv_path_tracking/
├── archives/                    # 归档目录
│   ├── bug_fixes/              # Bug修复归档
│   │   └── YYYYMMDD_bug名称/   # 按日期和bug名称组织
│   │       ├── code/           # 修复的代码文件
│   │       ├── docs/           # 相关文档
│   │       └── tests/          # 测试文件
│   ├── updates/                # 功能更新归档
│   │   └── YYYYMMDD_功能名称/  # 按日期和功能名称组织
│   │       ├── code/           # 新增/修改的代码
│   │       ├── docs/           # 更新文档
│   │       └── tests/          # 测试文件
│   └── versions/               # 版本归档
│       └── vX.Y.Z/             # 按版本号组织
│           ├── release_notes.md
│           └── backup/         # 完整代码备份
├── docs/                        # 项目文档
│   ├── fixes/                  # Bug修复文档（当前）
│   ├── updates/                # 功能更新文档（当前）
│   ├── guides/                 # 使用指南
│   └── protocol/               # 协议文档
├── src/                         # 源代码（主工作目录）
├── include/                     # 头文件（主工作目录）
└── examples/                    # 示例代码（主工作目录）
```

## 命名规范

### 1. Bug修复命名
- **文件夹命名**: `YYYYMMDD_bug描述`
  - 例如: `20251115_fix_path_tracking_error`
- **文件命名**: 保持原有文件名，或添加`_fixed`后缀
  - 例如: `path_tracker_fixed.cpp`

### 2. 功能更新命名
- **文件夹命名**: `YYYYMMDD_功能描述`
  - 例如: `20251115_add_adaptive_lookahead`
- **文件命名**: 清晰描述功能
  - 例如: `adaptive_lookahead.cpp`

### 3. 文档命名
- **Bug修复文档**: `BUG_描述_日期.md`
  - 例如: `BUG_path_tracking_error_20251115.md`
- **更新文档**: `UPDATE_功能描述_日期.md`
  - 例如: `UPDATE_adaptive_lookahead_20251115.md`

## 工作流程

### Bug修复流程

1. **创建工作目录**
   ```bash
   mkdir -p archives/bug_fixes/YYYYMMDD_bug名称/{code,docs,tests}
   ```

2. **在主代码目录进行修复**
   - 在 `src/`, `include/` 等目录直接修复bug
   - 及时提交git commit

3. **归档修复**
   - 将修复的文件副本保存到 `archives/bug_fixes/YYYYMMDD_bug名称/code/`
   - 创建修复文档保存到 `archives/bug_fixes/YYYYMMDD_bug名称/docs/`
   - 同时在 `docs/fixes/` 创建文档副本供快速查阅

4. **文档内容应包含**
   - Bug描述和复现步骤
   - 根本原因分析
   - 修复方案说明
   - 修改的文件列表
   - 测试验证结果
   - 相关的git commit ID

### 功能更新流程

1. **创建工作目录**
   ```bash
   mkdir -p archives/updates/YYYYMMDD_功能名称/{code,docs,tests}
   ```

2. **在主代码目录进行开发**
   - 在 `src/`, `include/` 等目录添加新功能
   - 及时提交git commit

3. **归档更新**
   - 将新增/修改的文件副本保存到 `archives/updates/YYYYMMDD_功能名称/code/`
   - 创建更新文档保存到 `archives/updates/YYYYMMDD_功能名称/docs/`
   - 同时在 `docs/updates/` 创建文档副本供快速查阅

4. **文档内容应包含**
   - 功能需求描述
   - 设计方案
   - 实现细节
   - API文档（如有）
   - 使用示例
   - 测试结果
   - 相关的git commit ID

### 版本发布流程

1. **创建版本目录**
   ```bash
   mkdir -p archives/versions/vX.Y.Z/backup
   ```

2. **准备发布**
   - 更新版本号
   - 编写 `release_notes.md`
   - 汇总本版本所有bug修复和功能更新

3. **创建备份**
   - 可选：将完整代码打包到 `archives/versions/vX.Y.Z/backup/`
   - 创建git tag

4. **发布说明应包含**
   - 版本号和发布日期
   - 新增功能列表
   - Bug修复列表
   - 重大变更说明
   - 升级指南（如需要）

## 文档模板

### Bug修复文档模板

```markdown
# Bug修复: [Bug简短描述]

**日期**: YYYY-MM-DD
**修复者**: [姓名]
**相关Issue**: #[编号]（如有）

## Bug描述
[详细描述bug的表现]

## 复现步骤
1. [步骤1]
2. [步骤2]
3. [观察到的错误行为]

## 根本原因
[分析bug的根本原因]

## 修复方案
[描述如何修复这个bug]

## 修改文件
- `src/xxx.cpp` - [修改说明]
- `include/xxx.h` - [修改说明]

## 测试验证
[描述如何测试验证修复有效]

## Git Commit
- Commit ID: [commit_hash]
- Commit Message: [message]

## 备注
[其他需要说明的内容]
```

### 功能更新文档模板

```markdown
# 功能更新: [功能名称]

**日期**: YYYY-MM-DD
**开发者**: [姓名]
**相关Issue**: #[编号]（如有）

## 功能概述
[简要描述新功能的目的和价值]

## 需求背景
[为什么需要这个功能]

## 设计方案
[技术设计方案描述]

### 架构变更
[如有架构层面的变更，在此说明]

### API设计
[如果是库函数，描述API接口]

## 实现细节

### 新增文件
- `src/xxx.cpp` - [文件说明]
- `include/xxx.h` - [文件说明]

### 修改文件
- `src/yyy.cpp` - [修改说明]

## 使用方法
```cpp
// 示例代码
```

## 测试结果
[测试场景和结果]

## Git Commit
- Commit ID: [commit_hash]
- Commit Message: [message]

## 后续计划
[如有待完善的内容]

## 备注
[其他需要说明的内容]
```

## 最佳实践

1. **及时归档**: 完成修复或更新后立即归档，不要拖延
2. **详细文档**: 文档要详细清晰，方便他人理解和维护
3. **代码备份**: 归档时保存相关代码的副本，便于追溯
4. **版本控制**: 善用git，每次修复/更新都要commit
5. **交叉引用**: 文档中包含git commit ID，方便关联
6. **定期整理**: 定期检查归档目录，清理过时内容
7. **命名一致**: 严格遵循命名规范，保持一致性

## 快速参考

### 创建Bug修复归档
```bash
DATE=$(date +%Y%m%d)
BUG_NAME="bug_description"
mkdir -p archives/bug_fixes/${DATE}_${BUG_NAME}/{code,docs,tests}
mkdir -p docs/fixes/
# 编辑文档
vim archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md
# 复制到快速查阅目录
cp archives/bug_fixes/${DATE}_${BUG_NAME}/docs/BUG_${BUG_NAME}_${DATE}.md docs/fixes/
```

### 创建功能更新归档
```bash
DATE=$(date +%Y%m%d)
FEATURE_NAME="feature_description"
mkdir -p archives/updates/${DATE}_${FEATURE_NAME}/{code,docs,tests}
mkdir -p docs/updates/
# 编辑文档
vim archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md
# 复制到快速查阅目录
cp archives/updates/${DATE}_${FEATURE_NAME}/docs/UPDATE_${FEATURE_NAME}_${DATE}.md docs/updates/
```

### 查看归档历史
```bash
# 查看所有bug修复
ls -la archives/bug_fixes/

# 查看所有功能更新
ls -la archives/updates/

# 查看所有版本
ls -la archives/versions/
```

## 维护说明

本规范文档应该：
- 随着项目发展持续更新
- 被所有项目成员遵守
- 在项目README中引用

最后更新: 2025-11-15
```