DronePlanning/docs/地面站后端开发文档.md

地面站后端开发文档

版本: 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应用。

---