CollisionAvoidanceSystem/doc/design/road_network_design.md

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

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) 中，以优化空间查询。
  • 提供公共方法用于查询道路信息。
• 主要接口方法签名示例:

  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. 第四阶段（扩展功能）：

   • 道路属性扩展
   • 可视化功能
   • 高级分析功能