Coastal Shipping 07 — Voyage Accounts & Agency Settlement Manager (coast_07_accounts)
Settle with the carrier's port agent on actual cash — agency appointments, collection responsibility, the receipts and payments the agent really made, commission, remittances, and settlement statements that are issued once and never edited.
Its central question:
What does this agent owe the carrier for this voyage and port call, on confirmed cash only — and can we prove every figure?
coast_07_accounts is application SHP-07 of the Coastal Shipping series, Stage 2 (coast_NN_<name>, numbered by the pack catalogue; each able to run stand-alone or as a member of a network).
It shares no tables and no foreign keys with its siblings (for example coast_05_rating, which owns the customer invoices) — they link by string references and by messages. All data is fictional.
The spine
AccountAgent → AgencyAppointment → VoyageAccount → (AccountSource / AgentCollection / AgentPayment / AgentCommission / AgentRemittance / SettlementAdjustment) → SettlementStatement, with CollectionResponsibility deciding which charges the agent collects and AccountAudit recording history.
The documents
| Page | What's in it |
|---|---|
| 00 — Overview | What the app is, the rules it is built around, the 17 models by area, the demo scenario |
| 01 — Quick Reference | Menu map, every model, status vocabularies, how to run, seed and regenerate |
| 02 — System Diagram | The data model as diagrams (+ interactive viewer) and how the app links to its siblings |
Status
Built (rules and handlers, tested): the appointment, account and statement workflows with their guards (reconcile, submit, approve, settle, reopen; statement approve and issue); collection, payment, commission, remittance, adjustment, dispute, assignment and conversion rules (signed exact reversal, evidence, approval by someone other than the maker, no over-allocation, no cash while the statement is being finalised); the settlement balance, which agrees with the pack's reference calculation (PGK 110.00 in the pack's example); the single-currency rule with approved conversions; immutable approved and issued statements with linked revisions; handlers for the voyage, port-call, effective-cargo, call-mapping, issued-charge and approved-cost facts it consumes (versioned, idempotent by source key and hash, out-of-order facts wait pending); control exceptions and the assurance action.
Scheduled (built, tested): accounts.detect_variances raises AGENT_SETTLEMENT_VARIANCE once for a latest statement that no longer equals the actual cash, and retries charges and costs that were waiting.
Not built yet: opening an account by hand does not itself pull the charges that were waiting for it (they are retried on the next message or sweep); no general-ledger posting (SHP-15); the sibling applications' events (voyage.*, portcost.*, cartage.*) and rating.billing_charge_detail_issued need their producers. The rules are in integration/ (rules.py, handlers.py, exceptions.py, calc.py), with their tests under server/tests/integration_apps/ and server/tests/test_coast_accounts_pack_crosscheck.py.
Prototype system; draft. All names and amounts in the demo data are fictional.