# 车辆异常运行监控告警功能实现说明

## 功能概述

实现车辆无任务运行超公里数告警功能，当监控到车辆在无绑定任务状态下运行超过配置的公里数（默认10公里）时，自动产生告警并通过小程序发送通知给相关负责人。

## 功能特性

### 1. 智能监控
- **时间窗口监控**：每5分钟执行一次，监控最近10分钟（可配置）内的车辆运行情况
- **任务状态检测**：自动识别车辆是否有正在执行的任务
- **里程自动计算**：基于GPS分段里程记录自动累计运行公里数
- **部门智能识别**：自动关联车辆归属部门信息

### 2. 灵活配置
- **公里数阈值**：默认10公里，可通过系统配置调整
- **告警频率限制**：
  - 每天每车最多告警5次（可配置）
  - 两次告警最小间隔5分钟（可配置）
- **监控时间窗口**：默认10分钟，可配置
- **通知用户配置**：支持配置固定用户列表或根据部门自动通知负责人

### 3. 多渠道通知
- **企业微信通知**：集成企业微信消息推送
- **小程序通知**：通过小程序发送告警信息
- **通知内容**：包含车牌号、运行公里数、时间段等关键信息

### 4. 完整的管理界面
- **告警列表查看**：支持按车牌号、时间、部门、状态等多维度查询
- **告警详情查看**：查看告警的完整信息
- **告警处理**：支持单个或批量处理告警，记录处理人和处理意见
- **数据导出**：支持导出Excel进行数据分析
- **统计功能**：展示未处理告警数量、今日告警数量等统计信息

## 技术实现

### 数据库设计

#### 1. 车辆异常告警记录表 (tb_vehicle_abnormal_alert)
存储每次告警的详细信息：
- 基本信息：车辆ID、车牌号、告警时间、累计公里数
- 告警详情：告警类型、原因描述、开始/结束时间
- 处理信息：处理状态、处理人、处理时间、处理备注
- 通知信息：通知状态、通知时间、通知用户列表
- 部门信息：归属部门ID、部门名称

#### 2. 车辆异常告警配置表 (tb_vehicle_alert_config)
支持全局、部门、车辆三级配置：
- 配置层级：GLOBAL(全局)/DEPT(部门)/VEHICLE(车辆)
- 告警参数：公里数阈值、每日告警次数、告警间隔
- 通知配置：通知用户ID列表、通知角色列表
- 启用状态：可灵活开启或关闭某个配置

### 核心组件

#### 1. 定时监控任务 (VehicleAbnormalAlertTask)
```java
@Component("vehicleAbnormalAlertTask")
public class VehicleAbnormalAlertTask {
    // 每5分钟执行一次
    public void monitorVehicleAbnormalRunning()
}
```

**监控流程**：
1. 检查功能开关是否启用
2. 加载配置参数（阈值、频率限制等）
3. 查询所有活跃车辆
4. 逐车检查：
   - 是否有正在执行的任务
   - 计算监控窗口内的运行里程
   - 判断是否超过阈值
   - 检查告警频率限制
5. 创建告警记录
6. 发送通知

#### 2. 告警服务 (VehicleAbnormalAlertService)
提供告警的增删改查、处理等核心业务逻辑：
- `checkAndCreateAlert()`: 检查并创建告警
- `handleAlert()`: 处理单个告警
- `batchHandleAlert()`: 批量处理告警

#### 3. 告警控制器 (VehicleAbnormalAlertController)
提供RESTful API接口：
- `GET /system/vehicleAlert/list`: 查询告警列表
- `GET /system/vehicleAlert/{id}`: 查询告警详情
- `PUT /system/vehicleAlert/handle/{id}`: 处理告警
- `GET /system/vehicleAlert/unhandledCount`: 获取未处理告警数
- `POST /system/vehicleAlert/export`: 导出告警数据

## 配置说明

### 系统配置参数 (sys_config表)

| 配置键 | 说明 | 默认值 |
|-------|------|--------|
| vehicle.alert.enabled | 告警功能总开关 | true |
| 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列表 | （空） |

### 定时任务配置

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

## 部署步骤

### 1. 执行SQL脚本
```sql
source sql/vehicle_abnormal_alert.sql;
```

该脚本会自动创建：
- 告警记录表
- 告警配置表
- 系统配置参数
- 定时任务
- 菜单权限

### 2. 配置通知用户
在系统配置中设置 `vehicle.alert.notify.users`，填入接收告警的用户ID列表（逗号分隔）

### 3. 启用定时任务
在"系统监控 > 定时任务"中找到"车辆异常运行监控任务"，点击"恢复"按钮启用

### 4. 配置企业微信（可选）
如需使用企业微信通知，确保以下配置正确：
- `qy_wechat.enable = true`
- `qy_wechat.corp_id` = 企业ID
- `qy_wechat.corp_secret` = 应用Secret
- `qy_wechat.agent_id` = 应用ID

## 使用指南

### 管理员操作

#### 1. 查看告警列表
- 进入"车辆管理 > 车辆异常告警"
- 可按车牌号、时间范围、部门、状态筛选
- 默认按告警时间倒序排列

#### 2. 处理告警
- 点击"处理"按钮
- 填写处理备注
- 提交后告警状态变更为"已处理"

#### 3. 批量处理
- 勾选多个告警
- 点击"批量处理"
- 填写统一的处理备注

#### 4. 导出数据
- 设置筛选条件
- 点击"导出"按钮
- 下载Excel文件进行分析

#### 5. 调整配置
- 进入"系统管理 > 参数设置"
- 搜索"vehicle.alert"
- 修改相关参数
- 修改后立即生效，无需重启

### 监控原理

#### 里程计算
- 基于`tb_vehicle_gps_segment_mileage`表
- 每5分钟自动分段统计GPS里程
- 查询监控窗口内的所有分段里程记录
- 累加计算总运行公里数

#### 任务关联判断
- 查询`sys_task`和`sys_task_vehicle`表
- 检查车辆在监控时间窗口内是否有任务
- 排除已完成和已取消的任务
- 只有完全无任务时才触发告警

#### 频率控制
- **每日次数限制**：查询当天该车已告警次数，达到上限则跳过
- **时间间隔限制**：查询最后一次告警时间，未达到间隔则跳过
- 防止频繁告警骚扰

## 告警状态流转

```
未处理(0) -> 已处理(1)
         \-> 已忽略(2)
```

- **未处理**：新创建的告警，待处理
- **已处理**：管理员已处理并填写了处理意见
- **已忽略**：管理员确认为误报或无需处理

## 注意事项

1. **GPS数据依赖**
   - 需要GPS分段里程计算任务正常运行
   - 确保`tb_vehicle_gps_segment_mileage`表有数据
   - 建议先运行GPS里程计算任务测试

2. **性能优化**
   - 监控任务每5分钟执行一次
   - 每次只查询最近10分钟的数据
   - 数据库已建立必要的索引
   - 大量车辆时注意监控执行时间

3. **通知配置**
   - 优先使用配置的用户列表
   - 其次根据车辆归属部门查找负责人
   - 最后使用全局默认用户列表
   - 确保至少配置一种通知方式

4. **测试建议**
   - 先在测试环境验证
   - 调整阈值为较小值（如1公里）方便触发
   - 观察告警记录和通知是否正常
   - 确认频率限制是否生效

5. **监控调优**
   - 根据实际情况调整公里数阈值
   - 合理设置每日告警次数
   - 适当调整监控时间窗口
   - 避免告警过于频繁或遗漏

## 扩展功能

### 未来可扩展的功能方向

1. **多种告警类型**
   - 长时间停车告警
   - 超速告警
   - 偏离路线告警

2. **告警规则引擎**
   - 自定义告警规则
   - 规则组合与优先级
   - 动态调整规则

3. **数据分析**
   - 告警趋势分析
   - 车辆异常行为统计
   - 部门告警对比

4. **智能推荐**
   - 基于历史数据预测异常
   - 推荐最优配置参数
   - 自动识别误报

## 技术支持

如有问题，请联系技术支持团队或查看相关文档：
- 系统日志：`/logs/sys-*.log`
- 定时任务日志：`/monitor/job/log`
- GPS里程计算说明：`/doc/GPS分段里程计算.md`

## 文件清单

### 后端代码
- `ruoyi-system/src/main/java/com/ruoyi/system/domain/VehicleAbnormalAlert.java` - 告警实体类
- `ruoyi-system/src/main/java/com/ruoyi/system/domain/VehicleAlertConfig.java` - 配置实体类
- `ruoyi-system/src/main/java/com/ruoyi/system/mapper/VehicleAbnormalAlertMapper.java` - 数据访问接口
- `ruoyi-system/src/main/java/com/ruoyi/system/service/IVehicleAbnormalAlertService.java` - 业务接口
- `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/VehicleAbnormalAlertServiceImpl.java` - 业务实现
- `ruoyi-system/src/main/resources/mapper/system/VehicleAbnormalAlertMapper.xml` - MyBatis映射文件
- `ruoyi-admin/src/main/java/com/ruoyi/web/controller/system/VehicleAbnormalAlertController.java` - 控制器
- `ruoyi-quartz/src/main/java/com/ruoyi/quartz/task/VehicleAbnormalAlertTask.java` - 定时任务

### 数据库脚本
- `sql/vehicle_abnormal_alert.sql` - 建表及初始化脚本

### 文档
- 本文档 - 完整的功能说明和使用指南

## 更新日志

### V1.0.0 (2026-01-12)
- ✅ 实现基础监控功能
- ✅ 支持企业微信通知
- ✅ 完整的管理界面
- ✅ 灵活的配置系统
- ✅ 告警频率控制
- ✅ 数据导出功能