SecMPS/warehouse/docs/巡更管理系统改造/DESIGN_巡更管理系统改造.md

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

1. 架构概述

1.1 系统架构图

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 状态管理

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

2.1.3 核心方法

// 地图点击事件处理
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 状态管理

// 核心状态
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 核心方法

// 提交排班表单
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 路径管理数据流程

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 排班管理数据流程

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）

// 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请求异常

// 统一异常处理
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 地图交互异常

// 地图点击异常处理
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兼容性
• 监控地图点击事件的稳定性
• 关注排班功能的使用情况
• 根据用户反馈优化交互体验