# 地面站后端开发文档

**版本**: 1.0
**负责人**: 后端开发团队

---

## 1. 概述与目标

本文档旨在为 **模块二：后端服务** 提供一份完整、清晰的开发与实现指南。后端服务是整个无人机自然语言控制系统的核心枢纽，其主要职责包括：

1.  **接收前端指令**: 通过Web API接收来自QGC插件的自然语言指令。
2.  **智能任务规划**: 集成并调用RAG（检索增强生成）系统和大型语言模型（LLM），将用户指令转化为结构化的无人机任务（`py_tree.json`）。
3.  **任务下发与监控**: 通过ROS2 Action将用户确认后的任务下发给无人机执行，并实时接收无人机的执行状态。
4.  **状态实时反馈**: 通过WebSocket将无人机的执行状态实时、透明地转发给前端QGC插件，实现闭环监控。

本项目将整合现有零散的脚本和资源，构建一个统一、健壮且可扩展的FastAPI应用程序。

## 2. 技术栈

- **Web框架**: FastAPI (用于构建高性能的HTTP和WebSocket接口)
- **ROS2通信**: `rclpy` (Python客户端库，用于与无人机ROS2节点交互)
- **异步处理**: `asyncio` (Python标准库，FastAPI和`rclpy`都基于此)
- **数据模型**: Pydantic (用于API请求/响应的数据验证)
- **RAG向量数据库**: ChromaDB (基于现有`vector_store`目录推断)
- **依赖管理**: `pip` 和 `requirements.txt`

## 3. 最终项目结构

为了实现模块化和高可维护性，项目将采用以下目录结构：

```
.
├── backend_service/
│   ├── src/
│   │   ├── __init__.py
│   │   ├── main.py                 # FastAPI应用主入口
│   │   ├── websocket_manager.py    # WebSocket连接管理器
│   │   ├── py_tree_generator.py    # RAG与LLM集成，生成py_tree
│   │   ├── ros2_client.py          # ROS2 Action客户端
│   │   ├── models.py               # Pydantic数据模型
│   │   └── prompts/                # 存放LLM的prompt模板
│   │       ├── system_prompt.txt
│   │       └── ...
│   ├── knowledge_base/             # RAG知识库源文件
│   │   └── first.ndjson
│   ├── vector_store/               # ChromaDB向量数据库
│   │   └── ...
│   └── requirements.txt            # Python依赖项
│
├── drone_interfaces/               # ROS2接口定义 (保持不变)
│   └── ...
└── (其他项目文件...)
```

## 4. 核心模块详解

### 4.1. FastAPI应用 (`main.py`)

这是整个服务的入口点，负责初始化所有组件并定义API端点。

- **职责**:
    - 创建FastAPI应用实例。
    - 初始化`PyTreeGenerator`, `MissionActionClient`, 和 `ConnectionManager`的单例对象。
    - 定义`POST /generate_plan`, `POST /execute_mission`, 和 `WS /ws/status`三个核心接口。
    - 在后台启动ROS2节点，并确保其与FastAPI的事件循环正确集成。

### 4.2. WebSocket管理器 (`websocket_manager.py`)

该模块专门处理与QGC插件的WebSocket连接。

- **类**: `ConnectionManager`
- **职责**:
    - `connect(websocket: WebSocket)`: 接受并存储新的客户端连接。
    - `disconnect(websocket: WebSocket)`: 移除断开的连接。
    - `broadcast(message: str)`: 向所有已连接的客户端广播消息。此方法必须是**线程安全**的，因为它将被ROS2回调（运行在不同线程）调用。

### 4.3. PyTree生成器 (`py_tree_generator.py`)

封装了所有与任务生成相关的复杂逻辑。

- **类**: `PyTreeGenerator`
- **职责**:
    - 初始化RAG系统，加载`vector_store`中的知识库。
    - 提供一个核心方法 `generate(user_prompt: str) -> dict`。
    - **`generate`方法内部流程**:
        1.  接收用户输入。
        2.  使用RAG的检索器从`vector_store`中查找最相关的知识片段（例如，可用的无人机动作、地理位置信息等）。
        3.  从`prompts/`目录加载系统Prompt模板。
        4.  将用户输入、检索到的知识组合成一个完整的Prompt。
        5.  调用外部或本地的LLM服务，获取生成的`py_tree.json`字符串。
        6.  验证返回的JSON是否符合`00_System_Overview_and_Interfaces.md`中定义的契约，确保其结构正确。
        7.  返回验证通过的Python字典。

### 4.4. ROS2 Action客户端 (`ros2_client.py`)

负责与无人机（模块三）进行通信。

- **类**: `MissionActionClient` (继承自 `rclpy.node.Node`)
- **职责**:
    - 初始化一个ROS2节点。
    - 创建一个`ExecuteMission` Action的客户端。
    - 提供一个核心方法 `send_goal(py_tree: dict)`。
    - **`send_goal`方法内部流程**:
        1.  将`py_tree`字典序列化为JSON字符串。
        2.  构建`ExecuteMission.Goal`消息。
        3.  异步发送Action目标，并注册`feedback_callback`。
    - **`feedback_callback`方法**:
        1.  此回调由`rclpy`的执行器在单独的线程中触发。
        2.  当收到无人机的状态反馈时，将`current_node_id`和`status`打包成一个字典。
        3.  获取FastAPI的事件循环，并使用`loop.call_soon_threadsafe()`安全地调用`websocket_manager.broadcast()`方法，将状态更新推送到前端。

### 4.5. 数据模型 (`models.py`)

使用Pydantic定义清晰、严格的API数据结构。

- **类**:
    - `GeneratePlanRequest(BaseModel)`: 包含`user_prompt: str`。
    - `ExecuteMissionRequest(BaseModel)`: 包含`py_tree: dict`。
    - `StatusUpdate(BaseModel)`: 包含`node_id: str`和`status: int`。

## 5. 数据流

### 5.1. 任务规划流程

`QGC Plugin` -> `POST /generate_plan` -> `main.py` -> `py_tree_generator.generate()` -> `RAG/LLM` -> `py_tree.json` -> `main.py` -> `QGC Plugin`

### 5.2. 任务执行与反馈流程

`QGC Plugin` -> `POST /execute_mission` -> `main.py` -> `ros2_client.send_goal()` -> `ROS2 Network` -> `Drone`
`Drone` -> `ROS2 Feedback` -> `ros2_client.feedback_callback()` -> `websocket_manager.broadcast()` -> `WS /ws/status` -> `QGC Plugin`

## 6. 后续步骤

1.  **环境搭建**: 根据`requirements.txt`创建虚拟环境并安装所有依赖。
2.  **代码实现**: 按照上述设计，逐一编写`websocket_manager.py`, `py_tree_generator.py`, `ros2_client.py`, `models.py`, 和 `main.py`。
3.  **单元测试与集成测试**: (可选，但建议) 为关键模块（如`py_tree_generator`）编写单元测试，并进行完整的集成测试。
4.  **部署**: 使用`uvicorn`等ASGI服务器运行FastAPI应用。

---