Shipment Transportation Service - Full Business Capabilities & Domain Architecture

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
@DomainService
public class RateShoppingService {

    public ShippingRate selectOptimalRate(
        ShipmentRequest request,
        RateSelectionStrategy strategy
    ) {
        // Get rates from all carriers
        List<CarrierRate> rates = carriers.parallelStream()
            .filter(carrier -> carrier.supportsServiceArea(request.getDestination()))
            .map(carrier -> carrier.getRate(request))
            .filter(Objects::nonNull)
            .collect(Collectors.toList());

        // Apply business rules
        rates = applyBusinessRules(rates, request);

        // Score each rate
        List<ScoredRate> scoredRates = rates.stream()
            .map(rate -> scoreRate(rate, request, strategy))
            .sorted(Comparator.comparing(ScoredRate::getScore).reversed())
            .collect(Collectors.toList());

        // Select best rate
        ScoredRate selected = scoredRates.get(0);

        // Record decision
        recordRateSelection(request, scoredRates, selected);

        return selected.getRate();
    }

    private ScoredRate scoreRate(
        CarrierRate rate,
        ShipmentRequest request,
        RateSelectionStrategy strategy
    ) {
        RateScore score = RateScore.builder()
            .costScore(calculateCostScore(rate, request))
            .speedScore(calculateSpeedScore(rate, request))
            .reliabilityScore(getCarrierReliability(rate.getCarrier()))
            .capacityScore(getCarrierCapacity(rate.getCarrier()))
            .build();

        return new ScoredRate(
            rate,
            strategy.calculateWeightedScore(score)
        );
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@Service
public class LabelGenerationService {

    private final Map<CarrierType, LabelGenerator> generators;

    public ShippingLabel generateLabel(
        Shipment shipment,
        LabelFormat format
    ) {
        // Select appropriate generator
        LabelGenerator generator = generators.get(
            shipment.getCarrier().getType()
        );

        // Validate shipment data
        ValidationResult validation = generator.validate(shipment);
        if (!validation.isValid()) {
            throw new LabelGenerationException(validation.getErrors());
        }

        // Generate label via carrier API
        CarrierLabelResponse response = generator.createLabel(
            mapToCarrierRequest(shipment)
        );

        // Store label
        ShippingLabel label = ShippingLabel.builder()
            .shipmentId(shipment.getId())
            .trackingNumber(response.getTrackingNumber())
            .labelData(response.getLabelData())
            .format(format)
            .cost(response.getCost())
            .createdAt(LocalDateTime.now())
            .build();

        labelRepository.save(label);

        // Publish event
        eventPublisher.publish(new LabelGeneratedEvent(label));

        return label;
    }

    public void voidLabel(String trackingNumber, String reason) {
        ShippingLabel label = labelRepository.findByTrackingNumber(trackingNumber);

        // Check if can be voided
        if (!label.canVoid()) {
            throw new LabelVoidException("Label already in transit");
        }

        // Void with carrier
        LabelGenerator generator = generators.get(label.getCarrier());
        generator.voidLabel(trackingNumber);

        // Update status
        label.void(reason);
        labelRepository.save(label);

        // Publish event
        eventPublisher.publish(new LabelVoidedEvent(label, reason));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
@Component
public class ShipmentTrackingService {

    @Scheduled(fixedDelay = 300000) // Every 5 minutes
    public void updateTracking() {
        List<Shipment> activeShipments = shipmentRepository
            .findByStatus(ShipmentStatus.IN_TRANSIT);

        activeShipments.parallelStream()
            .forEach(this::updateShipmentTracking);
    }

    private void updateShipmentTracking(Shipment shipment) {
        try {
            // Get tracking from carrier
            TrackingInfo tracking = carrierAdapters
                .get(shipment.getCarrier())
                .getTracking(shipment.getTrackingNumber());

            // Normalize events
            List<TrackingEvent> normalizedEvents = normalizeEvents(
                tracking.getEvents(),
                shipment.getCarrier()
            );

            // Detect status changes
            TrackingStatus newStatus = determineStatus(normalizedEvents);

            if (hasStatusChanged(shipment, newStatus)) {
                // Update shipment
                shipment.updateTracking(newStatus, normalizedEvents);
                shipmentRepository.save(shipment);

                // Publish events
                publishTrackingEvents(shipment, newStatus);

                // Send notifications
                notificationService.sendTrackingUpdate(shipment);
            }

            // Check for exceptions
            detectAndHandleExceptions(shipment, normalizedEvents);

        } catch (Exception e) {
            log.error("Failed to update tracking for {}",
                shipment.getTrackingNumber(), e);
        }
    }

    private void detectAndHandleExceptions(
        Shipment shipment,
        List<TrackingEvent> events
    ) {
        events.stream()
            .filter(TrackingEvent::isException)
            .forEach(event -> {
                ShipmentException exception = ShipmentException.builder()
                    .shipmentId(shipment.getId())
                    .type(event.getExceptionType())
                    .description(event.getDescription())
                    .severity(calculateSeverity(event))
                    .suggestedAction(determineSuggestedAction(event))
                    .build();

                exceptionService.handleException(exception);
            });
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
public interface CarrierAdapter {
    CarrierRate getRate(ShipmentRequest request);
    ShippingLabel createLabel(LabelRequest request);
    void voidLabel(String trackingNumber);
    TrackingInfo getTracking(String trackingNumber);
    PickupConfirmation schedulePickup(PickupRequest request);
    boolean isAvailable();
}

@Component
public class FedExAdapter implements CarrierAdapter {

    private final FedExClient fedexClient;
    private final CircuitBreaker circuitBreaker;

    @Override
    public CarrierRate getRate(ShipmentRequest request) {
        return circuitBreaker.executeSupplier(() -> {
            FedExRateRequest fedexRequest = mapToFedExRequest(request);
            FedExRateResponse response = fedexClient.rate(fedexRequest);
            return mapToCarrierRate(response);
        });
    }

    @Override
    public ShippingLabel createLabel(LabelRequest request) {
        // Implementation with retry logic
        return Retry.decorateSupplier(retry, () -> {
            FedExShipRequest fedexRequest = mapToFedExShipRequest(request);
            FedExShipResponse response = fedexClient.ship(fedexRequest);
            return mapToShippingLabel(response);
        }).get();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
@Service
public class RateOptimizationEngine {

    public OptimalRate findOptimalRate(
        ShipmentRequest request,
        OptimizationCriteria criteria
    ) {
        // Step 1: Determine eligible carriers
        List<Carrier> eligibleCarriers = carrierSelector
            .getEligibleCarriers(request);

        // Step 2: Get rates in parallel
        Map<Carrier, List<CarrierRate>> ratesByCarrier =
            eligibleCarriers.parallelStream()
                .collect(Collectors.toMap(
                    carrier -> carrier,
                    carrier -> getRatesWithCache(carrier, request)
                ));

        // Step 3: Apply filters
        List<CarrierRate> filteredRates = ratesByCarrier.values().stream()
            .flatMap(List::stream)
            .filter(rate -> meetsRequirements(rate, request))
            .collect(Collectors.toList());

        // Step 4: Calculate total cost including accessorials
        List<EnrichedRate> enrichedRates = filteredRates.stream()
            .map(rate -> enrichRate(rate, request))
            .collect(Collectors.toList());

        // Step 5: Score and rank
        List<ScoredRate> scoredRates = enrichedRates.stream()
            .map(rate -> scoreRate(rate, criteria))
            .sorted(Comparator.comparing(ScoredRate::getScore).reversed())
            .collect(Collectors.toList());

        // Step 6: Select optimal
        return selectOptimal(scoredRates, criteria);
    }

    private EnrichedRate enrichRate(CarrierRate base, ShipmentRequest request) {
        Money totalCost = base.getBaseCost();

        // Add residential surcharge
        if (request.getDestination().isResidential()) {
            totalCost = totalCost.add(base.getResidentialSurcharge());
        }

        // Add fuel surcharge
        totalCost = totalCost.add(
            calculateFuelSurcharge(base, currentFuelRate())
        );

        // Add dimensional weight if applicable
        if (isDimensionalWeight(request.getPackage())) {
            totalCost = totalCost.add(base.getDimensionalSurcharge());
        }

        // Add peak season surcharge
        if (isPeakSeason()) {
            totalCost = totalCost.add(base.getPeakSurcharge());
        }

        return new EnrichedRate(base, totalCost, calculateTransitDays(base));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Component
public class ZoneSkippingOptimizer {

    public ZoneSkipStrategy optimize(List<Shipment> shipments) {
        // Group by destination zone
        Map<Zone, List<Shipment>> byZone = shipments.stream()
            .collect(Collectors.groupingBy(
                s -> zoneCalculator.calculate(s.getDestination())
            ));

        // Analyze consolidation opportunities
        List<ConsolidationOpportunity> opportunities = byZone.entrySet().stream()
            .map(entry -> analyzeConsolidation(entry.getKey(), entry.getValue()))
            .filter(ConsolidationOpportunity::isViable)
            .collect(Collectors.toList());

        // Calculate savings
        return opportunities.stream()
            .map(this::calculateStrategy)
            .max(Comparator.comparing(ZoneSkipStrategy::getSavings))
            .orElse(ZoneSkipStrategy.none());
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
@Service
@Transactional
public class LabelService {

    public ShippingLabel generateLabel(
        Shipment shipment,
        LabelOptions options
    ) {
        // Validate shipment
        validateShipment(shipment);

        // Check for existing label
        if (shipment.hasLabel() && !options.isForceRegenerate()) {
            throw new LabelAlreadyExistsException(shipment.getTrackingNumber());
        }

        // Get carrier adapter
        CarrierAdapter adapter = carrierAdapterFactory.get(shipment.getCarrier());

        // Build request
        LabelRequest request = LabelRequest.builder()
            .shipFrom(shipment.getOrigin())
            .shipTo(shipment.getDestination())
            .packages(shipment.getPackages())
            .serviceType(shipment.getServiceLevel())
            .labelFormat(options.getFormat())
            .reference1(shipment.getOrderId())
            .reference2(shipment.getShipmentId())
            .build();

        // Add special services
        if (shipment.requiresSignature()) {
            request.addSpecialService(SpecialService.SIGNATURE_REQUIRED);
        }
        if (shipment.hasInsurance()) {
            request.addSpecialService(SpecialService.INSURANCE);
            request.setInsuranceAmount(shipment.getInsuranceAmount());
        }

        // Generate label
        LabelResponse response = adapter.createLabel(request);

        // Store label
        ShippingLabel label = ShippingLabel.builder()
            .shipmentId(shipment.getId())
            .trackingNumber(response.getTrackingNumber())
            .carrier(shipment.getCarrier())
            .labelData(response.getLabelData())
            .format(options.getFormat())
            .cost(response.getCost())
            .status(LabelStatus.ACTIVE)
            .build();

        labelRepository.save(label);

        // Update shipment
        shipment.assignLabel(label);
        shipmentRepository.save(shipment);

        // Publish event
        eventPublisher.publish(new LabelGeneratedEvent(shipment, label));

        return label;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@Component
public class TrackingOrchestrator {

    @EventListener
    public void handleCarrierWebhook(CarrierTrackingWebhook webhook) {
        // Process immediately for real-time updates
        processTrackingUpdate(webhook.getTrackingNumber(), webhook.getEvents());
    }

    @Scheduled(cron = "0 */15 * * * *") // Every 15 minutes
    public void pollActiveShipments() {
        List<Shipment> activeShipments = shipmentRepository
            .findByStatusIn(TRACKABLE_STATUSES);

        // Batch by carrier for efficiency
        Map<Carrier, List<Shipment>> byCarrier = activeShipments.stream()
            .collect(Collectors.groupingBy(Shipment::getCarrier));

        byCarrier.forEach(this::batchUpdateTracking);
    }

    private void processTrackingUpdate(
        String trackingNumber,
        List<CarrierEvent> events
    ) {
        Shipment shipment = shipmentRepository.findByTrackingNumber(trackingNumber);

        // Normalize events
        List<TrackingEvent> normalized = eventNormalizer.normalize(
            events,
            shipment.getCarrier()
        );

        // Update tracking history
        TrackingHistory history = shipment.getTrackingHistory();
        normalized.forEach(history::addEvent);

        // Determine new status
        ShipmentStatus newStatus = statusResolver.resolve(normalized);

        if (shipment.getStatus() != newStatus) {
            shipment.updateStatus(newStatus);

            // Handle status-specific actions
            handleStatusChange(shipment, newStatus);
        }

        // Check for delivery
        if (newStatus == ShipmentStatus.DELIVERED) {
            handleDelivery(shipment, normalized);
        }

        shipmentRepository.save(shipment);
    }

    private void handleDelivery(Shipment shipment, List<TrackingEvent> events) {
        TrackingEvent deliveryEvent = events.stream()
            .filter(e -> e.getType() == EventType.DELIVERED)
            .findFirst()
            .orElseThrow();

        ProofOfDelivery pod = ProofOfDelivery.builder()
            .shipmentId(shipment.getId())
            .deliveredAt(deliveryEvent.getTimestamp())
            .signedBy(deliveryEvent.getSignature())
            .location(deliveryEvent.getLocation())
            .photo(deliveryEvent.getPhotoUrl())
            .build();

        proofOfDeliveryRepository.save(pod);

        eventPublisher.publish(new ShipmentDeliveredEvent(shipment, pod));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
@Service
public class InternationalShippingService {

    public InternationalShipment prepareInternationalShipment(
        Shipment shipment,
        CustomsInfo customsInfo
    ) {
        // Validate international requirements
        validateInternationalShipment(shipment, customsInfo);

        // Generate commercial invoice
        CommercialInvoice invoice = generateCommercialInvoice(
            shipment,
            customsInfo
        );

        // Generate customs forms based on destination
        List<CustomsForm> forms = new ArrayList<>();

        if (requiresCN22(shipment.getDestination())) {
            forms.add(generateCN22(shipment, customsInfo));
        }

        if (requiresEEI(shipment.getDestination(), customsInfo.getValue())) {
            forms.add(generateEEI(shipment, customsInfo));
        }

        // Calculate duties and taxes
        DutiesAndTaxes duties = calculateDuties(
            shipment,
            customsInfo,
            shipment.getDestination().getCountry()
        );

        return InternationalShipment.builder()
            .shipment(shipment)
            .commercialInvoice(invoice)
            .customsForms(forms)
            .duties(duties)
            .build();
    }
}