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

功能概述

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

核心算法

1. 距离计算

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

2. 里程分摊算法

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

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

部署步骤

1. 执行数据库脚本

按顺序执行以下SQL文件：

# 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接口批量执行：

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

扩展说明

天地图接口集成

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

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

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

技术支持

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

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