项目结构调整

2025-11-15 14:31:47 +08:00
parent a77ae6fac1
commit ec1d6f0cee
12 changed files with 2242 additions and 110 deletions
--- a/FILE_ORGANIZATION.md
+++ b/FILE_ORGANIZATION.md
@@ -0,0 +1,276 @@
+# 文件组织规范
+
+本文档定义了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
+```