xudan/web-map

Fork 0

xudan 4146a64ebf feat: 添加AMR调度系统技术交付文档，详细描述项目概述、技术架构、功能模块及API接口设计

2025-08-28 15:47:58 +08:00

16 KiB

Raw Permalink Blame History

AMR调度系统技术交付文档

文档信息

项目名称: AMR调度系统 (arm_system)
版本: 1.0.0
技术栈: Vue 3 + TypeScript + Vite + Ant Design Vue + Meta2D
文档版本: v1.0

1. 项目概述

1.1 项目简介

AMR调度系统是一个基于Web的智能仓储解决方案，集成了场景编辑器、机器人监控、运动仿真等核心功能。系统采用现代化的前端技术架构，提供直观的可视化界面和强大的编辑功能。

1.2 核心特性

场景编辑器: 支持点位、路线、区域的创建和编辑
机器人监控: 实时监控AMR机器人状态和运动轨迹
运动仿真: 提供机器人运动路径的仿真和验证
库位管理: 智能管理仓储库位状态和分配
多主题支持: 支持明暗主题切换
国际化: 支持中英文双语界面

1.3 技术亮点

基于Meta2D引擎的2D图形渲染
WebSocket实时数据通信
响应式设计，支持多种设备
模块化架构，易于扩展和维护

2. 技术架构

2.1 技术栈详情

前端框架

Vue 3.5.13: 采用Composition API，提供响应式数据绑定
TypeScript 5.7.2: 强类型支持，提升代码质量和开发效率
Vite 6.3.1: 现代化构建工具，支持快速开发和热重载

UI组件库

Ant Design Vue 4.2.6: 企业级UI组件库
@ant-design/icons-vue 7.0.1: 图标组件库

图形引擎

@meta2d/core 1.0.78: 2D图形渲染引擎，支持复杂图形绘制

状态管理

RxJS 7.8.2: 响应式编程库，处理异步数据流
@vueuse/rxjs 13.1.0: Vue与RxJS的集成工具

样式处理

Sass: CSS预处理器，支持变量、嵌套、混合等特性
SCSS: Sass的SCSS语法

开发工具

ESLint 9.25.0: 代码质量检查
Prettier 3.5.3: 代码格式化
Stylelint 16.19.1: 样式代码检查

2.2 项目结构

web-amr/
├── src/                          # 源代码目录
│   ├── apis/                     # API接口定义
│   │   ├── map/                  # 地图相关API
│   │   ├── robot/                # 机器人相关API
│   │   └── scene/                # 场景相关API
│   ├── assets/                   # 静态资源
│   │   ├── fonts/                # 字体文件
│   │   ├── icons/                # 图标资源
│   │   ├── images/               # 图片资源
│   │   ├── locales/              # 国际化文件
│   │   └── themes/               # 主题配置
│   ├── components/               # 公共组件
│   ├── pages/                    # 页面组件
│   ├── services/                 # 核心服务
│   └── workers/                  # Web Worker
├── public/                       # 公共资源
├── docs/                         # 项目文档
├── mocks/                        # 模拟数据
└── dist/                         # 构建输出

2.3 核心服务架构

编辑器服务 (EditorService)

继承自Meta2D引擎
管理场景文件的加载、保存
处理点位、路线、区域的创建和编辑
管理机器人组和实时状态更新

WebSocket服务 (EnhancedWebSocket)

支持心跳检测和自动重连
处理实时数据通信
优化连接稳定性和性能

图层管理服务 (LayerManagerService)

管理不同图层的显示和隐藏
控制图层的层级顺序
提供图层操作接口

区域操作服务 (AreaOperationService)

处理区域的选择、编辑、删除等操作
管理区域与点位的关联关系

3. 功能模块详解

3.1 场景编辑器模块

3.1.1 核心功能

场景加载: 支持JSON格式场景文件的导入和加载
场景保存: 将编辑后的场景保存为JSON格式
场景推送: 将场景配置推送到后端系统

3.1.2 编辑功能

点位管理: 创建、编辑、删除各种类型的点位
路线绘制: 支持直线、贝塞尔曲线等路线类型
区域定义: 创建和管理仓储区域
机器人配置: 设置机器人组和机器人参数

3.1.3 技术实现

// 场景加载示例
public async load(
  map?: string,
  editable = false,
  detail?: Partial<GroupSceneDetail>,
  isImport = false,
): Promise<void> {
  const scene: StandardScene = map ? JSON.parse(map) : {};
  // 加载机器人组和机器人信息
  this.#loadRobots(scene.robotGroups, scene.robots);
  // 加载场景点位
  await this.#loadScenePoints(scene.points, isImport);
  // 加载场景路线
  this.#loadSceneRoutes(scene.routes, isImport);
  // 加载场景区域
  await this.#loadSceneAreas(scene.areas, isImport);
}

3.2 机器人监控模块

3.2.1 监控功能

实时位置: 显示机器人的实时坐标和角度
状态监控: 监控机器人的运行状态、电量、故障等
路径显示: 可视化机器人的运动路径
告警提示: 显示机器人的告警和故障信息

3.2.2 数据通信

WebSocket连接: 建立与后端的实时数据连接
心跳检测: 定期发送心跳包，确保连接稳定
自动重连: 连接断开时自动尝试重连

3.2.3 性能优化

// 使用requestAnimationFrame优化渲染性能
const batchUpdateRobots = (updates: Array<{ id: string; data: RobotRealtimeInfo }>) => {
  if (!editor.value || updates.length === 0) return;

  // 批量更新机器人数据，减少渲染调用次数
  updates.forEach(({ id, data }) => {
    const { x, y, active, angle, path: points, isWaring, isFault, ...rest } = data;
    editor.value?.updateRobot(id, rest);
  });
};

3.3 运动仿真模块

3.3.1 仿真功能

路径规划: 模拟机器人的运动路径
碰撞检测: 检测机器人运动过程中的潜在碰撞
时间估算: 计算机器人到达目标点的时间
场景验证: 验证场景配置的合理性

3.3.2 仿真算法

A*算法: 用于路径规划
贝塞尔曲线: 用于平滑路径生成
物理引擎: 模拟机器人的运动物理特性

3.4 库位管理模块

3.4.1 库位功能

库位状态: 管理库位的占用、锁定、禁用等状态
库位分配: 智能分配库位给机器人
库位监控: 实时监控库位的使用情况
库位统计: 提供库位使用率等统计信息

3.4.2 数据结构

export interface StorageLocationInfo {
  id: string; // 库位ID
  layer_index: number; // 层索引
  layer_name: string; // 层名称
  operate_point_id: string; // 操作点ID
  station_name: string; // 站点名称
  scene_id: string; // 场景ID
  storage_area_id: string; // 库区ID
  area_name: string; // 库区名称
  is_occupied: boolean; // 是否占用
  is_locked: boolean; // 是否锁定
  is_disabled: boolean; // 是否禁用
  goods_content: string; // 货物内容
  goods_weight: number | null; // 货物重量
  goods_volume: number | null; // 货物体积
}

4. 数据模型

4.1 场景数据模型

4.1.1 标准场景结构

export interface StandardScene {
  scale?: number; // 缩放比例
  origin?: { x: number; y: number }; // 默认载入原点
  robotGroups?: Array<RobotGroup>; // 机器人组信息
  robots?: Array<RobotInfo>; // 机器人信息
  points?: Array<StandardScenePoint>; // 标准点位信息
  routes?: Array<StandardSceneRoute>; // 标准线路信息
  areas?: Array<StandardSceneArea>; // 标准区域信息
  width?: number; // 场景宽度
  height?: number; // 场景高度
  ratio?: number; // 坐标缩放比例
}

4.1.2 点位数据结构

export interface StandardScenePoint {
  id: string; // 点位ID
  name: string; // 点位名称
  desc?: string; // 描述
  x: number; // X坐标
  y: number; // Y坐标
  type: number; // 点位类型
  extensionType?: number; // 扩展类型
  robots?: Array<string>; // 绑定机器人ID集合
  actions?: Array<string>; // 绑定动作点ID集合
  associatedStorageLocations?: string[]; // 库位名称
  deviceId?: string; // 设备ID
  enabled?: 0 | 1; // 是否启用
}

4.2 机器人数据模型

4.2.1 机器人信息

export interface RobotInfo {
  gid?: string; // 机器人组ID
  id: string; // 机器人ID
  label: string; // 机器人名称
  brand: RobotBrand; // 机器人品牌
  type: RobotType; // 机器人类型
  ip?: string; // 机器人IP地址
  battery?: number; // 机器人电量
  isConnected?: boolean; // 连接状态
  state?: RobotState; // 机器人状态
  canOrder?: boolean; // 接单状态
  canStop?: boolean; // 急停状态
  canControl?: boolean; // 控制状态
  targetPoint?: string; // 目标点位
  isLoading?: 0 | 1; // 载货状态
}

4.2.2 实时机器人信息

export interface RobotRealtimeInfo extends RobotInfo {
  x: number; // 实时X坐标
  y: number; // 实时Y坐标
  active?: boolean; // 是否运行
  angle?: number; // 旋转角度
  path?: Array<Point>; // 规划路径
  isWaring?: boolean; // 是否告警
  isFault?: boolean; // 是否故障
}

4.3 地图数据模型

4.3.1 地图元素

export interface MapPen extends Pen {
  label?: string; // 展示名称
  desc?: string; // 描述
  point?: MapPointInfo; // 点位信息
  route?: MapRouteInfo; // 线路信息
  area?: MapAreaInfo; // 区域信息
  robot?: MapRobotInfo; // 实时机器人信息
  attrs?: Record<string, unknown>; // 额外属性
  activeAttrs?: Array<string>; // 已激活的额外属性
  properties?: unknown; // 第三方附加参数
  statusStyle?: string; // 状态颜色
  strokeStyle?: string; // 边框颜色
}

5. API接口设计

5.1 场景管理API

5.1.1 场景操作

GET /api/scene/{id}: 获取场景详情
POST /api/scene/{id}: 保存场景配置
PUT /api/scene/{id}/push: 推送场景配置
GET /api/scene/group/{groupId}: 获取群组场景

5.1.2 场景监控

GET /ws/scene/{id}/monitor: 监控场景实时数据
GET /ws/scene/{id}/simulation: 仿真场景数据

5.2 机器人管理API

5.2.1 机器人信息

GET /api/robot/group/{groupId}: 获取机器人组信息
GET /api/robot/{id}: 获取机器人详情
POST /api/robot/register: 注册机器人
PUT /api/robot/{id}/seize: 占用机器人

5.2.2 机器人同步

POST /api/robot/sync/group/{groupId}: 同步机器人组数据
GET /ws/robot/{id}/status: 获取机器人实时状态

5.3 地图管理API

5.3.1 地图数据

GET /api/map/area/{id}: 获取区域信息
POST /api/map/area: 创建区域
PUT /api/map/area/{id}: 更新区域
DELETE /api/map/area/{id}: 删除区域

6. 部署说明

6.1 环境要求

6.1.1 开发环境

Node.js: >= 18.0.0
包管理器: pnpm >= 8.0.0
浏览器: Chrome >= 90, Firefox >= 88, Safari >= 14

6.1.2 生产环境

Web服务器: Nginx >= 1.18.0 或 Apache >= 2.4
HTTPS: 支持SSL证书（推荐）
CDN: 可选，用于静态资源加速

6.2 构建部署

6.2.1 开发环境启动

# 安装依赖
pnpm install

# 启动开发服务器
pnpm start

# 访问地址: http://localhost:8888/web-amr

6.2.2 生产环境构建

# 构建生产版本
pnpm build

# 构建输出目录: dist/

6.2.3 部署配置

# Nginx配置示例
server {
    listen 80;
    server_name your-domain.com;

    location /web-amr {
        alias /path/to/dist;
        try_files $uri $uri/ /web-amr/index.html;

        # 静态资源缓存
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }

    # API代理
    location /api/ {
        proxy_pass http://backend-server:8080/jeecg-boot/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket代理
    location /ws/ {
        proxy_pass http://backend-server:8080/jeecg-boot/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

6.3 环境变量配置

6.3.1 开发环境

# .env.development
VITE_API_BASE_URL=http://localhost:8080/jeecg-boot
VITE_WS_BASE_URL=ws://localhost:8080/jeecg-boot
VITE_APP_BASE_URL=/web-amr

6.3.2 生产环境

# .env.production
VITE_API_BASE_URL=https://your-domain.com/api
VITE_WS_BASE_URL=wss://your-domain.com/ws
VITE_APP_BASE_URL=/web-amr

7. 性能优化

7.1 前端优化

7.1.1 代码分割

使用Vite的动态导入实现路由级别的代码分割
组件级别的懒加载，减少初始包大小

7.1.2 渲染优化

使用requestAnimationFrame优化高频数据渲染
批量更新DOM，减少重绘和回流
虚拟滚动处理大量数据

7.1.3 缓存策略

静态资源长期缓存
API响应数据缓存
浏览器本地存储优化

7.2 网络优化

7.2.1 WebSocket优化

心跳检测机制，及时发现问题
自动重连策略，提高连接稳定性
数据压缩，减少传输量

7.2.2 HTTP优化

请求合并，减少网络请求次数
响应数据压缩
合理的缓存策略

8. 安全考虑

8.1 前端安全

8.1.1 输入验证

所有用户输入进行验证和过滤
防止XSS攻击
防止CSRF攻击

8.1.2 权限控制

基于角色的访问控制
前端路由权限验证
API接口权限校验

8.2 通信安全

8.2.1 HTTPS/WSS

生产环境强制使用HTTPS
WebSocket使用WSS协议
证书有效期监控

8.2.2 数据加密

敏感数据加密传输
本地存储数据加密
API密钥安全管理

9. 监控与日志

9.1 性能监控

9.1.1 前端监控

页面加载性能
接口响应时间
用户交互响应时间
错误率统计

9.1.2 业务监控

用户活跃度
功能使用率
系统可用性

9.2 日志管理

9.2.1 日志级别

ERROR: 错误信息
WARN: 警告信息
INFO: 一般信息
DEBUG: 调试信息

9.2.2 日志内容

时间戳
日志级别
模块名称
详细描述
错误堆栈（错误日志）

10. 维护与支持

10.1 日常维护

10.1.1 代码维护

定期代码审查
依赖包更新
代码重构优化
性能监控和调优

10.1.2 系统维护

日志清理
缓存清理
数据库优化
服务器资源监控

10.2 故障处理

10.2.1 常见问题

WebSocket连接断开
数据加载失败
页面渲染异常
性能问题

10.2.2 解决方案

自动重连机制
错误重试策略
降级处理方案
用户友好的错误提示

11. 扩展开发

11.1 新功能开发

11.1.1 开发流程

需求分析和设计
接口设计和开发
前端组件开发
测试和调试
部署和上线

11.1.2 技术规范

遵循现有代码风格
使用TypeScript强类型
编写单元测试
更新相关文档

11.2 第三方集成

11.2.1 地图服务

支持多种地图提供商
地图数据格式转换
坐标系统统一

11.2.2 设备集成

支持多种机器人品牌
标准化通信协议
设备状态监控

12. 项目总结

12.1 技术优势

12.1.1 架构优势

模块化设计，易于维护和扩展
响应式架构，支持高并发
现代化技术栈，开发效率高

12.1.2 功能优势

完整的仓储管理解决方案
直观的可视化界面
强大的编辑和仿真功能

12.2 应用价值

12.2.1 业务价值

提高仓储管理效率
降低人工成本
提升系统可靠性

12.2.2 技术价值

可复用的技术架构
标准化的开发流程
完善的文档体系

附录

A. 依赖包版本清单

{
  "dependencies": {
    "@ant-design/icons-vue": "^7.0.1",
    "@meta2d/core": "^1.0.78",
    "@vueuse/rxjs": "^13.1.0",
    "ant-design-vue": "^4.2.6",
    "axios": "^1.8.4",
    "dayjs": "^1.11.13",
    "lodash-es": "^4.17.21",
    "rxjs": "^7.8.2",
    "vue": "^3.5.13",
    "vue-i18n": "^11.1.3",
    "vue-router": "^4.5.0"
  }
}

B. 浏览器兼容性

Chrome >= 90
Firefox >= 88
Safari >= 14
Edge >= 90

文档版本: v1.0
最后更新: 2025年8月28日10:25:21
文档状态: 已完成

16 KiB Raw Permalink Blame History Unescape Escape

AMR调度系统技术交付文档

文档信息

1. 项目概述

1.1 项目简介

1.2 核心特性

1.3 技术亮点

2. 技术架构

2.1 技术栈详情

前端框架

UI组件库

图形引擎

状态管理

样式处理

开发工具

2.2 项目结构

2.3 核心服务架构

编辑器服务 (EditorService)

WebSocket服务 (EnhancedWebSocket)

图层管理服务 (LayerManagerService)

区域操作服务 (AreaOperationService)

3. 功能模块详解

3.1 场景编辑器模块

3.1.1 核心功能

3.1.2 编辑功能

3.1.3 技术实现

3.2 机器人监控模块

3.2.1 监控功能

3.2.2 数据通信

3.2.3 性能优化

3.3 运动仿真模块

3.3.1 仿真功能

3.3.2 仿真算法

3.4 库位管理模块

3.4.1 库位功能

3.4.2 数据结构

4. 数据模型

4.1 场景数据模型

4.1.1 标准场景结构

4.1.2 点位数据结构

4.2 机器人数据模型

4.2.1 机器人信息

4.2.2 实时机器人信息

4.3 地图数据模型

4.3.1 地图元素

5. API接口设计

5.1 场景管理API

5.1.1 场景操作

5.1.2 场景监控

5.2 机器人管理API

5.2.1 机器人信息

5.2.2 机器人同步

5.3 地图管理API

5.3.1 地图数据

6. 部署说明

6.1 环境要求

6.1.1 开发环境

6.1.2 生产环境

6.2 构建部署

6.2.1 开发环境启动

6.2.2 生产环境构建

6.2.3 部署配置

6.3 环境变量配置

6.3.1 开发环境

6.3.2 生产环境

7. 性能优化

7.1 前端优化

7.1.1 代码分割

7.1.2 渲染优化

7.1.3 缓存策略

7.2 网络优化

7.2.1 WebSocket优化

7.2.2 HTTP优化

8. 安全考虑

8.1 前端安全

8.1.1 输入验证

8.1.2 权限控制

8.2 通信安全

8.2.1 HTTPS/WSS

8.2.2 数据加密

16 KiB

Raw Permalink Blame History