# 碰撞避免系统数据结构设计文档

## 1. 数据结构概述

本文档描述碰撞避免系统中的核心数据结构设计及其关系。系统采用面向对象设计方法，通过继承和组合实现不同移动物体类型的统一管理。

## 2. 核心数据结构设计

### 2.1 类图

```mermaid
classDiagram
    class MovingObject {
        +GeoPosition currentPosition
        +Velocity velocity
        +double heading
        +long timestamp
        +Deque~MovementState~ stateHistory
        +int MAX_HISTORY
        +double maxSpeed
        +MovingObjectType type
    }
    
    class Aircraft {
        +String flightNo
        +Long trackNumber
    }
    
    class SpecialVehicle {
        +String vehicleNo
    }
    
    class UnmannedVehicle {
        +String transId
        +String vehicleId
    }
    
    class GeoPosition {
        +double latitude
        +double longitude
        +double altitude
    }
    
    class Velocity {
        +double x, y, z
        +double vx, vy, vz
        +double confidence
        +double cachedAcceleration
        +getSpeed()
    }
    
    class MovementState {
        +GeoPosition position
        +Velocity velocity
        +double heading
        +long timestamp
        +DataQuality dataQuality
    }
    
    class MovingObjectType {
        <<enumeration>>
        AIRCRAFT
        SPECIAL_VEHICLE
        UNMANNED_VEHICLE
    }
    
    MovingObject <|-- Aircraft
    MovingObject <|-- SpecialVehicle
    MovingObject <|-- UnmannedVehicle
    MovingObject "1" *-- "1" GeoPosition
    MovingObject "1" *-- "1" Velocity
    MovingObject "1" *-- "0..*" MovementState
    MovingObject "1" *-- "1" MovingObjectType
    MovementState "1" *-- "1" GeoPosition
    MovementState "1" *-- "1" Velocity
```

## 3. 数据结构详解

### 3.1 基础抽象类 - MovingObject

`MovingObject` 是系统中所有移动物体的基类，定义了共有属性：

- **currentPosition**: 当前地理位置，使用 `GeoPosition` 类表示，包含经度、纬度和高度信息
- **velocity**: 局部坐标系位置消息（xy坐标、速度等等），使用 `Velocity` 类表示，包含三维速度向量
- **heading**: 航向角度，以度为单位
- **timestamp**: 时间戳，表示数据最后更新时间
- **stateHistory**: 历史状态队列，存储 `MovementState` 对象，用于轨迹分析
- **MAX_HISTORY**: 历史记录最大保存数量，默认为30
- **maxSpeed**: 最大速度限制
- **type**: 移动物体类型，使用 `MovingObjectType` 枚举

### 3.2 具体移动物体类型

系统实现了三种具体的移动物体类型，它们都继承自 `MovingObject` 抽象类：

#### 3.2.1 航空器 (Aircraft)

航空器特有属性：
- **flightNo**: 航班号，字符串类型，用于唯一标识航班
- **trackNumber**: 航迹号，长整型，用于雷达跟踪标识

构造函数接收位置参数（纬度、经度、高度）和时间戳，初始化基类属性。

#### 3.2.2 特勤车辆 (SpecialVehicle)

特勤车辆特有属性：
- **vehicleNo**: 车牌号，字符串类型，用于唯一标识车辆

构造函数接收位置参数（纬度、经度）、时间戳、速度和方向，并据此计算速度向量。特勤车辆被标记为"不可控"对象，表示系统只能监控而不能控制其行为。

#### 3.2.3 无人车 (UnmannedVehicle)

无人车特有属性：
- **transId**: 消息唯一ID，用于消息跟踪
- **vehicleId**: 车辆ID，用于唯一标识无人车

构造函数接收位置参数（经度、纬度）、航向和速度，并据此计算速度向量。无人车被标记为"可控"对象，表示系统可以向其发送控制指令。

### 3.3 辅助数据结构

#### 3.3.1 地理位置 - GeoPosition

`GeoPosition` 表示三维空间中的位置：
- **latitude**: 纬度，单位为度
- **longitude**: 经度，单位为度
- **altitude**: 高度，单位为米

#### 3.3.2 速度 - Velocity

`Velocity` 描述局部坐标系的位置消息：
- **x, y, z**: 三维坐标系中的位置
- **vx, vy, vz**: 三个方向上的速度分量，单位为米/秒
- **confidence**: 速度计算置信度，取值范围0-1
- **cachedAcceleration**: 加速度计算结果缓存
- **getSpeed()**: 计算速度标量的方法

#### 3.3.3 运动状态 - MovementState

`MovementState` 封装了移动物体在特定时刻的完整状态：
- **position**: 地理位置，GeoPosition类型
- **velocity**: 局部坐标系的位置消息，Velocity类型
- **heading**: 航向，度数
- **timestamp**: 时间戳
- **dataQuality**: 数据质量枚举，表示数据可靠性

#### 3.3.4 移动物体类型 - MovingObjectType

`MovingObjectType` 是一个枚举类型，定义了系统支持的移动物体类型：
- **AIRCRAFT**: 航空器（飞机）
- **SPECIAL_VEHICLE**: 特勤车辆（不可控）
- **UNMANNED_VEHICLE**: 无人车（可控）

### 3.4 静态环境数据结构 - 道路网络

除了移动物体，系统还需要处理静态环境信息，特别是机场的道路网络。相关数据结构位于 `com.dongni.collisionavoidance.roads.model` 包下。

#### 3.4.1 道路信息 - RoadInfo

`RoadInfo` 类封装了系统运行时使用的单条道路信息。它由 `RoadNetworkService` 在初始化时根据配置文件 (`airport_roads.yaml`) 创建，包含处理后的属性和用于空间计算的 JTS 几何对象。关键属性包括：

- **id**: 道路的唯一标识符 (String)。
- **name**: 道路名称 (String)。
- **speedLimitMetersPerSecond**: 该道路的限速，已统一为米/秒 (Double)。
- **directionality**: 道路方向性，使用 `RoadDirectionality` 枚举表示。
- **heightLimitMeters**, **widthLimitMeters**: 限高和限宽，已统一为米 (Double)。
- **prohibited**: 是否禁止通行 (boolean)。
- **centerline**: 道路中心线的 JTS `LineString` 对象，用于路径分析和距离计算。
- **boundary**: 道路边界范围的 JTS `Polygon` 对象，通过对中心线进行缓冲计算得到，用于判断车辆是否在道路上。
- **relatedZones**: 与该道路关联的区域 ID 列表 (List<String>)。

#### 3.4.2 道路方向性 - RoadDirectionality

`RoadDirectionality` 是一个枚举类型，定义了道路的通行方向：

- **ONE_WAY**: 单向通行。
- **TWO_WAY**: 双向通行。
- **UNKNOWN**: 未知或未指定。

## 4. 数据流转机制

### 4.1 历史状态存储机制

每个 `MovingObject` 对象维护一个 `stateHistory` 队列，用于存储历史状态：

1. 当对象位置或速度更新时，系统创建新的 `MovementState` 对象
2. 新的状态对象被添加到 `stateHistory` 队列
3. 如果队列长度超过 `MAX_HISTORY`（默认30），最旧的记录会被移除
4. 历史记录用于轨迹分析、异常检测和预测计算

```mermaid
sequenceDiagram
    participant 系统
    participant MovingObject
    participant stateHistory队列
    
    系统->>MovingObject: 更新位置和速度
    MovingObject->>MovingObject: 创建MovementState对象
    MovingObject->>stateHistory队列: 添加新状态记录
    
    alt 队列长度 > MAX_HISTORY
        stateHistory队列->>stateHistory队列: 移除最旧记录
    end
```