01 — Quick Reference
Menu map
| Group | Models |
|---|---|
| Orders & Evidence | PortServiceOrder · PortServicePerformance · PortCostEstimate |
| Supplier Invoices | PortSupplierInvoice · PortSupplierInvoiceLine · PortCostDispute |
| Approved Costs & Allocation | PortApprovedCost · PortCostAllocation |
| Services & Rates | PortServiceType · PortSupplierRate · PortServiceProvider |
| From the Network | PortCostVoyageProjection · PortCostCallProjection · PortCostAppointmentProjection · PortCostActivityFact |
| Audit & Exceptions | PortCostAudit · PortCostException |
Every model (17) — one line each
| Model | It records | Key foreign keys |
|---|---|---|
| PortServiceProvider | A port service supplier (authority, tug company, stevedore) | — |
| PortServiceType | One of the 22 service categories (berthage, towage, wharfage ...) and its usual basis | — |
| PortSupplierRate | A dated, port- and provider-specific rate: basis, unit rate, minimum, rounding increment, tax | PortServiceType, PortServiceProvider |
| PortServiceOrder | A service ordered for a call, with the responsible payer | PortServiceType, PortServiceProvider |
| PortServicePerformance | Evidence that the service happened: verified quantity, times, tug count, vessel size | PortServiceOrder |
| PortCostEstimate | An immutable estimate from the approved rate (not payable) | PortServiceOrder, PortSupplierRate |
| PortSupplierInvoice | A supplier invoice or credit note with its normalised key | PortServiceProvider |
| PortSupplierInvoiceLine | One invoice line against one order; its unique line key; variance reason and authority | PortSupplierInvoice, PortServiceOrder, PortServicePerformance, PortCostEstimate |
| PortApprovedCost | The immutable approved cost of one invoice line; published to the network | PortSupplierInvoiceLine |
| PortCostAllocation | An internal attribution of a cost to a manifest line (or call overhead) | PortApprovedCost |
| PortCostDispute | A dispute of an invoice line and its resolution | PortSupplierInvoiceLine |
| PortCostAudit | Who did what to an order, invoice or cost (append-only) | PortServiceOrder, PortSupplierInvoice, PortApprovedCost |
| PortCostException | A control exception (variance, unmatched fact, invalid payer appointment) for assurance | — |
| PortCostVoyageProjection | The voyage as coast_06_voyage published it (version, hash, payload) | — |
| PortCostCallProjection | A port call as published (identity distinct from port) | — |
| PortCostAppointmentProjection | An agent appointment as coast_07_accounts published it | — |
| PortCostActivityFact | A verified service activity from coast_06_voyage, matched to a performance | PortServicePerformance |
Vocabularies
- PortServiceOrder.status: DRAFT → APPROVED → PERFORMED → CLOSED · DRAFT → CANCELLED · payer_type: AGENT · CARRIER
- PortServicePerformance.status: RECORDED · VERIFIED · REJECTED
- PortSupplierRate.basis: FIXED · HOUR · DAY · MOVEMENT · TONNE · RT · TEU · ITEM · status: DRAFT · APPROVED · RETIRED
- PortSupplierInvoice.status: DRAFT → MATCHED → APPROVED · MATCHED ⇄ DISPUTED · DRAFT → CANCELLED · document_type: INVOICE · CREDIT_NOTE
- PortApprovedCost.status: APPROVED · REVERSED
- PortCostAllocation.status: PREPARED → APPROVED · PREPARED → CANCELLED · basis: REVENUE_TONNES · PACKAGE_COUNT · GROSS_MASS · VOLUME · EQUAL · DIRECT
- PortCostException.exception_type: PORT_COST_VARIANCE · UNMATCHED_SERVICE_FACT · PAYER_APPOINTMENT_INVALID
Messages (when run in the Shipping Cargo & Voyage network)
| Direction | Message | What |
|---|---|---|
| publishes | portcost.cost_approved |
an approved cost (or its signed reversal) with payer, appointment, call and exact amounts |
| publishes | portcost.exception_raised / portcost.exception_resolved |
a control exception, and its resolution for assurance |
| consumes | voyage.snapshot, voyage.portcall_snapshot |
versioned voyage and port call projections |
| consumes | voyage.activity_verified |
a verified service fact, matched to an approved order |
| consumes | accounts.appointment_changed |
a versioned agent appointment |
| consumes | assurance.action_requested |
an action aimed at a port cost exception |
| accepts | portcost.detect_unmatched_facts |
the orchestrator's sweep: match pending facts to newly approved orders, raise the ones nobody matched |
Run, seed, regenerate
python server/run.py coast_08_portcosts # http://localhost:5161
python -m codegen.cli all coast_08_portcosts # regenerate models, controllers and JSON after a schema change
python -m codegen.cli seed coast_08_portcosts --reset # reload the sample data
python scripts/build_diagram_viewer.py coast_08_portcosts # rebuild the interactive diagram