# 机场车辆位置过滤功能设计文档

## 概述

本设计文档描述了如何在现有的机场车辆位置数据处理流程中添加过滤功能，通过系统配置控制是否转发未注册车辆的位置信息。

## 架构

### 整体架构
```
机场API -> DataCollectorService -> 车辆过滤器 -> 缓存/前端转发
                                      ↓
                              sys_vehicle_info表查询
                                      ↓
                              系统配置(ISysConfigService)
```

### 核心组件
1. **VehicleLocationFilter**: 新增的车辆位置过滤器
2. **DataCollectorService**: 修改现有的数据采集服务，集成过滤逻辑
3. **ISysConfigService**: 利用现有的系统配置服务
4. **ISysVehicleInfoService**: 利用现有的车辆信息服务

## 组件和接口

### 1. VehicleLocationFilter (新增)

```java
@Component
public class VehicleLocationFilter {
    
    private static final String CONFIG_KEY = "unmanaged.vehicle.filter.enabled";
    
    @Autowired
    private ISysConfigService configService;
    
    @Autowired
    private ISysVehicleInfoService vehicleInfoService;
    
    /**
     * 过滤机场车辆位置数据
     * @param vehicles 原始车辆列表
     * @return 过滤后的车辆列表
     */
    public List<AirportVehicle> filterVehicles(List<AirportVehicle> vehicles);
    
    /**
     * 检查过滤功能是否启用
     * @return true表示启用过滤
     */
    private boolean isFilterEnabled();
    
    /**
     * 批量检查车辆是否在数据库中存在
     * @param plateNumbers 车牌号列表
     * @return 存在的车牌号集合
     */
    private Set<String> getExistingVehiclePlates(List<String> plateNumbers);
}
```

### 2. DataCollectorService (修改)

在现有的 `collectVehicleData()` 方法中集成过滤逻辑：

```java
@Scheduled(fixedRateString = "${data.collector.interval}")
@Async
public void collectVehicleData() {
    // ... 现有代码 ...
    
    List<AirportVehicle> vehicles = dataCollectorDao.collectVehicleData(airportVehicleEndpoint, airportBaseUrl);
    
    // 新增：应用过滤器
    List<AirportVehicle> filteredVehicles = vehicleLocationFilter.filterVehicles(vehicles);
    
    // 继续处理过滤后的车辆数据
    for (AirportVehicle vehicle : filteredVehicles) {
        // ... 现有处理逻辑 ...
    }
}
```

### 3. 系统配置

在 `sys_config` 表中添加配置项：
- config_key: `unmanaged.vehicle.filter.enabled`
- config_value: `false` (默认值，不过滤)
- config_name: `未管理车辆位置过滤开关`
- config_type: `Y` (系统内置)

## 数据模型

### 配置项数据结构
```sql
INSERT INTO sys_config (config_name, config_key, config_value, config_type, remark) 
VALUES ('未管理车辆位置过滤开关', 'unmanaged.vehicle.filter.enabled', 'false', 'Y', '控制是否过滤未在sys_vehicle_info表中注册的车辆位置信息');
```

### 车辆信息查询
利用现有的 `sys_vehicle_info` 表结构，通过 `license_plate` 字段进行匹配。

## 错误处理

### 异常处理策略
1. **配置读取失败**: 默认不过滤，记录警告日志
2. **数据库查询失败**: 默认不过滤，记录错误日志
3. **车辆数据异常**: 跳过异常数据，继续处理其他车辆

### 日志记录
- DEBUG级别: 记录过滤统计信息
- WARN级别: 记录配置读取失败
- ERROR级别: 记录数据库查询异常

## 测试策略

### 单元测试
1. **VehicleLocationFilter测试**
   - 测试过滤功能启用/禁用
   - 测试车辆存在性检查
   - 测试异常处理

2. **DataCollectorService集成测试**
   - 测试过滤器集成
   - 测试数据流完整性

### 集成测试
1. 测试配置修改后的实时生效
2. 测试大量车辆数据的过滤性能
3. 测试数据库连接异常时的降级处理

## 性能考虑

### 优化策略
1. **批量查询**: 一次查询所有车牌号，避免N+1问题
2. **配置缓存**: 利用现有的系统配置缓存机制
3. **快速失败**: 配置禁用时直接跳过所有过滤逻辑

### 性能指标
- 单批次车辆过滤处理时间 < 50ms (100辆车以内)
- 数据库查询次数: 每批次最多1次
- 内存占用: 忽略不计 (仅临时存储车牌号列表)