QDAirPortBackend0122/docs/superpowers/plans/2026-04-17-collision-registration-and-thresholds.md

Collision Registration And Thresholds Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make collision participation follow full-sync registration semantics, expose current crossing thresholds for现场排查, and relax route deviation tolerance so near-route equipment is still evaluated.

Architecture: Keep the current periodic detection loop intact and make the behavior clearer at the boundaries: registration remains the source of truth, the preparation/status API exposes current threshold values, and path-conflict detection accepts a wider route deviation before dropping a pair. This stays inside the existing controller/runtime-state/detection services to avoid spreading new concepts.

Tech Stack: Spring Boot, JUnit 5, MockMvc, Mockito, JTS

---

Task 1: Lock Expected API Behavior With Tests

Files:

• Modify: qaup-collision/src/test/java/com/qaup/collision/controller/PlatformIntegrationControllerTest.java

• Step 1: Write the failing test

@Test
void shouldExposeCurrentCrossingThresholdsInPreparationStatus() throws Exception {
    mockMvc.perform(post("/api/collision/preparation/status"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.thresholds.vehicleDistance").value(40.0))
        .andExpect(jsonPath("$.thresholds.aircraftDistance").value(40.0));
}

• Step 2: Run test to verify it fails

Run: mvn -pl qaup-collision -Dtest=PlatformIntegrationControllerTest#shouldExposeCurrentCrossingThresholdsInPreparationStatus test Expected: FAIL because $.thresholds.vehicleDistance does not exist yet

• Step 3: Write minimal implementation

Map<String, Object> thresholds = new LinkedHashMap<>();
thresholds.put("vehicleDistance", platformRuntimeStateService.getCollisionDivergingReleaseDistanceForVehicle());
thresholds.put("aircraftDistance", platformRuntimeStateService.getCollisionDivergingReleaseDistanceForAircraft());
payload.put("thresholds", thresholds);

• Step 4: Run test to verify it passes

Run: mvn -pl qaup-collision -Dtest=PlatformIntegrationControllerTest#shouldExposeCurrentCrossingThresholdsInPreparationStatus test Expected: PASS

• Step 5: Commit

git add qaup-collision/src/test/java/com/qaup/collision/controller/PlatformIntegrationControllerTest.java qaup-collision/src/main/java/com/qaup/collision/controller/PlatformIntegrationController.java
git commit -m "feat: expose collision thresholds in preparation status"

Task 2: Lock Wider Route Participation With Tests

Files:

• Modify: qaup-collision/src/test/java/com/qaup/collision/pathconflict/service/PathConflictDetectionDirectionalTest.java

• Step 1: Write the failing test

@Test
void shouldStillEvaluateConflictWhenAircraftIsWithinTwoHundredMetersOfAssignedRoute() throws Exception {
    // Build intersecting routes, place aircraft 150m off the route, then expect one event.
}

• Step 2: Run test to verify it fails

Run: mvn -pl qaup-collision -Dtest=PathConflictDetectionDirectionalTest#shouldStillEvaluateConflictWhenAircraftIsWithinTwoHundredMetersOfAssignedRoute test Expected: FAIL because no event is published under the current 80m deviation limit

• Step 3: Write minimal implementation

private static final double MAX_ROUTE_DEVIATION_METERS = 200.0;

• Step 4: Run test to verify it passes

Run: mvn -pl qaup-collision -Dtest=PathConflictDetectionDirectionalTest#shouldStillEvaluateConflictWhenAircraftIsWithinTwoHundredMetersOfAssignedRoute test Expected: PASS

• Step 5: Commit

git add qaup-collision/src/test/java/com/qaup/collision/pathconflict/service/PathConflictDetectionDirectionalTest.java qaup-collision/src/main/java/com/qaup/collision/pathconflict/service/PathConflictDetectionService.java
git commit -m "fix: widen route deviation tolerance for collision detection"

Task 3: Verify Full-Sync Registration Still Removes Omitted Objects

Files:

• Modify: qaup-collision/src/test/java/com/qaup/collision/service/PlatformRuntimeStateServiceTest.java

• Step 1: Write the failing test

@Test
void shouldReportRemovedObjectsWhenVehicleRegistryIsResubmitted() {
    // first update with three objects, second update with one object, then assert removed IDs
}

• Step 2: Run test to verify it fails

Run: mvn -pl qaup-collision -Dtest=PlatformRuntimeStateServiceTest#shouldReportRemovedObjectsWhenVehicleRegistryIsResubmitted test Expected: FAIL because the result does not expose removed IDs yet

• Step 3: Write minimal implementation

TreeSet<String> previousVehicleIds = new TreeSet<>(vehicleTypes.keySet());
vehicleTypes.clear();
...
previousVehicleIds.removeAll(vehicleTypes.keySet());
return new VehicleRegistryUpdateResult(..., new ArrayList<>(previousVehicleIds));

• Step 4: Run test to verify it passes

Run: mvn -pl qaup-collision -Dtest=PlatformRuntimeStateServiceTest#shouldReportRemovedObjectsWhenVehicleRegistryIsResubmitted test Expected: PASS

• Step 5: Commit

git add qaup-collision/src/test/java/com/qaup/collision/service/PlatformRuntimeStateServiceTest.java qaup-collision/src/main/java/com/qaup/collision/service/PlatformRuntimeStateService.java qaup-collision/src/main/java/com/qaup/collision/controller/PlatformIntegrationController.java
git commit -m "feat: surface removed objects on registry full sync"

Task 4: Run Focused Verification

Files:

• Modify: None

• Test: qaup-collision/src/test/java/com/qaup/collision/controller/PlatformIntegrationControllerTest.java

• Test: qaup-collision/src/test/java/com/qaup/collision/pathconflict/service/PathConflictDetectionDirectionalTest.java

• Test: qaup-collision/src/test/java/com/qaup/collision/pathconflict/service/PathConflictDetectionServiceRuntimeConfigTest.java

• Test: qaup-collision/src/test/java/com/qaup/collision/service/PlatformRuntimeStateServiceTest.java

• Step 1: Run focused module tests

mvn -pl qaup-collision -Dtest=PlatformIntegrationControllerTest,PathConflictDetectionDirectionalTest,PathConflictDetectionServiceRuntimeConfigTest,PlatformRuntimeStateServiceTest test

• Step 2: Confirm expected result

Expected: BUILD SUCCESS with all targeted tests green

• Step 3: Summarize the operational impact

1. Preparation status now shows current vehicle/aircraft crossing thresholds.
2. Collision detection accepts route offsets up to 200m before dropping the pair.
3. Registry re-submission remains full-sync and now reports which objects were removed.