01 — Quick Reference

Group Models
Financial Sources FinSource · FinSourceSnapshot
Postings & Batches FinPostingBatch · FinPostingDocument · FinJournalLine
Ledger Exchange FinExportAttempt · FinPostingAck · FinReconciliationItem
External Payments FinPaymentNotice
Accounting Configuration FinAccountingProfile · FinAccountMapping · FinPostingPeriod
Audit & Exceptions FinAudit · FinException

Every model (14) — one line each

Model It records Key foreign keys
FinAccountingProfile One legal entity's accounting set-up: ledger, base currency, simulated connector, mode (SIMULATION / LIVE) —
FinAccountMapping An effective-dated approved mapping of a source component to a debit and a credit account, with a dimension rule FinAccountingProfile
FinSource An immutable financial source: an issued billing document, an approved cost or an agency fact, with signed amounts and a hash —
FinPostingBatch A batch for one profile, period and currency; prepared, approved, exported, reconciled FinAccountingProfile
FinPostingDocument One balanced journal document (original, reversal or replacement) with its stable key and payload hash FinPostingBatch, FinSource, FinPostingDocument (the document it corrects)
FinJournalLine One debit or credit line of a document, with dimensions FinPostingDocument
FinExportAttempt One attempt to send a batch to the simulated adapter (or a status query) FinPostingBatch
FinPostingAck The simulated ledger's answer for one document FinPostingDocument
FinReconciliationItem A difference found: amount, currency, hash, rejection, conflict, duplicate acknowledgment, external origin FinSource, FinPostingDocument
FinPaymentNotice An external receipt or payment notice, routed to the source owner; never exported FinAccountingProfile
FinPostingPeriod An accounting period of a profile; open or closed FinAccountingProfile
FinAudit Who did what to a batch, document or source (append-only) —
FinSourceSnapshot An observed billing header or agency statement (versioned; never posts) —
FinException A control exception (quarantine, conflict, rejected / uncertain / mismatched posting, header unposted, unmatched or duplicate payment) for assurance —

Vocabularies

  • FinSource.status: RECEIVED → VALIDATED · RECEIVED → QUARANTINED · source_type: BILLING_INVOICE · PORT_COST_AGENT · PORT_COST_CARRIER · CARTAGE_COST_AGENT · CARTAGE_COST_CARRIER · AGENCY_CASH · AGENCY_COMMISSION · AGENCY_REMITTANCE · posting_mode: POST · RECONCILE_ONLY
  • FinPostingBatch.status: DRAFT → PREPARED → APPROVED → EXPORTED → RECONCILED · EXPORTED → EXCEPTION → RECONCILED
  • FinPostingDocument.status: DRAFT · PREPARED · APPROVED · SENT (simulated transport accepted, not posted) · POSTED · REJECTED · MISMATCHED · UNCERTAIN · REVERSED · document_type: ORIGINAL · REVERSAL · REPLACEMENT
  • FinExportAttempt.outcome: SIMULATED_ACCEPTED · SIMULATED_REJECTED · UNKNOWN · QUERY_FOUND · QUERY_NOT_FOUND
  • FinPostingAck.outcome: POSTED · REJECTED
  • FinReconciliationItem.variance_type: AMOUNT_MISMATCH · CURRENCY_MISMATCH · HASH_MISMATCH · REJECTED · UNCERTAIN · SOURCE_CONFLICT · DUPLICATE_ACKNOWLEDGMENT · EXTERNAL_ORIGIN
  • FinPaymentNotice.status: RECEIVED → ROUTED · UNMATCHED · DUPLICATE
  • FinAccountMapping.status: DRAFT → APPROVED → RETIRED · FinAccountingProfile.status: DRAFT → ACTIVE → RETIRED · FinPostingPeriod.status: OPEN → CLOSED
  • FinException.exception_type: SOURCE_QUARANTINED · SOURCE_CONFLICT · POSTING_REJECTED · POSTING_UNCERTAIN · POSTING_MISMATCH · UNBALANCED_JOURNAL · HEADER_UNPOSTED · PAYMENT_UNMATCHED · PAYMENT_DUPLICATE (control FINANCE_POSTING_MISMATCH / FINANCE_PAYMENT_UNMATCHED)

Messages (when run in the Shipping Cargo & Voyage network)

Direction Message What
publishes finance.posting_status a document's status (SENT, POSTED, REJECTED, MISMATCHED, UNCERTAIN, REVERSED) with source app and reference, hash, external document ref, version, evidence and reason — to the source owner, never a new source
publishes finance.payment_notice an external payment notice, routed for matching (coast_05_rating, coast_07_accounts); never exported as cash
publishes finance.exception_raised / finance.exception_resolved a control exception, and its resolution for assurance
consumes rating.posting_snapshot the complete issued billing document: the one billing source
consumes rating.billing_document_issued the header: an observation compared with the snapshot
consumes portcost.cost_approved, cartage.cost_approved an approved supplier cost (agent-paid or carrier-payable)
consumes accounts.financial_fact_committed a committed agency cash / commission / remittance fact
consumes accounts.statement_issued an agency statement: an observation only
consumes assurance.action_requested an action aimed at a finance exception
accepts finance.record_ledger_acknowledgment the simulated ledger's answer for one document
accepts finance.record_payment_notice an external payment notice
accepts finance.detect_unreconciled the sweep: sent documents never answered become UNCERTAIN; unposted headers raise an exception
accepts finance.retry_export {batch_no}: resend an exception batch's unsent or unanswered documents (same document keys); refused after an unknown outcome until the ledger was queried
accepts finance.query_ledger {batch_no}: ask the simulated ledger whether it has the batch after an unknown outcome (QUERY_FOUND / QUERY_NOT_FOUND)

Simulated connector scripts (profile connector_ref)

mock_ledger (accepts) · mock_ledger_reject (refuses the whole batch) · mock_ledger_timeout_received (answer lost; a status query finds the batch) · mock_ledger_timeout_lost (answer lost; a status query finds nothing).

Run, seed, regenerate

python server/run.py coast_15_finance                     # http://localhost:5199
python -m codegen.cli all coast_15_finance                # regenerate models, controllers and JSON after a schema change
python -m codegen.cli integration coast_15_finance        # regenerate the integration contract (handlers.py is never overwritten)
python -m codegen.cli seed coast_15_finance --reset       # reload the sample data
python scripts/build_diagram_viewer.py coast_15_finance   # rebuild the interactive diagram