implement self-healing for freight payment milestones and enhance contract change request visibility

apps/edr-freight-api/src/modules/contracts/clearance-milestone.service.ts

@@ -6,6 +6,7 @@ import {
   CustomsRiskLevel,
   MilestoneMetadata,
 } from './entities/clearance-milestone.entity';
+import { Booking } from '../bookings/entities/booking.entity';
 import { Contract } from './entities/contract.entity';
 import {
   HANDOFF_MILESTONES,
@@ -85,10 +86,36 @@ export class ClearanceMilestoneService {
   }
 
   async listForBooking(bookingId: string): Promise<ClearanceMilestone[]> {
-    return this.repo.find({
+    const rows = await this.repo.find({
       where: { bookingId },
       order: { sortOrder: 'ASC' },
     });
+
+    // Self-heal: a booking that has settled its freight payment must have
+    // FREIGHT_PAYMENT_SETTLED completed. The batch settle path writes it, but an
+    // export FCFS booking (linked to its train at booking time) paid via the
+    // prepaid invoice can leave the milestone PENDING — the clearance "Payment &
+    // wagon allocation" step then never ticks. getClearanceView backfills it, but
+    // the stepper reads its gating milestones straight from here, so heal here too.
+    // Idempotent (no-op once COMPLETED); recovers already-stuck rows with no migration.
+    const paymentSettled = rows.find(
+      (m) => m.milestoneCode === 'FREIGHT_PAYMENT_SETTLED',
+    );
+    if (paymentSettled && paymentSettled.status === 'PENDING') {
+      const booking = await this.dataSource.getRepository(Booking).findOne({
+        where: { id: bookingId },
+        select: { id: true, status: true, paymentStatus: true },
+      });
+      if (booking?.paymentStatus === 'PAID' || booking?.status === 'PAID') {
+        await this.completeForBooking(bookingId, 'FREIGHT_PAYMENT_SETTLED');
+        return this.repo.find({
+          where: { bookingId },
+          order: { sortOrder: 'ASC' },
+        });
+      }
+    }
+
+    return rows;
   }
 
   /**