# 巡更管理系统改造 - 设计文档

## 1. 架构概述
### 1.1 系统架构图
```mermaid
flowchart TD
    A[用户] --> B[Main.vue]
    B --> C[路由管理]
    C --> D[PathManagement.vue]
    C --> E[ScheduleManagement.vue]
    C --> F[PatrolLog.vue]
    D --> G[地图组件]
    D --> H[Pinia状态管理]
    E --> I[排班表单]
    G --> J[设备点击事件]
    H --> K[路径点数据]
    I --> L[班次选择]
    I --> M[人员选择]
    I --> N[线路选择]
    D --> O[后端API]
    E --> O
    F --> O
```

### 1.2 核心组件关系
| 组件名称 | 功能描述 | 依赖关系 |
|---------|---------|---------|
| PathManagement.vue | 巡更路径管理 | 地图组件、Pinia状态管理、后端API |
| ScheduleManagement.vue | 巡更排班管理 | 排班表单、后端API |
| Map.vue | 地图显示和交互 | 设备数据、Pinia状态管理 |
| useMapStore | 地图状态管理 | Pinia |

## 2. 核心组件设计

### 2.1 PathManagement.vue（路径管理组件）
#### 2.1.1 功能设计
- **路径列表展示**：显示所有巡更路径
- **路径点管理**：
  - 点击地图设备自动添加路径点
  - 按点击顺序自动生成序号
  - 显示路径点名称和序号
- **路径保存**：批量保存所有路径点

#### 2.1.2 状态管理
```javascript
// 核心状态
const mainTableData = ref([]) // 巡更路径列表
const subTableData = ref([]) // 当前选中路径的路径点列表
const selectedRow = ref(null) // 当前选中的路径
const loadingMain = ref(false) // 主表加载状态
const loadingSub = ref(false) // 子表加载状态
```

#### 2.1.3 核心方法
```javascript
// 地图点击事件处理
const handleMapClick = (deviceInfo) => {
  // 自动生成路径点
  const newPoint = {
    PointIndex: subTableData.value.length + 1,
    PointDeviceId: deviceInfo.DeviceId,
    PointDeviceName: deviceInfo.DeviceName,
    MapModuleID: deviceInfo.MapModuleID,
    deviceName: deviceInfo.DeviceName
  }
  subTableData.value.push(newPoint)
}

// 保存路径点
const savePathPoints = async () => {
  // 批量提交所有路径点
  for (const point of subTableData.value) {
    await saveSinglePoint(point)
  }
}
```

### 2.2 ScheduleManagement.vue（排班管理组件）
#### 2.2.1 功能设计
- **排班列表展示**：显示所有巡更排班
- **排班表单**：
  - 班次选择（多选）
  - 人员选择（最多3人）
  - 线路选择（单选）
- **批量保存**：一次保存多个班次的排班信息

#### 2.2.2 状态管理
```javascript
// 核心状态
const scheduleData = ref([]) // 排班列表数据
const loading = ref(false) // 加载状态
const showScheduleForm = ref(false) // 排班表单显示状态
const scheduleForm = ref({
  shiftIds: [], // 选中的班次ID列表
  userId1: '', // 巡更人员1
  userId2: '', // 巡更人员2
  userId3: '', // 巡更人员3
  patrolPathId: '' // 巡更线路ID
})
const shifts = ref([ // 12个班次定义
  { id: 1, name: '00:00-02:00' },
  { id: 2, name: '02:00-04:00' },
  // ... 其他班次
  { id: 12, name: '22:00-24:00' }
])
```

#### 2.2.3 核心方法
```javascript
// 提交排班表单
const submitSchedule = async () => {
  // 为每个选中的班次创建排班记录
  for (const shiftId of scheduleForm.value.shiftIds) {
    const schedule = {
      PatrolDay: getCurrentWeekDay(), // 当前星期几
      PatrolStartTime: getShiftStartTime(shiftId), // 班次开始时间
      PatrolEndTime: getShiftEndTime(shiftId), // 班次结束时间
      UserId1: scheduleForm.value.userId1,
      UserId2: scheduleForm.value.userId2,
      UserId3: scheduleForm.value.userId3,
      PatrolPathId: scheduleForm.value.patrolPathId
    }
    await saveSchedule(schedule)
  }
}
```

## 3. 数据流向设计

### 3.1 路径管理数据流程
```mermaid
sequenceDiagram
    participant User
    participant PathComp as PathManagement.vue
    participant MapComp as Map.vue
    participant Store as Pinia Store
    participant API as Backend API
    
    User->>PathComp: 选择巡更路径
    PathComp->>API: 获取路径点数据
    API-->>PathComp: 返回路径点列表
    PathComp->>PathComp: 显示路径点列表
    User->>MapComp: 点击地图设备
    MapComp->>PathComp: 触发设备点击事件
    PathComp->>PathComp: 自动生成路径点
    PathComp->>PathComp: 更新路径点列表
    User->>PathComp: 点击保存按钮
    PathComp->>API: 批量提交路径点
    API-->>PathComp: 返回保存结果
    PathComp->>User: 显示保存成功提示
```

### 3.2 排班管理数据流程
```mermaid
sequenceDiagram
    participant User
    participant ScheduleComp as ScheduleManagement.vue
    participant API as Backend API
    
    User->>ScheduleComp: 点击添加排班按钮
    ScheduleComp->>API: 获取班次、人员、线路数据
    API-->>ScheduleComp: 返回数据列表
    ScheduleComp->>User: 显示排班表单
    User->>ScheduleComp: 选择班次、人员、线路
    User->>ScheduleComp: 点击保存按钮
    ScheduleComp->>API: 批量提交排班记录
    API-->>ScheduleComp: 返回保存结果
    ScheduleComp->>ScheduleComp: 刷新排班列表
    ScheduleComp->>User: 显示保存成功提示
```

## 4. API交互设计

### 4.1 路径管理API
| API地址 | 方法 | 功能描述 |
|---------|------|---------|
| /api/warehouse_patrolpath/GetPageData | POST | 获取巡更路径列表 |
| /api/warehouse_patrolpathpoint/GetPageData | POST | 获取路径点列表 |
| /api/warehouse_patrolpathpoint/add | POST | 添加路径点 |
| /api/warehouse_patrolpathpoint/edit | POST | 编辑路径点 |
| /api/warehouse_patrolpathpoint/delete | POST | 删除路径点 |

### 4.2 排班管理API
| API地址 | 方法 | 功能描述 |
|---------|------|---------|
| /api/warehouse_patrolschedule/GetPageData | POST | 获取排班列表 |
| /api/warehouse_patrolschedule/add | POST | 添加排班记录 |
| /api/warehouse_patrolschedule/edit | POST | 编辑排班记录 |
| /api/warehouse_patrolschedule/delete | POST | 删除排班记录 |

### 4.3 辅助API
| API地址 | 方法 | 功能描述 |
|---------|------|---------|
| /api/Warehouse_Device/GetPageData | POST | 获取设备列表 |
| /api/Sys_User/GetPageData | POST | 获取用户列表 |

## 5. 状态管理设计

### 5.1 地图状态管理（useMapStore）
```javascript
// useMapStore核心结构
export const useMapStore = defineStore('map', () => {
  // 状态
  const map = ref(null) // 地图实例
  const devices = ref([]) // 设备列表
  const selectedDevices = ref([]) // 选中的设备列表
  const pathPoints = ref([]) // 当前编辑的路径点列表
  
  // 方法
  const setMap = (mapInstance) => {
    map.value = mapInstance
  }
  
  const addPathPoint = (deviceInfo) => {
    pathPoints.value.push({
      index: pathPoints.value.length + 1,
      ...deviceInfo
    })
  }
  
  const clearPathPoints = () => {
    pathPoints.value = []
  }
  
  return {
    map,
    devices,
    selectedDevices,
    pathPoints,
    setMap,
    addPathPoint,
    clearPathPoints
  }
})
```

## 6. 界面设计

### 6.1 路径管理界面
```
+--------------------------+
| 巡更路径列表              |
+--------------------------+
| 路径名称 | 备注 | 路径ID |
|----------|------|--------|
| 路线1    | 备注1 | 1     |
| 路线2    | 备注2 | 2     |
+--------------------------+

+--------------------------+
| 巡更路径点列表 - 路线1    |
+--------------------------+
| [保存路径]                |
+--------------------------+
| 序号 | 名称             |
|------|------------------|
| 1    | 设备1            |
| 2    | 设备2            |
+--------------------------+

+--------------------------+
| 地图显示区域             |
| （点击设备添加路径点）    |
+--------------------------+
```

### 6.2 排班管理界面
```
+--------------------------+
| 巡更排班管理              |
+--------------------------+
| [添加排班]                |
+--------------------------+
| 标题 | 星期 | 开始时间 | 结束时间 | 巡检员1 | 巡检员2 | 巡检员3 | 巡检路线 |
+------+------+----------+----------+---------+---------+---------+----------+
| 排班1 | 周一 | 00:00   | 02:00   | 张三    | 李四    | 王五    | 路线1    |
+------+------+----------+----------+---------+---------+---------+----------+

+--------------------------+
| 排班表单（弹窗）          |
+--------------------------+
| 班次选择：               |
| [ ] 00:00-02:00 [ ] 02:00-04:00 ... |
+--------------------------+
| 巡更人员：               |
| 巡检员1：[下拉选择]       |
| 巡检员2：[下拉选择]       |
| 巡检员3：[下拉选择]       |
+--------------------------+
| 巡更线路：               |
| [下拉选择]                |
+--------------------------+
| [取消] [保存]             |
+--------------------------+
```

## 7. 异常处理设计

### 7.1 API请求异常
```javascript
// 统一异常处理
const handleApiError = (error) => {
  if (error.response) {
    // 服务器返回错误状态码
    ElMessage.error(`请求失败: ${error.response.data.message || '未知错误'}`)
  } else if (error.request) {
    // 请求已发送但没有收到响应
    ElMessage.error('网络错误，请检查网络连接')
  } else {
    // 请求配置错误
    ElMessage.error(`请求配置错误: ${error.message}`)
  }
}
```

### 7.2 地图交互异常
```javascript
// 地图点击异常处理
const handleMapClickError = (error) => {
  ElMessage.error('地图点击失败，请重试')
  console.error('地图点击错误:', error)
}
```

## 8. 性能优化设计

### 8.1 数据加载优化
- **分页加载**：路径列表和排班列表使用分页加载
- **并行请求**：关联数据（如用户名称、线路名称）使用并行请求获取
- **缓存机制**：设备列表等静态数据使用缓存，减少API请求

### 8.2 交互优化
- **防抖处理**：地图点击事件使用防抖，避免重复触发
- **批量提交**：路径点和排班记录使用批量提交，减少API请求次数
- **异步加载**：非关键数据使用异步加载，提高页面响应速度

## 9. 测试要点

### 9.1 路径管理测试
- 路径列表显示是否正确
- 地图点击设备是否能自动添加路径点
- 路径点序号是否按点击顺序生成
- 路径点保存功能是否正常

### 9.2 排班管理测试
- 排班列表显示是否正确
- 排班表单是否能正常打开和关闭
- 班次选择功能是否正常
- 人员和线路选择功能是否正常
- 批量保存功能是否正常

### 9.3 边界情况测试
- 选择所有12个班次进行排班
- 添加大量路径点（如20个以上）
- 选择不同数量的巡检人员（1-3人）
- 网络异常情况下的表现

## 10. 部署和维护

### 10.1 部署方式
- 使用现有Vite构建工具进行打包
- 部署到现有服务器
- 无需额外配置

### 10.2 维护要点
- 定期检查API兼容性
- 监控地图点击事件的稳定性
- 关注排班功能的使用情况
- 根据用户反馈优化交互体验