27 · Business auditability & invoicing

What management actually needs

Three layers of “truth” (do not mix them blindly)

flowchart TB
  subgraph MONEY["1 · Money truth — canonical"]
    INV[(Invoices + line items
tenant main)]
    PAY[Payments / tenders linked]
  end

  subgraph OPS["2 · Operational timeline"]
    CART[pos_carts + cart events]
    TT[transaction tracking timeline]
    REG[register_shifts]
  end

  subgraph COMP["3 · Compliance / security audit"]
    AL[(audit_logs · analytics DB)]
    HR[hr_audit_log write-only]
  end

  POS[POS finalize] --> INV
  POS --> CART
  POS --> AL
  TIX[Ticket bill checkout] --> INV
  INV --> PAY
          

Core Invoicing system

Deliberate backbone: POS, kiosk, crypto, inventory adjustments, and service tickets are supposed to create invoices through CoreInvoicingService — single money language (cents, org, source, type).

Factory methods

HTTP API — /api/core-invoicing

POST /invoice · /payment · /pos-sale · /kiosk-order · /crypto-invoice · /service-ticket · /inventory-adjustment · /void-invoice · /refund-invoice · sales/inventory analytics GETs

Also

• /api/invoices — list/create/get/update + payments on invoice
• Receipts hang off invoice IDs (DocHub 23)
• Void/refund should emit financial audit events (taxonomy includes INVOICE_VOID / INVOICE_REFUND)

Ticketing ↔ invoicing (billable tickets)

flowchart TD
  T[Service ticket]
  B[bill.items · amountCts · status]
  C[POST .../bill/checkout]
  I[CoreInvoicingService.createServiceTicketInvoice]
  INV[(Invoice source=service_ticket)]
  P[Payments / mark-paid]
  CRYPTO[POST .../invoice crypto]

  T --> B
  B --> C --> I --> INV
  INV --> P
  T --> CRYPTO
          

Ticket bill API (scopes tickets:read/write)

Appointment create can also spawn a ticket with ticketId/ticketNumber (DocHub 16) — that ticket can then be billed the same way if the business uses invoice-style service work.

Bill shape (conceptual)

status: none | unpaid | paid · items[] · amountCts · currency · invoiceId · paidAt

Transaction & sales visibility (owner UI)

Backend list APIs (multiple — intentional stress point)

• /api/transactions — primary list + get by id
• /api/unified/transactions — unified listing
• /api/simple simple transactions — read-only convenience
• /api/transaction-tracking — timeline, entity trail, stats, search
• /api/v1/transactions — payments-engine style

Audit system (compliance layer)

Storage

General audit_logs live in tenant analytics DB (high-volume, off the hot POS path). Categories enum: authentication, authorization, data_access, configuration, financial, system, general.

API /api/audit (session + tenant)

UI /admin/audit-logs

Presets: Financial & POS, Staff, Register shifts, Sign-in, Authorization, Configuration, Catalogs. Tabs/helpers pull employee activity, time/attendance, transaction audit reports, security/financial summaries.

What is actually written today (honest)

Register & shift (cash accountability)

Open/close ceremony + admin force close create auditable register_shift rows and audit events. Shift history CSV export supports EOD. See DocHub 14 / Appendix B.

Maturity assessment (ownership lens)

What “fully thought through” still needs

1. Instrumentation matrix — spreadsheet of every money-moving and permission-changing endpoint → must emit audit event type X (close taxonomy gaps).
2. Canonical owner “Sale detail” page — one UI that joins invoice + tenders + cart timeline + audit entity trail + receipt link.
3. Ticket billing UX polish — service desk bill editor → checkout → paid status visible next to ticket; appointment-created tickets auto-open bill when appropriate.
4. Reconciliation report — invoices total vs payments vs register cash vs reports for a date range (detect dual-path drift).
5. Retention & export policy — how long audit_logs / invoices kept; scheduled export.
6. Role matrix for who can void/refund/export — permission sets, not only admin role.
7. Automated tests — POS sale → invoice → audit row; ticket bill checkout → service invoice.

File anchors

Related DocHub