# 碰撞避免系统目录结构说明

本文档描述了碰撞避免系统项目的目录结构及各个目录的功能和用途。

## 1. 根目录结构

```
CollisionAvoidanceSystem/
├── doc/                    # 文档目录
├── src/                    # 源代码目录
├── target/                 # 编译输出目录
├── .idea/                  # IDE配置
├── .mvn/                   # Maven包装器配置
├── .git/                   # Git版本控制
├── pom.xml                 # Maven项目配置
├── mvnw / mvnw.cmd         # Maven包装器脚本
├── README.md               # 项目说明
├── VERSION.txt             # 版本信息
├── change_log.md           # 变更日志
├── development_log.md      # 开发日志
├── .gitignore              # Git忽略配置
└── .gitattributes          # Git属性配置
```

## 2. 源代码目录结构 (`src`)

```
src/
├── main/                   # 主要源代码
│   ├── java/               # Java源代码
│   │   └── com/
│   │       └── dongni/
│   │           └── collisionavoidance/    # 应用程序主包
│   └── resources/          # 配置文件和静态资源
│       ├── config/           # 特定配置文件 (如 airport_roads.yaml, airport_areas.yaml)
│       ├── data/             # 数据文件
│       ├── scripts/          # 脚本文件
│       └── static/           # 静态Web资源
└── test/                   # 测试源代码
```

## 3. 应用程序主包结构 (`com.dongni.collisionavoidance`)

```
com.dongni.collisionavoidance/
├── CollisionAvoidanceApplication.java    # 应用程序入口类
├── common/                               # 通用组件目录
│   ├── model/                            # 核心移动对象等数据模型
│   │   ├── base/                         # 基础类和常量
│   │   ├── dto/                          # 数据传输对象
│   │   └── repository/                   # 仓储模式实现
│   └── config/                           # 通用配置 (较少使用，优先模块内配置)
├── config/                               # 应用程序配置
│   ├── properties/                       # 配置属性映射类 (POJOs)
│   ├── RoadNetworkConfig.java            # 道路网络配置加载类
│   ├── AirportAreaConfig.java            # 机场区域配置加载类
│   ├── YamlPropertySourceFactory.java    # YAML加载工厂类
│   ├── RedisConfig.java                  # Redis配置
│   └── ThreadPoolConfig.java             # 线程池配置
├── controller/                           # 控制器层 (REST API)
├── dataCollector/                        # 数据采集模块
│   ├── model/                            # 数据采集相关模型
│   │   └── enums/                        # 枚举类型定义
│   ├── service/                          # 数据采集服务
│   ├── dao/                              # 数据访问对象
│   └── config/                           # 数据采集配置
├── dataProcessing/                       # 数据处理模块
│   ├── service/                          # 数据处理服务
│   └── config/                           # 数据处理配置
├── areas/                                # 新增：机场区域管理模块
│   ├── model/                            # 区域相关数据模型
│   └── service/                          # 区域管理服务
├── roads/                                # 道路网络模块
│   ├── model/                            # 道路网络运行时模型
│   └── service/                          # 道路网络服务
└── webSocket/                            # WebSocket通信模块
    ├── controller/                       # WebSocket控制器
    └── config/                           # WebSocket配置
```

## 4. 数据模型目录

### 4.1 通用数据模型 (`common/model`)

包含系统核心的、跨模块共享的数据结构：

```
common/model/
├── Aircraft.java                         # 航空器实体类
├── GeoPosition.java                      # 地理位置数据结构
├── MovementState.java                    # 移动状态封装
├── MovingObject.java                     # 移动物体抽象基类
├── MovingObjectType.java                 # 移动物体类型枚举
├── PositionRecord.java                   # 位置记录
├── SpecialVehicle.java                   # 特勤车辆实体类
├── UnmannedVehicle.java                  # 无人车实体类
├── Velocity.java                         # 速度和局部坐标系信息
├── base/                                 # 基础类和常量
│   ├── Constant.java                     # 系统常量定义
│   └── Response.java                     # 统一响应格式
├── dto/                                  # 数据传输对象
│   ├── AircraftDTO.java                  # 航空器数据传输对象
│   └── SpecialVehicleDTO.java            # 特勤车辆数据传输对象
└── repository/                           # 仓储模式实现
    └── MovingObjectRepository.java       # 移动物体仓储接口
```

### 4.2 机场区域数据模型 (`areas/model`)

包含机场区域管理模块的数据结构：

```
areas/model/
├── AreaInfo.java                         # 区域信息实体类 (含JTS几何对象)
└── AreaType.java                         # 区域类型枚举
```

### 4.3 道路网络数据模型 (`roads/model`)

包含道路网络模块内部使用的运行时数据结构：

```
roads/model/
├── RoadInfo.java                         # 运行时道路信息 (含JTS对象)
└── RoadDirectionality.java              # 道路方向枚举
```

### 4.4 数据采集模型 (`dataCollector/model`)

包含数据采集模块的专用数据结构：

```
dataCollector/model/
├── CommandResponse.java                  # 命令响应
├── VehicleCommand.java                   # 车辆命令
├── VehicleLocationInfo.java              # 车辆位置信息
├── VehicleStateInfo.java                 # 车辆状态信息
└── enums/                                # 枚举类型定义
    ├── CommandReason.java                # 命令原因枚举
    ├── CommandType.java                  # 命令类型枚举
    └── SignalState.java                  # 信号状态枚举
```

## 5. 配置属性类目录 (`config/properties`)

包含用于绑定配置文件的POJO类：

```
config/properties/
├── AirportAreasProperties.java           # 机场区域配置属性
├── AirportRoadsProperties.java           # 机场道路配置属性
├── AreaProperties.java                   # 单个区域配置属性
├── DimensionValue.java                   # 尺寸值配置
├── GeometryProperties.java               # 几何图形配置属性
└── RoadProperties.java                   # 单个道路配置属性
```

## 6. 资源文件目录 (`resources`)

```
resources/
├── application.yml                       # 主配置文件
├── config/                               # 特定配置文件目录
│   ├── airport_areas.yaml               # 机场区域配置
│   ├── airport_roads.yaml               # 机场道路配置
│   └── airport_zones.yaml               # 机场区域配置
├── data/                                 # 数据文件目录
├── scripts/                              # 脚本文件目录
└── static/                               # 静态Web资源
    ├── index.html                        # 主页面
    ├── geoposition-test.html             # 地理位置测试页面
    └── js/                               # JavaScript文件
```

## 7. 各模块功能说明

### 7.1 通用数据模型 (common/model)

数据模型模块定义了系统中使用的所有数据结构：

- **MovingObject**: 所有移动物体的抽象基类，定义共有属性和行为
- **Aircraft**: 代表航空器的具体实现类
- **SpecialVehicle**: 代表特勤车辆的具体实现类
- **UnmannedVehicle**: 代表无人车的具体实现类
- **GeoPosition**: 表示地理位置的数据结构
- **Velocity**: 表示速度和局部坐标系位置信息的数据结构
- **MovementState**: 封装移动物体在特定时刻的完整状态
- **MovingObjectType**: 定义了系统支持的移动物体类型的枚举
- **base/**: 包含系统基础类和常量定义
- **dto/**: 包含数据传输对象，用于API交互
- **repository/**: 包含仓储模式实现，提供数据访问抽象

### 7.2 机场区域管理模块 (areas)

**新增模块**，负责管理机场内各种功能区域的边界、权限和规则：

- **areas/model**: 定义区域信息数据结构，包含JTS几何对象用于空间计算
- **areas/service**: 提供`AirportAreaService`，负责：
  - 加载`airport_areas.yaml`配置文件
  - 构建空间索引以支持高效的几何查询
  - 提供区域查询接口（根据位置查找包含区域、获取限速等）
  - 支持区域权限验证和时间有效性检查
  - 使用JTS库进行复杂的空间几何计算

### 7.3 数据采集模块 (dataCollector)

负责从各种数据源获取移动物体的实时位置和状态信息：

- **model/**: 包含数据采集专用的数据结构
  - 车辆位置信息、状态信息、命令响应等
  - 枚举类型定义（命令类型、信号状态等）
- **service/**: 数据采集服务实现
- **dao/**: 数据访问对象，处理外部数据源交互
- **config/**: 数据采集相关配置

支持的数据源：
- 航空器数据采集（ADS-B、雷达等）
- 特勤车辆数据采集（GPS、地面雷达等）
- 无人车数据采集（车载传感器等）

### 7.4 数据处理模块 (dataProcessing)

处理和分析采集到的数据：

- 轨迹计算和预测
- 碰撞风险评估
- 数据质量检查和过滤
- 历史数据管理和分析

### 7.5 控制器层 (controller)

提供RESTful API接口，用于：

- 数据查询和检索
- 系统配置和管理
- 状态报告和监控

### 7.6 WebSocket模块 (webSocket)

提供实时通信功能：

- 推送实时位置更新
- 发送碰撞警告
- 支持客户端实时监控

### 7.7 配置模块 (config)

包含应用程序的配置类和配置加载机制：

- **config/properties**: 存放用于绑定配置文件的POJO类，支持：
  - 机场区域配置绑定（`AirportAreasProperties`、`AreaProperties`）
  - 道路网络配置绑定（`AirportRoadsProperties`、`RoadProperties`）
  - 几何图形配置绑定（`GeometryProperties`、`DimensionValue`）
- 系统参数配置、Bean配置（如`RedisConfig`、`ThreadPoolConfig`）
- 特定配置加载器（如`RoadNetworkConfig`、`AirportAreaConfig`、`YamlPropertySourceFactory`）
- 服务注册、安全、数据库连接等配置

### 7.8 道路网络模块 (roads)

负责管理和查询机场静态道路网络信息：

- **roads/model**: 定义运行时的道路数据结构（`RoadInfo`），包含JTS几何对象和处理过的属性
- **roads/service**: 提供`RoadNetworkService`，负责加载`airport_roads.yaml`配置，初始化道路数据和空间索引，并提供查询接口（如根据位置查找道路、获取限速等）

## 8. 文档目录 (doc)

包含系统相关的设计文档和说明文档：

```
doc/
├── design_document.md          # 系统数据结构设计文档
├── directory_structure.md      # 目录结构说明文档（本文档）
├── cad_to_yaml_guide.md        # CAD转YAML操作指南
└── road_network_design.md      # 道路网络配置集成设计方案
```

## 9. 主要技术特性

### 9.1 空间计算能力
- 使用JTS（Java Topology Suite）库进行复杂的空间几何计算
- 支持多边形区域定义和点包含查询
- 构建空间索引（STRtree）以提高查询性能

### 9.2 配置管理
- 支持YAML格式的配置文件
- 使用Spring Boot配置属性绑定机制
- 模块化配置设计，支持独立的配置文件管理

### 9.3 数据模型设计
- 采用继承和组合的面向对象设计
- 支持DTO模式进行数据传输
- 实现仓储模式进行数据访问抽象

### 9.4 实时通信
- WebSocket支持实时数据推送
- Redis缓存支持高性能数据访问
- 线程池配置支持并发处理 