# 车辆异常运行监控告警功能 - 快速部署指南

## 功能概述
监控车辆无任务运行超过配置公里数（默认10公里）时自动产生告警，并通过小程序/企业微信通知相关负责人。

## 快速部署（5步完成）

### 第1步：执行数据库脚本
```bash
cd /path/to/RuoYi-Vue-master
mysql -u用户名 -p密码 数据库名 < sql/vehicle_abnormal_alert.sql
```

**脚本内容包括**：
- ✅ 创建告警记录表 (tb_vehicle_abnormal_alert)
- ✅ 创建告警配置表 (tb_vehicle_alert_config)  
- ✅ 插入系统配置参数 (6个配置项)
- ✅ 创建定时任务 (vehicle Abnormal Alert Task)
- ✅ 创建菜单权限 (车辆异常告警管理)

### 第2步：配置通知用户
在"系统管理 > 参数设置"中配置以下参数：

| 参数名称 | 参数键名 | 配置值示例 | 说明 |
|---------|---------|-----------|------|
| 车辆异常告警通知用户 | vehicle.alert.notify.users | 1,2,3 | 接收通知的用户ID，逗号分隔 |

> 💡 **提示**：如果不配置，将尝试根据车辆归属部门查找负责人

### 第3步：启用定时任务
1. 登录后台管理系统
2. 进入"系统监控 > 定时任务"
3. 找到"车辆异常运行监控任务"
4. 点击状态开关，将其设置为"运行中"

### 第4步：配置企业微信（可选）
如需使用企业微信通知功能，在"系统管理 > 参数设置"中确保以下配置：

| 参数键名 | 说明 | 示例值 |
|---------|------|--------|
| qy_wechat.enable | 企业微信启用开关 | true |
| qy_wechat.corp_id | 企业ID | ww123456789 |
| qy_wechat.corp_secret | 应用Secret | xxxxx |
| qy_wechat.agent_id | 应用ID | 1000002 |

### 第5步：验证功能
1. 确保GPS分段里程计算任务正常运行
2. 查看"车辆管理 > 车辆异常告警"菜单是否显示
3. 观察定时任务执行日志
4. 测试告警生成和通知发送

## 核心配置参数说明

### 必需配置
| 配置键 | 默认值 | 说明 |
|-------|--------|------|
| vehicle.alert.enabled | true | 功能总开关，false则停用 |
| vehicle.alert.mileage.threshold | 10 | 告警阈值（公里） |

### 可选配置
| 配置键 | 默认值 | 说明 |
|-------|--------|------|
| vehicle.alert.daily.limit | 5 | 每车每天最多告警次数 |
| vehicle.alert.interval.minutes | 5 | 两次告警最小间隔（分钟） |
| vehicle.alert.time.window | 10 | 监控时间窗口（分钟） |
| vehicle.alert.notify.users | （空） | 通知用户ID列表 |

## 定时任务说明

### 任务配置
- **任务名称**：车辆异常运行监控任务  
- **执行频率**：`0 */5 * * * ?` (每5分钟执行一次)
- **调用方法**：`vehicleAbnormalAlertTask.monitorVehicleAbnormalRunning()`
- **并发控制**：禁止并发
- **默认状态**：暂停（需手动启用）

### 监控逻辑
```
每5分钟执行一次
  ↓
查询所有车辆
  ↓
逐车检查（并行处理）
  ├─ 检查是否有正在执行的任务
  ├─ 计算最近10分钟运行里程
  ├─ 判断是否超过阈值
  ├─ 检查告警频率限制
  └─ 创建告警并发送通知
```

## 权限配置

### 菜单权限
- **父菜单**：车辆管理
- **菜单名称**：车辆异常告警
- **权限标识**：system:vehicleAlert:list

### 按钮权限
- `system:vehicleAlert:query` - 查询告警
- `system:vehicleAlert:detail` - 告警详情
- `system:vehicleAlert:handle` - 处理告警
- `system:vehicleAlert:export` - 导出数据
- `system:vehicleAlert:config` - 配置管理

## 常见问题

### Q1: 告警不生成？
**排查步骤**：
1. 检查定时任务是否启用
2. 查看定时任务执行日志：`系统监控 > 调度日志`
3. 确认 `vehicle.alert.enabled = true`
4. 确认GPS分段里程表有数据
5. 检查车辆是否真的无任务运行

### Q2: 通知不发送？
**排查步骤**：
1. 检查企业微信配置是否正确
2. 确认 `qy_wechat.enable = true`
3. 查看后台日志：搜索"发送告警通知"
4. 确认用户已绑定企业微信ID

### Q3: 告警太频繁？
**解决方案**：
1. 调高公里数阈值：`vehicle.alert.mileage.threshold = 20`
2. 减少每日告警次数：`vehicle.alert.daily.limit = 3`
3. 增加告警间隔：`vehicle.alert.interval.minutes = 10`

### Q4: GPS里程数据不准？
**检查项**：
1. 确认GPS分段里程计算任务正常运行
2. 查看 `tb_vehicle_gps_segment_mileage` 表数据
3. 调整监控时间窗口：`vehicle.alert.time.window = 15`

## 测试指南

### 测试步骤
1. **准备测试数据**
   - 确保有车辆GPS数据
   - 确保GPS分段里程计算任务已运行
   - 选择一辆无任务的车辆

2. **调整配置便于触发**
   ```sql
   UPDATE sys_config SET config_value = '1' 
   WHERE config_key = 'vehicle.alert.mileage.threshold';
   ```

3. **手动触发定时任务**
   - 进入"系统监控 > 定时任务"
   - 找到"车辆异常运行监控任务"
   - 点击"执行一次"按钮

4. **查看执行结果**
   - 查看"系统监控 > 调度日志"
   - 查看"车辆管理 > 车辆异常告警"列表
   - 检查是否收到企业微信通知

5. **恢复配置**
   ```sql
   UPDATE sys_config SET config_value = '10' 
   WHERE config_key = 'vehicle.alert.mileage.threshold';
   ```

## 性能优化建议

### 数据库索引（已自动创建）
```sql
-- 告警记录表索引
CREATE INDEX idx_vehicle_id ON tb_vehicle_abnormal_alert(vehicle_id);
CREATE INDEX idx_alert_date ON tb_vehicle_abnormal_alert(alert_date);
CREATE INDEX idx_vehicle_date ON tb_vehicle_abnormal_alert(vehicle_id, alert_date);
CREATE INDEX idx_status ON tb_vehicle_abnormal_alert(status);
```

### 监控建议
- **车辆数 < 100**：使用默认配置
- **车辆数 100-500**：考虑增加时间窗口为15分钟
- **车辆数 > 500**：考虑增加执行间隔为10分钟

### 日志级别
在生产环境，建议设置日志级别为 INFO：
```yaml
logging:
  level:
    com.ruoyi.quartz.task.VehicleAbnormalAlertTask: INFO
```

## 故障排查

### 日志位置
- **应用日志**：`logs/sys-info.log`
- **定时任务日志**：数据库表 `sys_job_log`

### 关键日志搜索
```bash
# 监控任务执行日志
grep "车辆异常运行监控" logs/sys-info.log

# 告警生成日志
grep "产生异常告警" logs/sys-info.log

# 通知发送日志
grep "发送告警通知" logs/sys-info.log
```

### 数据库检查
```sql
-- 查看今日告警统计
SELECT status, COUNT(*) as count 
FROM tb_vehicle_abnormal_alert 
WHERE DATE(alert_date) = CURDATE()
GROUP BY status;

-- 查看告警频繁的车辆
SELECT vehicle_no, COUNT(*) as alert_count
FROM tb_vehicle_abnormal_alert
WHERE DATE(alert_date) = CURDATE()
GROUP BY vehicle_no
ORDER BY alert_count DESC
LIMIT 10;

-- 查看定时任务执行情况
SELECT job_name, status, job_message, create_time
FROM sys_job_log
WHERE job_name = '车辆异常运行监控任务'
ORDER BY create_time DESC
LIMIT 10;
```

## 技术支持

如遇到问题：
1. 查看本文档的"常见问题"部分
2. 检查系统日志和定时任务日志
3. 查询数据库表确认数据状态
4. 联系技术支持团队

## 文件清单

| 文件类型 | 文件路径 | 说明 |
|---------|---------|------|
| SQL脚本 | sql/vehicle_abnormal_alert.sql | 数据库初始化脚本 |
| 实体类 | ruoyi-system/.../domain/VehicleAbnormalAlert.java | 告警实体 |
| Mapper | ruoyi-system/.../mapper/VehicleAbnormalAlertMapper.java | 数据访问 |
| Service | ruoyi-system/.../service/impl/VehicleAbnormalAlertServiceImpl.java | 业务逻辑 |
| Controller | ruoyi-admin/.../controller/system/VehicleAbnormalAlertController.java | 接口控制器 |
| 定时任务 | ruoyi-quartz/.../task/VehicleAbnormalAlertTask.java | 监控任务 |
| 配置文档 | doc/车辆异常运行监控告警功能说明.md | 完整文档 |
| 部署指南 | 本文档 | 快速部署 |

---

**部署完成后**，请确认：
- [  ] 数据库表创建成功
- [  ] 菜单显示正常
- [  ] 定时任务已启用
- [  ] 配置参数已设置
- [  ] 测试告警生成成功
- [  ] 通知发送正常

**版本**: V1.0.0  
**更新日期**: 2026-01-12