# AGV 路径跟踪项目文件结构

## 📁 目录结构

```
agv_path_tracking/
├── 📄 README.md                    # 项目主文档
├── 📄 CMakeLists.txt               # CMake 构建配置
├── 📄 build_can.sh/bat             # CAN 模块编译脚本
├── 📄 build.sh                     # 主程序编译脚本
│
├── 📂 src/                         # 源代码目录
│   ├── 📂 can/                    # CAN 通信模块
│   │   ├── CANController.h        # CAN 控制器头文件
│   │   ├── CANController.cpp      # CAN 控制器实现
│   │   ├── can_example.cpp        # CAN 基础示例
│   │   └── can_complete_example.cpp  # CAN 完整示例
│   │
│   ├── 📂 tests/                  # 测试代码
│   │   └── test_csv_load.cpp      # CSV 加载测试
│   │
│   ├── agv_model.cpp              # AGV 模型
│   ├── control_generator.cpp      # 控制生成器
│   ├── path_curve.cpp             # 路径曲线
│   ├── path_curve_custom.cpp      # 自定义路径曲线
│   └── path_tracker.cpp           # 路径跟踪器
│
├── 📂 include/                     # 头文件目录
│   └── 📂 can/                    # CAN 相关头文件
│       └── CANController.h        # CAN 控制器头文件
│
├── 📂 lib/                         # 库文件目录
│   ├── ControlCAN.h               # CAN 设备 API 头文件
│   ├── ControlCAN.dll             # CAN 驱动动态库
│   ├── ControlCAN.lib             # CAN 导入库
│   └── README.md                  # 库说明文档
│
├── 📂 docs/                        # 文档目录
│   ├── 📂 can/                    # CAN 相关文档
│   │   ├── CAN_README.md          # CAN 使用说明
│   │   └── CAN_API_Reference.cpp  # CAN API 快速参考
│   │
│   ├── 📂 guides/                 # 使用指南
│   │   ├── START_HERE.txt         # 快速开始
│   │   ├── QUICK_START.md         # 快速入门
│   │   ├── QUICKSTART.md          # 快速开始指南
│   │   ├── BUILD_INSTRUCTIONS.md  # 编译说明
│   │   ├── CUSTOM_PATH_README.md  # 自定义路径说明
│   │   ├── SMOOTH_PATH_GENERATOR_README.md  # 平滑路径生成器说明
│   │   └── TRACKING_TEST_GUIDE.md # 跟踪测试指南
│   │
│   ├── 📂 fixes/                  # 修复记录
│   │   ├── ALL_FIXES_SUMMARY.md   # 所有修复总结
│   │   ├── BUG_FIXES_SUMMARY.md   # Bug 修复总结
│   │   ├── CSV_LOAD_FIX.md        # CSV 加载修复
│   │   ├── FIX_SUMMARY.md         # 修复总结
│   │   ├── README_FIXES.md        # 修复说明
│   │   ├── TRACKING_ERROR_ANALYSIS.md  # 跟踪误差分析
│   │   ├── TRACKING_FIX_COMPLETE.md    # 跟踪修复完成
│   │   ├── TRAJECTORY_COMPLETE.md      # 轨迹完成
│   │   ├── TRAJECTORY_FIX.md           # 轨迹修复
│   │   └── FINAL_REPORT.md             # 最终报告
│   │
│   ├── 📂 custom_path/            # 自定义路径文档
│   │   ├── README.md              # 自定义路径说明
│   │   ├── CUSTOM_PATH_GUIDE.md   # 自定义路径指南
│   │   ├── QT_GUI_CUSTOM_PATH_GUIDE.md  # QT GUI 指南
│   │   ├── QUICKSTART_CUSTOM_PATH.md    # 快速开始
│   │   ├── SMOOTH_PATH_QUICKSTART.md    # 平滑路径快速开始
│   │   └── PROJECT_STRUCTURE.md   # 项目结构
│   │
│   └── 📂 protocol/               # 协议文档
│       └── CAN_Protocol.pdf       # CAN 协议规范
│
├── 📂 build/                       # 构建输出目录
│   ├── can_demo.exe               # CAN 完整示例程序
│   ├── can_simple.exe             # CAN 简单示例程序
│   ├── ControlCAN.dll             # CAN 驱动库（运行时）
│   └── ...                        # 其他构建文件
│
└── 📂 examples/                    # 示例目录（如果有）

```

## 📋 主要模块说明

### 1. CAN 通信模块 (`src/can/`)
- **CANController.h/cpp** - CAN 控制器封装类，提供易用的 CAN 设备操作接口
- **can_example.cpp** - 基础 CAN 通信示例
- **can_complete_example.cpp** - 完整的 CAN 通信示例，包含 AGV 控制场景

### 2. 路径跟踪模块 (`src/`)
- **agv_model.cpp** - AGV 运动学模型
- **path_curve.cpp** - 路径曲线定义和处理
- **path_tracker.cpp** - 路径跟踪算法实现
- **control_generator.cpp** - 控制量生成器

### 3. 文档模块 (`docs/`)
- **can/** - CAN 通信相关文档和 API 参考
- **guides/** - 各种使用指南和快速开始文档
- **fixes/** - Bug 修复记录和分析报告
- **custom_path/** - 自定义路径功能文档
- **protocol/** - 通信协议规范

### 4. 库文件 (`lib/`)
- **ControlCAN.h/dll/lib** - USBCAN 设备驱动库

## 🚀 快速开始

### 编译项目

#### 编译 CAN 模块
```bash
# Linux/MSYS2
./build_can.sh

# Windows
build_can.bat
```

#### 编译主程序
```bash
./build.sh
```

### 运行示例

#### CAN 通信示例
```bash
cd build
./can_demo.exe
```

## 📖 文档导航

### 新手入门
1. **START_HERE.txt** - 从这里开始 (`docs/guides/START_HERE.txt`)
2. **QUICK_START.md** - 快速入门指南 (`docs/guides/QUICK_START.md`)
3. **BUILD_INSTRUCTIONS.md** - 编译说明 (`docs/guides/BUILD_INSTRUCTIONS.md`)

### CAN 通信
1. **CAN_README.md** - CAN 使用说明 (`docs/can/CAN_README.md`)
2. **CAN_API_Reference.cpp** - API 快速参考 (`docs/can/CAN_API_Reference.cpp`)

### 自定义路径
1. **CUSTOM_PATH_README.md** - 自定义路径说明 (`docs/guides/CUSTOM_PATH_README.md`)
2. **custom_path/README.md** - 详细文档 (`docs/custom_path/README.md`)

### 修复记录
1. **ALL_FIXES_SUMMARY.md** - 所有修复总结 (`docs/fixes/ALL_FIXES_SUMMARY.md`)
2. **FINAL_REPORT.md** - 最终报告 (`docs/fixes/FINAL_REPORT.md`)

## 🔧 开发指南

### 添加新的 CAN 功能
1. 在 `src/can/` 目录下创建源文件
2. 如需要头文件，同时在 `include/can/` 创建
3. 更新 `build_can.sh/bat` 编译脚本
4. 在 `docs/can/` 添加相关文档

### 添加新的文档
- 使用指南 → `docs/guides/`
- 修复记录 → `docs/fixes/`
- 模块文档 → `docs/模块名/`

## 📝 文件命名规范

### 源代码文件
- C++ 源文件：小写字母 + 下划线，如 `path_tracker.cpp`
- C++ 头文件：小写字母 + 下划线，如 `path_tracker.h`
- 类名：驼峰命名，如 `CANController`

### 文档文件
- Markdown 文档：大写字母 + 下划线，如 `QUICK_START.md`
- 说明文件：`README.md`

## ⚙️ 构建系统

- **CMakeLists.txt** - CMake 构建配置
- **build.sh** - Linux/MSYS2 构建脚本
- **build_can.sh/bat** - CAN 模块构建脚本

## 📦 依赖库

- ControlCAN - USBCAN 设备驱动库（位于 `lib/`）
- 标准 C++11 或更高版本

## 🎯 下一步

1. 阅读 `docs/guides/START_HERE.txt` 快速开始
2. 查看 `docs/can/CAN_README.md` 了解 CAN 通信
3. 运行示例程序了解项目功能
4. 查看 `docs/fixes/` 了解已修复的问题

---

**注意**：本文档描述了重新组织后的项目结构。所有文档和代码文件都已按模块分类整理。