AP Processing Modes Design

Context

AP invoice behavior is currently controlled by organically grown checks around DATEV connectivity and tenant_ap_approval_config.is_enabled. That toggle now controls more than approvals: it also gates inline editing, approval snapshots, and automatic DATEV export after final approval. This makes the business policy implicit and spread across app handlers, ingestion workers, and export code.

We want an explicit tenant-level AP processing mode that describes how invoices move through Orcha:

• read-only invoices with no output
• human review with edits and approvals before output
• straight-through output without human review

This design also builds on the document output dispatcher design: app code creates generic output jobs, and workers execute external outputs. DATEV remains the first output implementation, but AP processing policy must not be DATEV specific.

Goals

• Replace the approval boolean as the source of AP processing policy with an append-only tenant AP processing config.
• Keep approvals and inline editing inseparable: tenants either have both human review capabilities or neither.
• Preserve approver rosters across mode changes.
• Request output from the generic document output dispatcher instead of direct DATEV calls.
• Allow straight-through tenants to export invoices with validation, matching, or reconciliation errors.
• Allow manual export of older terminal invoices after a tenant switches to straight-through mode, without auto-exporting the historical backlog.
• Enforce export authorization server-side; UI visibility is not an authorization boundary.

Non-Goals

• Add per-source AP modes. Processing mode is tenant-wide.
• Add additional per-document policy snapshot tables.
• Add per-target output policy or per-target audit tables.
• Auto-export invoices that reached terminal processing before the tenant was switched to straight-through mode.
• Export non-invoice AP documents.
• Export documents that failed before Orcha has a usable invoice payload.

Data Model

Add an append-only tenant AP processing configuration table.

CREATE TYPE ap_processing_mode AS ENUM (
  'read_only',
  'human_review_export',
  'straight_through_export'
);

CREATE TABLE tenant_ap_processing_config (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id  UUID NOT NULL REFERENCES tenant(id) ON DELETE CASCADE,
  mode       ap_processing_mode NOT NULL,
  created_by UUID REFERENCES "identity"(id) ON DELETE SET NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_tenant_ap_processing_config_latest
  ON tenant_ap_processing_config (tenant_id, created_at DESC, id DESC);

The current mode is the latest row for the tenant ordered by created_at DESC, id DESC. A tenant with no config row is treated as read_only.

The table is append-only. Saving a new mode inserts a row; old rows remain for auditability. This setting controls whether invoices can leave Orcha, so the history of who changed it and when should be durable.

Existing tables remain responsible for their current domains:

• tenant_ap_approver stores the reusable approver roster.
• ap_invoice_approval stores per-invoice approval snapshots.
• ap_invoice_approval_event stores approval-row audit events.
• document_output_job stores generic output attempts.
• ap_datev_export_audit stores DATEV-specific export task state.

tenant_ap_approval_config is legacy policy state. It should be used only to backfill the initial tenant_ap_processing_config rows and then removed from runtime decisions. The implementation should either drop the table after code no longer references it, or leave it unused only as temporary rollback scaffolding. It must not remain a second policy source.

Mode Semantics

read_only

• New invoices do not receive approval rows.
• Invoice detail is read-only.
• No automatic output is requested.
• Manual export and re-export are forbidden.

human_review_export

• New invoices snapshot the current tenant approver roster into ap_invoice_approval.
• Inline editing is enabled for invoices that have approval rows.
• Automatic output is requested after aggregate approval state becomes fully approved.
• Manual re-export is allowed only after aggregate approval state is fully approved.
• Validation, matching, and reconciliation errors do not block output. Human approval is the business gate.

Approvals and inline editing are one capability. There is no supported mode with approvals but no edits, or edits but no approvals.

straight_through_export

• New invoices do not receive approval rows.
• Invoice detail is read-only.
• Automatic output is requested when invoice processing reaches its terminal point.
• Manual export and re-export are allowed for terminal invoices.
• Validation, matching, and reconciliation warnings or errors do not block output. They are included in diagnostics and the DATEV cover page where applicable.

Processing Terminal Point

Straight-through automatic output must not run immediately after complete-ingestion!, because matching and reconciliation can add diagnostics that should be included in the export cover page.

The automatic output boundary is the matching worker's terminal handling for an invoice. Reconciliation runs synchronously inside the matching processor, so there is no separate reconciliation worker to wait for. At that point:

• the document is an invoice
• structured invoice data exists and can build an output payload
• ingestion completed
• matching reached a terminal state: completed, skipped, or failed
• reconciliation, when applicable, reached a terminal state: completed, skipped/not applicable, or failed

The matching worker should call the shared AP output request function from terminal paths only:

• after process-document! / engine/run-processors! returns successfully, before deleting the SQS message
• after handle-failure! has written a terminal failed matching run

The call should not live in process-document-with-notify!'s finally block, because that block also runs for transient attempts that should not request output yet. Non-matchable document types are marked with a skipped matching run; the shared output request function still checks that the document is an invoice before creating a job.

If the document is not an invoice, if there is no usable invoice payload, or if the tenant mode does not allow output, the function returns without creating a job.

If an invoice reached this terminal point before the tenant switched to straight_through_export, the mode-change action does not auto-enqueue it. Users may manually export that older terminal invoice after the switch.

Output Requests

Document output dispatch remains generic. AP processing policy decides when an invoice may request output; the document output worker decides which configured outputs to execute.

document_output_job.trigger should include:

• approval_completed
• processing_completed
• manual

The existing document output migration currently creates document_output_trigger with only approval_completed and manual. Adding processing_completed requires a new migration:

ALTER TYPE document_output_trigger ADD VALUE IF NOT EXISTS 'processing_completed';

This migration must land before any code attempts to insert processing_completed jobs. PostgreSQL enum values added by ALTER TYPE may not be usable until the transaction commits, so keep this as its own migration step rather than combining it with inserts that use the new value.

The job table must not include a target. A job means "dispatch this document's configured outputs." DATEV is the first output implementation, but the model must support later outputs without changing the AP policy table.

Keep the active-job uniqueness rule from the output dispatcher design:

CREATE UNIQUE INDEX idx_document_output_job_document_active
  ON document_output_job (document_id)
  WHERE status IN ('pending', 'running');

This prevents duplicate exports from double clicks, duplicate events, or automatic/manual races.

Authorization

Create one shared AP output authorization layer and use it from:

• final approval handling
• matching worker terminal handling
• manual export/re-export routes

Rules:

• read_only: never authorized.
• human_review_export: authorized only when the invoice has approval rows and aggregate approval state is fully approved.
• straight_through_export: authorized when the invoice is terminal for output.
• all modes: reject if an active output job already exists for the document.
• all modes: failed or dispatched output jobs do not block re-export; only pending and running jobs are active blockers.
• all modes: reject if the document is not an invoice or cannot build the output payload.

Manual endpoints must enforce these checks server-side. Hiding a button in the UI is only presentation.

DATEV Eligibility

DATEV eligibility should not check validation errors. Validation, matching, and reconciliation diagnostics are output content, not blockers.

DATEV-specific capability checks should only cover whether DATEV can physically receive the invoice:

• active usable DATEV integration exists
• credentials are usable
• invoice payload can be built
• source/display PDF is available

The existing maesn/export-eligible? should be narrowed accordingly or replaced with a better-named DATEV capability predicate. The implemented document output worker currently calls this predicate before maesn/create-booking-proposal!; that dispatch-time check must stop treating validation errors as blockers. The invoice UI does not currently call maesn/export-eligible? directly, but its export-button visibility must also be moved to the shared AP output authorization rules so UI behavior matches the server-side route.

Admin UI

Replace the tenant "AP Approvals" section with "AP Processing" on the tenant detail page.

The section shows:

• current AP processing mode
• who set it and when
• a selector for read_only, human_review_export, and straight_through_export
• recent mode history, such as the last five rows
• the approver roster

The approver roster is preserved across modes. It is active only when the mode is human_review_export, but admins may still view and maintain it while the tenant is in another mode.

Saving human_review_export requires at least one approver. Saving a mode inserts a new tenant_ap_processing_config row.

Saving straight_through_export does not enqueue historical terminal invoices. It only affects invoices that reach the terminal processing point after the mode change. Older terminal invoices become manually exportable.

Document UI

The invoice detail page derives behavior from the current tenant mode and the document's approval rows.

read_only:

• no inline editing assets
• no approvers section unless historical rows exist
• no export button
• no DATEV output section unless historical output/audit state exists and is useful for debugging

human_review_export:

• approvers section renders when rows exist
• inline editing is enabled for invoices with approval rows
• export/re-export button is hidden until fully approved
• pending/rejected approval state is shown as the reason output is unavailable

straight_through_export:

• no inline editing assets
• no approval controls
• output status is visible
• manual export/re-export button is visible for terminal invoices

Event Flow

New Invoice, read_only

1. Ingestion completes.
2. No approval rows are created.
3. Matching/reconciliation may run.
4. No output job is created.

New Invoice, human_review_export

1. Ingestion completes.
2. The current approver roster is snapshotted into ap_invoice_approval.
3. Matching/reconciliation runs.
4. Users can edit while the invoice has approval rows.
5. On final approval, the approval handler calls the shared AP output request function.
6. If authorized and no active output job exists, a document_output_job is created with trigger approval_completed and sent to SQS.

New Invoice, straight_through_export

1. Ingestion completes.
2. No approval rows are created.
3. Matching/reconciliation runs.
4. When matching terminal handling runs, it calls the shared AP output request function.
5. If authorized and no active output job exists, a document_output_job is created with trigger processing_completed and sent to SQS.

Manual Export/Re-Export

1. The route verifies document access.
2. The route calls the shared AP output authorization function with trigger manual.
3. If authorized and no active output job exists, a document_output_job is created and sent to SQS.
4. If not authorized, the route returns a forbidden or conflict response that the UI can render inline.

Rollout And Migration

Create an initial config row for each existing tenant. The migration must map the existing approval boolean into the new mode:

• tenant_ap_approval_config.is_enabled = true -> human_review_export
• missing config row or is_enabled = false -> read_only

Use created_by = NULL for migration-created rows unless a reliable actor is available. This preserves current approval-enabled tenants and prevents them from silently falling back to read_only.

After backfill, tenant_ap_approval_config.is_enabled should stop being the source of policy. Existing approval rows remain valid as historical per-invoice review snapshots.

The migration should avoid deleting approver rosters. Approvers remain reusable tenant setup.

Testing

Add tests for:

• current mode selection: latest config row wins
• no config row defaults to read_only
• saving a mode appends a row
• saving human_review_export without approvers is rejected
• approver roster persists across mode changes
• inline edits are allowed only for invoices with approval rows
• new human_review_export invoices snapshot approval rows
• new read_only and straight_through_export invoices do not snapshot approval rows
• final approval creates an output job only when the current mode authorizes it
• matching terminal handling creates an output job only in straight_through_export
• matching/reconciliation/validation errors do not block output authorization
• manual export endpoint forbids read_only
• manual export endpoint forbids pending or rejected human-review invoices
• manual export endpoint allows fully approved human-review invoices
• manual export endpoint allows terminal straight-through invoices, including older terminal invoices after a mode switch
• switching to straight_through_export does not auto-enqueue historical terminal invoices
• active output job uniqueness prevents duplicate output requests

Open Risks

• The exact SQL/helper for determining matching and reconciliation terminal state must match the existing document_processor_run conventions. Failed matching/reconciliation is terminal for output, not a blocker.
• Existing UI status labels currently mix validation and export state. They may need copy updates so "errors" do not imply output is blocked.
• DATEV payload construction may still fail for some invoices with malformed structured data. Those failures should be represented as output job or DATEV audit failures, not pre-authorization validation blocks.