integreat/docs/testing/behaviors/invoice.md

Invoice Behaviors

Overview

Invoices are the core entity of the Integreat accounts payable system. They represent bills from vendors that clients must pay. The invoice subsystem supports full lifecycle management from creation/import through payment and voiding, with comprehensive filtering, bulk operations, and OCR-based automated entry via Glimpse.

User value:

• Track all vendor bills in one place
• Pay invoices individually or in bulk via checks, debits, cash, or credit
• Import invoices from CSV/PDF files with automatic data extraction
• Spread expenses across multiple locations
• Manage invoice status (unpaid, paid, voided, scheduled)

Routes & Pages

Route	Handler	Purpose
GET /invoices	::all-page	List all invoices
GET /invoices/unpaid	::unpaid-page	List unpaid invoices
GET /invoices/paid	::paid-page	List paid invoices
GET /invoices/voided	::voided-page	List voided invoices
GET /invoices/table	::table	HTMX table refresh
GET /invoices/new	::new-wizard	Create new invoice wizard
POST/PUT /invoices/new	::new-invoice-submit	Submit new/edit invoice
PUT /invoices/new/navigate	::new-wizard-navigate	Wizard step navigation
PUT /invoices/new/due-date	::due-date	Calculate due date from vendor terms
PUT /invoices/new/scheduled-payment-date	::scheduled-payment-date	Calculate scheduled payment from vendor autopay
PUT /invoices/new/account/prediction	::account-prediction	Show vendor default account suggestion
PUT /invoices/new/total	::expense-account-total	Calculate expense account total
PUT /invoices/new/balance	::expense-account-balance	Calculate balance vs invoice total
GET /invoices/new/account/new	::new-wizard-new-account	Add new expense account row
GET /invoices/new/account/location-select	::location-select	Location dropdown for account
GET /invoices/pay-button	::pay-button	Render pay button with selected invoice totals
GET /invoices/pay	::pay-wizard	Pay selected invoices wizard
POST /invoices/pay	::pay-submit	Submit payment
POST /invoices/pay/using-credit	::pay-using-credit	Pay using vendor credit balance
PUT /invoices/pay/navigate	::pay-wizard-navigate	Pay wizard step navigation
GET /invoices/bulk-delete	::bulk-delete	Bulk void confirmation dialog
DELETE /invoices/bulk-delete	::bulk-delete-confirm	Execute bulk void
GET /invoices/bulk-edit	::bulk-edit	Bulk edit expense accounts wizard
PUT /invoices/bulk-edit	::bulk-edit-submit	Submit bulk edit
GET /invoices/bulk-edit/account	::bulk-edit-new-account	Add new account row in bulk edit
PUT /invoices/bulk-edit/total	::bulk-edit-total	Calculate percentage total
PUT /invoices/bulk-edit/balance	::bulk-edit-balance	Calculate percentage balance
DELETE /invoices/:id	::delete	Void single invoice
PUT /invoices/:id/undo-autopay	::undo-autopay	Undo scheduled autopay
PUT /invoices/:id/unvoid	::unvoid	Restore voided invoice
PUT /invoices/:id/edit	::edit-wizard	Edit existing invoice
GET /invoices/import	::import-page	Import invoices page
POST /invoices/import/upload	::import-file	Upload and parse invoice files
GET /invoices/import/table	::import-table	Import table refresh
DELETE /invoices/import/:id/disapprove	::disapprove	Remove pending imported invoice
PUT /invoices/import/:id/approve	::approve	Approve pending imported invoice
DELETE /invoices/import/disapprove	::bulk-disapprove	Bulk remove pending imports
PUT /invoices/import/approve	::bulk-approve	Bulk approve pending imports

Behaviors by Page

Invoice List Page

Unit Tests

• fetch-ids generates correct Datomic queries for all filter combinations
• fetch-page returns [results count outstanding-sum total-sum] tuple
• sum-outstanding and sum-total-amount calculate aggregates correctly
• selected->ids resolves "all selected" vs individual selection
• hydrate-results groups and orders pulled entities by input IDs
• payable-ids filters to only unpaid, non-scheduled invoices
• can-undo-autopayment validates invoice state for undo eligibility

Integration Tests

• Happy path: Load list page with invoices, verify table renders
• Filter by vendor: Select vendor, table refreshes with filtered results
• Filter by account: Select account, table refreshes
• Filter by date range: Apply date range, results filtered
• Filter by amount range: Set min/max amounts, results filtered
• Filter by invoice number: Partial match on invoice number
• Filter by check number: Search by check number
• Exact match: Navigate from notification to specific invoice via exact-match-id
• Sort by each column: Click column headers (client, vendor, date, due, invoice-number, total, outstanding-balance, location, description-original)
• Pagination: Navigate pages, change per-page (default 25)
• Selection: Check individual rows, select all, select all filtered
• Action buttons appear conditionally: Based on permissions and selection state
• Legacy redirects: Old routes redirect to new SSR routes

UI Tests (SSR)

• Table renders with correct columns: Client, Vendor, Invoice #, Date, Due, Status, Account, Outstanding, Links
• Status pills display correctly: Paid (primary), Voided (red), Scheduled (yellow), Unpaid (secondary)
• Due date shows relative time: "today", "in X days", "X days ago" with color coding
• Outstanding shows partial payment indicator when balance != total
• Links dropdown shows payments, transactions, ledger entries, source files
• Client column hidden when single client with single location
• Row action buttons: Void (unpaid), Edit (unpaid/paid), Unvoid (voided), Undo autopay (eligible)
• Pay button tooltip explains why disabled: no selection, multiple clients, mixed debit/credit
• Break table grouping by vendor name when sorting by vendor

New Invoice Wizard

Unit Tests

• new-form-schema validates required fields, money amounts, entity IDs
• Vendor must have default expense account (check-vendor-default-account)
• clientize-vendor applies client-specific terms, account overrides, autopay settings
• assert-no-conflicting prevents duplicate invoice numbers per vendor/client
• assert-invoice-amounts-add-up validates expense accounts sum to total
• maybe-spread-locations spreads "Shared" location across all client locations
  • Existing tests in new_invoice_wizard_test.clj cover:
    • Equal spread across 2 locations
    • Negative amount spreading
    • Remainder distribution (33.34, 33.33, 33.33)
    • Negative remainder distribution
    • Single cent leftover tolerance (apply-total-delta-to-account)
• $->cents and cents->$ round correctly
• calculate-spread distributes base amount + remainder

Integration Tests

• Happy path create:
  1. Open wizard, select client, vendor, date, invoice number, total
  2. Due date auto-calculates from vendor terms when client+date+vendor selected
  3. Scheduled payment auto-calculates from vendor autopay setting
  4. Save with default account → invoice created with vendor's default account
  5. Wizard navigates to "Next Steps" with Pay now / Add another / Close options
• Happy path customize accounts:
  1. Select "Customize accounts" on basic details
  2. Add multiple expense account rows
  3. Select account, location (auto-populated from account or Shared), amount
  4. Total and balance update dynamically via HTMX
  5. Location dropdown updates when account changes
  6. Save validates totals match
• Edit existing invoice:
  1. Open edit wizard for unpaid/paid invoice
  2. Vendor field disabled (cannot change)
  3. Modify amounts, add/remove accounts
  4. Save updates row in place

UI Tests (SSR)

• Wizard renders as modal with Basic Details → Expense Accounts (optional) → Next Steps
• Client typeahead searches companies
• Vendor typeahead searches vendors, disabled when editing
• Date inputs use normal date format
• "Add due / scheduled payment date" link appears when dates not set
• Account prediction radio shows vendor default account name
• Expense account grid: Account, Location, Amount columns
• New account row button adds empty row
• Remove row button with Alpine.js transition
• Total/Balance rows update on amount change
• Validation errors display per field

Pay Wizard

Unit Tests

• payment-form-schema validates payment structure
• does-amount-exceed-outstanding? catches over/under payments
• can-handwrite? validates single vendor and positive balance for handwritten checks
• credit-only? detects when all vendor totals are negative (credit scenario)
• pay-button* calculates vendor totals and detects credit payment scenarios

Integration Tests

• Happy path - debit:
  1. Select unpaid invoices from same client
  2. Click Pay → Choose Payment Method modal opens
  3. Select bank account → click Debit
  4. Confirm "Pay in full" or switch to "Customize payments"
  5. Submit → payments created, checks printed if applicable
• Happy path - print check:
  1. Select check-type bank account
  2. Choose "Print check"
  3. Payment processed, PDF URL returned for printing
• Happy path - cash:
  1. Select cash-type bank account
  2. Payment processed immediately
• Happy path - handwrite check:
  1. Single vendor, positive balance required
  2. Enter check number and date
  3. Payment created with pending status
• Happy path - credit payment:
  1. Select invoices where vendor total is 0 (credit + debit balance)
  2. Pay button shows "Pay invoices using credit"
  3. Credit invoices offset payment invoices
  4. Balance payment created
• Validation:
  • Cannot pay invoices from multiple clients
  • Cannot pay with mixed vendor debit/credit totals
  • Custom payment amounts cannot exceed outstanding balance
  • Handwritten check requires check number
  • Locked client dates blocked

UI Tests (SSR)

• Pay button shows count and total amount
• Warning pill appears when some selected invoices are locked/scheduled
• Bank account cards show type-appropriate icons (cash=green, check=blue, credit=purple)
• Tooltip on Pay button explains disabled state
• Payment method selection buttons: Print check, With cash, Debit, Handwrite check
• Payment details step shows invoice grid with vendor, number, total, pay amount
• Mode toggle: "Pay in full" vs "Customize payments"
• Success modal shows thumbs up, PDF download link for checks, scaling reminder

Bulk Edit

Unit Tests

• assert-percentages-add-up validates percentages sum to 100%
• maybe-code-accounts distributes expense accounts by percentage
  • Shared location spreads across all client locations
  • Rounds cents correctly with remainder handling
  • Validates account location matches

Integration Tests

• Happy path:
  1. Select invoices via checkboxes
  2. Click "Bulk Edit" → wizard opens
  3. Add expense account rows with account, location, percentage
  4. Submit → all selected invoices coded with new expense accounts
• Locked invoices excluded: Only invoices with date >= client locked-until are processed
• Validation:
  • Percentages must sum to 100%
  • Account location must match account's configured location

UI Tests (SSR)

• Wizard shows count of invoices to be edited
• Account typeahead with location dropdown
• Percentage input (displayed as whole number, stored as decimal)
• Total/Balance percentage display
• New account row button

Bulk Delete/Void

Unit Tests

• void-invoices-internal:
  • Voids cash payments linked to selected invoices
  • Only voids invoices without linked invoice-payments
  • Only voids invoices with date >= client locked-until
  • Sets total, outstanding-balance, and expense account amounts to 0

Integration Tests

• Happy path:
  1. Select invoices
  2. Click "Void selected" → confirmation modal
  3. Confirm → invoices voided, table refreshes with notification
• Admin only: Bulk delete requires admin permission
• Validation:
  • Paid invoices with linked payments require voiding payments first
  • Locked dates blocked

UI Tests (SSR)

• Red alert icon in confirmation modal
• Shows count of invoices to void
• Modal closes on success with notification

Import Page

Unit Tests

• import->invoice maps parsed data to invoice entity
• validate-invoice checks required keys and client access
• match-vendor finds vendor by code or throws with search hint
• admin-only-if-multiple-clients flags source-url for admin-only when multiple clients
• upload-schema validates force-client, force-vendor, force-location, force-chatgpt

Integration Tests

• Happy path CSV/PDF import:
  1. Upload file(s) via drag-and-drop or file input
  2. File parsed (CSV direct, PDF via OCR when allowed)
  3. Invoices created with pending import status
  4. Results table shows success/failure per file
• Force overrides:
  • Force client overrides parsed client
  • Force vendor overrides parsed vendor
  • Force location overrides parsed location
  • Force ChatGPT restricts to GPT-only parsing
• Approve/disapprove:
  • Individual approve → status changes to imported
  • Individual disapprove → invoice deleted
  • Bulk approve/disapprove with selection
• Validation:
  • Missing client, vendor, date, total → error
  • No client access → error
  • Vendor not found → error with search hint

UI Tests (SSR)

• Upload zone with drag-and-drop styling (blue idle, green hover)
• File list shows selected files
• Force client/vendor/location typeaheads
• "Only use ChatGPT" checkbox
• Results table: File, Result, Template, Sample columns
• Green/red styling for success/error
• Error list shows first 5 errors
• Import table shows pending invoices with approve/disapprove buttons
• Filters: vendor, date range, check number, invoice number, amount range

Glimpse (OCR Import)

Unit Tests

• textract->textract-invoice extracts fields from AWS Textract response
• stack-rank sorts field descriptors by confidence
• clean-customer normalizes customer names for search
• deduplicate removes duplicate parsed values
• textract-invoice->invoice converts to invoice with vendor terms and autopay

Integration Tests

• Happy path:
  1. Upload PDF to Glimpse page
  2. File uploaded to S3, Textract job started
  3. Poll every 5s while IN_PROGRESS
  4. On SUCCESS, display extracted fields with alternatives
  5. User selects client, vendor, date, total, invoice number from alternatives
  6. Save creates invoice and links to textract job
• Field extraction:
  • Total: from AMOUNT_DUE or TOTAL fields
  • Customer: from CUSTOMER_NUMBER or RECEIVER_NAME (with Solr fallback)
  • Vendor: from VENDOR_NAME with Solr search
  • Date: from INVOICE_RECEIPT_DATE, ORDER_DATE, DELIVERY_DATE
  • Invoice number: from INVOICE_RECEIPT_ID or PO_NUMBER

UI Tests (SSR)

• Upload form with Dropzone integration (PDF only)
• Progress indicator while analyzing
• Side-by-side layout: PDF preview iframe + form
• Form fields: Client, Location, Vendor, Date, Total, Invoice Number
• Alternatives shown as clickable pills below each field
• Disabled fields for client and vendor (must select from alternatives)
• Success notification with link to view new invoice

Cross-Cutting Behaviors

Filtering

All list pages support these filters (applied via HTMX with debounce):

• Vendor: Typeahead search, filters to specific vendor
• Account: Typeahead search, filters invoices with that expense account
• Date range: Start/end date for invoice date (uses scan-invoices for performance)
• Due date range: Start/end due date
• Amount range: Min/max total amount (inclusive)
• Invoice number: Partial string match via .contains
• Check number: Text search
• Status: Route-param based (all, unpaid, paid, voided) or query-param
• Import status: Filter by pending/imported
• Exact match: Navigate to specific invoice by ID (bypasses other filters)
• Scheduled payments: Filter to invoices with scheduled payment date
• Unresolved: Invoices missing expense accounts or with unassigned accounts
• Location: Filter by expense account location

Sorting

Click column headers to sort. Supported sort keys:

• client (by client name)
• vendor (by vendor name)
• description-original
• location (by expense account location)
• date
• due (nulls last with default 2050-01-01)
• invoice-number
• total
• outstanding-balance

Default sort: descending by scan-invoices default. Toggle asc/desc.

Pagination

• Default 25 per page
• Configurable per-page
• Offset-based pagination
• Import table supports up to 250 for "all selected" operations

Selection

• Individual row checkboxes
• "Select all" checkbox selects all visible
• "Select all filtered" selects all matching current filters (up to 250)
• Selection state maintained via Alpine.js
• Pay/Void/Edit/Bulk-Edit buttons use selection

Permissions

All invoice operations check permissions via can?:

Activity	Required Permission
Create invoice	{:subject :invoice :activity :create}
Edit invoice	{:subject :invoice :activity :edit}
Delete/Void invoice	{:subject :invoice :activity :delete}
Pay invoice	{:subject :invoice :activity :pay}
Bulk delete	{:subject :invoice :activity :bulk-delete}
Bulk edit	{:subject :invoice :activity :bulk-edit}
Import	{:subject :invoice :activity :import}

Additional checks:

• assert-can-see-client - user must have access to invoice's client
• assert-not-locked - invoice date must be >= client's locked-until date
• Admin-only for bulk delete confirmation

Edge Cases

Voiding Paid Invoices

• Single void: Blocked if invoice has linked non-voided payments. User must void payments first.
• Bulk void: Automatically voids linked cash payments before voiding invoices.

Unvoiding

• Restores invoice to original status, total, outstanding balance, and expense accounts
• Uses Datomic history to reconstruct previous state
• Requires edit permission and client access

Undo Autopay

• Only available for paid invoices with scheduled payment and no linked payments
• Resets status to unpaid, outstanding to total, clears scheduled payment
• Locked dates blocked

Paying with Credit

• Triggered when selected invoices for single vendor have net 0 balance (credit invoices + payment invoices)
• Credit invoices (negative balance) offset payment invoices
• Creates balance-credit payment

Location Spreading

• "Shared" location in expense accounts spreads across all client locations
• Base amount = total / location count (integer division in cents)
• Remainder distributed 1 cent at a time to first N locations
• Total delta applied to first account to handle rounding

Negative Amounts

• Supported throughout (credit memos, overpayments)
• Spread calculations handle negative totals
• Pay button validates all-credits-or-debits (can't mix positive and negative vendor totals)

Zero Balances

• Invoices with 0 outstanding balance show as paid
• Zero-balance selections excluded from payment

Duplicate Invoice Numbers

• assert-no-conflicting prevents same invoice number for same vendor/client
• Edit wizard preserves existing invoice number unless changed

Missing Vendor/Account

• New invoice wizard requires vendor with default expense account
• Import validation fails if vendor not found
• Unresolved filter finds invoices missing expense accounts

Locked Clients

• Client has locked-until date
• Invoices with date < locked-until cannot be: edited, paid, voided, imported, approved
• Bulk operations filter out locked invoices
• Pay wizard shows warning when some selections are locked

Large Invoice Counts

• scan-invoices Datomic query used for efficient date/client filtering
• Pagination limits to 25 per page by default
• "All selected" capped at 250 for bulk operations
• Outstanding/total sums calculated from all-ids, not just page

Test Data Requirements

Entities Needed

• Clients: Multiple clients with different locations, some with locked-until dates
• Vendors: With/without default accounts, terms, autopay settings, account overrides, terms overrides
• Accounts: Expense accounts with/without invoice allowance, different locations
• Bank Accounts: Check, cash, credit types, visible/hidden
• Invoices: Various statuses, dates, amounts, with/without payments, with/without scheduled payments

Specific Test Scenarios

• Client with multiple locations (for spreading)
• Client with single location (client column hidden)
• Vendor with terms (auto-due date) and autopay (auto-scheduled payment)
• Invoice with partial payment (outstanding < total)
• Invoice with linked payment (void blocked)
• Voided invoice with history (unvoid test)
• Paid invoice with scheduled payment, no linked payment (undo autopay)
• Negative balance invoice (credit)
• Imported pending invoice (approve/disapprove)
• Locked client with pre/post-lock invoices

File Upload Test Data

• Valid CSV with proper headers
• PDF with embedded text
• PDF requiring OCR
• File with multiple clients (admin-only source-url)
• File with missing required fields
• File with unmatchable vendor

Dependencies

• Datomic: Primary data store, history for unvoid
• AWS S3: File storage for imports and Glimpse PDFs
• AWS Textract: OCR for Glimpse PDF processing
• Solr: Search for vendor/client matching in Glimpse
• HTMX/Alpine.js: Frontend interactivity
• Bidi: Route generation
• Malli: Schema validation for forms and query params
• clj-time: Date parsing and manipulation

Existing Tests to Preserve

Unit Tests

• test/clj/auto_ap/ssr/invoice/new_invoice_wizard_test.clj
  • maybe-spread-locations-test - 6 test cases for location spreading logic

Integration Tests

• test/clj/auto_ap/integration/routes/invoice_test.clj
  • import-uploaded-invoices - import single, duplicate prevention, location override, coded invoice
• test/clj/auto_ap/integration/graphql/invoices.clj
  • test-add-invoice - add with valid/invalid accounts, vendor special accounts
  • edit-invoice - edit fields, vendor change blocked, conflicting invoice numbers
  • edit-expense-accounts - modify expense accounts
  • bulk-change-invoices - bulk coding with percentages
  • void-invoices - bulk void and unvoid
  • void-invoice - single void and unvoid