add GL operations for customs risk assignment, duty advising, and incident reporting

docs/freight-platform/SYSTEM-FLOW.md

@@ -235,6 +235,8 @@ GL finalize  (POST .../clearance/finalize)
 
 A **cycle** is one clearance round. ONE_TIME contracts have a single cycle (#1). GENERAL contracts open a new cycle each time they need clearance before the next shipment.
 
+> Clearance (section 3) is **pre-booking**. After GL creates the booking, the work continues as **GL Phase 2** — see section 4b.
+
 ---
 
 ## 4) Booking
@@ -299,6 +301,98 @@ payment status: PENDING → VERIFICATION_IN_PROGRESS → PAID (or FAILED)
 
 ---
 
+## 4b) Global Logistics — Phase 2 (after the booking exists)
+
+> Customs (Path B) shipments keep moving through GL after booking. This phase is
+> a **milestone timeline** plus a set of **structured GL actions**. The customer
+> only watches and, when asked, pays / uploads a duty slip.
+
+### Milestone timeline
+
+When GL creates the booking, the system seeds the **post-booking milestones**
+for that direction (import ~15, export ~11). Each is `PENDING → COMPLETED`.
+
+```
+Import (post-booking):  WAGON_REQUESTED → FREIGHT_PAYMENT_SETTLED → WAGON_ALLOCATED
+   → GATEPASS_GRANTED → READY_FOR_LOADING → LOADED → DEPARTED_FROM_DJIBOUTI
+   → ARRIVED_ETHIOPIA → OFFLOADED → T1_CLOSED → RISK_ASSIGNED
+   → IMPORT_RELEASE_GRANTED → IMPORT_PROCESS_COMPLETED
+   → STORAGE_INVOICE_RAISED → EXIT_NOTE_GENERATED
+
+Export (post-booking):  WAGON_REQUESTED → FREIGHT_PAYMENT_PENDING → FREIGHT_PAYMENT_SETTLED
+   → WAGON_ALLOCATED → CARGO_ARRIVED → READY_FOR_LOADING → LOADED
+   → DEPARTED_TO_DJIBOUTI → ARRIVED_AT_DJIBOUTI → GATEPASS_GRANTED → OFFLOADED
+```
+
+Each milestone has an **owner**: ET (GL Ethiopia), DJ (GL Djibouti), OPS (Operations),
+CUST (customer). Backoffice shows the timeline with a **Complete** button on the
+next pending step; the customer portal shows the same timeline **read-only**.
+
+### GL actions (the structured part)
+
+Plain "Complete" covers most steps. These carry extra data, so they have their
+own UI cards on the backoffice **milestones page** (`GlActionsPanel`):
+
+```
+Station routing   → route shipment to a station yard (+ bind GL staff)        (GL US-02)
+Customs risk      → assign GREEN / YELLOW / RED → completes RISK_ASSIGNED
+Duty & tax        → GL advises amount + declaration serial → completes
+                    DUTY_TAXES_ADVISED → customer uploads slip → DUTY_TAX_PAID
+GL documents      → upload DO / RO / T1 / import release / interchange /
+                    final declaration → auto-completes the matching milestone
+Cargo exception   → log SEAL_BROKEN / CONTAINER_OPENED / CONTAINER_DAMAGED /
+                    FLUID_LEAKING with photos → alert GL Ethiopia             (GL US-07)
+```
+
+**Doc-triggered milestones:** uploading the mapped document completes the
+milestone automatically — no separate click:
+
+| Upload (code) | Completes milestone | Who |
+|---------------|---------------------|-----|
+| `delivery_order` | DO_COLLECTED | GL DJ |
+| `release_order` | RELEASE_ORDER_SECURED | GL DJ |
+| `t1_transport_document` | T1_CLOSED | GL ET |
+| `import_release` | IMPORT_RELEASE_GRANTED | GL ET |
+| `full_in_interchange` | OFFLOADED | GL DJ |
+| `final_declaration` | IMPORT_PROCESS_COMPLETED | GL ET |
+| `duty_tax_receipt` | DUTY_TAX_PAID | **Customer** |
+
+### ET ↔ DJ handoff
+
+```
+DEPARTED_FROM_DJIBOUTI (import)  → lead returns to GL Ethiopia + Operations
+DEPARTED_TO_DJIBOUTI   (export)  → lead moves to GL Djibouti
+```
+Ownership region is encoded per-milestone in the catalog; notifications fire on
+handoff (notification module pending).
+
+### What the customer does in Phase 2
+
+```
+watch the timeline (read-only)
+pay duty/tax  → upload payment slip  (only when GL advised it)
+pay freight   → Pay button on the booking when batch-selected
+that's all — every other step is GL / Ops / Terminal
+```
+
+### Where it lives (Phase 2)
+
+| Area | Files |
+|------|-------|
+| Milestone seed/advance | `api/.../contracts/clearance-milestone.service.ts`, `clearance-milestone.catalog.ts` |
+| GL actions (risk/duty/station/docs/incident) | `api/.../contracts/gl-operations.service.ts`, `dto/gl-operations.dto.ts`, `entities/clearance-incident.entity.ts` |
+| Endpoints | `api/.../contracts/contracts.controller.ts` (`bookings/:id/risk` · `/duty` · `/station-assign` · `/documents` · `/incidents` · `/duty-slip`) |
+| Backoffice UI | `backoffice/.../pages/contracts/BookingMilestonesPage.tsx`, `components/contracts/ClearanceMilestoneTimeline.tsx`, `components/contracts/gl-actions/*` |
+| Portal UI | `portal/.../bookings/BookingDetailPage/components/ShipmentTrackingCard.tsx` |
+
+### Still out of scope (per design doc §18)
+
+Demurrage auto-calc & storage invoicing, finance AP closure, multimodal
+(sea/air + MTO/OBL/HBL), truck waybill PDF + POD signing. `STORAGE_INVOICE_RAISED`
+and `EXIT_NOTE_GENERATED` exist as **manual milestones** only — no fee engine yet.
+
+---
+
 ## 5) Schedule (Operations)
 
 > Goal: put the booking on a train (or dispatch by road). Day-level pooling — the
@@ -371,6 +465,12 @@ BOOKING
   created by CUSTOMER (Path A / domestic) or GL (Path B)
   price → pay → (its own doc clearance if applicable) → ready to schedule
 
+GL PHASE 2  (customs/Path B, after booking)
+  milestone timeline: wagon → pay → allocate → load → depart → handover
+    → arrive → offload → T1 close → risk → release → complete
+  GL actions: station routing · risk (G/Y/R) · duty advise · DO/RO/T1 upload · incident
+  customer: watch read-only · upload duty slip · pay freight
+
 SCHEDULE
   request a day → Operations accept → batch engine → train assigned
   → pay → IN_TRANSIT → COMPLETED