Finance Routes, Controls, and Dialogs

Shared page behavior

Every Finance route uses the active partner scope and capability snapshot. Filters, search, date/cutoff, currency, density, selected row, and saved-view state affect only the disclosed result scope; they do not change accounting truth. Tables must disclose page/result counts and must not imply that a visible page is a complete export.

Opening a row reveals its domain detail, related journal/audit/evidence history, and permitted actions. Mutations validate server-side, reject stale or locked state, disable repeated submission while pending, return a canonical result, and preserve focus when the dialog closes.

Overview

The overview shows partner liquidity and event comparison without mixing currencies. Use the currency, cutoff, search, density, and event-selection controls to inspect a stable server projection. Selected-event cards show authoritative available cash, pending outflows, book net, reconciliation coverage, exception count, source, and freshness. If an event/currency snapshot is absent, show unavailable/empty state; never divide the partner balance to fabricate one.

Primary actions open manual entry, outflow, period, payment-default, and route dialogs only when the current capability allows them. The accountability rail links outstanding approvals, evidence gaps, reconciliation issues, and close blockers to their owning route.

Transactions

Use search and date, account, event, counterparty, category, state, currency, amount, reconciliation, and evidence filters to inspect immutable posted activity. A row detail includes balanced debit/credit lines, source, dimensions, allocation, reconciliation link, evidence history, approvals, reversals/corrections, and audit correlation.

The manual-entry dialog requires posting date, reference, description, currency, and balanced account lines. Allocation, attach/detach evidence, and reverse/correct are separate accountable actions. A locked period, mixed-currency lines, unbalanced total, stale version, or duplicate idempotency payload must stop the action with a specific error.

Outflows

The route separates draft, submitted, approved, scheduled, paid, rejected, cancelled, and reversed states and shows counts and amounts per currency. Create/edit requires payee, payment account, event/cost dimensions, amount/currency, due date, reference, purpose, and required evidence. Submit, approve, reject, schedule, mark paid, cancel, and reverse are explicit commands. When recording a disbursement, choose an evidence file in the action dialog; the dashboard uploads it through the Worker to the restricted journal-evidence vault after the authoritative posting succeeds. Do not paste an external evidence URL.

Bulk controls apply only to compatible selected states. Maker-checker and approval thresholds are server-enforced. A provider timeout cannot silently mark an outflow paid; verify its receipt and journal link before retrying.

Reconciliation

The workbench presents account/session, statement rows, and candidate/detail context. Import accepts a supported statement file, previews parse results and duplicate hashes, and does not post during preview. Operators can match, unmatch, classify, exclude with reason, and create permitted adjustments. Split/combine support remains a release item until its strict real-stack contract is certified.

Commit requires the evidence-package review acknowledgement and atomically seals the statement population and accepted resolutions. Browser-entered evidence URLs are not accounting proof. A non-zero variance, stale candidate, duplicate source hash, locked period, or incomplete evidence package blocks commit.

Events

The comparison view groups authoritative event metrics by ISO currency. It exposes income/inflow, cost/outflow, book net, available cash, pending commitments, reconciliation coverage, exceptions, source, cutoff, and freshness. Filters and sorting run against the server-owned result set.

Event detail shows accounts, categories, mappings, settlement/reconciliation state, and transaction drill-down. Mapping changes require effective dates, conflict checks, impact preview, version protection, and audit history; this administration remains a real-stack release gate.

Audit

Filter receipts by actor, action, target, result, source, date, request/correlation ID, partner, or event. Detail includes safe before/after differences, linked journal, approval chain, evidence access history, and provider receipt without secrets or unnecessary personal data.

Exports require an immutable manifest with scope, cutoff, row count, digest, requester, expiry, and proxy artifact. Integrity failure, missing correlation, or a duplicate authoritative transition is a release-blocking finding.

Payables

Bills require vendor, vendor invoice reference, document/due dates, currency, lines, tax/fees, event/category/account dimensions, and evidence. Lifecycle actions cover draft, submit, approve/reject, schedule, partial/full pay, credit, cancel, and permitted reversal. Outstanding equals gross minus valid credits and payments, never below zero.

Duplicate invoice references, payment above outstanding, missing evidence, maker-checker conflict, and locked periods block the command. Partial payments retain application history and journal links.

Receivables

Invoices require debtor, document/due dates, currency, lines, dimensions, terms, and reference. Record collection allocates exact amounts and preserves unapplied money separately; over-allocation is forbidden. Lifecycle actions include issue, collect, allocate/unallocate, credit, write off with approval, cancel, and correct.

The route discloses outstanding, overdue, aging, application history, and journal effects by currency. A write-off is an accountable approval, not a visual status change.

Expenses

Claims contain claimant, event/category, purpose, dates, currency, itemized rows, evidence, and policy results. Operators save draft, submit, review, approve/reject, and reimburse through separate commands. Policy exceptions require a disclosed rule, explanation, approver, and audit record.

Receipt entry is guided; raw JSON is not an operator control. Reimbursement cannot exceed the approved outstanding amount or post into a locked period.

Budgets

Budget versions define owner, period, currency, event/category/account dimensions, line allocations, forecast, thresholds, and state. The route shows original, revisions, transfers, actuals, commitments, available amount, and variance with formula and cutoff.

Revisions are immutable versions. Draft, submit, approve/reject, publish, revise, transfer, and archive require exact totals, valid scope, version checks, and journal/audit linkage where applicable.

Close

Period detail shows readiness, checklist owner/state, reconciliation completeness, trial-balance/summary, exceptions, evidence, sign-offs, and current lock. Close is atomic: unresolved blockers prevent lock and later posting. Reopen requires capability, reason, recent authentication when configured, and an audit receipt.

Use pre-close review, close-day sign-off, post-close verification, and correction/reopen as distinct procedures. Never change a closed journal row directly.

Custody

Open checkout binds custodian, account, event, currency, purpose, opening float, and guided denomination counts. The current PHP form uses ₱1,000, ₱500, ₱200, ₱100, ₱50, and ₱20 count rows and derives the total. The API must validate counts and total rather than trust a hidden/browser total.

Acknowledge, movement, count, discrepancy, handover, return, and close retain actor and timestamp evidence. Dual control applies to supervisor close and handover where policy requires it. A count difference blocks normal close until explained and approved.

Automation

The route contains search/filter, six health metrics, routing rules, job history, detail, test, edit, enable/disable, and run controls. Rules have typed conditions/actions, priority/order, destination, and version. Test/dry-run shows matched scope without causing the authoritative action.

Jobs retain lease, attempt, next retry, provider receipt, error class, quarantine/dead-letter, replay, and audit state. Telegram and Discord actions require a currently linked identity and the same capability as the equivalent dashboard command.

Integrations

Bank, accounting, and interchange connections are distinct types. Cards and detail expose health, granted scope, mapping, last/next sync, imported counts, failure state, and available recovery. Guided add collects provider/type and only the configuration required for that connector.

Test, sync, pause, reauthorize, remap, and disconnect are accountable commands. Credentials are encrypted by platform bindings and never returned after write. Provider revocation, signature/state failure, duplicate imports, and stale sync leases require explicit recovery.

Settings

Tabs cover cash/ledger accounts, default accounts, roles/capabilities, approval rules, close/custody policies, numbering, currencies, integrations, and notifications as shipped. Cash-account create/edit requires name, ledger account, currency, opening balance, active state, and impact preview.

The API rejects a ledger account outside the partner, a currency mismatch, and changes to ledger/currency/opening balance after postings. Archive preserves historical journals. Every policy edit requires a version, effective behavior, impact disclosure, capability, and audit receipt.

Dialog interaction contract

Family	Required interaction evidence
Entry/outflow/record	Labelled fields, inline and summary validation, balanced/exact amounts, pending lockout, success focus return
Import/review	File/type limits, preview population and digest, duplicate/errors, separate commit acknowledgement
Period/payment default/settings	Current version, impact preview, safeguard warning, explicit confirmation, canonical refreshed result
Custody/custody action	Guided denominations, derived expected/counted/difference, actor binding, dual-control warning
Automation/integration/profile	Provider/type/scope, test result, secret redaction, retry/revoke guidance, audit receipt
Destructive action	Specific consequence and correction path; never rely on a generic native confirmation

All dialogs need an accessible title/description, initial focus, logical tab order, visible focus, Escape behavior when safe, focus return, and live validation/status text.