214 lines
9.1 KiB
Markdown
214 lines
9.1 KiB
Markdown
# 设计方案：机场道路网络配置集成
|
||
|
||
## 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. 第四阶段（扩展功能）：
|
||
* 道路属性扩展
|
||
* 可视化功能
|
||
* 高级分析功能 |