# 技术文档

## 1. 项目定位

`robot_cloud_system` 是一个面向移动机器人云控场景的 Web + ROS 2 集成项目。系统以 Flask-SocketIO 作为 Web 服务入口，以 ROS 2 节点作为机器人能力接入层，以 SQLite 作为本地任务存储，提供以下核心能力：

- 浏览器远程控制机器人运动
- 实时展示地图、位姿和激光雷达数据
- 管理导航点与导航任务
- 查询与更新任务状态
- 展示基础系统状态信息

项目当前更偏向“教学演示 / 原型验证 / 二次开发基础仓库”，不是完整生产级平台。

## 2. 技术栈

- 后端框架：Flask
- 实时通信：Flask-SocketIO
- ROS 通信：rclpy、Action Client、Topic Subscription
- 数据存储：SQLite
- 前端实现：Jinja2 模板 + 原生 JavaScript
- 运行环境：Python 3.10+、ROS 2 Humble

## 3. 整体架构

项目分为四层：

### 3.1 Web 接入层

入口文件为 `app.py`，负责：

- 创建 Flask 应用
- 初始化 Socket.IO
- 暴露 HTTP API
- 注册 WebSocket 事件
- 初始化 ROS 2 节点
- 启动后台线程进行状态推送

### 3.2 机器人服务层

位于 `service_nodes/`，负责封装不同类型的机器人能力：

- `WebNode.py`
  速度控制、IMU 数据、电池状态
- `MapServer.py`
  地图、位姿、雷达、导航点
- `NavigationClient.py`
  导航目标发送、路径缓存、导航状态
- `TaskQueueManager.py`
  任务数据库读写、状态历史管理
- `TaskStateMachine.py`
  任务状态转换规则校验
- `TrajectoryRecorder.py`
  轨迹记录服务
- `SystemShow.py`
  系统状态和控制反馈

### 3.3 前端展示层

位于 `robot_dashboard/templates/`：

- `base.html`
  公共布局与全局样式
- `index.html`
  主控制台入口
- `map.html`
  地图、路径、导航点相关 UI
- `tasks.html`
  任务管理页面
- `system.html`
  系统信息与系统操作页面
- `system_show.html`
  `/system` 路由使用的包装模板

### 3.4 数据持久化层

使用 SQLite，本地数据库文件路径来自环境变量 `DATABASE_PATH`。

主要表：

- `tasks`
- `task_status_history`

## 4. 目录说明

```text
robot_cloud_system/
├─ app.py
├─ config.py
├─ requirements.txt
├─ .env.example
├─ maps/
├─ robot_dashboard/
│  ├─ static/
│  └─ templates/
├─ service_nodes/
├─ scripts/
│  └─ init_database.py
└─ docs/
```

目录职责：

- `maps/`
  示例地图文件，供前端地图展示和导航调试使用
- `robot_dashboard/static/`
  浏览器静态资源
- `robot_dashboard/templates/`
  页面模板与内联前端逻辑
- `service_nodes/`
  ROS 2 业务节点
- `scripts/`
  辅助脚本
- `docs/`
  项目文档

## 5. 运行流程

### 5.1 启动前准备

1. 加载 ROS 2 环境
2. 安装 Python 依赖
3. 初始化数据库
4. 启动 rosbridge
5. 启动 Flask-SocketIO 服务

### 5.2 系统启动顺序

`app.py` 启动时的核心流程：

1. 创建 Flask 应用
2. 创建 Socket.IO 服务
3. 调用 `init_ros_nodes()`
4. 初始化以下节点实例：
   `WebNode`、`LidarProcessor`、`MapServer`、`NavigationClient`、`TrajectoryRecorder`、`TaskQueueManager`、`TaskStateMachine`、`SystemShow`
5. 创建 `MultiThreadedExecutor`
6. 启动 ROS 线程执行 `spin()`
7. 启动系统状态更新线程
8. 启动 Web 服务

## 6. 配置说明

配置文件为 `config.py`，通过 `.env` 读取参数。

主要配置项：

- `FLASK_SECRET_KEY`
  Flask 密钥
- `FLASK_HOST`
  监听地址
- `FLASK_PORT`
  服务端口
- `FLASK_DEBUG`
  调试模式
- `DATABASE_PATH`
  SQLite 文件路径
- `ROS_DISTRO`
  ROS 发行版标识

## 7. 核心模块详解

### 7.1 `app.py`

`app.py` 同时承担“页面路由 + API + WebSocket + ROS 初始化”四类职责。

主要能力：

- 页面渲染
- 地图、位姿、雷达 HTTP 查询
- 任务 API
- 系统状态 API
- 控制指令转发
- 导航事件调度
- 状态广播

当前特点：

- 入口集中，易于快速理解
- 但单文件职责较重，后续可拆分为蓝图、服务层和事件处理模块

### 7.2 `MapServer.py`

职责：

- 订阅 `/map`
- 订阅 `/amcl_pose`
- 订阅 `/odom`
- 订阅 `/scan`
- 维护地图缓存、机器人位姿、雷达数据、导航点

输出给前端的数据类型：

- 地图元数据和栅格数据
- 机器人位姿
- 激光雷达点云基础数据
- 导航点列表

### 7.3 `NavigationClient.py`

职责：

- 发送 `NavigateToPose` 导航目标
- 订阅 `/plan` 和 `/local_plan`
- 缓存全局路径和局部路径
- 管理导航队列与导航状态

典型调用场景：

- 前端点击“开始导航”
- `app.py` 组织目标点
- `NavigationClient` 发出 ROS 导航请求

### 7.4 `TaskQueueManager.py`

职责：

- 初始化任务表
- 创建任务
- 查询任务
- 删除任务
- 更新任务状态
- 记录状态历史

当前实现特点：

- 以 SQLite 为主
- 同时带有一部分内存队列逻辑
- 兼具“数据库服务”和“任务调度器”双重角色

后续可演进方向：

- 拆分数据库访问层和调度执行层
- 引入更清晰的任务领域模型

### 7.5 `SystemShow.py`

职责：

- 维护系统运行时长
- 维护网络状态
- 提供重连、重启、恢复出厂等操作的模拟反馈

说明：

- 当前更偏演示逻辑，真实部署时需要替换为实际系统控制能力

## 8. HTTP API 清单

### 页面路由

- `/`
  主页面
- `/system`
  系统状态页面
- `/debug/map`
  地图调试接口
- `/debug/request_map`
  手动触发地图请求

### 地图与传感器接口

- `/api/robot_pose`
  获取机器人位姿
- `/api/lidar_data`
  获取雷达数据
- `/api/map_data`
  获取地图数据

### 任务接口

- `GET /api/tasks`
  获取任务列表
- `POST /api/tasks`
  创建任务
- `GET /api/tasks/<task_id>`
  获取任务详情
- `PUT /api/tasks/<task_id>/status`
  更新任务状态
- `GET /api/tasks/<task_id>/history`
  获取任务历史
- `DELETE /api/tasks/<task_id>`
  删除任务

### 系统接口

- `GET /api/system/status`
  获取系统状态

## 9. WebSocket 事件清单

### 连接与基础状态

- `connect`
- `disconnect`
- `update_battery_data`
- `update_imu_data`
- `update_lidar_data`
- `request_map_data`

### 控制相关

- `control_command`
- `real_control_command`

### 导航点与导航

- `add_waypoint`
- `delete_waypoint`
- `clear_waypoints`
- `request_robot_pose`
- `request_lidar_data`
- `start_nav_sequence`
- `stop_navigation`
- `trajectory_record_command`
- `get_waypoints`
- `get_navigation_path`

### 任务相关

- `start_task`
- `stop_task`
- `complete_task`
- `fail_task`

### 系统相关

- `system_reconnect`
- `system_restart`
- `system_factory_reset`

## 10. 数据模型

### 10.1 tasks

字段说明：

- `id`
- `name`
- `type`
- `priority`
- `status`
- `parameters`
- `created_at`
- `updated_at`

### 10.2 task_status_history

字段说明：

- `id`
- `task_id`
- `status`
- `timestamp`
- `message`

## 11. 前后端数据流

### 11.1 控制链路

1. 浏览器发起控制命令
2. Socket.IO 将事件发送到 `app.py`
3. `app.py` 调用 `WebNode.publish_cmd_vel()`
4. ROS 2 发布到 `/cmd_vel`

### 11.2 地图展示链路

1. `MapServer` 接收 `/map`
2. `MapServer` 更新内部缓存
3. 前端通过 `request_map_data` 请求
4. `app.py` 将地图和位姿通过 Socket.IO 推送到页面

### 11.3 任务执行链路

1. 前端调用 `/api/tasks` 创建任务
2. 任务写入 SQLite
3. 前端触发 `start_task`
4. `app.py` 从数据库读取任务
5. 导航目标进入导航流程
6. 状态变化写入 `task_status_history`

## 12. 已知设计特点与限制

- 页面脚本主要以内联方式编写，适合原型，但不利于长期维护
- `app.py` 过大，后续适合按领域拆分
- 任务系统目前仍偏轻量，状态机和调度能力可以继续完善
- 系统操作能力目前以演示为主，不应直接视为生产级运维接口
- 项目强依赖 ROS 2 运行环境，缺少 ROS 时只能进行静态开发

## 13. 建议的后续演进方向

### 结构层面

- 将 `app.py` 拆成 `routes/`、`socket_handlers/`、`services/`
- 将前端大段内联 JS 拆到独立静态文件

### 工程层面

- 增加自动化测试
- 增加日志模块
- 增加类型标注和静态检查
- 增加 Docker / 部署脚本

### 业务层面

- 完善任务状态机
- 增加权限和身份认证
- 增加机器人多实例支持
- 增加真实系统操作适配层

## 14. 快速阅读建议

第一次接手这个项目，建议按下面顺序阅读：

1. `README.md`
2. `docs/architecture.md`
3. `docs/technical-reference.md`
4. `app.py`
5. `service_nodes/MapServer.py`
6. `service_nodes/NavigationClient.py`
7. `service_nodes/TaskQueueManager.py`

这样可以先建立整体模型，再进入具体实现。