mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-27 23:40:56 +00:00
605 lines
25 KiB
Markdown
605 lines
25 KiB
Markdown
# EDR Freight — Major Flow Variants (each self-contained)
|
||
|
||
The single master graph lives in [`FREIGHT_MASTER_FLOW.md`](./FREIGHT_MASTER_FLOW.md). This file breaks the
|
||
business logic into **one comprehensive, self-contained diagram per major scenario**, each organised with
|
||
phase **subgraphs** so it can be read on its own.
|
||
|
||
**Axes covered**
|
||
|
||
| Axis | Values |
|
||
| --------------- | -------------------------------------------------------------------------------------------- |
|
||
| Origin | **One-time booking** · **General contract** (Path A transport-only / Path B GENERAL+customs) |
|
||
| Trade direction | **Export** · **Import** · **Intercity / Domestic** |
|
||
| Customs | **With customs** · **Without customs** |
|
||
|
||
**Legend** — (P) Portal (customer) · (B) Backoffice (staff) · (sys) System/event · (green) rounded = success end · (red) rounded = fail end · <> decision.
|
||
|
||
**Which diagram do I read?**
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef box fill:#e0e7ff,stroke:#3730a3,color:#111
|
||
A{"Origin?"}:::dec
|
||
A -->|"one-time"| B{"Trade direction?<br/>(gate is direction-driven, NOT a customs toggle)"}:::dec
|
||
A -->|"framework agreement"| C{"Contract type?"}:::dec
|
||
B -->|"DOMESTIC"| D1["§1 One-time · DOMESTIC (no gate)"]:::box
|
||
B -->|"IMPORT / EXPORT<br/>(with or without customs)"| D2["§2 One-time · IMPORT/EXPORT (gate)"]:::box
|
||
C -->|"transport-only (self-clearance)"| D3["§3 Contract · Path A"]:::box
|
||
C -->|"GENERAL + customs"| D4["§4 Contract · Path B"]:::box
|
||
D1 --> E{"Physical direction?"}:::dec
|
||
D2 --> E
|
||
D3 --> E
|
||
D4 --> E
|
||
E -->|"export"| F5["§5 EXPORT operations"]:::box
|
||
E -->|"import"| F6["§6 IMPORT operations"]:::box
|
||
E -->|"domestic"| F7["§7 INTERCITY operations"]:::box
|
||
```
|
||
|
||
> **How the two halves connect:** §1–§4 are the **commercial** journeys (intake → approval → contract →
|
||
> clearance → operation → payment). §5–§7 are the **physical** journeys (mile legs → warehouse → train →
|
||
> delivery). A shipment = one commercial variant **+** one physical variant. Each diagram fully details its
|
||
> own half and summarises the other so it stands alone.
|
||
|
||
---
|
||
|
||
## §1 — One-time booking · DOMESTIC (no clearance gate)
|
||
|
||
The commercial lifecycle when the counter-sign gate resolves to **no clearance** — which, in code, means
|
||
**trade direction = DOMESTIC** (not a customs toggle). Counter-sign goes straight to `FULLY_EXECUTED` and the
|
||
booking is enqueued **directly into the scheduling batch pipeline, skipping the operation-request/clearance
|
||
phase**. NOTE: Import/export bookings — _even with customs off_ — do **not** land here; they always hit the
|
||
clearance gate (§2, just with a lighter "without customs" document set).
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
pre(["Company ACTIVE (approved profile)"]):::sys
|
||
|
||
subgraph DRAFT["1 · Create & price"]
|
||
direction TB
|
||
d1["POST /bookings → DRAFT<br/>reference, containers, cargo modifiers, files (P)"]:::port
|
||
d2["POST /bookings/:id/generate-price<br/>rule-engine: LIVE rates + surcharges (P)"]:::port
|
||
dW{"weight-limit-rules"}:::dec
|
||
dWx(["HARD BLOCK 400 — VGM > capacity"]):::bad
|
||
d3["POST /bookings/:id/submit → SUBMITTED<br/>freeze booking_rate_snapshot (P)"]:::port
|
||
dP{"price moved?"}:::dec
|
||
d3c["confirm-submit → SUBMITTED (P)"]:::port
|
||
d1 --> d2 --> dW
|
||
dW -->|"over capacity"| dWx
|
||
dW -->|"ok / warn+surcharge"| d3 --> dP
|
||
dP -->|"yes"| d3c
|
||
dP -->|"no"| out1
|
||
d3c --> out1
|
||
d1 -.->|"delete draft"| ddx(["removed"]):::bad
|
||
d3 -.->|"reject price"| drx(["REJECTED"]):::bad
|
||
end
|
||
out1[" "]:::sys
|
||
|
||
subgraph INTAKE["2 · Staff intake & approval"]
|
||
direction TB
|
||
g{"government?"}:::dec
|
||
gexp["governmentExpedite → PAID + Eligible (B)"]:::back
|
||
i{"staff/accept | request-changes | reject (B)"}:::dec
|
||
ir["CHANGES_REQUESTED (B)"]:::back
|
||
irx(["REJECTED"]):::bad
|
||
ia["→ PENDING_APPROVAL<br/>instantiate approval steps + validity window (B)"]:::back
|
||
ac{"chain: LINE_STAFF → DIRECTOR → CEO (B)"}:::dec
|
||
acx(["rejectStep → REJECTED"]):::bad
|
||
g -->|"yes"| gexp
|
||
g -->|"no"| i
|
||
i -->|"request-changes"| ir
|
||
i -->|"reject"| irx
|
||
i -->|"accept"| ia --> ac
|
||
ac -->|"rejectStep"| acx
|
||
end
|
||
|
||
subgraph SIGN["3 · Contract doc & sign (DOMESTIC → no gate)"]
|
||
direction TB
|
||
s1["contract/generate → CONTRACT_READY (B)"]:::back
|
||
s2["customer sign → SIGNED_CUSTOMER (P)"]:::port
|
||
s3["staff counter-sign (DOMESTIC) → FULLY_EXECUTED<br/>enqueueScheduleProcessing (no op-request) (B)(sys)"]:::back
|
||
s1 --> s2 --> s3
|
||
end
|
||
|
||
subgraph OPPAY["4 · Batch pipeline & payment"]
|
||
direction TB
|
||
fe["FULLY_EXECUTED enters day batch pool (sys)"]:::sys
|
||
b1["batch engine offers wagons → SELECTED_FOR_BATCH<br/>invoice generated (sys)"]:::sys
|
||
p1["customer pays → gateway → PAID (P)"]:::port
|
||
pexp(["pay window lapses → reservation EXPIRED"]):::bad
|
||
fe --> b1 --> p1
|
||
p1 -.->|"unpaid"| pexp
|
||
end
|
||
|
||
phys(["Physical execution:<br/>§7 intercity → COMPLETED (done)"]):::good
|
||
|
||
pre --> DRAFT
|
||
out1 --> INTAKE
|
||
ac -->|"APPROVED"| SIGN
|
||
SIGN --> OPPAY
|
||
p1 --> phys
|
||
gexp -.->|"gov → PAID/Eligible"| phys
|
||
```
|
||
|
||
> **Road-mode note:** a domestic booking billed by road (truck) instead of rail goes through
|
||
> `operation/review` → `ROAD_DISPATCH_PENDING` (the road branch shown in the master graph), not the rail
|
||
> batch pool above.
|
||
|
||
---
|
||
|
||
## §2 — One-time booking · IMPORT / EXPORT (clearance gate)
|
||
|
||
Every IMPORT/EXPORT one-time booking traverses the clearance gate — **whether or not customs is enabled**
|
||
(the customs flag only selects a heavier vs lighter `clearance_*` document set; both go through
|
||
`AWAITING_DOCUMENTS`). Commercial spine as §1 (phases 1–3) **plus** the gate: counter-sign → `AWAITING_DOCUMENTS`
|
||
→ document review loop → `CLEARANCE_READY`, phased ET/DJ actions, then operation-request → payment.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
a0(["Booking APPROVED & signed by customer<br/>(see §1 phases 1–3)"]):::sys
|
||
|
||
subgraph CS["Counter-sign with customs"]
|
||
direction TB
|
||
cs1["staff counter-sign (IMPORT/EXPORT) → AWAITING_DOCUMENTS (B)"]:::back
|
||
end
|
||
|
||
subgraph DOCS["5 · Document clearance gate"]
|
||
direction TB
|
||
x1["customer clearance/documents<br/>→ DOCUMENTS_UNDER_REVIEW (P)"]:::port
|
||
x2{"GL clearance/review each doc (B)"}:::dec
|
||
x2q["doc Queried → customer re-uploads (B)"]:::back
|
||
x3["clearance/finalize (100% approved) → CLEARANCE_READY (B)"]:::back
|
||
x1 --> x2
|
||
x2 -->|"query"| x2q --> x1
|
||
x2 -->|"approve all"| x3
|
||
end
|
||
|
||
subgraph PHASED["6 · Phased ET / DJ clearance (as applicable)"]
|
||
direction TB
|
||
ph1["upload declaration (serial) (B)"]:::back
|
||
ph2["duty/tax advise → customer duty-slip (P)(B)"]:::back
|
||
ph3["transit permit (ET) (B)"]:::back
|
||
ph4["delivery order / release order (DJ) (B)"]:::back
|
||
ph5["T1 docs → T1 close (B)"]:::back
|
||
ph6["export release / finalize-pre-clearance (B)"]:::back
|
||
ph1 --> ph2 --> ph3 --> ph4 --> ph5 --> ph6
|
||
end
|
||
|
||
subgraph OPPAY2["7 · Operation request & payment"]
|
||
direction TB
|
||
o1["clearance/proceed → OPERATION_REQUEST_PENDING (P)"]:::port
|
||
o2{"operation/review (B)"}:::dec
|
||
o2c["OPERATION_CHANGES_REQUESTED (B)"]:::back
|
||
om{"mode?"}:::dec
|
||
ot["accept=train: invoice → FULLY_EXECUTED<br/>→ batch offer → SELECTED_FOR_BATCH (B)(sys)"]:::back
|
||
orr["accept=road: invoice → ROAD_DISPATCH_PENDING (B)"]:::back
|
||
p1["customer pays → PAID (sys)(P)"]:::sys
|
||
pexp(["pay window lapses → EXPIRED"]):::bad
|
||
o1 --> o2
|
||
o2 -->|"request-changes"| o2c --> o1
|
||
o2 -->|"accept"| om
|
||
om -->|"train"| ot --> p1
|
||
om -->|"road"| orr --> p1
|
||
p1 -.->|"unpaid"| pexp
|
||
end
|
||
|
||
cancel(["CANCELLED — staff-only, only from<br/>OPERATION_REQUEST_PENDING here (not from<br/>AWAITING_DOCUMENTS / DOCUMENTS_UNDER_REVIEW)"]):::bad
|
||
phys(["Physical execution:<br/>§5 export · §6 import → COMPLETED (done)"]):::good
|
||
|
||
a0 --> CS --> DOCS
|
||
x3 --> PHASED
|
||
ph6 --> OPPAY2
|
||
p1 --> phys
|
||
o1 -.->|"cancel"| cancel
|
||
```
|
||
|
||
---
|
||
|
||
## §3 — General contract · Path A (transport-only, self-clearance)
|
||
|
||
Framework agreement where the customer clears customs independently. After the contract is active and
|
||
operations verify self-clearance (`SELF_CLEARED`), the **customer books directly** under the contract; each
|
||
booking then runs the operation/payment/physical flow.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
pre(["Company ACTIVE"]):::sys
|
||
|
||
subgraph CTR["1 · Contract lifecycle"]
|
||
direction TB
|
||
c1["POST /contracts → DRAFT<br/>routes + cargo scope + unit rates (NO quantities) (P)"]:::port
|
||
c2["generate-price → submit → SUBMITTED<br/>freeze contract_rate_snapshots (P)"]:::port
|
||
c3{"staff/accept | request-changes | reject (B)"}:::dec
|
||
c3r["CHANGES_REQUESTED (B)"]:::back
|
||
c3x(["Contract REJECTED"]):::bad
|
||
c4["→ PENDING_APPROVAL (B)"]:::back
|
||
c4a{"approval chain (B)"}:::dec
|
||
c4x(["rejectStep → REJECTED"]):::bad
|
||
c5["generate-contract → CONTRACT_READY (B)"]:::back
|
||
c6["customer sign → SIGNED_CUSTOMER (P)"]:::port
|
||
c7["staff counter-sign (IMPORT/EXPORT self-clearance) →<br/>AWAITING_CLEARANCE_DOCUMENTS (B)"]:::back
|
||
c1 --> c2 --> c3
|
||
c3 -->|"request-changes"| c3r --> c2
|
||
c3 -->|"reject"| c3x
|
||
c3 -->|"accept"| c4 --> c4a
|
||
c4a -->|"reject"| c4x
|
||
c4a -->|"approve"| c5 --> c6 --> c7
|
||
c7 -.->|"lapse"| cexp(["EXPIRED"]):::bad
|
||
c7 -.->|"renew"| cren(["RENEWAL_DRAFT → new cycle"]):::bad
|
||
end
|
||
|
||
subgraph SELF["2 · Self-clearance verification"]
|
||
direction TB
|
||
o1["customer uploads self-clearance docs (P)"]:::port
|
||
o2{"ops-review each doc (B)"}:::dec
|
||
o2q["query → re-upload (B)"]:::back
|
||
o3["ops-finalize → clearanceStatus SELF_CLEARED (B)"]:::back
|
||
o1 --> o2
|
||
o2 -->|"query"| o2q --> o1
|
||
o2 -->|"approve"| o3
|
||
end
|
||
|
||
subgraph BK["3 · Book directly under contract"]
|
||
direction TB
|
||
b1["customer POST /contracts/:id/bookings (P)"]:::port
|
||
bv{"validate-shipment:<br/>window + capacity draw-down + pairing"}:::dec
|
||
bvx(["rejected: over capacity /<br/>20ft pairing hard-block"]):::bad
|
||
b2["Booking created under contract<br/>(bookings.contract_id) (sys)"]:::sys
|
||
b1 --> bv
|
||
bv -->|"fail"| bvx
|
||
bv -->|"ok"| b2
|
||
end
|
||
|
||
op(["Booking runs operation + payment<br/>(see §1 phase 4) then §5/§6/§7 → COMPLETED (done)"]):::good
|
||
|
||
pre --> CTR
|
||
c7 --> SELF
|
||
o3 --> BK
|
||
b2 --> op
|
||
```
|
||
|
||
---
|
||
|
||
## §4 — General contract · Path B (GENERAL + customs)
|
||
|
||
Framework agreement **with** customs. The customer cannot book directly — they submit a **BookingRequest**
|
||
(date + quantities only); GL Ethiopia accepts it and creates the booking, which then runs **per-booking
|
||
phased customs** on the `/contracts/bookings/:bookingId/*` surface.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
pre(["Company ACTIVE"]):::sys
|
||
|
||
subgraph CTR["1 · Contract lifecycle (customs)"]
|
||
direction TB
|
||
c1["POST /contracts → DRAFT → submit → approve → sign (P)(B)"]:::port
|
||
c7["staff counter-sign (GENERAL + customs) → CONTRACT_ACTIVE<br/>(contract clearance cycle SKIPPED — runs per-booking) (B)"]:::back
|
||
c1 --> c7
|
||
c1 -.->|"reject / lapse"| cx(["REJECTED / EXPIRED"]):::bad
|
||
end
|
||
|
||
subgraph REQ["2 · Booking request → GL creates booking"]
|
||
direction TB
|
||
r1["customer POST /contracts/:id/booking-requests<br/>(date + quantities, no per-unit data) (P)"]:::port
|
||
r2{"GL booking-request queue (B)"}:::dec
|
||
r2x(["reject / customer cancel →<br/>REJECTED / CANCELLED"]):::bad
|
||
r3["GL accept → GL creates booking under contract<br/>(ct:create_booking) (B)"]:::back
|
||
r1 --> r2
|
||
r2 -->|"reject/cancel"| r2x
|
||
r2 -->|"accept"| r3
|
||
end
|
||
|
||
subgraph GLC["3 · Per-booking GL clearance & milestones"]
|
||
direction TB
|
||
g1["station-assign (route + bind staff) (B)"]:::back
|
||
g2["declaration → duty advise (GREEN/YELLOW/RED risk) (B)"]:::back
|
||
g3["customer duty-slip → transit / delivery / release order (P)(B)"]:::back
|
||
g4["T1 docs → T1 close (B)"]:::back
|
||
g5["final-invoice → customer slip → confirm paid (P)(B)"]:::back
|
||
g6["second-duty (post-arrival import) → slip (P)(B)"]:::back
|
||
gi["incident reports (photos) as needed (B)"]:::back
|
||
g1 --> g2 --> g3 --> g4 --> g5 --> g6
|
||
g4 -.-> gi
|
||
end
|
||
|
||
op(["Booking runs operation + payment (see §1 phase 4)<br/>then §5/§6 physical → COMPLETED (done)"]):::good
|
||
|
||
pre --> CTR
|
||
c7 --> REQ
|
||
r3 --> GLC
|
||
g6 --> op
|
||
```
|
||
|
||
---
|
||
|
||
## §5 — EXPORT operations (physical execution)
|
||
|
||
Given a PAID, scheduled **export** booking: optional first-mile road leg → origin warehouse inbound → train
|
||
build & dispatch → corridor transit → Djibouti port unload → interchange handover. Cargo leaves the country
|
||
at the port; the booking's terminal here is **dispatched/handed-over at Djibouti**.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
pre(["Export booking PAID & Eligible<br/>(see §1/§2/§3/§4)"]):::sys
|
||
|
||
subgraph FM["1 · First-mile (if EXPORT + requested)"]
|
||
direction TB
|
||
fmq{"first-mile requested?"}:::dec
|
||
fm1["leg auto-created firstMile.acceptBooking<br/>READY_TO_TRANSIT (sys)"]:::sys
|
||
fm2["setVehicles → vehicle BUSY, SMS driver, fleet_events (B)"]:::back
|
||
fm3["IN_TRANSIT (needs vehicle) → RECEIVED_TO_PORT (B)"]:::back
|
||
fm4["first-mile invoice (FIRST_MILE fee); distances lock once invoiced (B)"]:::back
|
||
fmq -->|"yes"| fm1 --> fm2 --> fm3 --> fm4
|
||
fmq -->|"no"| fmskip[" "]:::sys
|
||
end
|
||
|
||
subgraph WH["2 · Origin warehouse inbound"]
|
||
direction TB
|
||
w1["receive / bulkReceive → RECEIVED<br/>capacity assert, GRN, notify owner SMS (B)"]:::back
|
||
w2{"inspection"}:::dec
|
||
w2f["FAILED / NEEDS_REVIEW → hold + re-inspect (B)"]:::back
|
||
w3["store (allocation rule → yard/zone) → STORED (B)"]:::back
|
||
w4["reserve (booking PAID) → RESERVED (B)"]:::back
|
||
w5["mark-ready-for-loading (inspection PASSED) → READY_FOR_LOADING (B)"]:::back
|
||
w6["load onto wagon → LOADED (+ warehouse_loadings) (B)"]:::back
|
||
w1 --> w2
|
||
w2 -->|"fail"| w2f --> w2
|
||
w2 -->|"PASSED"| w3 --> w4 --> w5 --> w6
|
||
end
|
||
|
||
subgraph SCHED["3 · Train build & schedule"]
|
||
direction TB
|
||
s1["schedule DRAFT (≥2 locos, derive EXPORT direction) (B)"]:::back
|
||
s2["assign-bookings + run-allocation (wagons) (B)"]:::back
|
||
s3["pin wagons → finalize → SCHEDULED (bookings Scheduled) (B)"]:::back
|
||
s3x["cancel schedule → bookings Eligible (B)"]:::back
|
||
s1 --> s2 --> s3
|
||
s3 -.->|"cancel"| s3x -.-> s1
|
||
s3 -.->|"gov preempt / maintenance"| sr["reschedule: retained/displaced/readmitted (B)"]:::back
|
||
sr -.-> s2
|
||
end
|
||
|
||
subgraph RUN["4 · Dispatch → Djibouti"]
|
||
direction TB
|
||
r1["dispatch → DISPATCHED<br/>train_number, locos ASSIGNED, window CLOSED, unpaid EXPIRED (B)"]:::back
|
||
r2["checkpoints (corridor) → train_checkpoint_events (B)"]:::back
|
||
rc["customer tracking page GET /tracking/:id (JWT) (P)<br/>NOTE: tracking_events has no writer — timeline empty"]:::port
|
||
r3["arrive → ARRIVED (bookings IN_TRANSIT, wagons/locos freed) (B)"]:::back
|
||
ru["export/auto-unload-at-djibouti →<br/>UNLOADED_AT_DJIBOUTI_PORT (B)"]:::back
|
||
ri["interchange document generate-from-schedule → GENERATED (B)"]:::back
|
||
ria{"port acknowledges?"}:::dec
|
||
r1 --> r2 --> r3 --> ru --> ri --> ria
|
||
r2 -.-> rc
|
||
end
|
||
|
||
done(["Export dispatched & handed over at Djibouti (done)"]):::good
|
||
disp(["interchange DISPUTED → remarks / re-issue"]):::bad
|
||
|
||
pre --> FM
|
||
fm4 --> WH
|
||
fmskip --> WH
|
||
w6 --> SCHED
|
||
s3 --> RUN
|
||
ria -->|"acknowledge"| done
|
||
ria -->|"dispute"| disp
|
||
```
|
||
|
||
---
|
||
|
||
## §6 — IMPORT operations (physical execution)
|
||
|
||
Given a PAID, scheduled **import** booking arriving by train from Djibouti: destination warehouse unload →
|
||
inspection → import customs finalization → optional last-mile → fee gate-clearance → release → delivery →
|
||
**COMPLETED**.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
pre(["Import booking PAID & scheduled<br/>(see §1/§2/§4)"]):::sys
|
||
|
||
subgraph RAIL["1 · Import train arrival"]
|
||
direction TB
|
||
t1["import train dispatched from Djibouti → DISPATCHED (B)"]:::back
|
||
t2["checkpoints → train_checkpoint_events (B)"]:::back
|
||
tc["customer tracking page GET /tracking/:id (JWT) (P)<br/>NOTE: tracking_events has no writer — timeline empty"]:::port
|
||
t3["arrive → ARRIVED (bookings IN_TRANSIT) → warehouse arrival automation (B)"]:::back
|
||
t1 --> t2 --> t3
|
||
t2 -.-> tc
|
||
end
|
||
|
||
subgraph WH["2 · Destination warehouse"]
|
||
direction TB
|
||
w1["import/auto-unload-arrived-bookings (assign WH/yard/zone) → UNLOADED (B)"]:::back
|
||
w2{"inspection PASSED?"}:::dec
|
||
w2f["FAILED → hold / re-inspect / djibouti-incident report (B)"]:::back
|
||
w3["→ READY_FOR_PICKUP (IMPORT) (B)"]:::back
|
||
w1 --> w2
|
||
w2 -->|"no"| w2f --> w2
|
||
w2 -->|"yes"| w3
|
||
end
|
||
|
||
subgraph CUST["3 · Import customs finalization (timestamp-driven)"]
|
||
direction TB
|
||
u1["upload docs (IM4/IM5/T1_CLOSURE/TRANSIT_PERMIT/…) (B)"]:::back
|
||
u2["record declaration serial (B)"]:::back
|
||
u3["notify duties/taxes (B)"]:::back
|
||
u4["mark duties paid (needs CUSTOMER_PAYMENT_SLIP) (B)"]:::back
|
||
u5["assign risk (GREEN/YELLOW/BLUE/RED) (B)"]:::back
|
||
u6{"release gates satisfied?<br/>T1 + release permit + declaration + risk + paid"}:::dec
|
||
u6x["blocked — missing gate → resolve (B)"]:::back
|
||
u7["release-permitted → completedAt (B)"]:::back
|
||
u1 --> u2 --> u3 --> u4 --> u5 --> u6
|
||
u6 -->|"no"| u6x --> u6
|
||
u6 -->|"yes"| u7
|
||
end
|
||
|
||
subgraph LM["4 · Last-mile (if requested)"]
|
||
direction TB
|
||
lq{"last-mile requested?"}:::dec
|
||
l1["leg auto-created lastMile.acceptBooking<br/>READY_TO_TRANSIT (sys)"]:::sys
|
||
l2["setVehicles → IN_TRANSIT → DELIVERED (free vehicles) (B)"]:::back
|
||
l3["last-mile invoice (LAST_MILE fee) (B)"]:::back
|
||
lq -->|"yes"| l1 --> l2 --> l3
|
||
lq -->|"no"| lskip[" "]:::sys
|
||
end
|
||
|
||
subgraph DEL["5 · Release & delivery"]
|
||
direction TB
|
||
d0{"warehouse/storage fees fully PAID?"}:::dec
|
||
d0x["gate-clearance BLOCKED (findBlockingInvoice) (B)"]:::back
|
||
d0p["customer pays storage/demurrage online (P)"]:::port
|
||
d1["release order (DO) + gate-clearance → deliver (B)"]:::back
|
||
d2["customer approve-delivery (saved signature) → POD (P)"]:::port
|
||
d3["inventory DELIVERED, POD to cargo, container freed (sys)"]:::sys
|
||
d0 -->|"no"| d0x --> d0p --> d0
|
||
d0 -->|"yes"| d1 --> d2 --> d3
|
||
end
|
||
|
||
ecr(["empty-container-return chain (post-import):<br/>RETURNED → … → HANDOVER_ISSUED → COMPLETED"]):::sys
|
||
done(["Booking COMPLETED (done) (operations/complete)"]):::good
|
||
|
||
pre --> RAIL
|
||
t3 --> WH
|
||
w3 --> CUST
|
||
u7 --> LM
|
||
l3 --> DEL
|
||
lskip --> DEL
|
||
d3 --> done
|
||
done -.-> ecr
|
||
```
|
||
|
||
---
|
||
|
||
## §7 — INTERCITY / DOMESTIC operations (no cross-border customs)
|
||
|
||
Rail movement **between Ethiopian yards** (e.g. inland dry ports). No import/export customs, no Djibouti
|
||
port unload or interchange handover. Optional road mile legs if the service includes door delivery.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
classDef port fill:#dbeafe,stroke:#2563eb,color:#111
|
||
classDef back fill:#fef3c7,stroke:#b45309,color:#111
|
||
classDef sys fill:#dcfce7,stroke:#15803d,color:#111
|
||
classDef dec fill:#f8fafc,stroke:#475569,color:#111
|
||
classDef good fill:#86efac,stroke:#166534,color:#062e14
|
||
classDef bad fill:#fecaca,stroke:#991b1b,color:#450a0a
|
||
|
||
pre(["Domestic booking PAID & Eligible<br/>(see §1 — customs OFF)"]):::sys
|
||
|
||
subgraph FMD["1 · Optional origin pickup (road)"]
|
||
direction TB
|
||
fq{"door pickup / first-mile requested?"}:::dec
|
||
f1["first-mile leg → vehicle assign → RECEIVED_TO_PORT (B)"]:::back
|
||
fq -->|"yes"| f1 --> fnext[" "]:::sys
|
||
fq -->|"no (drop at origin yard)"| fnext
|
||
end
|
||
|
||
subgraph WHO["2 · Origin warehouse"]
|
||
direction TB
|
||
w1["receive → RECEIVED (B)"]:::back
|
||
w2{"inspection PASSED?"}:::dec
|
||
w2f["hold + re-inspect (B)"]:::back
|
||
w3["store → STORED → reserve (PAID) → RESERVED (B)"]:::back
|
||
w4["ready-for-loading → LOADED onto wagon (B)"]:::back
|
||
w1 --> w2
|
||
w2 -->|"no"| w2f --> w2
|
||
w2 -->|"yes"| w3 --> w4
|
||
end
|
||
|
||
subgraph RUN["3 · Train (ET yard → ET yard)"]
|
||
direction TB
|
||
s1["schedule DRAFT (direction DOMESTIC) → assign → finalize → SCHEDULED (B)"]:::back
|
||
r1["dispatch → DISPATCHED (unpaid EXPIRED) (B)"]:::back
|
||
r2["checkpoints → train_checkpoint_events; customer tracking (JWT) (P)(B)"]:::back
|
||
r3["arrive → ARRIVED (bookings IN_TRANSIT) (B)"]:::back
|
||
s1 --> r1 --> r2 --> r3
|
||
end
|
||
|
||
subgraph WHD["4 · Destination warehouse & delivery"]
|
||
direction TB
|
||
d1["auto-unload arrived → UNLOADED / RECEIVED (B)"]:::back
|
||
di{"inspection PASSED?"}:::dec
|
||
dif["hold + re-inspect (B)"]:::back
|
||
d2["READY_FOR_PICKUP (B)"]:::back
|
||
fee{"storage fees paid?"}:::dec
|
||
feex["gate-clearance blocked → customer pays (P)"]:::port
|
||
d3["release order → deliver (B)"]:::back
|
||
lq{"door delivery / last-mile?"}:::dec
|
||
l1["last-mile leg → DELIVERED (B)"]:::back
|
||
d4["customer approve-delivery → POD → inventory DELIVERED (P)(sys)"]:::sys
|
||
d1 --> di
|
||
di -->|"no"| dif --> di
|
||
di -->|"yes"| d2 --> fee
|
||
fee -->|"no"| feex --> fee
|
||
fee -->|"yes"| d3 --> lq
|
||
lq -->|"yes"| l1 --> d4
|
||
lq -->|"no (pickup at yard)"| d4
|
||
end
|
||
|
||
done(["Booking COMPLETED (done)"]):::good
|
||
|
||
pre --> FMD
|
||
fnext --> WHO
|
||
w4 --> RUN
|
||
r3 --> WHD
|
||
d4 --> done
|
||
```
|
||
|
||
---
|
||
|
||
## Cross-reference
|
||
|
||
| Variant | Distinctive gate(s) | Terminal ends unique to it |
|
||
| --------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
||
| §1 One-time · DOMESTIC | counter-sign → `FULLY_EXECUTED` (skips clearance **and** op-request; enters batch directly) | HARD BLOCK, price/intake/approval REJECTED, EXPIRED |
|
||
| §2 One-time · IMPORT/EXPORT | `AWAITING_DOCUMENTS` → review loop → phased ET/DJ → op-request (gate applies with **or without** customs) | + doc-query loop, CANCELLED (only from OPERATION_REQUEST_PENDING) |
|
||
| §3 Contract · Path A | `SELF_CLEARED` via ops-review; customer books direct | contract REJECTED/EXPIRED/RENEWAL, capacity/pairing block |
|
||
| §4 Contract · Path B | BookingRequest → GL creates booking; per-booking milestones | BookingRequest REJECTED/CANCELLED |
|
||
| §5 Export ops | first-mile → Djibouti unload → interchange handover | dispatched@Djibouti (success), interchange DISPUTED |
|
||
| §6 Import ops | import customs finalization gates → last-mile → gate-clearance | COMPLETED (+ empty-container-return chain) |
|
||
| §7 Intercity ops | ET→ET rail, no cross-border customs, optional mile legs | COMPLETED |
|
||
|
||
Full endpoint tables & per-domain state machines: [`FREIGHT_SYSTEM_FLOW.md`](./FREIGHT_SYSTEM_FLOW.md).
|
||
Single all-in-one branching graph: [`FREIGHT_MASTER_FLOW.md`](./FREIGHT_MASTER_FLOW.md).
|