CollisionAvoidanceSystem/change_log.md

碰撞避免系统变更日志

本文档记录碰撞避免系统的所有重要变更，包括新功能、改进和修复。

[0.6.14] - 2025-06-11

新增功能 (Features)

• WebSocket实时消息推送系统: 实现完整的WebSocket消息推送功能，支持实时数据通信
  • 事件驱动架构: 基于Spring事件机制的扁平化事件系统
    • PositionUpdateEvent: 位置更新事件（航空器、机场车辆、无人车）
    • TrafficLightStatusEvent: 红绿灯状态变化事件
    • CollisionWarningEvent: 碰撞预警事件
    • VehicleCommandEvent: 车辆控制指令事件
    • SystemAlertEvent: 系统告警事件
  • 统一消息格式: 符合前端JSON格式的标准化消息封装
    • WebSocketMessage<T>: 统一消息格式，包含type、timestamp、messageId、payload
    • 完整的@JsonProperty注解，确保与C++测试客户端格式兼容
    • 支持微秒级时间戳和消息优先级分类
  • 实时数据推送: 数据处理完成后立即发布事件和推送消息
    • 航空器位置数据处理完成后实时推送
    • 机场车辆位置数据处理完成后实时推送
    • 无人车数据存储完成后实时推送
    • 统一推送到/topic/realtime主题，适配控制台需求
  • 消息缓存恢复: Redis缓存服务支持客户端重连后消息恢复
    • 最近100条消息缓存，30分钟过期时间
    • 支持按消息类型获取遗漏消息
    • 重连后自动推送遗漏的重要消息

消息类型支持 (Message Types)

• 位置更新消息 (position_update): object_id、object_type、position、heading、speed
• 红绿灯状态消息 (intersection_traffic_light_status): intersection_id、ns_status、ew_status
• 碰撞预警消息 (collision_warning): object1/2_id/type、risk_level、distance、estimated_time
• 车辆控制指令消息 (vehicle_command): vehicleId、commandType、reason、description
• 系统告警消息 (system_alert): alert_id、alert_type、alert_level、component

技术架构 (Technical Architecture)

• 数据流程: 数据采集 → 数据处理 → 事件发布 → WebSocket推送 → 前端
• 事件集成: 在DataCollectorService和VehicleDataPersistenceService中集成事件发布
• 错误容错: 事件发布失败不影响主业务流程，包含异常处理机制
• 性能优化: 实时同步事件处理，无异步延迟，确保实时性

测试验证 (Testing)

• 事件测试: WebSocketEventTest 验证所有事件类创建和属性正确性
• 集成测试: WebSocketIntegrationTest 验证消息格式JSON序列化兼容性
• 格式兼容: 验证与C++测试客户端和前端JSON格式完全兼容
• 编译验证: 所有代码编译成功，无语法错误

[0.6.13] - 2025-01-15

架构重构 (Architecture Refactoring)

• 车辆分类架构优化: 实现分层的车辆分类管理策略
  • 数据模型层简化: 移除 MovingObjectType.SPECIAL_VEHICLE，保持与API数据源一致的三种类型
    • AIRCRAFT: 航空器（第1章航空器位置数据接入）
    • AIRPORT_VEHICLE: 机场车辆（第1章车辆位置数据接入）
    • UNMANNED_VEHICLE: 无人车（第2章无人车控制接口）
  • 业务逻辑层增强: 新增 VehicleSubType 枚举实现车辆细分管理
    • 特勤车辆：警车、消防车、救护车、引导车（有特殊权限）
    • 一般机场车辆：加油车、行李车、清洁车等（无特殊权限）
    • 无人车子类型：巡逻车、配送车、检查车等
  • 权限管理服务: 新增 VehiclePermissionService 处理复杂的业务规则
    • 特勤车辆滑行道特殊通行权限
    • 红绿灯遵守规则（特勤车辆免遵守）
    • 车辆避让优先级管理
    • 区域访问权限控制

业务逻辑增强 (Business Logic Enhancement)

• 特勤车辆特权: 实现特勤车辆的特殊业务规则
  • 滑行道紧急通行权限
  • 不受红绿灯限制
  • 其他车辆主动避让
  • 特殊区域访问权限
• 权限分级管理: 建立清晰的车辆权限等级体系
  • 最高权限：航空器
  • 特殊权限：特勤车辆
  • 一般权限：机场车辆
  • 受控权限：无人车
• 智能车辆识别: 基于车辆ID的启发式车辆类型推断

技术改进 (Technical Improvements)

• 架构分层: 明确分离数据模型层和业务逻辑层职责
• 服务封装: 车辆权限管理逻辑统一封装，提升可维护性
• 扩展性: 支持未来新增车辆子类型和权限规则
• 性能优化: 基于枚举的快速权限检查机制

设计理念 (Design Philosophy)

• 单一职责: 数据模型专注API映射，业务逻辑专注规则处理
• 开放封闭: 易于扩展新的车辆类型，无需修改现有代码
• 业务驱动: 架构设计直接反映真实的机场运营规则

[0.6.12] - 2025-06-11

架构重构 (Architecture Refactoring)

• 车辆分类精细化重构: 明确区分机场车辆和特勤车辆的业务概念
  • 重命名 MovingObjectType.SPECIAL_VEHICLE 为 AIRPORT_VEHICLE
  • 明确数据分类：
    • AIRCRAFT: 航空器（第1章航空器位置数据接入）
    • AIRPORT_VEHICLE: 机场车辆（第1章车辆位置数据接入，服务车辆、清洁车等）
    • UNMANNED_VEHICLE: 无人车（第2章无人车控制接口）
  • 保留 CommandReason.SPECIAL_VEHICLE 用于特勤车辆控制指令（警车、消防车、救护车等）
  • 更新所有相关测试用例，确保数据分类一致性
• 业务逻辑澄清:
  • 机场车辆：一般服务车辆，仅实时处理不持久化
  • 特勤车辆：紧急车辆，作为控制指令原因存在
  • 无人车：可控车辆，需要持久化存储

技术改进 (Technical Improvements)

• 枚举类型更新: 所有MovingObjectType引用已正确更新为AIRPORT_VEHICLE
• 注释完善: 更新所有相关类和方法的注释，明确车辆分类定义
• 测试一致性: 确保测试数据与业务逻辑保持一致

文档更新 (Documentation)

• API文档: 更新车辆类型说明，明确各类型车辆的数据处理策略
• 代码注释: 完善MovingObjectType枚举和CommandReason枚举的注释说明

[0.6.11] - 2025-06-11

新增功能 (Features)

• 数据分类架构重构: 根据官方API文档重新定义数据分类和处理策略
  • 重命名 SpecialVehicle 为 AirportVehicle，明确数据来源为第1章车辆位置数据接入
  • 数据分类明确化：航空器数据、机场车辆数据（第1章）、无人车数据（第2章）
  • 更新数据采集服务日志，将"特种车辆"改为"机场车辆"以符合官方API定义
  • 完善配置文件注释，明确标注各接口的官方API章节来源
  • 统一数据处理策略：航空器和机场车辆仅实时处理，无人车数据持久化存储

[0.6.10] - 2025-06-11

新增功能 (Features)

• 数据库迁移文件完善: 创建缺失的V002核心表迁移文件
  • 新增 V002__create_core_tables.sql 迁移文件，基于 create_tables.sql 内容
  • 建立完整的数据库迁移序列：V001(PostGIS扩展) → V002(核心表) → V003(车辆指令表)
  • 移除重复的PostGIS扩展创建语句，确保迁移文件逻辑清晰
  • 包含vehicle_locations、airport_areas、vehicle_trajectories三个核心表的完整结构
  • 包含所有PostGIS空间索引、JSONB索引、触发器和数据清理函数
  • 遵循Flyway迁移文件命名规范和最佳实践

技术改进 (Technical Improvements)

• 迁移文件组织: 建立了标准化的数据库版本控制体系
• PostGIS架构: 确保核心空间数据表结构的迁移可追溯性
• 数据库管理: 提升了数据库schema变更的可维护性和部署一致性
• API文档一致性: 代码实现与官方API文档完全对应，提升系统规范性

[0.6.9] - 2025-06-11

修复 (Fixes)

• Hibernate配置错误修复: 解决集成测试失败问题
  • 修正 generate_statistics 和 log_slow_query 配置错误
  • 移除与Spring Boot 3.x冲突的事务管理配置
  • 修复 JSONB 查询参数语法冲突
  • 修正 AirportAreaRepository.findByAreaName 方法名
• PostgreSQL事务管理优化: 移除 provider_disables_autocommit 配置冲突
• JPA Repository查询修复: 统一使用标准的命名参数和JSONB函数

技术改进 (Technical Improvements)

• 配置简化: 移除复杂的自定义数据库配置，使用Spring Boot默认策略
• 测试稳定性: 集成测试 VehicleDataPersistenceServiceIntegrationTest 全部通过
• 兼容性提升: 确保与PostgreSQL 17 + PostGIS + Hibernate Spatial完全兼容

测试 (Testing)

• ✅ 所有9个集成测试方法成功执行
• ✅ ApplicationContext正常启动，无配置冲突
• ✅ 事务回滚功能正常工作

[0.6.8] - 2025-06-11

新增功能

• 外部接口对接完整实现: 根据官方API文档实现无人车控制接口
  • 实现VehicleCommandEntity实体类，支持PostGIS空间数据存储
  • 创建VehicleCommandRepository，提供丰富的查询方法
  • 添加数据库迁移脚本，创建vehicle_commands表和PostGIS索引
  • 实现UnmannedVehicleController控制器，提供三个核心API端点
  • 创建UnmannedVehicleControlService服务类，处理核心业务逻辑
  • 实现VehicleDataPersistenceService，选择性数据持久化策略
  • 扩展DataCollectorService，集成选择性存储逻辑
  • 添加VehicleControlExceptionHandler统一异常处理
  • 更新应用配置，添加无人车控制相关参数

数据持久化策略

• 选择性存储: 仅无人车数据持久化存储，其他车辆数据仅实时处理
  • 无人车控制指令和位置数据保存到PostgreSQL数据库
  • 航空器和特种车辆数据仅用于实时处理和WebSocket推送
  • 支持PostGIS空间数据类型和空间索引优化

API接口

• 控制指令接口: POST /api/unmanned-vehicle/command
  • 支持ALERT、SIGNAL、WARNING、RESUME指令类型
  • 包含空间位置数据和相对运动参数
  • 完整的参数验证和错误处理
• 位置上报接口: GET /api/unmanned-vehicle/location/{vehicleId}
  • 获取指定无人车实时位置信息
  • 包含经纬度、速度、方向等核心数据
• 状态查询接口: POST /api/unmanned-vehicle/state
  • 支持单个车辆或所有车辆状态查询
  • 包含登录状态、故障信息、控制模式等完整状态

架构重构

• DTO统一管理: 重构Response类到common.model.dto包
• dataCollector DTO重构: 移动相关DTO类到正确包结构
• VehicleStateRequest: 新增DTO类支持状态查询请求体

测试覆盖

• 单元测试: UnmannedVehicleControllerTest，覆盖所有控制器方法
• 集成测试: VehicleDataPersistenceServiceIntegrationTest，测试数据持久化策略
• 测试修复: 解决Mock参数匹配、返回消息一致性等问题

文档完善

• API文档: 创建完整的API接口文档，包含请求响应示例
• 配置说明: 详细的配置参数和数据持久化策略说明
• 安全考虑: API安全、数据验证、性能监控等指导

技术特性

• 完整的PostGIS空间数据支持
• 批量数据处理优化
• 统一异常处理机制
• 配置化参数管理
• 符合Spring Boot最佳实践的分层架构

[0.6.7] - 2025-06-10

新增功能

• 数据库连接池优化: 实现HikariCP连接池完整配置和性能优化
  • 配置HikariCP连接池参数：最大连接数20，最小空闲连接5，连接生命周期管理
  • 添加PostgreSQL性能优化参数：预编译语句缓存、批量插入重写、超时设置
  • 配置PostGIS空间查询优化：连接池针对空间查询的特殊配置
• Hibernate性能调优: 全面优化JPA/Hibernate配置
  • 启用二级缓存和查询缓存，配置JCache缓存工厂
  • 配置批量操作：批量大小50，排序插入/更新，版本化数据批处理
  • 优化空间数据处理：PostGIS连接查找器，空间查询fetch size配置
• 数据库性能监控: 创建DatabasePerformanceConfig配置类
  • 实时连接池状态监控：连接使用率、等待线程数警告
  • Hibernate统计信息收集：查询执行次数、缓存命中率、事务统计
  • 定期性能报告：每5分钟生成详细的数据库性能报告
  • 数据库健康检查：通过Actuator endpoint提供连接池状态
• 日志优化: 配置数据库和性能相关的详细日志
  • HikariCP连接池日志、Hibernate SQL日志、PostGIS空间查询日志
  • SQL参数绑定日志、事务日志、查询性能日志
  • 优化日志格式，便于性能分析和问题排查

技术改进

• 连接池管理: HikariCP替代默认连接池，提供更好的性能和监控
• 缓存策略: 多层缓存配置，提升查询性能，减少数据库负载
• 批处理优化: 针对PostGIS空间数据的批量操作优化
• 监控体系: 完整的数据库性能监控和告警机制

[0.6.6] - 2025-06-10

修复

• SQL表结构修正: 修正PostGIS数据库表结构，确保与JPA实体类完全匹配
  • 修正airport_areas表字段名称：
    • area_name → name
    • area_type → type
    • geometry → boundary
    • is_active → enabled
  • 新增area_id字段，对应实体类的区域标识符
  • 扩展表字段以支持实体类的所有属性：
    • 添加speed_limit_kph、restricted等基础限制字段
    • 添加allowed_vehicle_types、allowed_aircraft_types JSONB字段
    • 添加max_height、max_weight等扩展限制字段
    • 添加active_time、expiry_time时间控制字段
  • 修正vehicle_locations表字段：
    • 添加data_quality字段，移除accuracy和data_source字段
    • 统一时间戳字段类型为TIMESTAMP
  • 更新所有相关索引名称和示例数据，确保与新表结构一致

技术改进

• 数据库兼容性: 确保Spring Data JPA能够正确映射实体类到数据库表
• 空间索引优化: 更新PostGIS空间索引以匹配新的字段名称
• JSONB查询支持: 优化车辆类型和航空器类型的JSONB字段索引

[0.6.5] - 2025-06-10

新增功能

• 实现PostGIS Redis缓存策略完整架构
  • 扩展RedisConfig配置，支持PostGIS实体类序列化（VehicleLocation、AirportArea）
  • 创建CacheConstants常量定义类，统一管理缓存键前缀和过期时间
  • 新增VehicleLocationCacheService车辆位置缓存服务
    • 支持车辆最新位置缓存和轨迹数据缓存
    • 实现批量操作和缓存失效策略
    • 提供缓存统计和清理功能
  • 新增AirportAreaCacheService机场区域缓存服务
    • 支持区域配置数据缓存和空间查询结果缓存
    • 实现区域类型索引缓存和缓存预热功能
    • 提供区域变更时的缓存刷新机制
  • 新增SpatialQueryCacheService空间查询缓存服务
    • 基于地理网格的缓存策略
    • 支持车辆半径查询和冲突检测结果缓存
    • 实现缓存失效和清理机制
• 分层缓存策略设计
  • 热数据：车辆最新位置（30秒过期）
  • 温数据：车辆轨迹和空间查询结果（60-300秒过期）
  • 冷数据：区域配置和统计数据（3600秒过期）
• 缓存穿透保护和性能优化机制

[0.6.4] - 2024-12-19

修复

• 重写AirportAreaServiceIntegrationTest.java测试文件
  • 移除对已删除的areas.service.AirportAreaService和AirportAreaConfig的依赖
  • 改为测试新的PostGIS版本的common.service.AirportAreaService
  • 使用JTS几何对象和PostGIS空间查询功能
  • 添加@Transactional注解和setUp方法来管理测试数据
  • 测试空间查询、几何验证、区域重叠检测等PostGIS功能
• 修复所有编译错误，测试现在与PostGIS架构完全兼容

[0.6.3] - 2025-01-09

移除

• YAML配置系统清理: 移除机场区域相关的YAML配置加载机制
  • 删除 AirportAreasProperties.java - 机场区域顶层配置属性
  • 删除 AreaProperties.java - 单个区域配置属性
  • 删除 AirportAreaConfig.java - 机场区域配置加载类
  • 删除重复的 areas.service.AirportAreaService - 避免与PostGIS版本冲突

重构

• 统一服务架构: 现在所有机场区域操作都通过PostGIS common.service.AirportAreaService 进行
  • 消除了YAML配置与数据库存储的双重架构
  • 统一数据源为PostGIS数据库
  • 简化了服务层依赖关系

保留

• 道路网络配置: 保留 GeometryProperties.java 以支持道路网络的YAML配置
  • 道路网络仍使用YAML配置方式
  • 确保道路配置功能不受影响

技术优化

• 架构简化: 消除了类名冲突和循环依赖
• 数据一致性: 所有区域数据现在统一从PostGIS获取
• 维护性提升: 减少了重复代码和冗余配置

[0.6.2] - 2025-01-09

移除

• MovingObjectRepository内存存储: 完全移除内存存储仓库及其相关代码
  • 删除 MovingObjectRepository.java 内存存储实现
  • 重构 GeopositionController.java 以使用PostGIS VehicleLocationService
  • 清理测试配置中的MovingObjectRepository引用

改进

• WebSocket服务升级: GeopositionController现在基于PostGIS数据库提供实时数据
  • 新增按车辆类型查询的WebSocket接口
  • 新增全部车辆位置查询接口
  • 提供更准确的实时位置数据（基于数据库而非内存）
  • 增强异常处理和日志记录

技术优化

• 数据一致性: 所有位置数据现在统一从PostGIS数据库获取
• 性能提升: 利用数据库索引优化查询性能
• 可扩展性: 支持更复杂的空间查询和历史数据分析

[0.6.1] - 2025-01-09

改进

• 系统架构简化: 删除DataProcessor组件，简化数据处理流程
  • 移除 DataProcessor.java 及其相关依赖
  • 清理测试代码中的DataProcessor引用
  • 数据现在直接通过DataCollectorService保存到PostGIS数据库，无需中间处理层

技术优化

• 减少组件复杂度: 消除不必要的数据处理中间层
• 提升维护性: 简化代码结构，减少组件间耦合
• 优化数据流: 数据采集直接入库，减少内存占用和处理延迟

[0.6.0] - 2025-06-10

新增

• PostGIS数据模型迁移完成: 完全替换内存存储，实现基于PostGIS的车辆位置和机场区域数据管理
• VehicleLocation实体类: 支持PostGIS POINT类型的车辆位置存储，包含时间戳、数据质量等字段
• AirportArea实体类: 支持PostGIS GEOMETRY类型的机场区域存储，支持POLYGON/MULTIPOLYGON，包含JSONB限制信息
• VehicleLocationRepository: 提供丰富的PostGIS空间查询接口（半径查询、区域查询、轨迹查询等）
• AirportAreaRepository: 提供全面的PostGIS空间查询接口（包含查询、相交查询、重叠检测、优先级处理等）
• VehicleLocationService: 车辆位置服务类，提供完整的空间查询、轨迹分析、数据验证和管理功能
• AirportAreaService: 机场区域服务类，提供空间查询、区域管理、冲突检测、几何验证等功能
• SpatialQueryService: 综合空间查询服务类，提供冲突检测、轨迹分析、区域密度分析等高级功能
• PostGIS数据库表结构: 完整的车辆位置表、机场区域表、轨迹表，配置空间索引、触发器、数据清理函数

改进

• 数据存储架构: 从内存STRtree索引改为PostgreSQL + PostGIS持久化存储
• 空间查询性能: 利用PostGIS GIST索引大幅提升空间查询性能
• 数据一致性: 通过数据库事务和约束确保数据一致性
• 扩展性: 支持大规模数据存储和复杂空间查询

修复

• Lombok兼容性: 升级Lombok版本到1.18.38，解决与JDK 17.0.15的兼容性问题
• 编译错误: 修复MovingObjectType枚举类型和JSONB字段序列化相关编译错误
• 依赖管理: 优化PostGIS和Hibernate Spatial依赖配置

技术栈更新

• 数据库: PostgreSQL 17 + PostGIS扩展
• ORM: Spring Boot JPA + Hibernate Spatial
• 空间数据: JTS几何库 + PostGIS原生函数
• 坐标系: 统一使用WGS84 (SRID 4326)

[0.5.3] - 2025-06-10

PostGIS空间扩展集成

• PostGIS扩展支持: 为PostgreSQL添加强大的空间数据处理能力
  • 添加 hibernate-spatial 依赖，支持JPA空间数据类型
  • 添加 postgis-jdbc 扩展（v2023.1.0）
  • 更新Hibernate方言为 PostgisPG95Dialect
  • 创建PostGIS扩展初始化脚本

空间数据功能

• 支持POINT和POLYGON空间数据类型
• SRID 4326（WGS84坐标系统）支持GPS坐标
• 提供空间查询示例（ST_Contains、ST_DWithin、ST_Distance）
• 空间索引（GIST）优化查询性能

项目能力提升

• 精确的机场围栏检测
• 高效的碰撞预测和距离计算
• 优化的轨迹分析和历史查询
• 为实时空间分析奠定技术基础

[0.5.2] - 2025-06-10

数据库技术栈升级

• PostgreSQL 17 迁移: 将数据库从MySQL切换到PostgreSQL 17
  • 替换 mysql-connector-java 为 postgresql 驱动（v42.7.1）
  • 更新数据源配置：jdbc:postgresql://localhost:5432/collision_avoidance
  • 更新Hibernate方言为 PostgreSQLDialect
  • 数据保留策略调整为 postgresql-days

技术优势提升

• PostgreSQL原生支持更强大的JSON和空间数据处理
• 为未来PostGIS空间扩展奠定基础
• 更好的并发性能和查询优化
• 符合现代开发的主流技术选型

[0.5.1] - 2025-06-10

架构重构

• 数据库迁移: 移除MongoDB依赖，统一使用关系型数据库
  • 移除 spring-boot-starter-data-mongodb 依赖
  • 添加 spring-boot-starter-data-jpa 依赖
  • 移除主应用类中的 @EnableMongoRepositories 注解

技术栈简化

• 采用关系型数据库作为统一数据存储方案
• 配置JPA/Hibernate用于ORM映射

配置优化

• 数据库名：collision_avoidance
• Hibernate配置：ddl-auto: update 用于开发阶段表结构自动更新
• 启用SQL日志输出，便于开发调试

[0.5.0] - 2025-04-29

新增

• 通过 geojson_to_yaml.py 脚本，将GIS 系统导出的道路地理信息文件转换为 YAML 格式的配置文件airport_roads.yaml

[0.4.0] - 2025-04-21

新增

• 道路网络服务 (RoadNetworkService)，实现道路网络的配置文件处理和查询功能
• 道路网络配置文件 (airport_roads.yaml)，定义机场的道路网络信息
• 机场区域服务 (AirportAreaService)，实现机场区域的配置文件处理和查询功能
• 机场区域配置文件 (airport_areas.yaml)，定义机场的区域信息

[0.3.0] - 2025-03-31

新增

• 坐标系统服务 (CoordinateSystemService)，实现WGS84到局部坐标系的转换
• 速度计算服务 (SpeedCalculationService)，处理移动物体的动力学参数
• processLoop方法实现，支持持续数据处理流
• 航空器、特种车辆和无人车的数据处理流程

改进

• 优化数据采集模块与数据处理模块的交互接口
• 实现异步处理机制，提高系统响应速度
• 增强坐标转换精度，支持UTM分区自动计算

修复

• 修复速度计算中的时间戳异常处理问题
• 处理轨迹历史记录超出最大限制的情况

[0.2.0] - 2025-03-16

新增

• 数据采集模块完整功能实现
• 多数据源适配器：支持机场API和第三方车辆API
• 移动物体模型定义，包含基类和三种具体类型
• 历史状态记录和轨迹分析基础功能
• 数据仓库组件，提供数据存储和检索功能
• RestTemplate配置，支持外部API调用

改进

• 重构配置管理，支持不同环境下的配置切换
• 实现授权服务，优化API认证流程

修复

• 修复数据采集过程中的并发问题
• 修复连接超时导致的数据丢失问题

[0.1.0] - 2025-03-3

新增

• 系统基础架构设计
• 项目框架搭建，包括Maven配置和依赖管理
• 基础配置类实现，包括线程池、Redis和WebSocket配置
• 数据模型初步定义
• 系统文档结构建立

改进

• 完善日志系统，支持不同级别的日志记录
• 建立开发规范，统一代码风格和文档格式