RCS-3000/docs/custom_path/PROJECT_STRUCTURE.md

# AGV自定义路径功能 - 项目结构

## 📁 完整目录结构

```
agv_path_tracking/
│
├── 📄 CUSTOM_PATH_README.md        # 快速导航（从这里开始）
├── 📄 README.md                     # 项目主README
├── 📄 QUICKSTART.md                 # 原有快速开始
├── 📄 CMakeLists.txt                # 需要修改：添加path_curve_custom.cpp
│
├── 📂 src/                          # 源代码
│   ├── agv_model.cpp
│   ├── path_curve.cpp              # 原有路径实现
│   ├── path_curve_custom.cpp       # ⭐ 新增：自定义路径实现
│   ├── control_generator.cpp
│   └── path_tracker.cpp
│
├── 📂 include/                      # 头文件
│   ├── agv_model.h
│   ├── path_curve.h                # ⚠️ 需要修改：添加3个方法声明
│   ├── control_generator.h
│   └── path_tracker.h
│
├── 📂 examples/                     # 示例程序
│   ├── demo.cpp                    # 原有命令行demo
│   ├── generate_data.cpp
│   ├── gui_demo.cpp
│   ├── qt_gui_demo.cpp             # ⚠️ 可修改：添加自定义路径选项
│   ├── qt_gui_enhanced.cpp         # 参考实现
│   ├── custom_path.csv             # ⭐ 示例：基础路径
│   └── warehouse_path.csv          # ⭐ 示例：仓库路径
│
├── 📂 docs/                         # 📚 文档目录
│   └── custom_path/                # 🎯 自定义路径功能文档（所有文档在这里）
│       ├── README.md               # 📖 文档导航（从这里开始！）
│       │
│       ├── 🚀 快速开始
│       ├── FINAL_SUMMARY.md        # ⭐ 功能总览（推荐首读）
│       ├── QUICKSTART_CUSTOM_PATH.md # 3分钟快速上手
│       │
│       ├── 📖 详细教程
│       ├── CUSTOM_PATH_GUIDE.md    # 完整使用指南
│       │
│       ├── 🖥️ QT界面集成
│       ├── apply_qt_modifications.md # ⭐ 快速修改步骤
│       ├── QT_GUI_CUSTOM_PATH_GUIDE.md # 详细修改指南
│       ├── qt_gui_custom_code_snippet.cpp # 完整代码示例
│       │
│       ├── 🔧 安装和配置
│       ├── install_custom_path.sh  # 自动安装脚本
│       ├── path_curve.h.patch      # 头文件修改补丁
│       │
│       ├── 💻 开发文档
│       ├── CUSTOM_PATH_IMPLEMENTATION_SUMMARY.txt # 实现细节
│       ├── REFERENCE_PATH_SUMMARY.txt # 原系统分析
│       └── PROJECT_STRUCTURE.md    # 本文件（项目结构）
│
├── 📂 build/                        # 编译输出目录
│   ├── agv_demo                    # 可执行文件
│   ├── agv_qt_gui
│   └── ...
│
└── 📂 output/                       # 运行结果（自动生成）
    ├── trajectory.csv
    ├── control_sequence.csv
    └── ...
```

## 🎯 核心文件说明

### ⭐ 必须了解的文件

| 文件 | 位置 | 说明 | 优先级 |
|------|------|------|--------|
| **CUSTOM_PATH_README.md** | 根目录 | 快速导航 | ⭐⭐⭐ |
| **docs/custom_path/README.md** | docs/custom_path/ | 文档导航 | ⭐⭐⭐ |
| **FINAL_SUMMARY.md** | docs/custom_path/ | 功能总览 | ⭐⭐⭐ |

### 📝 文档文件（docs/custom_path/）

| 文件名 | 大小 | 用途 | 适合人群 |
|--------|------|------|----------|
| README.md | 4.2KB | 文档导航 | 所有人 ⭐ |
| FINAL_SUMMARY.md | 6.9KB | 功能总览 | 新手 ⭐⭐⭐ |
| QUICKSTART_CUSTOM_PATH.md | 5.9KB | 快速上手 | 新手 ⭐⭐⭐ |
| CUSTOM_PATH_GUIDE.md | 8.2KB | 完整教程 | 深入学习 ⭐⭐ |
| apply_qt_modifications.md | 2.0KB | QT快速修改 | QT用户 ⭐⭐⭐ |
| QT_GUI_CUSTOM_PATH_GUIDE.md | 7.9KB | QT详细指南 | QT用户 ⭐⭐ |
| qt_gui_custom_code_snippet.cpp | 7.2KB | QT代码示例 | QT开发 ⭐⭐ |
| install_custom_path.sh | 2.1KB | 安装脚本 | 所有人 ⭐⭐⭐ |
| path_curve.h.patch | 1.4KB | 头文件补丁 | 开发者 ⭐ |
| CUSTOM_PATH_IMPLEMENTATION_SUMMARY.txt | 8.4KB | 实现细节 | 开发者 ⭐ |
| REFERENCE_PATH_SUMMARY.txt | 8.7KB | 原系统分析 | 背景知识 ⭐ |
| PROJECT_STRUCTURE.md | 本文件 | 项目结构 | 开发者 ⭐ |

### 💻 核心代码文件

| 文件 | 位置 | 说明 | 是否需要修改 |
|------|------|------|--------------|
| **path_curve_custom.cpp** | src/ | 自定义路径实现 | ❌ 已实现 |
| **path_curve.h** | include/ | 路径类声明 | ⚠️ 需添加3个方法 |
| **CMakeLists.txt** | 根目录 | 编译配置 | ⚠️ 需添加custom文件 |
| **qt_gui_demo.cpp** | examples/ | QT界面 | 🔧 可选修改 |

### 📄 示例文件

| 文件 | 位置 | 说明 | 格式 |
|------|------|------|------|
| **custom_path.csv** | examples/ | 基础示例路径 | x, y |
| **warehouse_path.csv** | examples/ | 仓库场景路径 | x, y |

## 🔄 文件依赖关系

```
CMakeLists.txt
    └── src/path_curve_custom.cpp
            └── include/path_curve.h (需要添加方法声明)
                    └── examples/qt_gui_demo.cpp (可选使用)
                            └── examples/custom_path.csv (示例数据)
```

## 📊 修改检查清单

### 必须修改（功能才能工作）

- [ ] **include/path_curve.h**
  - 添加 `#include <string>`
  - 添加 `bool loadFromCSV(...)`
  - 添加 `bool saveToCSV(...) const`
  - 添加 `void generateSpline(...)`
  - 参考：`docs/custom_path/path_curve.h.patch`

- [ ] **CMakeLists.txt**
  - 在SOURCES中添加：`src/path_curve_custom.cpp`
  - 位置：第19行附近

- [ ] **重新编译**
  ```bash
  cd build
  cmake ..
  cmake --build .
  ```

### 可选修改（增强功能）

- [ ] **examples/qt_gui_demo.cpp**
  - 添加CSV加载选项
  - 添加样条插值选项
  - 参考：`docs/custom_path/qt_gui_custom_code_snippet.cpp`

## 🚀 使用流程

### 流程1: 自动安装（推荐）

```bash
# 1. 运行安装脚本
bash docs/custom_path/install_custom_path.sh

# 2. 编译
cd build && cmake .. && cmake --build .

# 3. 使用
./agv_demo
```

### 流程2: 手动安装

```bash
# 1. 查看文档
cat docs/custom_path/README.md

# 2. 阅读指南
cat docs/custom_path/QUICKSTART_CUSTOM_PATH.md

# 3. 修改文件（参考path_curve.h.patch）
vi include/path_curve.h
vi CMakeLists.txt

# 4. 编译测试
cd build && cmake .. && cmake --build .
```

## 📖 学习路径

### 路径1: 快速上手（15分钟）

```
1. CUSTOM_PATH_README.md        (根目录，2分钟)
   └─ 了解功能位置

2. docs/custom_path/FINAL_SUMMARY.md  (5分钟)
   └─ 功能总览

3. docs/custom_path/QUICKSTART_CUSTOM_PATH.md (5分钟)
   └─ 动手实践

4. bash docs/custom_path/install_custom_path.sh (3分钟)
   └─ 安装使用
```

### 路径2: QT界面集成（20分钟）

```
1. docs/custom_path/apply_qt_modifications.md (5分钟)
   └─ 了解需要修改什么

2. docs/custom_path/qt_gui_custom_code_snippet.cpp (10分钟)
   └─ 复制代码到qt_gui_demo.cpp

3. 编译运行 (5分钟)
   └─ 测试功能
```

### 路径3: 深入学习（1小时）

```
1. FINAL_SUMMARY.md (10分钟)
   └─ 整体了解

2. CUSTOM_PATH_GUIDE.md (30分钟)
   └─ 详细学习

3. CUSTOM_PATH_IMPLEMENTATION_SUMMARY.txt (20分钟)
   └─ 实现细节
```

## 🎯 常用命令

```bash
# 查看文档目录
ls docs/custom_path/

# 阅读文档导航
cat docs/custom_path/README.md

# 自动安装
bash docs/custom_path/install_custom_path.sh

# 查看示例路径
cat examples/custom_path.csv

# 编译项目
cd build && cmake .. && cmake --build .

# 运行demo
./build/agv_demo
./build/agv_qt_gui
```

## 💡 提示

- 📚 所有文档在：`docs/custom_path/`
- ⭐ 从这里开始：`docs/custom_path/FINAL_SUMMARY.md`
- 🚀 快速上手：`docs/custom_path/QUICKSTART_CUSTOM_PATH.md`
- 🖥️ QT修改：`docs/custom_path/apply_qt_modifications.md`
- 🔧 自动安装：`bash docs/custom_path/install_custom_path.sh`

---

**最后更新**: 2025-11-13  
**版本**: 1.0