525 lines
12 KiB
Markdown
525 lines
12 KiB
Markdown
# AMR机器人管理系统 - 详细说明文档
|
||
|
||
## 📋 项目概述
|
||
|
||
AMR(Autonomous Mobile Robot)机器人管理系统是一个基于Vue3 + TypeScript + Ant Design Vue开发的前端应用。该系统主要用于管理和监控AMR机器人，提供场景编辑、机器人组管理、路径规划和实时监控等功能。
|
||
|
||
### 🎯 核心功能
|
||
|
||
- **场景编辑器** - 可视化编辑机器人运行场景地图
|
||
- **机器人组管理** - 管理机器人分组和配置
|
||
- **路径规划** - 设计和管理机器人运行路径
|
||
- **实时监控** - 监控机器人运行状态和位置
|
||
- **点位管理** - 管理充电点、停靠点、动作点等特殊点位
|
||
- **区域管理** - 管理库区、互斥区等功能区域
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 前端技术栈
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[Vue 3.5.13] --> B[TypeScript]
|
||
A --> C[Ant Design Vue 4.2.6]
|
||
A --> D[Vue Router 4.5.0]
|
||
A --> E[Vue I18n 11.1.3]
|
||
A --> F[Vite 6.3.1]
|
||
|
||
B --> G[RxJS 7.8.2]
|
||
C --> H[@ant-design/icons-vue]
|
||
D --> I[动态路由]
|
||
E --> J[多语言支持]
|
||
F --> K[热重载开发]
|
||
|
||
L[Meta2d 1.0.78] --> M[2D图形引擎]
|
||
N[VueUse] --> O[组合式API工具]
|
||
P[Lodash-es] --> Q[工具函数库]
|
||
R[Axios] --> S[HTTP客户端]
|
||
T[Day.js] --> U[时间处理]
|
||
```
|
||
|
||
### 项目结构图
|
||
|
||
```
|
||
web-amr/
|
||
├── 📁 src/ # 源代码目录
|
||
│ ├── 📁 pages/ # 页面组件
|
||
│ │ ├── 🎨 scene-editor.vue # 场景编辑器页面
|
||
│ │ ├── 🎨 group-editor.vue # 机器人组编辑页面
|
||
│ │ ├── 📊 movement-supervision.vue # 运行监控页面
|
||
│ │ └── ❌ exception.vue # 异常页面
|
||
│ ├── 📁 components/ # 通用组件
|
||
│ │ ├── 📁 modal/ # 弹窗组件
|
||
│ │ ├── 📁 card/ # 卡片组件
|
||
│ │ ├── 🤖 robot-groups.vue # 机器人组组件
|
||
│ │ ├── 📍 pen-groups.vue # 点位组组件
|
||
│ │ └── 🛠️ editor-toolbar.vue # 编辑器工具栏
|
||
│ ├── 📁 apis/ # API接口层
|
||
│ │ ├── 📁 scene/ # 场景相关API
|
||
│ │ ├── 📁 robot/ # 机器人相关API
|
||
│ │ └── 📁 map/ # 地图相关API
|
||
│ ├── 📁 services/ # 核心服务层
|
||
│ │ ├── ⚙️ editor.service.ts # 编辑器服务（核心）
|
||
│ │ ├── 🎨 theme.service.ts # 主题服务
|
||
│ │ ├── 🌍 locale.service.ts # 国际化服务
|
||
│ │ ├── 🛤️ router.ts # 路由配置
|
||
│ │ ├── 🌐 http.ts # HTTP请求服务
|
||
│ │ └── 🔌 ws.ts # WebSocket服务
|
||
│ ├── 📁 assets/ # 静态资源
|
||
│ │ ├── 📁 themes/ # 主题文件
|
||
│ │ ├── 📁 images/ # 图片资源
|
||
│ │ ├── 📁 locales/ # 语言包
|
||
│ │ ├── 📁 icons/ # 图标资源
|
||
│ │ └── 📁 fonts/ # 字体文件
|
||
│ ├── 🎯 main.ts # 应用入口
|
||
│ ├── 📱 App.vue # 根组件
|
||
│ └── 🎨 style.scss # 全局样式
|
||
├── 📁 mocks/ # 模拟数据
|
||
├── 📁 public/ # 公共资源
|
||
├── ⚙️ vite.config.ts # Vite配置
|
||
├── 📦 package.json # 项目配置
|
||
└── 📝 README.md # 说明文档
|
||
```
|
||
|
||
## 🔧 核心模块详细说明
|
||
|
||
### 1. 场景编辑器模块 (Scene Editor)
|
||
|
||
**功能描述**: 提供可视化的2D场景编辑功能，允许用户创建和修改机器人运行环境。
|
||
|
||
**技术实现**:
|
||
|
||
- 基于 `Meta2d` 图形引擎构建可视化编辑器
|
||
- 使用 `EditorService` 服务类封装所有编辑功能
|
||
- 支持点、线、面的绘制和编辑
|
||
- 实时保存和加载场景配置
|
||
|
||
**核心组件**:
|
||
|
||
```vue
|
||
<!-- 场景编辑器主页面 -->
|
||
<template>
|
||
<a-layout class="full">
|
||
<!-- 顶部工具栏 -->
|
||
<a-layout-header> <编辑模式切换> <导入导出功能> <推送到服务器> </a-layout-header>
|
||
|
||
<!-- 主体布局 -->
|
||
<a-layout>
|
||
<!-- 左侧面板 -->
|
||
<a-layout-sider> <机器人组管理> <库区管理> <高级组管理> </a-layout-sider>
|
||
|
||
<!-- 中央编辑区 -->
|
||
<a-layout-content>
|
||
<div ref="container" class="editor-container"></div>
|
||
</a-layout-content>
|
||
</a-layout>
|
||
</a-layout>
|
||
|
||
<!-- 右侧属性面板 -->
|
||
<详细信息卡片>
|
||
</template>
|
||
```
|
||
|
||
### 2. 机器人管理模块 (Robot Management)
|
||
|
||
**功能描述**: 管理机器人设备，包括注册、分组、状态监控等功能。
|
||
|
||
**数据结构**:
|
||
|
||
```typescript
|
||
interface RobotInfo {
|
||
id: string; // 机器人ID
|
||
label: string; // 机器人名称
|
||
brand: string; // 品牌
|
||
type: RobotType; // 机器人类型
|
||
ip: string; // IP地址
|
||
isConnected?: boolean; // 连接状态
|
||
state?: number; // 运行状态
|
||
canOrder?: boolean; // 可否下达指令
|
||
canStop?: boolean; // 可否停止
|
||
canControl?: boolean; // 可否控制
|
||
}
|
||
|
||
interface RobotGroup {
|
||
sid: string; // 场景ID
|
||
id: string; // 组ID
|
||
label: string; // 组名称
|
||
robots: string[]; // 机器人ID列表
|
||
}
|
||
```
|
||
|
||
**核心功能实现**:
|
||
|
||
- **机器人注册**: 通过表单收集机器人基本信息
|
||
- **分组管理**: 支持创建、删除、重命名机器人组
|
||
- **状态监控**: 实时显示机器人连接和运行状态
|
||
- **批量操作**: 支持批量添加、移除机器人
|
||
|
||
### 3. 地图编辑系统 (Map Editor System)
|
||
|
||
**功能描述**: 基于Meta2d的强大地图编辑功能，支持多种地图元素的创建和编辑。
|
||
|
||
**地图元素类型**:
|
||
|
||
#### 📍 点位系统 (Point System)
|
||
|
||
```typescript
|
||
enum MapPointType {
|
||
普通点 = 0,
|
||
充电点 = 1,
|
||
停靠点 = 2,
|
||
动作点 = 3,
|
||
等待点 = 4,
|
||
禁行点 = 5,
|
||
}
|
||
```
|
||
|
||
#### 🛤️ 路径系统 (Route System)
|
||
|
||
```typescript
|
||
enum MapRouteType {
|
||
直线 = 'line',
|
||
二阶贝塞尔曲线 = 'bezier2',
|
||
三阶贝塞尔曲线 = 'bezier3',
|
||
}
|
||
```
|
||
|
||
#### 🏢 区域系统 (Area System)
|
||
|
||
```typescript
|
||
enum MapAreaType {
|
||
库区 = 1,
|
||
互斥区 = 2,
|
||
非互斥区 = 3,
|
||
}
|
||
```
|
||
|
||
### 4. 编辑器服务 (Editor Service)
|
||
|
||
**功能描述**: 系统核心服务类，继承自Meta2d，提供完整的编辑器功能。
|
||
|
||
**核心方法**:
|
||
|
||
```typescript
|
||
class EditorService extends Meta2d {
|
||
// 场景管理
|
||
async load(map?: string, editable?: boolean): Promise<void>;
|
||
save(): string;
|
||
|
||
// 机器人管理
|
||
addRobots(gid: string, robots: RobotInfo[]): void;
|
||
removeRobots(ids: string[]): void;
|
||
updateRobot(id: string, value: Partial<RobotInfo>): void;
|
||
|
||
// 点位管理
|
||
async addPoint(p: Point, type?: MapPointType, id?: string): Promise<void>;
|
||
updatePoint(id: string, info: Partial<MapPointInfo>): void;
|
||
changePointType(id: string, type: MapPointType): void;
|
||
|
||
// 路径管理
|
||
addRoute(p: [string, string], type?: MapRouteType, id?: string): void;
|
||
updateRoute(id: string, info: Partial<MapRouteInfo>): void;
|
||
|
||
// 区域管理
|
||
async addArea(p1: Point, p2: Point, type?: MapAreaType, id?: string): Promise<void>;
|
||
updateArea(id: string, info: Partial<MapAreaInfo>): void;
|
||
}
|
||
```
|
||
|
||
### 5. 实时监控模块 (Movement Supervision)
|
||
|
||
**功能描述**: 实时监控机器人运行状态，显示位置、路径、状态等信息。
|
||
|
||
**技术实现**:
|
||
|
||
- 使用WebSocket建立实时连接
|
||
- 基于RxJS处理实时数据流
|
||
- Canvas渲染机器人实时位置和路径
|
||
|
||
**数据流程**:
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as 客户端
|
||
participant W as WebSocket服务
|
||
participant S as 后端服务
|
||
participant R as 机器人设备
|
||
|
||
C->>W: 建立WebSocket连接
|
||
W->>S: 订阅机器人状态
|
||
R->>S: 上报状态数据
|
||
S->>W: 推送实时数据
|
||
W->>C: 广播状态更新
|
||
C->>C: 更新界面显示
|
||
```
|
||
|
||
## 🎨 UI/UX设计特色
|
||
|
||
### 主题系统
|
||
|
||
- **双主题支持**: 明亮主题和暗黑主题
|
||
- **动态切换**: 实时主题切换无需刷新
|
||
- **一致性设计**: 基于Ant Design设计语言
|
||
|
||
### 响应式布局
|
||
|
||
```scss
|
||
// 布局适配
|
||
.full {
|
||
width: 100%;
|
||
height: 100vh;
|
||
}
|
||
|
||
.editor-container {
|
||
background-color: transparent !important;
|
||
}
|
||
|
||
// 悬浮工具栏
|
||
.toolbar-container {
|
||
position: fixed;
|
||
bottom: 40px;
|
||
left: 50%;
|
||
transform: translateX(-50%);
|
||
}
|
||
```
|
||
|
||
### 交互体验
|
||
|
||
- **拖拽编辑**: 支持元素拖拽创建和编辑
|
||
- **快捷键**: 常用操作快捷键支持
|
||
- **上下文菜单**: 右键菜单功能
|
||
- **实时预览**: 编辑结果实时反馈
|
||
|
||
## 🔗 API接口设计
|
||
|
||
### RESTful API结构
|
||
|
||
#### 场景管理API
|
||
|
||
```typescript
|
||
// 获取场景详情
|
||
POST /scene/getById
|
||
Request: { id: string }
|
||
Response: SceneDetail
|
||
|
||
// 保存场景
|
||
POST /scene/saveById
|
||
Request: { id: string; json: string; png?: string }
|
||
|
||
// 推送场景到数据库
|
||
POST /scene/pushById
|
||
Request: { id: string }
|
||
|
||
// 获取组场景
|
||
POST /scene/getByGroupId
|
||
Request: { id: string; sid: string }
|
||
Response: GroupSceneDetail
|
||
```
|
||
|
||
#### 机器人管理API
|
||
|
||
```typescript
|
||
// 获取所有机器人
|
||
POST / robot / getAll;
|
||
Response: Array<RobotInfo>;
|
||
|
||
// 注册机器人
|
||
POST / robot / register;
|
||
Request: RobotDetail;
|
||
Response: RobotInfo;
|
||
```
|
||
|
||
#### WebSocket实时通信
|
||
|
||
```typescript
|
||
// 场景监控WebSocket
|
||
WebSocket /scene/monitor/:id
|
||
|
||
// 实时数据格式
|
||
interface RobotRealtimeInfo {
|
||
id: string;
|
||
x: number; // X坐标
|
||
y: number; // Y坐标
|
||
angle: number; // 角度
|
||
active: boolean; // 是否激活
|
||
path: [number, number][]; // 路径轨迹
|
||
}
|
||
```
|
||
|
||
## 🚀 开发和部署
|
||
|
||
### 开发环境启动
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
# 或
|
||
pnpm install
|
||
|
||
# 启动开发服务器
|
||
npm run start
|
||
# 访问 http://localhost:8888
|
||
```
|
||
|
||
### 构建和部署
|
||
|
||
```bash
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 预览构建结果
|
||
npm run preview
|
||
```
|
||
|
||
### 项目配置
|
||
|
||
#### Vite配置特色
|
||
|
||
```typescript
|
||
export default defineConfig({
|
||
plugins: [
|
||
vue(),
|
||
Components({
|
||
dts: true,
|
||
resolvers: [
|
||
AntDesignVueResolver({
|
||
importStyle: false,
|
||
resolveIcons: true,
|
||
}),
|
||
],
|
||
}),
|
||
],
|
||
|
||
// 路径别名
|
||
resolve: {
|
||
alias: {
|
||
'@': resolve(__dirname, 'src/pages/'),
|
||
'@api': resolve(__dirname, 'src/apis/'),
|
||
'@common': resolve(__dirname, 'src/components/'),
|
||
'@core': resolve(__dirname, 'src/services/'),
|
||
},
|
||
},
|
||
|
||
// 开发服务器
|
||
server: {
|
||
port: 8888,
|
||
host: true,
|
||
proxy: {
|
||
// API代理配置
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
## 🔧 核心服务详解
|
||
|
||
### 1. 主题服务 (Theme Service)
|
||
|
||
- 支持明暗主题切换
|
||
- 动态CSS变量管理
|
||
- 主题配置持久化存储
|
||
|
||
### 2. 国际化服务 (Locale Service)
|
||
|
||
- 多语言支持框架
|
||
- 动态语言切换
|
||
- 语言包懒加载
|
||
|
||
### 3. HTTP服务 (HTTP Service)
|
||
|
||
- 基于Axios的请求封装
|
||
- 请求/响应拦截器
|
||
- 错误统一处理
|
||
|
||
### 4. WebSocket服务 (WS Service)
|
||
|
||
- 实时通信连接管理
|
||
- 自动重连机制
|
||
- 消息队列处理
|
||
|
||
## 📈 性能优化策略
|
||
|
||
### 代码分割
|
||
|
||
- 路由级别懒加载
|
||
- 组件按需导入
|
||
- 第三方库代码分割
|
||
|
||
### 构建优化
|
||
|
||
```typescript
|
||
build: {
|
||
target: 'es2020',
|
||
outDir: 'dist',
|
||
sourcemap: false,
|
||
minify: 'esbuild',
|
||
chunkSizeWarningLimit: 2000
|
||
}
|
||
```
|
||
|
||
### 运行时优化
|
||
|
||
- 虚拟滚动大列表
|
||
- 图片懒加载
|
||
- 防抖节流处理
|
||
- 内存泄漏防护
|
||
|
||
## 🛡️ 代码质量保障
|
||
|
||
### 类型安全
|
||
|
||
- 完整的TypeScript类型定义
|
||
- 严格的类型检查配置
|
||
- 接口类型统一管理
|
||
|
||
### 代码规范
|
||
|
||
```json
|
||
{
|
||
"eslint": "代码质量检查",
|
||
"prettier": "代码格式化",
|
||
"stylelint": "样式规范检查",
|
||
"husky": "Git钩子管理"
|
||
}
|
||
```
|
||
|
||
### 测试策略
|
||
|
||
- 组件单元测试
|
||
- API接口测试
|
||
- E2E端到端测试
|
||
|
||
## 🔮 未来发展规划
|
||
|
||
### 功能扩展
|
||
|
||
- [ ] 3D场景编辑支持
|
||
- [ ] AI路径优化算法
|
||
- [ ] 多机器人协作调度
|
||
- [ ] 实时视频监控集成
|
||
|
||
### 技术升级
|
||
|
||
- [ ] Vue 3.6+ 新特性应用
|
||
- [ ] WebGL图形渲染优化
|
||
- [ ] PWA渐进式Web应用
|
||
- [ ] 微前端架构迁移
|
||
|
||
## 📞 技术支持
|
||
|
||
### 开发团队联系方式
|
||
|
||
- 技术负责人: [联系信息]
|
||
- 项目经理: [联系信息]
|
||
- 运维支持: [联系信息]
|
||
|
||
### 文档更新
|
||
|
||
- 最后更新时间: 2024年12月
|
||
- 文档版本: v1.0.0
|
||
- 维护状态: 积极维护中
|
||
|
||
---
|
||
|
||
**注意**: 本文档基于项目当前状态生成，随着项目发展会持续更新。如有疑问或建议，请联系开发团队。
|