# 设计方案：机场道路网络配置集成

## 1. 引言

本文档描述了将机场道路网络配置信息（定义在 `src/main/resources/config/airport_roads.yaml` 文件中）加载到碰撞避免系统中，并提供统一接口供其他模块使用的设计方案。目标是实现配置的结构化加载、地理空间表示和便捷查询。

## 2. 设计目标

*   **自动加载**: 在应用程序启动时自动加载并解析 `airport_roads.yaml` 文件。
*   **类型安全**: 将 YAML 配置映射到强类型的 Java 对象。
*   **空间表示**: 使用标准的地理空间库 (JTS) 将道路中心线和边界表示为内存中的几何对象。
*   **统一访问**: 提供一个中心服务 (`RoadNetworkService`) 来封装道路数据的访问逻辑。
*   **高效查询**: 支持根据 ID 获取道路信息，以及基于地理位置（点）查询所在道路及其属性（如限速）。
*   **模块解耦**: 其他模块（如数据处理）通过依赖注入使用服务，无需关心配置文件的具体加载和解析细节。

## 3. 核心组件

1.  **配置属性 POJOs**: 位于 `com.dongni.collisionavoidance.config.properties` 包下，用于映射 `airport_roads.yaml` 文件结构的 Java 类 (如 `AirportRoadsProperties`, `RoadProperties`, `GeometryProperties`, `DimensionValue`)。
2.  **配置加载器**: 位于 `com.dongni.collisionavoidance.config` 包下的 Spring 配置类 (如 `RoadNetworkConfig`) 和辅助类 (`YamlPropertySourceFactory`)，负责指定加载 `airport_roads.yaml` 文件并启用属性绑定到 POJOs。
3.  **运行时数据模型 (`RoadInfo`)**: 位于 `com.dongni.collisionavoidance.roads.model` 包下，包含道路静态属性（ID, name, limits 等，已进行单位转换）以及预处理的 JTS 地理空间对象（`LineString` 类型的 `centerline` 和 `Polygon` 类型的 `boundary`）。
4.  **道路网络服务 (`RoadNetworkService`)**: 位于 `com.dongni.collisionavoidance.roads.service` 包下的 Spring Service Bean，负责初始化和提供道路数据查询。

## 4. 依赖库

*   **Java Topology Suite (JTS)**: `org.locationtech.jts:jts-core:1.19.0` (或最新版)
*   **SnakeYAML**: (通常由 Spring Boot 包含)
*   **Lombok**: (可选)

## 5. 实现细节

### 5.1 配置加载

*   使用 `@PropertySource` 注解配合自定义的 `YamlPropertySourceFactory` 来指定加载 `classpath:config/airport_roads.yaml`。
*   使用 `@EnableConfigurationProperties` 将加载的配置绑定到 `AirportRoadsProperties` POJO 类及其嵌套类。
*   `AirportRoadsProperties` 类使用 `@ConfigurationProperties` (无前缀) 注解。
*   POJO 类结构需与 `airport_roads.yaml` 文件结构精确匹配（字段名、数据类型、列表、嵌套对象）。

### 5.2 运行时数据模型 (`RoadInfo`)

此类应设计为不可变对象 (e.g., 使用 Lombok `@Value` 和 `@Builder`)，包含以下关键信息：

*   `id`: String
*   `name`: String
*   `speedLimitMetersPerSecond`: Double (单位统一为 m/s)
*   `directionality`: Enum (`RoadDirectionality`)
*   `heightLimitMeters`: Double (单位统一为 m)
*   `widthLimitMeters`: Double (单位统一为 m)
*   `prohibited`: boolean
*   `centerline`: `org.locationtech.jts.geom.LineString` (JTS 对象)
*   `boundary`: `org.locationtech.jts.geom.Polygon` (JTS 对象)
*   `relatedZones`: `List<String>`

### 5.3 道路网络服务 (`RoadNetworkService`)

*   **职责**:
    *   注入 `AirportRoadsProperties`。
    *   在初始化阶段 (`@PostConstruct`) 执行以下操作：
        1.  遍历从配置加载的 `RoadProperties` 列表。
        2.  对每个 `RoadProperties`：
            *   使用 JTS `GeometryFactory` 将 `coordinates` 列表转换为 `LineString` 对象 (`centerline`)。
            *   根据 `width` 属性，使用 `LineString.buffer()` 方法计算道路边界 `Polygon` 对象 (`boundary`)。（注意：需要处理米到地理坐标度数的近似转换，或采用投影坐标系进行精确缓冲）。
            *   进行必要的单位转换（如速度 km/h -> m/s，长度单位 -> m）。
            *   解析方向性、禁止通行等属性。
            *   创建 `RoadInfo` 实例。
        3.  将所有创建的 `RoadInfo` 实例存储在内存中的 Map 中 (e.g., `Map<String, RoadInfo>`)，以 `roadId` 为键。
        4.  (推荐) 将所有 `RoadInfo` 的 `boundary` (Polygon) 添加到 JTS 空间索引 (如 `STRtree`) 中，以优化空间查询。
    *   提供公共方法用于查询道路信息。
*   **主要接口方法签名示例**:
    ```java
    public Optional<RoadInfo> getRoadById(String roadId);
    public List<RoadInfo> findRoadsContainingPoint(GeoPosition geoPosition);
    public Optional<RoadInfo> findDominantRoadAt(GeoPosition geoPosition); // 处理点在多条路重叠区域的情况
    public Optional<Double> getSpeedLimitMetersPerSecondAt(GeoPosition geoPosition);
    // ... 其他必要的查询方法 ...
    ```
*   **内部逻辑**:
    *   `findRoadsContainingPoint`: 使用空间索引 (`STRtree.query()`) 粗筛候选道路，然后使用 `Polygon.covers(Point)` 进行精确判断。
    *   包含健壮的单位转换和错误处理逻辑。

### 5.4 在其他模块中使用

*   需要访问道路信息的模块（如 `CollisionDetectionService`）通过 Spring 的依赖注入 (`@Autowired` 或构造函数注入) 获取 `RoadNetworkService` 实例。
*   调用 `RoadNetworkService` 提供的公共方法获取道路属性或执行空间查询。

## 6. 目录结构影响

引入以下新的包和类：

```
src/main/java/com/dongni/collisionavoidance/
├── config/
│   ├── properties/             # 新包：存放配置属性 POJOs
│   │   ├── AirportRoadsProperties.java
│   │   ├── RoadProperties.java
│   │   ├── GeometryProperties.java
│   │   └── DimensionValue.java
│   ├── RoadNetworkConfig.java    # 新类：加载道路配置
│   └── YamlPropertySourceFactory.java # 新类（如果不存在）
├── roads/                      # 新包：道路网络相关
│   ├── model/                  # 新包：运行时道路模型
│   │   ├── RoadInfo.java
│   │   └── RoadDirectionality.java
│   └── service/                # 新包：道路服务
│       └── RoadNetworkService.java
```

## 7. 未来考虑

*   **精确缓冲**: 实现基于 UTM 或其他合适投影坐标系的缓冲计算。
*   **复杂交叉口**: 可能需要更高级的拓扑模型或规则处理。
*   **动态更新**: 考虑配置热加载机制。
*   **单位转换**: 实现更健壮的单位转换库。

## 8. 改进计划

### 8.1 道路网络功能增强

#### 8.1.1 道路拓扑关系管理
* 实现道路连接点(节点)的识别和管理
* 建立道路之间的拓扑关系(相邻、连接等)
* 支持道路网络的路径规划功能
* 实现道路交叉口的特殊处理逻辑

#### 8.1.2 道路属性扩展
* 添加道路类型(跑道、滑行道、服务道路等)
* 增加道路优先级属性
* 支持道路状态(开放、关闭、维护等)
* 添加道路使用时间限制
* 实现道路使用权限管理

#### 8.1.3 空间查询优化
* 改进空间索引实现，使用更高效的索引结构
* 优化缓冲区计算，使用投影坐标系提高精度
* 添加道路相交检测功能
* 实现道路网络的可视化查询
* 支持复杂的空间关系查询

### 8.2 配置管理优化

#### 8.2.1 配置验证增强
* 添加道路配置的完整性检查
* 实现道路几何数据的有效性验证
* 增加配置项的类型检查和范围验证
* 添加道路网络拓扑完整性验证

#### 8.2.2 配置热更新
* 实现配置文件的动态加载
* 支持配置变更的实时生效
* 添加配置变更的事件通知机制
* 实现配置回滚机制

### 8.3 性能优化

#### 8.3.1 空间计算优化
* 优化坐标转换和投影计算
* 改进空间索引的构建和查询性能
* 实现空间计算的缓存机制
* 添加并行计算支持

#### 8.3.2 内存管理优化
* 优化道路数据的存储结构
* 实现数据的懒加载机制
* 添加内存使用监控
* 实现大规模道路网络的分片处理

### 8.4 测试覆盖

#### 8.4.1 单元测试
* 增加道路拓扑关系的测试用例
* 添加配置验证的测试场景
* 完善空间计算的测试覆盖
* 添加边界条件测试

#### 8.4.2 集成测试
* 添加道路网络完整功能的测试
* 实现性能测试场景
* 增加配置热更新的测试用例
* 添加负载测试

### 8.5 文档完善

#### 8.5.1 技术文档
* 更新道路网络设计文档
* 添加配置管理说明
* 完善API文档
* 添加性能优化指南

#### 8.5.2 使用文档
* 添加配置示例
* 提供最佳实践指南
* 编写故障排除指南
* 添加常见问题解答

### 8.6 实施优先级建议

1. 第一阶段（核心功能增强）：
   * 道路拓扑关系管理
   * 空间查询优化
   * 配置验证增强

2. 第二阶段（性能与可靠性）：
   * 空间计算优化
   * 内存管理优化
   * 单元测试覆盖

3. 第三阶段（可维护性）：
   * 配置热更新
   * 文档完善
   * 集成测试

4. 第四阶段（扩展功能）：
   * 道路属性扩展
   * 可视化功能
   * 高级分析功能