mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-26 18:42:49 +00:00
merge conflict
This commit is contained in:
marshal
1138
docs/docs-new
1138
docs/docs-new
File diff suppressed because it is too large
Load Diff
@@ -1,542 +0,0 @@
|
||||
# EDR Freight — System Flow (API)
|
||||
|
||||
How the freight API drives a shipment end to end:
|
||||
|
||||
**Onboarding → Contract → Booking → Clearance → Operation → Schedule → Delivery**
|
||||
|
||||
This document tracks the **API logic only** — exact statuses, transitions, branches, and endpoints as the `edr-freight-api` implements them. Read arrows (`→`) as "then". **IF** blocks are the branches.
|
||||
|
||||
> Two facts shape everything below:
|
||||
> 1. **Clearance is per-booking, not pre-booking** (except the one-time-customs special case). The contract agrees terms; each booking carries its own customs document loop.
|
||||
> 2. **Who creates the booking depends on customs.** No customs → the customer. Customs (Path B) → Global Logistics (GL) on the customer's behalf.
|
||||
|
||||
---
|
||||
|
||||
## 1) Onboarding
|
||||
|
||||
> Register the company so a profile can transact. Only an **active profile** may create contracts or bookings.
|
||||
|
||||
```
|
||||
Company → status PENDING
|
||||
Each operation profile (importer | exporter | freight_forwarder) → status PENDING
|
||||
Backoffice approves each profile → ACTIVE + reference (IM-00001 / EX-00001 / FF-00001)
|
||||
→ only an ACTIVE profile can create contracts / bookings
|
||||
```
|
||||
|
||||
Documents required depend **only on nationality**:
|
||||
|
||||
| Nationality | Company documents |
|
||||
|-------------|-------------------|
|
||||
| Ethiopian | TIN Certificate · Commercial License · National ID |
|
||||
| Foreign | TIN Certificate · Investment License · National ID · Passport |
|
||||
|
||||
Operation type adds one business-license card per profile — nothing else.
|
||||
|
||||
---
|
||||
|
||||
## 2) Contract
|
||||
|
||||
> Agree terms (route, cargo, price), run the approval chain, sign. Service: `ContractTransitionService`.
|
||||
|
||||
### Setup choices that decide later paths
|
||||
|
||||
```
|
||||
contractKind: ONE_TIME (one shipment per contract)
|
||||
GENERAL (many shipments over a validity window)
|
||||
|
||||
tradeDirection: IMPORT | EXPORT | DOMESTIC
|
||||
|
||||
customsClearingEnabled: true → Path B (GL clears + books) — IMPORT/EXPORT
|
||||
false → Path A (customer self-clears + books) — IMPORT/EXPORT
|
||||
(DOMESTIC → no clearance at all)
|
||||
```
|
||||
|
||||
### Status enum (`CONTRACT_STATUSES`)
|
||||
|
||||
```
|
||||
DRAFT · SUBMITTED · PRICE_CHANGED_PENDING_CONFIRM · CHANGES_REQUESTED
|
||||
PENDING_APPROVAL · APPROVED · APPROVED_PENDING_SIGNATURE · CONTRACT_READY
|
||||
SIGNED_CUSTOMER · FULLY_EXECUTED · CONTRACT_ACTIVE
|
||||
AWAITING_CLEARANCE_DOCUMENTS · CLEARANCE_UNDER_REVIEW · CLEARANCE_READY_FOR_BOOKING
|
||||
ACTIVE_SHIPMENT_IN_PROGRESS · CONTRACT_CLOSED · EXPIRED
|
||||
REJECTED · CANCELLED
|
||||
RENEWAL_DRAFT · RENEWAL_SUBMITTED · RENEWAL_PENDING_APPROVAL · AMENDMENTS_PROPOSED · ARCHIVED
|
||||
```
|
||||
|
||||
Clearance enum (`CONTRACT_CLEARANCE_STATUSES`): `NOT_APPLICABLE · AWAITING_DOCUMENTS · DOCUMENTS_UNDER_REVIEW · CLEARANCE_READY_FOR_BOOKING · SELF_CLEARED · ACTIVE_SHIPMENT_IN_PROGRESS`
|
||||
|
||||
### Transition table
|
||||
|
||||
| Method | Guard (allowed status) | Result |
|
||||
|--------|------------------------|--------|
|
||||
| `submit()` | DRAFT, CHANGES_REQUESTED | freeze rates → `SUBMITTED` |
|
||||
| `confirmSubmit()` | PRICE_CHANGED_PENDING_CONFIRM | freeze rates → `SUBMITTED` |
|
||||
| `staffAccept(validityDays)` | SUBMITTED | set validity window, build approval chain → `PENDING_APPROVAL` |
|
||||
| `requestChanges()` | SUBMITTED | review note → `CHANGES_REQUESTED` |
|
||||
| `reject()` | SUBMITTED, PENDING_APPROVAL | → `REJECTED` |
|
||||
| `approveStep(stepId, role)` | PENDING_APPROVAL, APPROVED_PENDING_SIGNATURE | complete step in order; all done → `APPROVED` |
|
||||
| `generateContract()` | APPROVED, APPROVED_PENDING_SIGNATURE | render PDF → `CONTRACT_READY` |
|
||||
| `sign(CUSTOMER)` | CONTRACT_READY | apply signature → `SIGNED_CUSTOMER` → auto `counterSign()` |
|
||||
| `counterSign(STAFF/DIRECTOR/CEO)` | SIGNED_CUSTOMER | **branch on path** ↓ |
|
||||
| `renew()` | any | clone with `renewalOfId`, version++ → `RENEWAL_DRAFT` |
|
||||
|
||||
**Approval chain** (`instantiateApprovalSteps`): `LINE_STAFF` → optional `DIRECTOR` → optional `CEO`. Director required when `freightType = BULK` OR `cargoType.requiresDirectorApproval`.
|
||||
|
||||
### The counter-sign branch — THIS is where the model differs from "clearance first"
|
||||
|
||||
```
|
||||
IF GENERAL + customsClearingEnabled (Path B):
|
||||
NO contract-level clearance cycle.
|
||||
status → CONTRACT_ACTIVE, clearanceStatus → NOT_APPLICABLE
|
||||
→ customer requests shipments; GL creates + clears each booking (per-booking)
|
||||
|
||||
IF ONE_TIME + customs (Path A self-clear OR one-time-customs):
|
||||
open a contract clearance cycle
|
||||
status → AWAITING_CLEARANCE_DOCUMENTS, clearanceStatus → AWAITING_DOCUMENTS
|
||||
→ contract-level clearance loop (section 3), then booking
|
||||
|
||||
IF DOMESTIC (no customs):
|
||||
status → FULLY_EXECUTED (ONE_TIME) or CONTRACT_ACTIVE (GENERAL)
|
||||
→ customer books immediately (section 4)
|
||||
```
|
||||
|
||||
> So contract-level clearance (section 3) only runs for the **one-time + customs** case. The common GENERAL-customs case goes straight to `CONTRACT_ACTIVE` and defers all clearance to the booking (section 5).
|
||||
|
||||
### Side branches
|
||||
|
||||
```
|
||||
staff requestChanges → CHANGES_REQUESTED → customer edits → submit → SUBMITTED
|
||||
staff reject → REJECTED
|
||||
GENERAL contract → renew → RENEWAL_DRAFT (clone of prior version)
|
||||
```
|
||||
|
||||
### Endpoints (`contracts.controller.ts`)
|
||||
|
||||
```
|
||||
POST /contracts/:id/submit submit()
|
||||
POST /contracts/:id/confirm-submit confirmSubmit()
|
||||
POST /contracts/:id/staff/accept staffAccept()
|
||||
POST /contracts/:id/staff/request-changes requestChanges()
|
||||
POST /contracts/:id/staff/reject reject()
|
||||
POST /contracts/:id/approval-steps/:stepId/approve approveStep()
|
||||
POST /contracts/:id/contract/generate generateContract()
|
||||
GET /contracts/:id/contract/view view PDF/HTML
|
||||
POST /contracts/:id/contract/sign sign()
|
||||
POST /contracts/:id/renew renew()
|
||||
GET /contracts/:id/capacity remaining drawdown (GENERAL)
|
||||
POST /contracts/:id/bookings create booking under contract (section 4)
|
||||
GET /contracts/list-summary list
|
||||
GET /contracts/booking-requests/queue staff shipment-request queue
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3) Contract-level clearance (ONE_TIME + customs only)
|
||||
|
||||
> Runs only when the counter-sign branch opened a contract clearance cycle.
|
||||
> Service: `ContractClearanceService`. Loop: **upload → review (approve/query) → re-upload → finalize.**
|
||||
|
||||
### Who reviews
|
||||
|
||||
```
|
||||
Path A (customsClearingEnabled = false) → OPERATIONS
|
||||
Path B (customsClearingEnabled = true) → GLOBAL LOGISTICS Ethiopia (GL ET)
|
||||
```
|
||||
|
||||
### Document states & loop
|
||||
|
||||
```
|
||||
each document: PENDING → APPROVED (reviewer approves)
|
||||
→ QUERIED (reviewer demands re-upload, note required)
|
||||
→ contract back to AWAITING_CLEARANCE_DOCUMENTS
|
||||
(only queried docs re-upload; approved stay)
|
||||
|
||||
1. customer uploads all required docs → CLEARANCE_UNDER_REVIEW, each doc PENDING
|
||||
2. reviewer goes doc by doc (approve / query)
|
||||
3. customer re-uploads queried docs → back to step 2
|
||||
4. all required docs APPROVED → finalize
|
||||
```
|
||||
|
||||
### Required-doc resolution (`contract-clearance.util.ts`)
|
||||
|
||||
```
|
||||
input (customer uploads):
|
||||
Path B: contract_clearance_{import|export}_{container|bulk}
|
||||
Path A: contract_clearance_selfclear_{import|export}_{container|bulk}
|
||||
DOMESTIC: null (no gate)
|
||||
|
||||
output (GL uploads, container customs only):
|
||||
contract_clearance_output_{import|export}_container
|
||||
(bulk or non-customs → null)
|
||||
```
|
||||
|
||||
### Finalize
|
||||
|
||||
```
|
||||
opsFinalize() Path A — requires every required input doc APPROVED
|
||||
→ clearanceStatus = SELF_CLEARED
|
||||
→ contract status = CONTRACT_ACTIVE (GENERAL) | FULLY_EXECUTED (ONE_TIME)
|
||||
→ CUSTOMER creates booking
|
||||
|
||||
finalize() Path B — requires every required input APPROVED + every required output uploaded
|
||||
→ clearanceStatus = CLEARANCE_READY_FOR_BOOKING
|
||||
→ GL creates booking
|
||||
```
|
||||
|
||||
### Endpoints
|
||||
|
||||
```
|
||||
GET /contracts/:id/clearance document grid
|
||||
POST /contracts/:id/clearance/documents customer upload (multipart)
|
||||
POST /contracts/:id/clearance/review GL approve | query
|
||||
POST /contracts/:id/clearance/output-documents GL upload output docs
|
||||
POST /contracts/:id/clearance/finalize GL finalize → CLEARANCE_READY_FOR_BOOKING
|
||||
POST /contracts/:id/clearance/ops-review Ops approve | query
|
||||
POST /contracts/:id/clearance/ops-finalize Ops finalize → SELF_CLEARED
|
||||
GET /contracts/clearance/queue GL ET queue (customs contracts)
|
||||
GET /contracts/clearance/ops-queue Operations queue (self-clear)
|
||||
GET /contracts/clearance/history GL completed
|
||||
GET /contracts/clearance/ops-history Ops completed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4) Booking — who creates it & the gate
|
||||
|
||||
> Turn a ready contract into a shipment. Service: `ContractBookingService` (creation gate), `BookingTransitionService` (lifecycle).
|
||||
> Endpoint: `POST /contracts/:id/bookings`.
|
||||
|
||||
### The gate (`assertGate`)
|
||||
|
||||
```
|
||||
Customs (Path B) — only GL ET (needs contracts.createBooking permission):
|
||||
ONE_TIME : contract.clearanceStatus = CLEARANCE_READY_FOR_BOOKING
|
||||
GENERAL : contract.status = CONTRACT_ACTIVE
|
||||
booking starts in AWAITING_DOCUMENTS (per-booking clearance), createdByRole = GL_ET
|
||||
|
||||
No customs (Path A / DOMESTIC) — customer or staff:
|
||||
contract.status = FULLY_EXECUTED or CONTRACT_ACTIVE
|
||||
booking starts in OPERATION_REQUEST_PENDING (no clearance gate),
|
||||
createdByRole = CUSTOMER | STAFF
|
||||
```
|
||||
|
||||
So per-booking clearance applies to **every customs booking** — both the GENERAL drawdown and the one-time case (whose contract cycle already ran). Path A / domestic bookings skip straight to the operation request.
|
||||
|
||||
### Booking status enum (`BOOKING_STATUSES`)
|
||||
|
||||
```
|
||||
DRAFT · SUBMITTED · PRICE_CHANGED_PENDING_CONFIRM · CHANGES_REQUESTED
|
||||
PENDING_APPROVAL · APPROVED_PENDING_SIGNATURE · APPROVED · CONTRACT_READY
|
||||
SIGNED_CUSTOMER · FULLY_EXECUTED
|
||||
AWAITING_DOCUMENTS · DOCUMENTS_UNDER_REVIEW · CLEARANCE_READY
|
||||
OPERATION_REQUEST_PENDING · OPERATION_CHANGES_REQUESTED
|
||||
SELECTED_FOR_BATCH · ROAD_DISPATCH_PENDING · PAID · IN_TRANSIT · COMPLETED
|
||||
REJECTED · CANCELLED · EXPIRED · PENDING_CONSOLIDATION · CONSOLIDATED
|
||||
```
|
||||
|
||||
Payment (`paymentStatus`): `PENDING → PNR_GENERATED → VERIFICATION_IN_PROGRESS → PAID` (or `FAILED`).
|
||||
Scheduling (`schedulingStatus`): `NOT_SCHEDULED · HOLDING · ELIGIBLE · SCHEDULED · DISPATCHED`.
|
||||
|
||||
### Customer-self-booking lifecycle (Path A / domestic — same approval shape as a contract)
|
||||
|
||||
```
|
||||
DRAFT
|
||||
→ generate-price → submit
|
||||
price unchanged → SUBMITTED
|
||||
price changed → PRICE_CHANGED_PENDING_CONFIRM → confirm-submit → SUBMITTED
|
||||
→ acceptIntake (staff) → PENDING_APPROVAL (validity window + approval steps)
|
||||
→ approveStep ×N (LINE_STAFF → DIRECTOR → CEO) → APPROVED (auto-generates contract)
|
||||
→ CONTRACT_READY → customerSign → SIGNED_CUSTOMER
|
||||
→ marketingApprove → FULLY_EXECUTED (sets fullyExecutedAt, lockedAt)
|
||||
→ (then operation request, section 5)
|
||||
```
|
||||
|
||||
Side branches: `requestChanges → CHANGES_REQUESTED`; `staffReject / reject → REJECTED`; `cancel → CANCELLED` (DRAFT…CONTRACT_READY).
|
||||
|
||||
### Transition methods (`BookingTransitionService`)
|
||||
|
||||
```
|
||||
submit · confirmSubmit · requestChanges · acceptIntake · staffReject · reject
|
||||
approveStep · rejectStep · generateContract · customerSign · marketingApprove
|
||||
governmentExpedite (govt fast-path → PAID)
|
||||
requestOperation · proceedToOperation · reviewOperationRequest
|
||||
submitClearanceDocuments · reviewDocument · uploadClearanceOutputDocuments · finalizeClearance
|
||||
startTransit · complete · cancel · requestConsolidation · removeConsolidation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) Per-booking clearance + operation request
|
||||
|
||||
> The customs booking's own document loop, then everyone funnels into the operation request that puts the shipment in the schedule pool.
|
||||
|
||||
### Per-booking clearance (customs bookings only)
|
||||
|
||||
```
|
||||
GL creates booking → AWAITING_DOCUMENTS
|
||||
submitClearanceDocuments (customer upload) → DOCUMENTS_UNDER_REVIEW
|
||||
reviewDocument (GL) → doc APPROVED | QUERIED (note)
|
||||
uploadClearanceOutputDocuments (GL, customs output)
|
||||
finalizeClearance requires 100% required inputs APPROVED + required outputs present
|
||||
→ CLEARANCE_READY
|
||||
proceedToOperation → OPERATION_REQUEST_PENDING
|
||||
```
|
||||
|
||||
inputCode / outputCode resolve from `(tradeDirection, freightType, customsClearingEnabled)` — same scheme as the contract loop. Doc review status: `PENDING · APPROVED · QUERIED`.
|
||||
|
||||
### Operation request (all paths)
|
||||
|
||||
```
|
||||
requestOperation() guard CLEARANCE_READY | OPERATION_CHANGES_REQUESTED, valid schedule day
|
||||
→ OPERATION_REQUEST_PENDING
|
||||
(Path A / domestic bookings begin life here directly)
|
||||
|
||||
reviewOperationRequest(decision):
|
||||
ACCEPT → acceptOperationRequest():
|
||||
train service → FULLY_EXECUTED + enqueue batch fill (origin, dest, day)
|
||||
truck service → ROAD_DISPATCH_PENDING (skips train pool, section 7)
|
||||
REQUEST_CHANGES → OPERATION_CHANGES_REQUESTED (note; customer resubmits)
|
||||
```
|
||||
|
||||
### Clearance / operation endpoints (`bookings.controller.ts`)
|
||||
|
||||
```
|
||||
GET /bookings/:id/clearance docs grid + GL review state
|
||||
POST /bookings/:id/clearance/documents submitClearanceDocuments → DOCUMENTS_UNDER_REVIEW
|
||||
POST /bookings/:id/clearance/review reviewClearanceDocument (approve | query)
|
||||
POST /bookings/:id/clearance/output-documents GL upload output
|
||||
POST /bookings/:id/clearance/finalize finalizeClearance → CLEARANCE_READY
|
||||
POST /bookings/:id/clearance/proceed proceedToOperation → OPERATION_REQUEST_PENDING
|
||||
POST /bookings/:id/operation/review reviewOperationRequest (ACCEPT | REQUEST_CHANGES)
|
||||
```
|
||||
|
||||
Booking lifecycle endpoints (selected):
|
||||
|
||||
```
|
||||
POST /bookings · PATCH /bookings/:id · DELETE /bookings/:id (DRAFT only)
|
||||
POST /bookings/:id/generate-price · /submit · /confirm-submit · /reject
|
||||
POST /bookings/:id/staff/accept · /staff/request-changes · /staff/reject
|
||||
POST /bookings/:id/approval-steps/:stepId/approve · /reject
|
||||
POST /bookings/:id/contract/generate · /contract/sign · GET /contract/view
|
||||
POST /bookings/:id/marketing/approve → FULLY_EXECUTED
|
||||
POST /bookings/:id/government-expedite govt → PAID
|
||||
POST /bookings/:id/operations/start-transit → IN_TRANSIT
|
||||
POST /bookings/:id/operations/complete → COMPLETED
|
||||
POST /bookings/:id/cancel → CANCELLED
|
||||
GET /bookings/my customer payable list
|
||||
GET /bookings/queues/:queue intake | approval | signatures | marketing | finance
|
||||
GET /bookings/:id/tracking shipment tracking
|
||||
POST /bookings/:id/consolidation · DELETE · GET pair partial-wagon bookings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6) GL Phase 2 — post-booking milestones (customs / Path B)
|
||||
|
||||
> Once GL creates a customs booking, the system seeds the **post-booking milestone timeline**.
|
||||
> Services: `ClearanceMilestoneService` (seed/advance), `GlOperationsService` (structured actions).
|
||||
> `seedPostBookingMilestones(booking)` runs at GL booking creation. Each milestone: `PENDING → COMPLETED` (or `SKIPPED`).
|
||||
|
||||
### Milestone owners
|
||||
|
||||
`ET` (GL Ethiopia) · `DJ` (GL Djibouti) · `OPS` (Operations) · `CUST` (Customer)
|
||||
|
||||
### Import timeline (catalog order, post-booking segment)
|
||||
|
||||
```
|
||||
WAGON_REQUESTED → FREIGHT_PAYMENT_SETTLED → WAGON_ALLOCATED → GATEPASS_GRANTED
|
||||
→ READY_FOR_LOADING → LOADED → DEPARTED_FROM_DJIBOUTI [HANDOFF ET↔DJ]
|
||||
→ ARRIVED_ETHIOPIA → OFFLOADED → T1_CLOSED → RISK_ASSIGNED
|
||||
→ IMPORT_RELEASE_GRANTED → IMPORT_PROCESS_COMPLETED
|
||||
→ STORAGE_INVOICE_RAISED → EXIT_NOTE_GENERATED
|
||||
```
|
||||
|
||||
(Pre-booking import milestones — `IMPORT_DOCS_UPLOADED · PENDING_DOCUMENT_REVIEW · DOCUMENTS_APPROVED · UNDER_CUSTOMS_CLEARANCE · DECLARED · DUTY_TAXES_ADVISED · DUTY_TAX_PAID · DO_COLLECTED` — track the clearance loop and end at `DO_COLLECTED`.)
|
||||
|
||||
### Export timeline (post-booking segment)
|
||||
|
||||
```
|
||||
WAGON_REQUESTED → FREIGHT_PAYMENT_PENDING → FREIGHT_PAYMENT_SETTLED → WAGON_ALLOCATED
|
||||
→ CARGO_ARRIVED → READY_FOR_LOADING → LOADED → DEPARTED_TO_DJIBOUTI [HANDOFF]
|
||||
→ ARRIVED_AT_DJIBOUTI → GATEPASS_GRANTED → OFFLOADED
|
||||
```
|
||||
|
||||
(Pre-booking export: `EXPORT_DOCS_UPLOADED · PENDING_DOCUMENT_REVIEW · DOCUMENTS_APPROVED · RELEASE_ORDER_SECURED · UNDER_CUSTOMS_CLEARANCE · DECLARED · EXPORT_RELEASED`.)
|
||||
|
||||
### Advance logic
|
||||
|
||||
```
|
||||
completeForBooking(bookingId, code, userId?, note?) mark COMPLETED + triggeredAt/By
|
||||
completeForContract(contractId, code, …) pre-booking contract milestones
|
||||
completeByDocTrigger(scope, code) auto-complete from a doc upload
|
||||
onHandoff(bookingId, code) fires on DEPARTED_* (notification reserved)
|
||||
```
|
||||
|
||||
### Structured GL actions (`GlOperationsService` + `gl-operations.dto.ts`)
|
||||
|
||||
```
|
||||
assignRisk riskLevel = GREEN | YELLOW | RED → completes RISK_ASSIGNED
|
||||
adviseDuty {amount, currency, declarationSerial?} → completes DUTY_TAXES_ADVISED
|
||||
customer uploads slip → DUTY_TAX_PAID
|
||||
assignStation {stationYardId, staffId?} sets glStationYardId/glAssignedStaffId (GL US-02)
|
||||
reportIncident incidentType = SEAL_BROKEN | CONTAINER_OPENED | CONTAINER_DAMAGED | FLUID_LEAKING
|
||||
+ description + photos → ClearanceIncident
|
||||
uploadDocuments / uploadDutySlip → doc-triggered milestone auto-complete
|
||||
```
|
||||
|
||||
### Doc-triggered milestones (`DOC_CODE_TO_MILESTONE`)
|
||||
|
||||
| Upload (code) | Completes | Owner |
|
||||
|---------------|-----------|-------|
|
||||
| `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** |
|
||||
| `incident_photo` | (logging only, no milestone) | — |
|
||||
|
||||
### Endpoints
|
||||
|
||||
```
|
||||
POST /contracts/bookings/:bookingId/milestones/:code/complete manual complete
|
||||
POST /contracts/:id/milestones/:code/complete pre-booking contract milestone
|
||||
POST /contracts/bookings/:bookingId/risk assignRisk
|
||||
POST /contracts/bookings/:bookingId/duty adviseDuty
|
||||
POST /contracts/bookings/:bookingId/station-assign assignStation
|
||||
POST /contracts/bookings/:bookingId/documents GL doc upload (DO/RO/T1/…)
|
||||
POST /contracts/bookings/:bookingId/duty-slip customer duty slip
|
||||
GET /contracts/bookings/:bookingId/incidents list
|
||||
POST /contracts/bookings/:bookingId/incidents reportIncident
|
||||
GET /contracts/bookings/:bookingId/milestones timeline
|
||||
```
|
||||
|
||||
> Still manual-only (no fee engine): `STORAGE_INVOICE_RAISED`, `EXIT_NOTE_GENERATED`. Out of scope: demurrage auto-calc, finance AP closure, multimodal, truck waybill/POD.
|
||||
|
||||
---
|
||||
|
||||
## 7) Schedule — demand batching (`booking-batch.service.ts`)
|
||||
|
||||
> Day-level pooling. Customer picks a **day**; the batch engine assigns the actual **train** later.
|
||||
> Cron groups bookings by `(origin yard, destination yard, day)`. EAT timezone, 3-hour windows (00–03 … 21–24).
|
||||
|
||||
### Pool states (`boardState`, read-only view)
|
||||
|
||||
```
|
||||
READY FULLY_EXECUTED + fullyExecutedAt, no train link yet
|
||||
SELECTED_FOR_BATCH picked by fill, in pay window (trainScheduleId set, paymentDeadline set)
|
||||
ALLOCATED linked to train via TrainScheduleBooking, PAID (or govt)
|
||||
WAITING PAID but not yet linked (staff-reconciled)
|
||||
EXPIRED failed to pay in window
|
||||
PENDING_CONTRACT any other non-terminal state
|
||||
```
|
||||
|
||||
### The cron cycle (every 3h; prod `0 */3 * * *`)
|
||||
|
||||
```
|
||||
1. Fill distribute (route, dest, day) pool across OPEN schedules by priorityScore
|
||||
pick earliest train; fit bookings (govt preempts commercial)
|
||||
commercial → reserve: SELECTED_FOR_BATCH + paymentDeadline = now + 1h
|
||||
govt → allocate: PAID, SCHEDULED
|
||||
2. Settle 1h after window closes — allocate paid reservations,
|
||||
expire unpaid (→ EXPIRED, unpin train), top up from waiting list
|
||||
3. Reconcile link orphaned PAID bookings to a schedule
|
||||
4. Allocate auto-assign wagon slots to allocated bookings
|
||||
```
|
||||
|
||||
`reserve()` → SELECTED_FOR_BATCH. `allocate()` → create `TrainScheduleBooking`, PAID, schedulingStatus SCHEDULED. `expire()` → trainScheduleId null, EXPIRED, schedulingStatus ELIGIBLE (back in pool).
|
||||
|
||||
### Payment → transit
|
||||
|
||||
```
|
||||
SELECTED_FOR_BATCH / AWAITING_PAYMENT → pay (Telebirr) → PAID
|
||||
PAID → startTransit → IN_TRANSIT → complete → COMPLETED
|
||||
```
|
||||
|
||||
### Wagon math
|
||||
|
||||
```
|
||||
wagonsRequired = ⌈ Σ over containers (qty × wagonsPerUnit) ⌉
|
||||
```
|
||||
|
||||
### Key endpoints (`train-scheduling.controller.ts`)
|
||||
|
||||
```
|
||||
GET /train-scheduling/available-days days with OPEN departures
|
||||
GET /train-scheduling/available-days-for-cargo capacity-aware bookable days
|
||||
GET /train-scheduling/bookable-schedules OPEN same-route schedules
|
||||
GET /train-scheduling/batch-board monitoring board (states + counts)
|
||||
GET /train-scheduling/eligible-bookings PAID/FULLY_EXECUTED ready to allocate
|
||||
POST /train-scheduling/{container|bulk}/schedules create schedule
|
||||
POST /train-scheduling/schedules/:id/assign-bookings
|
||||
POST /train-scheduling/schedules/:id/run-batch staff manual fill
|
||||
POST /train-scheduling/schedules/:id/run-allocation staff manual wagon allocation
|
||||
POST /train-scheduling/schedules/:id/finalize · /dispatch
|
||||
PATCH /train-scheduling/schedules/:id/booking-window OPEN | CLOSE
|
||||
POST /train-scheduling/bookings/:bookingId/mark-paid · /expire · /move-schedule
|
||||
GET /train-scheduling/schedules/:id/checkpoints · POST /checkpoints tracking events
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8) Delivery / last mile
|
||||
|
||||
```
|
||||
Road service: reviewOperationRequest ACCEPT → ROAD_DISPATCH_PENDING (skips train pool)
|
||||
billed by KM, dispatched by truck (First-Mile operations)
|
||||
|
||||
First/last mile: pickup + delivery addresses captured at booking; equipment return WITH | WITHOUT
|
||||
last-mile: PAYMENT_PENDING → READY_TO_TRANSIT → IN_TRANSIT → RECEIVED_TO_PORT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The whole thing on one page
|
||||
|
||||
```
|
||||
ONBOARD
|
||||
profile (importer/exporter/FF) approved → ACTIVE → can transact
|
||||
|
||||
CONTRACT (ContractTransitionService)
|
||||
submit → staffAccept → approveStep×N (LINE_STAFF→DIRECTOR→CEO) → CONTRACT_READY
|
||||
→ sign(CUSTOMER) → counterSign → BRANCH:
|
||||
GENERAL + customs → CONTRACT_ACTIVE (NOT_APPLICABLE) — clearance deferred to booking
|
||||
ONE_TIME + customs → AWAITING_CLEARANCE_DOCUMENTS — contract clearance cycle (section 3)
|
||||
DOMESTIC / no customs → FULLY_EXECUTED | CONTRACT_ACTIVE — book now
|
||||
|
||||
BOOKING (POST /contracts/:id/bookings, gate in ContractBookingService)
|
||||
customs (Path B) → only GL → starts AWAITING_DOCUMENTS
|
||||
no customs (Path A/domestic) → customer/staff → starts OPERATION_REQUEST_PENDING
|
||||
|
||||
PER-BOOKING CLEARANCE (customs only, BookingTransitionService)
|
||||
upload → review(approve/query) → finalize → CLEARANCE_READY → proceed → OPERATION_REQUEST_PENDING
|
||||
|
||||
OPERATION REQUEST (all paths)
|
||||
requestOperation → OPERATION_REQUEST_PENDING
|
||||
reviewOperationRequest ACCEPT → FULLY_EXECUTED (train) | ROAD_DISPATCH_PENDING (truck)
|
||||
|
||||
GL PHASE 2 (customs, post-booking) — ClearanceMilestoneService + GlOperationsService
|
||||
milestone timeline: wagon → pay → allocate → load → depart [handoff]
|
||||
→ arrive → offload → T1 close → risk → release → complete
|
||||
GL actions: risk (G/Y/R) · duty advise · station assign · DO/RO/T1 upload · incident
|
||||
customer: watch read-only · upload duty slip · pay freight
|
||||
|
||||
SCHEDULE (booking-batch.service.ts, 3h EAT cron)
|
||||
fill (route,dest,day) → SELECTED_FOR_BATCH (+1h pay) → pay → PAID/ALLOCATED
|
||||
→ IN_TRANSIT → COMPLETED (road → ROAD_DISPATCH_PENDING → truck)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Code map
|
||||
|
||||
| Area | Key files (`apps/edr-freight-api/src/modules/…`) |
|
||||
|------|---------------------------------------------------|
|
||||
| Contract state machine | `contracts/contract-transition.service.ts`, `contracts/entities/contract.entity.ts`, `contracts/contracts.controller.ts` |
|
||||
| Contract clearance | `contracts/contract-clearance.service.ts`, `contracts/contract-clearance.util.ts` |
|
||||
| Booking gate | `contracts/contract-booking.service.ts` |
|
||||
| Booking lifecycle + per-booking clearance | `bookings/booking-transition.service.ts`, `bookings/entities/booking.entity.ts`, `bookings/bookings.controller.ts` |
|
||||
| GL Phase 2 | `contracts/clearance-milestone.service.ts`, `contracts/clearance-milestone.catalog.ts`, `contracts/gl-operations.service.ts`, `contracts/dto/gl-operations.dto.ts`, `contracts/entities/clearance-incident.entity.ts` |
|
||||
| Schedule / batch engine | `train-scheduling/booking-batch.service.ts`, `train-scheduling/train-scheduling.service.ts`, `train-scheduling/train-scheduling.controller.ts` |
|
||||
```
|
||||
1872
docs/new-doc.md
1872
docs/new-doc.md
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user