Merge branch 'feature_gps'

wlzboy

2025-11-15 caf56217dc2bf898b63b0e1f31a7098202c32825

 sql/³µÁ¾Àï³Ìͳ¼ÆʹÓÃ˵Ã÷.md

@@ -0,0 +1,202 @@
# è½¦è¾†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`