# 车辆GPS里程统计功能使用说明

## 功能概述

本功能实现了车辆GPS行驶里程的自动统计，包括：
1. **总里程统计**：基于GPS点计算车辆每日总行驶里程
2. **任务时段里程**：计算车辆在执行任务期间的行驶里程
3. **非任务时段里程**：计算车辆非执行任务期间的行驶里程
4. **任务里程占比**：计算任务里程占总里程的比例

## 核心算法

### 1. 距离计算
使用 **Haversine公式** 计算相邻GPS点之间的实际距离（考虑地球曲率）

### 2. 里程分摊算法
根据GPS记录的时间区间与任务时间区间的**重叠比例**，将每段距离分摊到任务里程和非任务里程：

```
时间重叠比例 = 重叠时长 / 总时长
任务里程 = 段距离 × 时间重叠比例
非任务里程 = 段距离 × (1 - 时间重叠比例)
```

## 部署步骤

### 1. 执行数据库脚本

按顺序执行以下SQL文件：

```bash
# 1. 创建统计表
sql/vehicle_mileage_stats.sql

# 2. 添加定时任务
sql/vehicle_mileage_stats_job.sql

# 3. 添加菜单权限
sql/vehicle_mileage_stats_menu.sql
```

### 2. 代码已自动部署

以下代码文件已创建：

**实体类：**
- `VehicleMileageStats.java` - 里程统计实体
- `TaskTimeInterval.java` - 任务时间区间

**数据访问层：**
- `VehicleMileageStatsMapper.java` - 里程统计Mapper接口
- `VehicleMileageStatsMapper.xml` - MyBatis映射文件
- `VehicleGpsMapper.java` - 扩展GPS查询方法

**业务层：**
- `IVehicleMileageStatsService.java` - Service接口
- `VehicleMileageStatsServiceImpl.java` - Service实现（核心算法）

**控制层：**
- `VehicleMileageStatsController.java` - REST API接口

**定时任务：**
- `VehicleMileageStatsTask.java` - 定时统计任务

### 3. 启动定时任务

系统会自动添加定时任务，默认配置：
- **执行时间**：每天凌晨 1:30
- **统计范围**：前一天的所有车辆GPS数据
- **Cron表达式**：`0 30 1 * * ?`

在系统管理 -> 定时任务中可以查看和管理该任务。

## 使用方式

### 1. 自动统计（推荐）

定时任务每天凌晨自动执行，无需人工干预。

### 2. 手动触发统计

#### 2.1 单车辆统计

调用接口：
```
POST /system/mileageStats/calculate
参数：
  - vehicleId: 车辆ID
  - statDate: 统计日期（格式：yyyy-MM-dd）
```

#### 2.2 批量统计

调用接口：
```
POST /system/mileageStats/batchCalculate
参数：
  - statDate: 统计日期（格式：yyyy-MM-dd）
```

#### 2.3 通过定时任务补算历史数据

在定时任务管理中，执行：
```
vehicleMileageStatsTask.calculateMileageByDate('2025-11-09')
```

### 3. 查询统计结果

```
GET /system/mileageStats/list
参数（可选）：
  - vehicleId: 车辆ID
  - vehicleNo: 车牌号
  - statDate: 统计日期
  - beginStatDate: 开始日期
  - endStatDate: 结束日期
```

### 4. 导出统计数据

```
POST /system/mileageStats/export
参数：同查询接口
```

## 数据表结构

### tb_vehicle_mileage_stats（里程统计表）

| 字段 | 类型 | 说明 |
|------|------|------|
| stats_id | bigint | 统计ID（主键） |
| vehicle_id | bigint | 车辆ID |
| vehicle_no | varchar(20) | 车牌号 |
| stat_date | date | 统计日期 |
| total_mileage | decimal(10,2) | 总里程（公里） |
| task_mileage | decimal(10,2) | 任务时段里程（公里） |
| non_task_mileage | decimal(10,2) | 非任务时段里程（公里） |
| task_ratio | decimal(5,4) | 任务里程占比（0-1） |
| gps_point_count | int | GPS点数量 |
| task_count | int | 任务数量 |

### tb_vehicle_mileage_detail（里程明细表）

用于调试和追溯，记录每段GPS轨迹的里程分摊明细。

## 注意事项

### 1. GPS数据质量

- GPS采集间隔建议在 30-60秒
- 过短：计算量大，性能影响
- 过长：里程精度降低

### 2. 任务时间定义

任务时段 = 从任务创建时间（`create_time`）到任务完成时间（`actual_end_time`）

确保任务表中这两个字段准确记录。

### 3. 性能优化

- 统计数据按日期汇总，避免实时计算
- 建议保留3-6个月的统计数据，定期归档历史数据
- GPS原始数据建议保留7-30天（由清理任务控制）

### 4. 数据补算

如需补算历史数据，可以通过定时任务或API接口批量执行：

```java
// 补算最近7天的数据示例
for (int i = 1; i <= 7; i++) {
    String date = "2025-11-" + String.format("%02d", i);
    vehicleMileageStatsTask.calculateMileageByDate(date);
}
```

## 扩展说明

### 天地图接口集成

虽然核心算法使用Haversine公式计算距离，但系统已集成天地图接口，可用于：

1. **地址解析**：将GPS坐标转换为地址信息
2. **路径规划**：计算实际道路距离（比直线距离更准确）
3. **POI查询**：查询沿途兴趣点

如需使用天地图API进行路径距离计算，可参考 `VehicleGpsController` 中的天地图接口。

## 技术支持

如有问题，请检查：
1. 数据库表是否正确创建
2. 定时任务是否正常启动
3. GPS数据是否正常采集
4. 任务表的时间字段是否准确

日志位置：
- Service层日志：搜索 `VehicleMileageStatsServiceImpl`
- 定时任务日志：搜索 `VehicleMileageStatsTask`