ECOTRACK-1: Green Route Advisor: pre-shipment scenario comparison

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [2026-05-20]
+
+### Added
+- Green Route Advisor v1 scenario comparison endpoint: `POST /api/v1/shipments/compare`.
+- Scenario comparison DTOs for request/response payloads:
+  - `backend/src/main/java/com/ecotrack/dto/ScenarioComparisonRequestDTO.java`
+  - `backend/src/main/java/com/ecotrack/dto/ScenarioComparisonResponseDTO.java`
+  - `backend/src/main/java/com/ecotrack/dto/ScenarioInputDTO.java`
+  - `backend/src/main/java/com/ecotrack/dto/ScenarioResultDTO.java`
+- Shipment Hub UI support for side-by-side estimated scenario comparison and preferred scenario highlighting.
+- Client-side Shipment Hub status filter behavior and empty-state handling.
+
+### Changed
+- Shipment service now compares at least two scenarios using existing `SustainabilityService` logic, with explicit rule `MIN_ESTIMATED_CO2E` and methodology version `GLEC Framework v3`.
+- Shipment Hub status filter resets to `All Statuses` after creating a shipment.
+
+### Known Limitations
+- Full project frontend lint remains blocked by pre-existing issues outside feature scope.
+- Backend test execution in this environment is blocked by local Java compiler/toolchain initialization error.

backend/src/main/java/com/ecotrack/controller/ShipmentController.java

@@ -2,6 +2,8 @@
 
 import com.ecotrack.dto.ShipmentDTO;
 import com.ecotrack.dto.ShipmentDetailDTO;
+import com.ecotrack.dto.ScenarioComparisonRequestDTO;
+import com.ecotrack.dto.ScenarioComparisonResponseDTO;
 import com.ecotrack.model.enums.ShipmentStatus;
 import com.ecotrack.service.ShipmentService;
 import lombok.RequiredArgsConstructor;
@@ -53,4 +55,9 @@ public ShipmentDTO updateStatus(@PathVariable UUID id, @RequestBody Map<String,
     public List<ShipmentDTO> getLive() {
         return shipmentService.getLive();
     }
+
+    @PostMapping("/compare")
+    public ScenarioComparisonResponseDTO compare(@RequestBody ScenarioComparisonRequestDTO request) {
+        return shipmentService.compareScenarios(request.getScenarios());
+    }
 }

backend/src/main/java/com/ecotrack/dto/ScenarioComparisonRequestDTO.java

@@ -0,0 +1,10 @@
+package com.ecotrack.dto;
+
+import lombok.Data;
+
+import java.util.List;
+
+@Data
+public class ScenarioComparisonRequestDTO {
+    private List<ScenarioInputDTO> scenarios;
+}

backend/src/main/java/com/ecotrack/dto/ScenarioComparisonResponseDTO.java

@@ -0,0 +1,15 @@
+package com.ecotrack.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+@Data
+@Builder
+public class ScenarioComparisonResponseDTO {
+    private String preferredScenario;
+    private String rankingRule;
+    private String methodologyVersion;
+    private List<ScenarioResultDTO> scenarios;
+}

backend/src/main/java/com/ecotrack/dto/ScenarioInputDTO.java

@@ -0,0 +1,16 @@
+package com.ecotrack.dto;
+
+import lombok.Data;
+
+import java.util.UUID;
+
+@Data
+public class ScenarioInputDTO {
+    private String name;
+    private String origin;
+    private String destination;
+    private Double distanceKm;
+    private Double payloadTons;
+    private String transportMode;
+    private UUID vehicleId;
+}

backend/src/main/java/com/ecotrack/dto/ScenarioResultDTO.java

@@ -0,0 +1,19 @@
+package com.ecotrack.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+public class ScenarioResultDTO {
+    private String scenario;
+    private String origin;
+    private String destination;
+    private String transportMode;
+    private Double distanceKm;
+    private Double payloadTons;
+    private String vehicleModel;
+    private Double estimatedCo2;
+    private String estimateLabel;
+    private boolean preferred;
+}

backend/src/main/java/com/ecotrack/service/ShipmentService.java

@@ -2,11 +2,15 @@
 
 import com.ecotrack.dto.ShipmentDTO;
 import com.ecotrack.dto.ShipmentDetailDTO;
+import com.ecotrack.dto.ScenarioComparisonResponseDTO;
+import com.ecotrack.dto.ScenarioInputDTO;
+import com.ecotrack.dto.ScenarioResultDTO;
 import com.ecotrack.model.EmissionLog;
 import com.ecotrack.model.Shipment;
 import com.ecotrack.model.Vehicle;
 import com.ecotrack.model.enums.FuelType;
 import com.ecotrack.model.enums.ShipmentStatus;
+import com.ecotrack.model.enums.TransportMode;
 import com.ecotrack.repository.EmissionLogRepository;
 import com.ecotrack.repository.ShipmentRepository;
 import com.ecotrack.repository.VehicleRepository;
@@ -19,6 +23,8 @@
 import java.time.LocalDateTime;
 import java.util.List;
 import java.util.UUID;
+import java.util.Comparator;
+import java.util.Objects;
 import java.util.stream.Collectors;
 
 @Service
@@ -99,6 +105,75 @@ public List<ShipmentDTO> getLive() {
                 .stream().map(this::toDTO).collect(Collectors.toList());
     }
 
+    public ScenarioComparisonResponseDTO compareScenarios(List<ScenarioInputDTO> scenarios) {
+        if (scenarios == null || scenarios.size() < 2) {
+            throw new IllegalArgumentException("At least 2 scenarios are required for comparison");
+        }
+
+        List<ScenarioResultDTO> results = scenarios.stream()
+                .map(this::buildScenarioResult)
+                .collect(Collectors.toList());
+
+        ScenarioResultDTO preferred = results.stream()
+                .min(Comparator.comparing(ScenarioResultDTO::getEstimatedCo2))
+                .orElseThrow(() -> new IllegalArgumentException("No scenarios to compare"));
+
+        results.forEach(result -> result.setPreferred(Objects.equals(result.getScenario(), preferred.getScenario())));
+
+        return ScenarioComparisonResponseDTO.builder()
+                .preferredScenario(preferred.getScenario())
+                .rankingRule("MIN_ESTIMATED_CO2E")
+                .methodologyVersion("GLEC Framework v3")
+                .scenarios(results)
+                .build();
+    }
+
+    private ScenarioResultDTO buildScenarioResult(ScenarioInputDTO input) {
+        if (input.getDistanceKm() == null || input.getDistanceKm() <= 0) {
+            throw new IllegalArgumentException("distanceKm must be greater than 0");
+        }
+        if (input.getPayloadTons() == null || input.getPayloadTons() <= 0) {
+            throw new IllegalArgumentException("payloadTons must be greater than 0");
+        }
+        if (input.getVehicleId() == null) {
+            throw new IllegalArgumentException("vehicleId is required");
+        }
+
+        TransportMode mode;
+        try {
+            mode = TransportMode.valueOf(input.getTransportMode().toUpperCase());
+        } catch (Exception ex) {
+            throw new IllegalArgumentException("Unsupported transportMode: " + input.getTransportMode());
+        }
+
+        Vehicle vehicle = vehicleRepository.findById(input.getVehicleId())
+                .orElseThrow(() -> new EntityNotFoundException("Vehicle not found: " + input.getVehicleId()));
+
+        Shipment shipment = Shipment.builder()
+                .origin(input.getOrigin())
+                .destination(input.getDestination())
+                .distanceKm(input.getDistanceKm())
+                .payloadTons(input.getPayloadTons())
+                .transportMode(mode)
+                .vehicle(vehicle)
+                .build();
+
+        double estimate = sustainabilityService.calculateEmissions(shipment, vehicle);
+
+        return ScenarioResultDTO.builder()
+                .scenario(input.getName())
+                .origin(input.getOrigin())
+                .destination(input.getDestination())
+                .transportMode(mode.name())
+                .distanceKm(input.getDistanceKm())
+                .payloadTons(input.getPayloadTons())
+                .vehicleModel(vehicle.getModel())
+                .estimatedCo2(estimate)
+                .estimateLabel("Estimated")
+                .preferred(false)
+                .build();
+    }
+
     // ── Mapping helpers ──────────────────────────────────────────────────────
 
     public ShipmentDTO toDTO(Shipment s) {

docs/green-route-advisor-v1.md

@@ -0,0 +1,57 @@
+# Green Route Advisor v1
+
+## Scope
+Green Route Advisor v1 adds pre-shipment scenario comparison in Shipment Hub while reusing the existing emissions calculation path.
+
+In scope:
+- Compare at least two scenarios side-by-side from planning inputs.
+- Determine preferred scenario by lowest estimated CO2e.
+- Return methodology traceability in API response.
+- Visually mark compared values as `Estimated`.
+
+Out of scope:
+- Any parallel emissions engine or alternate formula path.
+- Multi-objective optimization (cost/time/carbon weighting).
+
+## API Contract
+Endpoint: `POST /api/v1/shipments/compare`
+
+Request body:
+- `scenarios`: array of scenario objects, minimum 2.
+- Scenario fields: `name`, `origin`, `destination`, `distanceKm`, `payloadTons`, `transportMode`, `vehicleId`.
+
+Response body:
+- `preferredScenario`: scenario name with lowest estimated CO2e.
+- `rankingRule`: `MIN_ESTIMATED_CO2E`.
+- `methodologyVersion`: `GLEC Framework v3`.
+- `scenarios`: result array with per-scenario estimate and `estimateLabel` (`Estimated`).
+
+Validation behavior:
+- Rejects requests with fewer than two scenarios.
+- Rejects non-positive `distanceKm` and `payloadTons`.
+- Rejects unsupported `transportMode` values.
+- Rejects unknown `vehicleId` values.
+
+## UI Behavior (Shipment Hub)
+File: `frontend/src/pages/ShipmentHub.jsx`
+
+- Adds a Green Route Advisor compare panel with two scenario inputs.
+- Calls `compareShipmentScenarios` from `frontend/src/api/shipments.js`.
+- Renders side-by-side estimated results and highlights preferred scenario.
+- Shows ranking rule and methodology version returned by backend.
+
+## Related Shipment Hub Fix
+The Shipment Hub status dropdown now:
+- Updates React state on selection.
+- Filters shipment rows client-side (no extra request).
+- Shows an explicit empty state when no rows match.
+- Resets to `All Statuses` after successful shipment creation.
+
+## Verification Status
+Implemented and wired across backend/frontend. Full-suite validation is partially blocked by known pre-existing/global environment issues:
+- Frontend project-wide lint includes unrelated violations in other pages.
+- Backend `mvn test` fails in this environment due to toolchain initialization error.
+
+Targeted validation completed during implementation:
+- Changed Shipment Hub file lint passes.
+- Compare flow wiring and response rendering are implemented and integrated.

frontend/src/api/shipments.js

@@ -19,3 +19,8 @@ export const getLiveShipments = async () => {
   const { data } = await client.get('/shipments/live');
   return data;
 };
+
+export const compareShipmentScenarios = async (scenarios) => {
+  const { data } = await client.post('/shipments/compare', { scenarios });
+  return data;
+};