# 任务GPS里程统计功能集成指南

## 功能概述

该功能实现了任务与GPS里程的自动关联，可以在任务详情页面直接展示该任务执行期间的GPS行驶里程统计。

## 核心特性

- ✅ 自动关联：GPS里程计算时自动关联正在执行的任务
- ✅ 实时查询：支持按任务ID快速查询关联的GPS里程数据
- ✅ 分段展示：显示任务期间每5分钟的GPS里程分段明细
- ✅ 统计汇总：自动计算任务总里程、分段数、GPS点数
- ✅ 可视化组件：提供开箱即用的Vue组件

## 快速开始

### 1. 执行数据库迁移

```bash
mysql -u root -p < sql/updates/add_task_id_to_segment_mileage.sql
```

### 2. 在任务详情页面集成组件

```vue
<template>
  <div>
    <!-- 任务基本信息 -->
    <el-card>
      <!-- ... 任务详情内容 ... -->
    </el-card>

    <!-- GPS里程统计组件 -->
    <task-mileage-detail :task-id="taskId" />
  </div>
</template>

<script>
import TaskMileageDetail from '@/components/TaskMileageDetail'

export default {
  components: {
    TaskMileageDetail
  },
  data() {
    return {
      taskId: 123 // 任务ID
    }
  }
}
</script>
```

### 3. API调用示例

```javascript
import { getTaskTotalMileage, getSegmentsByTaskId } from '@/api/system/gpsSegment'

// 查询任务总里程
getTaskTotalMileage(taskId).then(res => {
  console.log('任务总里程:', res.data, 'km')
})

// 查询任务GPS分段明细
getSegmentsByTaskId(taskId).then(res => {
  console.log('分段明细:', res.data)
})
```

## 组件属性

### TaskMileageDetail

| 属性 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| taskId | Number/String | 是 | 任务ID |

## API接口说明

### 1. 按任务ID查询GPS分段里程

**接口地址**: `GET /system/gpsSegment/task/{taskId}`

**权限**: `system:gpsSegment:query`

**返回示例**:
```json
{
  "code": 200,
  "data": [
    {
      "segmentId": 1,
      "vehicleId": 10,
      "vehicleNo": "粤A12345",
      "taskId": 100,
      "taskCode": "T20250115001",
      "segmentStartTime": "2025-01-15 10:00:00",
      "segmentEndTime": "2025-01-15 10:05:00",
      "segmentDistance": 2.5,
      "gpsPointCount": 5,
      "startLongitude": 113.264385,
      "startLatitude": 23.129112,
      "endLongitude": 113.280637,
      "endLatitude": 23.125178
    }
  ]
}
```

### 2. 查询任务总里程

**接口地址**: `GET /system/gpsSegment/task/{taskId}/total`

**权限**: `system:gpsSegment:query`

**返回示例**:
```json
{
  "code": 200,
  "data": 15.8
}
```

### 3. 按日期范围查询GPS分段里程

**接口地址**: `GET /system/gpsSegment/range`

**参数**:
- `vehicleId`: 车辆ID
- `startDate`: 开始日期 (格式: yyyy-MM-dd)
- `endDate`: 结束日期 (格式: yyyy-MM-dd)

## 数据流程

```mermaid
graph LR
    A[定时任务触发] --> B[计算GPS里程]
    B --> C[查询车辆正在执行的任务]
    C --> D{时间段是否重叠?}
    D -->|是| E[关联task_id和task_code]
    D -->|否| F[task_id为NULL]
    E --> G[保存分段里程记录]
    F --> G
    G --> H[前端查询展示]
```

## 统计逻辑

1. **时间重叠判断**：
   - GPS分段时间段：`[segmentStartTime, segmentEndTime]`
   - 任务执行时间段：`[actualStartTime, actualEndTime]`
   - 重叠条件：`segmentStartTime < taskEndTime && segmentEndTime > taskStartTime`

2. **优先级**：
   - 优先使用任务的实际开始/结束时间
   - 如果实际时间为空，则使用计划时间

3. **跨段里程**：
   - 自动计算相邻5分钟段之间的间隙距离
   - 避免里程统计遗漏

## 注意事项

1. **权限配置**：确保用户拥有 `system:gpsSegment:query` 权限
2. **数据准确性**：GPS里程计算后才会有关联数据
3. **实时性**：数据由定时任务更新，非实时数据
4. **历史数据**：已计算的历史GPS数据不会自动关联任务，需重新计算

## 扩展建议

1. **任务列表展示**：在任务列表中直接显示任务里程
2. **报表统计**：基于task_id进行任务里程分析
3. **异常检测**：对比预估里程与实际GPS里程，发现异常
4. **成本核算**：基于任务里程进行费用计算

## 性能优化

- ✅ 使用索引：`idx_task_id`, `idx_vehicle_task`
- ✅ 聚合查询：直接SUM计算总里程
- ✅ 分页加载：分段明细支持分页
- ✅ 缓存策略：可对任务总里程进行Redis缓存

## 技术栈

- **后端**: Spring Boot + MyBatis
- **前端**: Vue 2 + Element UI
- **数据库**: MySQL 5.7+