+
+
+
+
+
+
+1 项目概述本项目（metadata 名：光伏电站智能监控与运维系统）是一个面向光伏电站场景的机器人智能管理平台 。它将巡检机器人 / 无人机、视频监控、告警处理与运维工单整合到单一 Web 控制台，提供设备管理、实时监控、视频回传、状态预警、AI 诊断分析、清洗优化、报表中心与视频下载等一站式能力。
+
+
+
+系统定位是前端 SPA ，通过四条独立通信通道对接后端的 API、MQTT、WebSocket 与 GeoServer 服务，实现“低延迟控制 + 高吞吐遥测 + 实时视频”的多协议协同。
+
+
+
+2 技术栈选型
+ 层级 技术 用途
+ 框架 React 19 + TypeScript UI 渲染与类型安全 构建 Vite 6 + @vitejs/plugin-react 极速 HMR 与打包，含 CSS 代码分割 UI 组件 Ant Design 5 + TailwindCSS 4 企业级组件库 + 原子化样式 状态管理 Redux Toolkit + react-redux user / station 全局状态切片 路由 React Router DOM 7 全路由懒加载 + ProtectedRoute 鉴权 3D / GIS Cesium + vite-plugin-cesium 三维地图、设备轨迹与场站可视化 图表 ECharts 6 / Recharts / @ant-design/charts 告警统计、运行数据可视化 HTTP Axios 统一请求实例 + 拦截器 实时通信 MQTT / WebSocket / WebRTC / Socket.io 遥测 / 控制 / 视频 / 实时推送 音视频 @volcengine/rtc · agora-rtc-sdk-ng · JSWebrtc 多路无人机/机器人视频回传 其它 js-cookie · qrcode · lodash · motion · react-draggable 会话/二维码/工具/动画/拖拽
+
+
+
+
+3 系统分层架构系统自上而下分为四层。应用层内部进一步拆为路由、页面、组件、状态四个子层；通信层以四条并行通道桥接前后端。
+
+
+
+ 光伏电站智能监控与运维系统 · 分层架构
+ 用户浏览器 / Web Client
+ React 19 + TypeScript · Vite 6 (SPA 前端应用)
+ 路由层
+ Router7 · 懒加载 · 鉴权
+ 页面层
+ Home·设备·视频·告警·AI
+ 组件层
+ Layout·devices·alerts
+ 状态管理
+ Redux (user·station)
+ 实时通信层（四通道并行）
+ HTTP · Axios
+ API 请求 · 401 拦截
+ MQTT
+ 设备遥测 useMqtt
+ WebSocket
+ 设备控制 wsManager
+ WebRTC
+ 视频流 JSWebrtc
+ 后端服务层（1.95.137.212）
+ API server
+ :8081 REST 业务
+ MQTT broker
+ :8083 消息
+ WS server
+ :9002 设备控制
+ GeoServer
+ :59018 GIS 地图
+
+
图 1 · 系统四层分层架构
+
+
+
+4 核心模块详解4.1 路由层 src/router
+采用 createBrowserRouter + 全量 lazy() 懒加载，首屏只加载必要代码。路由通过 routeMeta 声明每个路径的 角色白名单 （admin / operator / viewer）与 requiresAuth，ProtectedRoute 在进入受保护路由前校验登录态与权限，未登录跳转 /login。
+
+4.2 页面层 src/pages
+
+ 页面 职责
+ Home / overview 总览首页，聚合设备状态、告警、作业统计概览 Devices 相关 设备总览 / 状态 / 航线任务 / 机器人任务 Video / VideoMonitorPage 在线视频与视频监控，多路 WebRTC 拉流 RealTimeMonitor 实时监控，Cesium 地图 + 设备轨迹 Alerts 告警中心：实时 / 历史 / 统计 / 规则 / 订阅 AIAnalysis AI 诊断分析（热成像分析） CleanOptimization 清洗优化 WorkOrder 工单任务管理 ReportCenter / Downloads 报表中心 / 视频下载 SystemSetting（嵌套子路由） 系统设置：基础设置、用户、菜单、组织、场站、设备接入、系统维护等 Login / Profile / Users / Roles 登录 / 个人中心 / 用户管理 / 角色管理
+
+
+4.3 组件层 src/components
+
+ 目录/组件 职责
+ Layout.tsx 应用外壳：侧边栏菜单（动态构建菜单树）、顶栏、场站切换器、全屏控制 ProtectedRoute 路由级鉴权守卫 devices/ 设备控制核心：DeviceControl、DeviceController（控制类）、DroneVideoPlayer、WayLinePage、RobotTaskPage、XboxController 手柄 alerts/ 告警六件套：实时 / 历史 / 概览 / 统计 / 规则 / 订阅 SystemSetting/ 系统设置全部子页面 Map.jsx Cesium 三维地图封装 VideoPlayer / VideoCanvas / AgoraRtc / VolcRtcPlayer / useWebRTCStream 多策略视频播放组件 WebSocketManager.ts WebSocket 单例管理器（见 5.3） Weather/ 天气动效组件（晴/云/雨）
+
+
+4.4 状态管理 src/store
+
+
Redux Toolkit，仅两个切片，均持久化到 localStorage ，刷新自动恢复：
+
+ userSlice：token、userInfo、isAuthenticated；含 userLogin 异步 thunk（调登录 API → 存 token / cookie / userInfo）与 logout、setUserInfo 同步 action。stationSlice：currentStation、stationId；场站切换后所有页面据此过滤数据。
+
4.5 API 服务层 src/api
+request.ts 创建全局唯一 Axios 实例：baseURL 来自 env.js，超时 100s，withCredentials。请求拦截器注入 Authorization: Bearer <token>；响应拦截器对 401（业务码或 HTTP 状态）触发带全局锁的统一登出 （isLoggingOut 保证并发 401 只执行一次），清存储 → dispatch logout → 跳转 /login。
+业务 API 按域拆分：api.ts（设备任务/作业/热成像）、device.ts、aiAnalysis.ts、alarmApi.js、workOrder.ts、reportDownloader.ts、systemSetting.ts，以及 login / mune / organization / role / stationManage / user 子模块。
+
+
+
+5 实时通信层设计这是系统区别于普通 CRUD 后台的核心。四条通道各司其职、并行工作：
+
+
+ 通道 协议 方向 用途 前端实现
+ 业务接口 HTTP/REST 请求-响应 用户/设备/工单/报表等增删改查 Axios 实例 + 拦截器 设备遥测 MQTT over WS 发布-订阅（上行） 机器人实时位置、状态、传感器数据广播 useMqtt Hook（自动重连 3s）设备控制 WebSocket 双向 下发手柄/触控指令、获取控制权、保活 WebSocketManager 单例 + DeviceController视频回传 WebRTC 单向拉流 无人机/机器人摄像头实时画面 JSWebrtc.Player / Agora / Volcengine RTC
+
+
+
+
WebSocketManager 单例设计要点
+
+ 单例 ：全局唯一连接，按设备序列号 serialNumber 绑定，切换设备先关旧连新。AUTH 握手 ：连接 onopen 后立即发送 {type:'AUTH', token, userName, deviceId} 认证包。自动重连 ：非主动关闭时，onclose 后 5s 自动重连；切后台关连接、切前台自动恢复。观察者模式 ：onMessage / onStatusChange 注册回调，返回取消订阅函数。
+
+
DeviceController 控制类
+
封装设备控制全流程：申请控制权（getControlRight）→ 握手连接 → sendGamepad 经 lodash throttle(50ms) 节流下发手柄数据 → 通过回调上抛设备信息 / 控制状态 / WS 状态变化。手柄输入 50ms 一发，兼顾流畅与带宽。
+
+
+
+6 数据流设计6.1 认证与会话流
+
+
Login 页
→
+
userLogin thunk
→
+
/login API
→
+
存 token/cookie/userInfo
→
+
ProtectedRoute 放行
+
登录成功后 token 写入 localStorage 与 cookie（含跨域 sharetoken），Layout 据用户 ID 拉取菜单列表 （动态构建侧边栏）与场站列表 （默认选第一个）。后续所有请求由拦截器自动带 token；401 时统一登出回登录页。
+
+6.2 实时设备控制环（核心链路）
+
+
+ 实时设备控制与遥测数据流
+ 操作员
+ 手柄 / 触控指令
+ DeviceController
+ 设备控制类 · 50ms 节流
+ WebSocketManager
+ 单例 · AUTH 握手 · 自动重连
+ WS server :9002
+ 设备控制服务
+ 机器人 / 无人机
+ 执行动作 · 采集状态
+ MQTT
+ 遥测上行
+ → 监控页
+
+
图 2 · 控制指令下行（蓝色实线 WebSocket）与遥测上行（橙色虚线 MQTT）走两条独立通道
+
关键设计：控制下行用 WebSocket（低延迟、可靠、双向），状态上行用 MQTT（发布订阅、一对多广播） 。两条通道互不阻塞——即便视频/遥测流量大，也不会影响控制指令的实时性。手柄输入经 50ms 节流，避免高频刷爆带宽。
+
+6.3 实时监控遥测流
+
+
机器人设备
→
+
MQTT broker :8083
→
+
useMqtt 订阅
→
+
监控页/Cesium 地图
+
设备按 topic 发布状态（位置、电量、传感器等），前端 useMqtt 订阅后驱动 Cesium 地图更新设备图标位置与实时监控面板。
+
+6.4 视频回传流
+
+
机器人摄像头
→
+
WebRTC/流媒体服务
→
+
JSWebrtc.Player
→
+
<video> 元素
+
useWebRTCPlayer(deviceId, url) 以 deviceId+url 为唯一键创建独立 video 元素并拉流，组件卸载时统一销毁 player，防止内存泄漏。同时支持 Agora RTC 与火山引擎 RTC 两套备选方案。
+
+6.5 HTTP 业务数据流
+
+
页面/组件
→
+
api/*.ts
→
+
request.ts (拦截器)
→
+
API server :8081
+
所有 REST 请求经统一 Axios 实例：请求拦截器注入 Bearer token，响应拦截器解包 response.data 并统一处理 401 登出。
+
+
+
+7 目录结构机器人智慧服务系统/
+├── env.js # 环境配置（baseURL / WS_URL / mqtt_url / geoserver_url）
+├── vite.config.ts # 构建配置（别名 @、Cesium 插件、CSS 分割）
+├── index.html # 入口 HTML
+├── metadata.json # 项目元信息（真实名称：光伏电站智能监控与运维系统）
+└── src/
+ ├── api/ # API 服务层
+ │ ├── request.ts # Axios 实例 + 拦截器（401 统一登出）
+ │ ├── api.ts # 设备任务/作业/热成像等业务接口
+ │ ├── device.ts / aiAnalysis.ts / alarmApi.js / workOrder.ts ...
+ │ └── login/ mune/ organization/ role/ stationManage/ user/
+ ├── components/ # 组件层
+ │ ├── Layout.tsx / ProtectedRoute.tsx
+ │ ├── devices/ # 设备控制（DeviceController / DroneVideoPlayer / XboxController ...）
+ │ ├── alerts/ # 告警六件套
+ │ ├── SystemSetting/ # 系统设置子页面
+ │ ├── WebSocketManager.ts # WS 单例
+ │ ├── useWebRTCStream.tsx # WebRTC 拉流 Hook
+ │ ├── Map.jsx / VideoPlayer / AgoraRtc / VolcRtcPlayer
+ │ └── Weather/
+ ├── hooks/useMqtt.ts # MQTT 订阅 Hook
+ ├── pages/ # 17 个业务页面
+ ├── router/index.tsx # 全懒加载路由 + routeMeta 角色白名单
+ ├── store/ # Redux（userSlice / stationSlice / types）
+ ├── lib/TracePoint/ # 工具库（轨迹点）
+ ├── assets/ / types/ # 静态资源 / 类型定义
+ └── App / main 入口
+
+
+8 关键设计决策与特点
+
多协议并行，职责分离
+
控制（WS）、遥测（MQTT）、视频（WebRTC）、业务（HTTP）各走独立通道。这是物联网实时控制系统的成熟模式：避免单通道拥塞互相拖累，也便于后端按特性独立伸缩。
+
+
全路由懒加载 + RBAC 元数据声明
+
所有页面 lazy() 按需加载，首屏轻量；权限不写死在组件里，而是在 routeMeta 集中声明角色白名单，ProtectedRoute 统一校验，新增页面只改路由表即可获得权限控制。
+
+
状态最小化 + 本地持久化
+
Redux 仅保留 user / station 两个跨页全局状态，其余页面数据就地管理；两者都持久化到 localStorage，刷新即恢复，体验接近原生应用。
+
+
连接健壮性
+
WebSocket 单例 + AUTH 握手 + 5s 自动重连 + 页面可见性监听（切后台关、切前台重连）；MQTT 3s 自动重连；Axios 401 全局锁防并发重复登出。多重保障弱网/切屏场景下的连接稳定。
+
+
待优化项（建议）：
+
+ useMqtt.ts 中 MQTT 凭据硬编码在前端（username/password），建议改为后端动态下发 token。useWebRTCStream.tsx 中视频 token 硬编码，应从登录态/接口动态获取。vite.config.ts 的 manualChunks 分包策略被注释掉，Cesium 等大体积依赖建议启用分包以优化加载。Redux store 仅两个切片，部分跨组件共享的设备/告警实时数据可考虑纳入统一管理或用 SWR/缓存层。
+
+
+
+
+ 光伏电站智能监控与运维系统 · 架构设计文档 · 由 WorkBuddy 基于源码静态分析生成
+
+
+