agv-control-slam/PROJECT_STRUCTURE.md

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 模块

# Linux/MSYS2
./build_can.sh

# Windows
build_can.bat

编译主程序

./build.sh

运行示例

CAN 通信示例

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/ 了解已修复的问题

---

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