# 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 技术实现 ```typescript // 场景加载示例 public async load( map?: string, editable = false, detail?: Partial, isImport = false, ): Promise { 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 性能优化 ```typescript // 使用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 数据结构 ```typescript 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 标准场景结构 ```typescript export interface StandardScene { scale?: number; // 缩放比例 origin?: { x: number; y: number }; // 默认载入原点 robotGroups?: Array; // 机器人组信息 robots?: Array; // 机器人信息 points?: Array; // 标准点位信息 routes?: Array; // 标准线路信息 areas?: Array; // 标准区域信息 width?: number; // 场景宽度 height?: number; // 场景高度 ratio?: number; // 坐标缩放比例 } ``` #### 4.1.2 点位数据结构 ```typescript export interface StandardScenePoint { id: string; // 点位ID name: string; // 点位名称 desc?: string; // 描述 x: number; // X坐标 y: number; // Y坐标 type: number; // 点位类型 extensionType?: number; // 扩展类型 robots?: Array; // 绑定机器人ID集合 actions?: Array; // 绑定动作点ID集合 associatedStorageLocations?: string[]; // 库位名称 deviceId?: string; // 设备ID enabled?: 0 | 1; // 是否启用 } ``` ### 4.2 机器人数据模型 #### 4.2.1 机器人信息 ```typescript 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 实时机器人信息 ```typescript export interface RobotRealtimeInfo extends RobotInfo { x: number; // 实时X坐标 y: number; // 实时Y坐标 active?: boolean; // 是否运行 angle?: number; // 旋转角度 path?: Array; // 规划路径 isWaring?: boolean; // 是否告警 isFault?: boolean; // 是否故障 } ``` ### 4.3 地图数据模型 #### 4.3.1 地图元素 ```typescript export interface MapPen extends Pen { label?: string; // 展示名称 desc?: string; // 描述 point?: MapPointInfo; // 点位信息 route?: MapRouteInfo; // 线路信息 area?: MapAreaInfo; // 区域信息 robot?: MapRobotInfo; // 实时机器人信息 attrs?: Record; // 额外属性 activeAttrs?: Array; // 已激活的额外属性 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 开发环境启动 ```bash # 安装依赖 pnpm install # 启动开发服务器 pnpm start # 访问地址: http://localhost:8888/web-amr ``` #### 6.2.2 生产环境构建 ```bash # 构建生产版本 pnpm build # 构建输出目录: dist/ ``` #### 6.2.3 部署配置 ```nginx # 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 开发环境 ```bash # .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 生产环境 ```bash # .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 开发流程 1. 需求分析和设计 2. 接口设计和开发 3. 前端组件开发 4. 测试和调试 5. 部署和上线 #### 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. 依赖包版本清单 ```json { "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 **文档状态**: 已完成