feat(statements): OCR intake for scanned utility bills

Staff key 300+ utility statements per company per month by hand. This adds
the ingest -> split -> OCR -> match -> review pipeline that proposes customer
and amount per page instead (RECEIPT_CAPTURE_SPEC §2), posting through the
existing BillingService.createBatch seam with source=OCR and a per-document
captureRef so machine and hand capture share one write path and audit trail.

Everything was designed against 10 real scanned statements (46 pages of CFE,
CESPT and Telnor bills) rather than from the sample-free spec. The scans have
no text layer at all — they are camera images — so OCR is mandatory, and they
arrive bundled one customer per page. Measured on those pages the parser
identifies the provider 46/46 and reads an account reference 43/46; against
the dev database that is 39/46 (85%) exact auto-match, 40/46 identified, with
the rest genuine review cases. That closes the OCR-provider question in favour
of self-hosted Tesseract: it clears the bar for a queue where a human confirms
every row, and OcrProvider keeps a managed API a one-line swap.

The samples corrected three things the spec had wrong or unknown:

- Clave catastral is NOT predial. DATMEX.clave (934 rows) is what CESPT and
  predial bills print; DATMEX.predial, which PROPERTY_TAX.accountNumber holds,
  has 663 distinct values across 1135 rows and appears on no statement. The
  clave now lives on Property.cadastralKey as the matcher's secondary key;
  predial is left untouched. This had been blocking predial matching.
- Gas was recoverable: 160 of 334 DATMEX.gas values are real account numbers
  (the rest are ESTACIONARIO/CILINDRO descriptors), now in GAS.meterNumber.
- Phone is one billed line per property (534/18/1 across phone1/2/3), so the
  new TELEPHONE ServiceKind backfills from phone1 only, not three rows.

Matching is scoped to one column per service kind and never reads the customer
name — a CESPT receipt prints ARNAIZ ROSAS ELSA AURORA for an account this
office holds under CATT, RANDY, because the printed name is the registrant,
not the current owner. Where a provider prints a payment barcode it beats the
printed label (one CFE label OCR'd a digit too many while its barcode was
correct) and the two cross-check, with disagreement forcing review.

Confirming a document whose service had no reference writes it back, so gas
and any other cold start is a one-time cost rather than a permanent queue.

Verified end to end against the live dev API and MinIO: real scans uploaded
over HTTP, matched, confirmed against a check, and the resulting rows checked
in MySQL (negative amounts, captureSource=OCR, concept derived from the batch
kind, captureRef linking back to each page). Re-confirming a posted batch is
refused. Test data was removed afterwards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/api/src/statements/ocr/ocr.provider.ts

@@ -0,0 +1,53 @@
+/**
+ * The OCR seam. Everything above this interface works in terms of page text and
+ * word boxes, so the concrete engine is swappable without touching the parsers,
+ * the matcher, or the schema.
+ *
+ * The shipped implementation is self-hosted Tesseract (see tesseract.provider).
+ * That choice is evidence-based rather than assumed: run against 46 pages of
+ * real scanned CFE, CESPT and Telnor statements, it identified the provider on
+ * 46/46 and extracted a usable account reference on 43/46, which is well past
+ * the bar for a queue whose whole point is that a human confirms every row. A
+ * managed document-extraction API (Textract, Document Intelligence, Document
+ * AI) fits behind this same interface if per-page accuracy ever proves
+ * insufficient, with no schema change — but at 300+ pages/month/company it
+ * would carry a real recurring cost for accuracy that is not currently the
+ * bottleneck.
+ */
+
+/** One OCR'd word, with where it sits on the page. */
+export interface OcrWord {
+  text: string;
+  /** Pixel box in the rendered page image. */
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  /** Engine confidence for this word, 0..1. */
+  confidence: number;
+}
+
+export interface OcrPage {
+  /** Full page text, reading order, newline-separated. */
+  text: string;
+  /**
+   * Word boxes. Needed because two of the three real layouts are *tables* —
+   * the CESPT "RECIBO" prints `No. DE CUENTA` as a column header with the
+   * value in the row beneath it, which line-oriented text cannot associate.
+   * Parsers fall back to geometry for exactly those fields.
+   */
+  words: OcrWord[];
+  /** Mean word confidence across the page, 0..1. */
+  confidence: number;
+}
+
+export interface OcrProvider {
+  /** True when the engine is actually usable in this deployment. */
+  available(): Promise<boolean>;
+  /** Split a PDF into one rendered page image per page. */
+  renderPages(pdf: Buffer): Promise<Buffer[]>;
+  /** OCR a single rendered page image. */
+  recognize(pageImage: Buffer): Promise<OcrPage>;
+}
+
+export const OCR_PROVIDER = Symbol("OCR_PROVIDER");