# 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
- 维护状态: 积极维护中

---

**注意**: 本文档基于项目当前状态生成，随着项目发展会持续更新。如有疑问或建议，请联系开发团队。