# 任务管理GPS坐标功能说明

## 功能概述

为通用任务管理系统增加了GPS坐标记录和距离计算功能，用于记录车辆的路程信息。

## 新增字段

### 数据库表字段
在 `sys_task` 表中新增以下字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `departure_longitude` | DECIMAL(10,7) | 出发地经度 |
| `departure_latitude` | DECIMAL(10,7) | 出发地纬度 |
| `destination_longitude` | DECIMAL(10,7) | 目的地经度 |
| `destination_latitude` | DECIMAL(10,7) | 目的地纬度 |
| `estimated_distance` | DECIMAL(8,2) | 预计公里数 |

## 技术实现

### 1. 数据库层
- **表结构更新**：`sql/task_tables.sql` - 新表创建脚本
- **现有表更新**：`sql/add_gps_coordinates.sql` - 现有表字段添加脚本

### 2. 实体层
- **SysTask实体类**：添加GPS坐标相关字段和getter/setter方法
- **TaskCreateVO**：任务创建对象，支持GPS坐标输入
- **TaskUpdateVO**：任务更新对象，支持GPS坐标修改

### 3. 数据访问层
- **SysTaskMapper.xml**：更新MyBatis映射文件，支持GPS坐标字段的增删改查

### 4. 业务逻辑层
- **SysTaskServiceImpl**：在创建和更新任务时自动计算预计公里数
- **GpsDistanceUtils**：GPS坐标距离计算工具类

### 5. 工具类
- **GpsDistanceUtils**：提供以下功能
  - 使用Haversine公式计算两点间球面距离
  - GPS坐标有效性验证
  - 坐标格式化显示
  - 度分秒格式转换

## 距离计算算法

### Haversine公式
使用Haversine公式计算地球表面两点间的球面距离：

```
a = sin²(Δφ/2) + cos φ1 ⋅ cos φ2 ⋅ sin²(Δλ/2)
c = 2 ⋅ atan2( √a, √(1−a) )
d = R ⋅ c
```

其中：
- φ1, φ2：两点的纬度
- Δφ：纬度差
- Δλ：经度差
- R：地球半径（6371公里）

### 精度说明
- 经度纬度：保留7位小数，精度约1.1厘米
- 距离：保留2位小数，精度到米
- 适用于中短距离计算（< 1000公里）

## 功能特性

### 1. 自动距离计算
- 创建任务时：如果提供了完整的GPS坐标，自动计算预计公里数
- 更新任务时：如果修改了GPS坐标，重新计算预计公里数
- 坐标验证：自动验证GPS坐标的有效性

### 2. 数据验证
- 纬度范围：-90° 到 90°
- 经度范围：-180° 到 180°
- 无效坐标：距离设置为0

### 3. 容错处理
- 坐标不完整：距离设置为0
- 坐标无效：距离设置为0
- 计算异常：距离设置为0

## 使用示例

### 创建任务时设置GPS坐标
```json
{
  "taskType": "MAINTENANCE",
  "taskDescription": "车辆维修任务",
  "departureAddress": "北京市朝阳区",
  "destinationAddress": "北京市海淀区",
  "departureLongitude": 116.397128,
  "departureLatitude": 39.916527,
  "destinationLongitude": 116.298056,
  "destinationLatitude": 39.959444,
  "plannedStartTime": "2024-01-15 09:00:00",
  "plannedEndTime": "2024-01-15 17:00:00"
}
```

### 系统自动计算
系统会自动计算两点间距离并设置到 `estimatedDistance` 字段。

## 执行步骤

### 新部署
1. 使用 `sql/task_tables.sql` 创建新表

### 现有系统升级
1. 执行 `sql/add_gps_coordinates.sql` 添加字段
2. 重新部署应用程序

## 验证方法

### 数据库验证
```sql
-- 查看表结构
SHOW CREATE TABLE sys_task;

-- 查看新增字段
DESCRIBE sys_task;

-- 测试数据插入
INSERT INTO sys_task (
    task_code, task_type, task_status, creator_id, dept_id, create_by,
    departure_longitude, departure_latitude, destination_longitude, destination_latitude
) VALUES (
    'TEST001', 'MAINTENANCE', 'PENDING', 1, 1, 'admin',
    116.397128, 39.916527, 116.298056, 39.959444
);
```

### 功能验证
1. 创建任务时输入GPS坐标，检查是否自动计算距离
2. 更新任务的GPS坐标，检查是否重新计算距离
3. 输入无效坐标，检查距离是否为0
4. 不输入坐标，检查距离是否为0

## 相关文件清单

### 数据库文件
- `sql/task_tables.sql` - 新表创建脚本
- `sql/add_gps_coordinates.sql` - 现有表更新脚本

### Java文件
- `ruoyi-system/src/main/java/com/ruoyi/system/domain/SysTask.java` - 实体类
- `ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/TaskCreateVO.java` - 创建VO
- `ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/TaskUpdateVO.java` - 更新VO
- `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/SysTaskServiceImpl.java` - 服务实现
- `ruoyi-system/src/main/resources/mapper/system/SysTaskMapper.xml` - MyBatis映射
- `ruoyi-common/src/main/java/com/ruoyi/common/utils/GpsDistanceUtils.java` - 工具类

## 注意事项

1. **坐标系统**：使用WGS84坐标系（GPS标准坐标系）
2. **精度要求**：经度纬度建议保留6-7位小数
3. **距离范围**：适用于中短距离计算，长距离可能有误差
4. **性能考虑**：大量数据时可考虑添加空间索引
5. **数据完整性**：建议同时提供地址和坐标信息

## 扩展功能建议

1. **地图集成**：集成地图API进行坐标选择
2. **路径规划**：集成路径规划API计算实际行驶距离
3. **历史轨迹**：记录车辆实际行驶轨迹
4. **距离统计**：按时间段统计总行驶距离
5. **地理围栏**：设置任务执行的地理范围