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

2025-08-28 15:47:58 +08:00 · 2025-08-28 15:47:58 +08:00 · 4146a64ebf
commit 4146a64ebf
parent b12a299194
1 changed files with 719 additions and 0 deletions
--- a/docs/前端开发文档-交付.md
+++ b/docs/前端开发文档-交付.md
@ -0,0 +1,719 @@
+# 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<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 性能优化
+
+```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<RobotGroup>; // 机器人组信息
+  robots?: Array<RobotInfo>; // 机器人信息
+  points?: Array<StandardScenePoint>; // 标准点位信息
+  routes?: Array<StandardSceneRoute>; // 标准线路信息
+  areas?: Array<StandardSceneArea>; // 标准区域信息
+  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<string>; // 绑定机器人ID集合
+  actions?: Array<string>; // 绑定动作点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<Point>; // 规划路径
+  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<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 开发环境启动
+
+```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  
+**文档状态**: 已完成