diff --git a/docs/前端开发文档-交付.md b/docs/前端开发文档-交付.md new file mode 100644 index 0000000..31d554d --- /dev/null +++ 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, + 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 +**文档状态**: 已完成