Invoice automation: vendor invoice audit

vendor invoices ──▶ Invoice Audit (reconcile table) ──▶ review ──▶ approved / disputed
                            │
                            ├── queries ──▶ PO Master (storage)
                            ├── queries ──▶ Goods Receipts (storage)
                            └── queries ──▶ Credit Notes (storage)

# SOP — Vendor invoice audit

Version 1.0 · Owner: Accounts Payable · Last approved by: <name>, <date>

## Purpose
Verify each vendor invoice against its purchase order and goods receipt
before it is approved for payment. Report discrepancies with evidence.
Do not correct the invoice. Do not approve payment.

## Step 1 — Match the invoice to a PO
Match in this order, stop at the first hit:
1. PO number quoted on the invoice → exact match in `po_master`.
2. Vendor + invoice line articles + date window (invoice date minus 90
   days) → single open PO with matching articles.
3. No match → `po_match_status: unmatched`, list up to five candidate PO
   numbers with vendor, date, and open amount. Stop here.

Confirm the vendor on the matched PO equals the invoicing vendor in
`vendor_master`. If not, flag — never override the vendor.

## Step 2 — Duplicate detection
Before checking anything else, look for a duplicate:
- **Exact duplicate**: same vendor + same invoice number → `duplicate: true`,
  verdict `fail`, name the earlier case. Stop.
- **Near duplicate**: same vendor + same total amount + invoice dates within
  10 days, different invoice number → `duplicate: suspected`, verdict
  `needs_confirmation`. List the other invoice. Do not decide.
- Same vendor and amount more than 10 days apart with different articles is
  not a duplicate — recurring charges look like this.

## Step 3 — Quantity check against receipt
For each invoiced line, compare the billed quantity to the received
quantity in `goods_receipts` for that PO line.
- Billed ≤ received → pass.
- Billed > received → `quantity_variance` with the difference. Partial
  deliveries are normal; billing ahead of receipt is not.
- No receipt at all for the PO line → flag as `not_received`. Service
  lines without a receipt are expected — say so rather than failing them.

## Step 4 — Price check against the PO
Compare each invoiced unit price to the agreed price on the PO line.
Tolerance: the smaller of **2%** or **10.00** per unit.
- Within tolerance → pass.
- Above tolerance → `price_variance` with agreed price, billed price, the
  per-line difference, and the total exposure across the invoice.
- Below the agreed price → report it too. An unexplained discount is a
  data problem worth knowing about.

Currency must match the PO. A different currency is always a flag, never
a conversion.

## Step 5 — Credit note check
Search `credit_notes` for open credits from this vendor that reference
this PO, this invoice, or any of its articles. Any open credit not applied
on the invoice → `unapplied_credit` with the credit number and amount.

## Step 6 — Verdict
Set exactly one:
- `pass` — matched to a PO, no duplicate, quantities and prices within
  tolerance, no unapplied credits.
- `needs_confirmation` — resolved, but a human should confirm before
  payment: suspected near-duplicate, a variance inside tolerance but on a
  high-value line, a service line with no receipt, or a price variance the
  vendor has a documented reason for.
- `fail` — a definite problem: exact duplicate, unmatched PO, vendor
  mismatch, quantity billed over received, price variance above tolerance,
  or an unapplied credit.

The middle bucket matters. Most invoices are not clean-or-broken — they
are fine but worth a glance. Do not push those into `pass` to look tidy,
and do not push them into `fail` and bury the real problems.

## Escalation thresholds
- Total exposure above **5,000.00** → always a human, whatever the verdict.
- Any new vendor with no prior invoices → always a human.
- More than three flagged lines on one invoice → escalate the whole
  invoice rather than reporting line by line.

## Outputs
Fill every output field. In the comment, state: which PO it matched and
how, what you checked, every discrepancy with its amount, and the total
exposure. A reviewer should be able to decide without opening the PDF.