jorgecuadros-platform/docs/RECEIPT_CAPTURE_SPEC.md

Receipt Capture ("Editor") & Related Net-New Features — Implementation Spec

Source: Jorge Cuadros meeting notes, 2026-07-25/26 (Utility Management section) plus a business-logic read-through of UTILITIES.accdb's legacy "Editor" workflow (docs/LEGACY_DATABASES_OBJECTS.md, docs/LEGACY_DATABASES.md). This is a forward spec for work not yet built, not a record of what exists — contrast with RENEWAL_NOTICES.md, which documents a legacy workflow already migrated.

Why these four features are one spec

The meeting covered one legacy workflow (receipt capture, the "Editor") plus three requests that have no legacy precedent at all. They're specified together because they compose:

1. Receipt capture module — the direct replacement for the legacy "Editor" screens, extending what's already built in billing/.
2. PDF/OCR auto-capture — a new intake path that feeds into module 1 (an OCR-confirmed statement becomes a captured receipt, not a separate ledger).
3. Multi-bank chequera — changes what a captured receipt's check number reconciles against (module 1's check-reconciliation view needs to know which bank account a check was drawn on).
4. Customer-number recycling — changes how a customer is created, which is the first step of capturing a receipt for them (module 1's customer picker needs to respect whatever number a recycled customer was assigned).

Each section below is independently buildable and independently useful, but 1 should land before 2 (2 posts through 1's API), and 4 is fully independent of the other three.

---

1. Receipt capture module (the "Editor" replacement)

What's already built (do not re-build)

apps/api/src/billing/ + apps/web MovementForm.tsx already provide single-movement manual capture: POST /billing (ledger:create) creates one signed Transaction row with customer, domain, amount, currency, date, concept (typeId), period, reference, check number, and message; POST /billing/:id/void (ledger:void) reverses one. This is the direct equivalent of the legacy DATOS AGUA/DATOS LUZ/DATOS TEL/DATOS CLAVE per-service capture screens, already generalized into one form — the per-service screens do not need to be rebuilt separately; domain + typeId (from TypeTransaction) already carry that distinction, and the capture form can pre-select a concept when opened from a property's service tab.

What's missing is everything the legacy system did around that single capture: batching many receipts against one check, separating out unpaid items, and reconciling a check's total against what was captured against it.

1.1 Outstanding ("NOPAGO") workflow

Transaction.outstanding already exists in the Prisma schema but nothing reads or writes it yet.

• CreateMovementDto (billing/movement.dto.ts): add outstanding?: boolean, default false. When true, the movement posts normally but is excluded from "settled" balance views — mirrors the legacy SALDOS ULTIMO 0 query, which already HAVING NOPAGO = 0s outstanding rows out of the balance.
• MovementForm.tsx: add an "Outstanding (sin fondos)" checkbox, shown only for domain = UTILITY charge-direction rows (this is a per-service charge concept, not a credit/payment concept).
• New endpoint POST /billing/:id/resolve-outstanding (ledger:create — same tier as capture, since resolving is completing a capture, not reversing one). Body: { checkNumber: string, resolvedDate: string }. Sets outstanding = false, checkNumber, and updates transactionDate to resolvedDate — this is the literal legacy behavior ("se actualiza registro con fecha del día y el cheque a pagar y quitas outstanding"). Reject (400) if the row is already resolved or voided.
• New list filter: GET /billing?outstanding=true (extend MovementParams) — replaces the legacy EDITA NO PAGO AGUA/LUZ/PHONE per-service outstanding screens with one filterable view (service already filterable via typeId).
• Web: an "Outstanding" tab or filter chip on /estado-cuenta (Movimientos tab), each row showing a "Resolver" action that opens a small form for check number + date.

1.2 Batch capture by check

Legacy staff key many customers' receipts against one check before cutting it, then verify the captured total matches the check amount (CAPTURA AGUA/CAPTURA LUZ/etc. feeding into EDITA CHEQUE COUNT/ REPORTE POR CHEQUE). Model this as a bulk-create, not a new persisted entity — a check number is already a plain field on Transaction; there's no need for a ReceiptBatch table when grouping by checkNumber already answers every legacy query.

• New endpoint POST /billing/batch (ledger:create). Body: { domain, typeId, transactionDate, currency, checkNumber, lines: [{ customerId, amount, reference, period, outstanding? }] } — the check-level fields are shared, only the per-customer fields repeat. Runs as one Prisma $transaction, returns the created rows plus { total, count } so the UI can show the running total against the physical check amount as staff add lines, exactly matching the legacy reconciliation practice.
• Web: a /estado-cuenta/captura (or /estado-cuenta/lote) page — a service-type + check-number header, then a repeating row (customer picker
  • reference + amount + outstanding toggle), a running total, and a single submit. This is the actual "Editor" screen the meeting notes are asking for; it should be reachable from a new nav entry under "Estado de cuenta" or "Servicios."

1.3 Check reconciliation view

Direct replacement for EDITA CHEQUE ALF/COUNT/NUM, REPORTE POR CHEQUE, REPORTE POR CHEQUE PARA ALFA, and the REPORTE CHEQUE COUNT report named explicitly in the meeting notes.

• New endpoint GET /billing/by-check?checkNumber=... — all non-voided Transaction rows with that checkNumber, plus { total, count }. Trivial query, no new indexes needed beyond the existing checkNumber column (add a plain index — it's currently unindexed).
• New report entry in reports.registry.ts: slug: "cheque-count", legacyName: "REPORTE CHEQUE COUNT", params { checkNumber: text }, columns customer/reference/period/concept/amount, reusing the by-check query above. This gives it a printable form for free via the existing /reportes/:slug machinery — no new page needed.

Abilities

No new abilities required — everything above reuses ledger:create / ledger:void (already STAFF / MANAGER). Batch capture and outstanding resolution are both "capturing a receipt," same trust tier as the existing single-movement form.

---

2. PDF / OCR auto-capture

Motivation (from the meeting)

Each utility company (CFE, water, phone, gas...) sends 300+ individual statements a month, one per customer, currently keyed in by hand through the per-service capture screens — a high-volume, error-prone manual step. The ask: scan/receive the statements as PDF(s), have the system determine customer + amount automatically, and only require staff review rather than full manual entry.

Pipeline

Upload (1+ PDFs, one service kind per batch)
  -> StorageService stores raw file(s)
  -> Split into one document per statement (if a batch PDF bundles multiple)
  -> OCR extraction (account/meter number, amount, period, due date)
  -> Auto-match against PropertyService (accountNumber / meterNumber / route)
  -> Review queue: high-confidence matches pre-filled, no-match/low-confidence flagged
  -> Staff confirms (bulk-confirm high-confidence rows, hand-correct the rest)
  -> Confirmed rows post through the SAME batch-capture path as §1.2
  -> Source PDF page attached as a ServiceDocument on the matched property

The last two steps deliberately reuse §1.2's batch-capture endpoint rather than writing Transaction rows directly — OCR-sourced and hand-keyed receipts should go through one write path, one validation path, one audit trail.

Data model (new)

enum StatementBatchStatus {
  UPLOADED
  PROCESSING
  READY_FOR_REVIEW
  COMPLETED
  FAILED
}

enum StatementDocumentStatus {
  PENDING_OCR
  OCR_FAILED
  NEEDS_REVIEW      // no confident match, or low OCR confidence
  MATCHED           // confident auto-match, awaiting staff confirmation
  CONFIRMED         // staff confirmed, not yet posted
  POSTED            // posted as a Transaction
  REJECTED          // staff rejected (duplicate, unreadable, wrong batch)
}

// `ServiceKind` needs one addition for this feature: `TELEPHONE`. It
// doesn't exist today — phone numbers live on `Property.phone1/2/3`, not as
// `PropertyService` rows. See "Matching logic" below for why OCR matching
// needs it as a real service kind, and the backfill this implies.

/// One upload session — e.g. "October CFE statements."
model StatementBatch {
  id           String                @id @default(uuid())
  serviceKind  ServiceKind
  status       StatementBatchStatus  @default(UPLOADED)
  uploadedById String
  fileCount    Int
  createdAt    DateTime              @default(now())
  documents    StatementDocument[]

  @@map("statement_batches")
}

/// One statement (one customer, one period) after splitting the batch.
model StatementDocument {
  id                  String                    @id @default(uuid())
  batchId             String
  batch               StatementBatch            @relation(fields: [batchId], references: [id])
  storageKey          String
  status              StatementDocumentStatus   @default(PENDING_OCR)

  // Raw OCR output, kept even after a manual correction so mismatches are
  // auditable.
  ocrRawText          String?                   @db.Text
  ocrConfidence        Decimal?                 @db.Decimal(4, 3)

  // Extracted (and, after review, staff-corrected) fields.
  extractedAccountRef String?                   // RPU / phone / water account / zona fed / clave catastral / gas meter — see "Matching logic" for which PropertyService field this maps to per serviceKind
  extractedAmount     Decimal?                  @db.Decimal(12, 2)
  extractedPeriod     String?
  extractedDueDate    DateTime?

  // Match result.
  matchedPropertyServiceId String?
  matchedPropertyService   PropertyService?      @relation(fields: [matchedPropertyServiceId], references: [id])
  matchedCustomerId        String?
  matchedCustomer          Customer?             @relation(fields: [matchedCustomerId], references: [id])

  reviewedById        String?
  reviewedAt          DateTime?
  postedTransactionId String?                   @unique
  postedTransaction   Transaction?              @relation(fields: [postedTransactionId], references: [id])

  createdAt           DateTime                  @default(now())

  @@map("statement_documents")
}

(PropertyService/Customer/Transaction gain the inverse relations. ServiceDocument is reused as-is for the confirmed receipt's permanent attachment — StatementDocument.storageKey and the eventual ServiceDocument.storageKey may point at the same object, or the confirm step copies it; either is fine, pick whichever is simpler at build time.)

Matching logic

Match extractedAccountRef against one specific PropertyService field, chosen by serviceKind — never a fuzzy match across all of accountNumber/meterNumber/route at once, since that's how a water account number could accidentally collide with an unrelated phone number. Per the meeting notes' own field list:

Service (meeting note)	ServiceKind	Match against	Legacy source (DATMEX)	Status
CFE — RPU	ELECTRIC	accountNumber	RPU / RPU2 / RPU3	✅ populated today (transform_properties.py)
Agua — Número de cuenta	WATER	accountNumber	AGUA	✅ populated today
Zona Fed — Número de Zona Federal	FEDERAL_ZONE	accountNumber	ZFED	✅ populated today
Tel — Número de teléfono	TELEPHONE (new)	accountNumber	Property.phone1/2/3 (currently on Property, not PropertyService)	⚠️ schema gap — see below
Impuesto — Clave Catastral	PROPERTY_TAX	accountNumber	migrated from PREDIAL, not CLAVE	⚠️ needs verification — see below
Gas — Número de medidor	GAS	meterNumber	not populated — folded into free-text notes today	⚠️ data gap — see below

Confidence rule of thumb once a field is confirmed populated, tune after seeing real statements:

• Exact match on the scoped field → MATCHED, high confidence, pre-checked for bulk-confirm.
• No match, or the OCR confidence itself is low → NEEDS_REVIEW.
• Multiple candidate matches (shouldn't happen if account numbers are unique, but the legacy data has had duplication issues before — see docs/LEGACY_DATABASES_OBJECTS.md's DUPLICADOS report) → NEEDS_REVIEW with all candidates surfaced, not an arbitrary pick.

Three gaps this depends on — resolve before building the matcher

Cross-checking the requested field list against transform_properties.py (the script that actually populated today's property_services table) surfaced three mismatches. OCR matching is only as good as the field it matches against, so these need to be closed first, not discovered mid-build:

1. No TELEPHONE service kind exists. ServiceKind today is WATER | ELECTRIC | GAS | CABLE | PROPERTY_TAX | FEDERAL_ZONE | ALARM | OTHER — telephone was never unpivoted into PropertyService at all; the three phone numbers live directly on Property.phone1/phone2/phone3 (raw contact fields, not billable-service rows), even though the legacy ledger clearly bills phone as its own TYPE OF TRX = "TELEPHONE" (see EDITA NO PAGO PHONE, DATOS TEL/CAPTURA TEL in the prior analysis). Fix: add TELEPHONE to the ServiceKind enum, and backfill one PropertyService row per non-null Property.phone1/2/3 (kind: TELEPHONE, accountNumber: <the phone number>) as a one-time migration script companion to this feature — mirrors how transform_properties.py already emits multiple WATER rows per property for secondary meters.

2. PROPERTY_TAX.accountNumber holds PREDIAL, not CLAVE. The meeting notes name "Clave Catastral" specifically, and the legacy query/report names agree (CAPTURA CLAVE, DATOS CLAVE, CLAVES CATASTRALES, CATASTRO — all filter on DATMEX.CLAVE). But transform_properties.py line ~191 sets PROPERTY_TAX.accountNumber = DATMEX.PREDIAL, a different column (DATMEX has both CLAVE VARCHAR and PREDIAL DOUBLE). Two live possibilities: either PREDIAL is the wrong field and the migration should have used CLAVE, or they're two genuinely different numbers (e.g. clave catastral = the cadastral lookup key stamped on the printed bill vs. predial = an internal receipt/folio number) and PropertyService needs both — only one of which (the clave catastral) is what OCR will actually read off a real predial statement. Needs a real predial receipt in hand (or Jorge's confirmation) before deciding; don't wire the matcher to PREDIAL on the untested assumption it's the same thing.

3. GAS.meterNumber is never populated. transform_properties.py only ever sets notes = DATMEX.GAS for gas service rows — there's no distinct meter-number column in the legacy DATMEX table for gas at all (unlike electric/water, which have RPU/MEDIDOR). This matches the earlier finding that "Gas – Número de medidor" has no legacy source field. This can't be backfilled from existing data — the practical fix is that gas OCR matching starts cold (every gas statement lands in NEEDS_REVIEW until a human confirms it once), and that first confirmation is what populates PropertyService.meterNumber for that property going forward, so subsequent statements for the same meter auto-match. Worth calling out in the review-queue UI ("first time seeing this meter — confirm to enable auto-match next time").

OCR provider — open decision, don't build against one prematurely

CFE (and most MX utility) bills are fixed-layout, single-language, high-volume forms, not arbitrary documents — this is closer to "template/anchor text extraction" (regex against OCR'd text for known labels like RPU, No. de Cuenta, Total a pagar) than to a full ML document-understanding problem. Recommend:

• Define an OcrProvider interface (extract(buffer, hints): Promise<{ text: string, fields: ExtractedFields, confidence: number }>) so the concrete engine is swappable.
• Start with a self-hosted OCR (e.g. Tesseract) + hand-written per-company extraction rules (one rule set per ServiceKind/provider, since CFE's layout differs from the water company's). Cheap, no per-page cost, and the layouts are stable enough that this is realistic.
• Escalate to a managed document-extraction API (AWS Textract, Azure Document Intelligence, Google Document AI) only if the self-hosted accuracy proves too low in practice — all three fit behind the same interface with no schema changes.
• This choice needs Jorge's input on budget/volume before committing — 300+ pages/month/company is enough volume that a per-page-priced API has a real recurring cost.

API surface

• POST /statements/batches (statement:ingest) — multipart upload, one or more PDFs + serviceKind. Creates the batch, kicks off async split+OCR+match (background job, not inline in the request).
• GET /statements/batches / GET /statements/batches/:id — status + document list.
• GET /statements/batches/:id/documents?status=NEEDS_REVIEW — the review queue.
• PATCH /statements/documents/:id (statement:review) — staff correction of extracted fields or match.
• POST /statements/documents/:id/confirm (statement:review) — single confirm.
• POST /statements/batches/:id/confirm-matched (statement:review) — bulk-confirm every MATCHED document in one call.
• POST /statements/documents/:id/reject (statement:review).
• Confirming posts through §1.2's batch-capture internals (same service method, not the HTTP endpoint) so it's one transaction per batch of confirms, not N.
• Confirm also backfills the matched field when it was empty — if matchedPropertyServiceId was set by staff (not by an exact auto-match) because the scoped field was blank on that PropertyService (the GAS case above, and any one-off historical gap in the other kinds), write extractedAccountRef into that service's accountNumber/meterNumber as part of the confirm transaction. This is what makes the "first confirmation teaches the matcher" behavior in gap 3 above actually work, rather than requiring a separate manual data-entry pass.

Abilities (new)

Ability	Min role	Notes
statement:ingest	STAFF	upload a batch
statement:review	STAFF	correct/confirm/reject; same tier as ledger:create since confirming is capturing

Open questions

• Clave catastral vs. predial (gap 2 above) — get a real predial statement or Jorge's confirmation of whether CLAVE and PREDIAL are the same number before wiring the PROPERTY_TAX matcher. Blocks that one service kind, not the whole feature.
• Telephone as a service kind (gap 1 above) — confirm the backfill approach (one PropertyService row per populated Property.phone1/2/3) is correct, and whether a property with all three phones populated should really produce three separate billable "services," or whether phone billing is actually 1-per-property regardless of how many numbers are on file (would change the backfill to pick a primary number instead of fanning out to three rows).
• Multi-statement PDF splitting: does the source ever arrive as one PDF per customer already (simplifies to "batch = folder of PDFs"), or as one giant PDF per company per month that needs page-range splitting? Changes whether a page-boundary detector is needed at all.
• Retention: keep StatementDocument.storageKey (and the raw OCR text) indefinitely for audit, or purge after posting since ServiceDocument already holds the permanent copy? Recommend keep — cheap, and it's the audit trail for "why did the system think this was customer X."

---

3. Multi-bank chequera

Motivation

Seguros uses a US bank account; Utilities uses a Mexican bank account. The current BankTransaction model (migrated from SCOTHIA.mdb) has no bank or currency dimension at all — it's a single implicit account, MXN-only, by design (see PLAN.md migration step 7 finding (c)). Need to support more than one register, each with its own bank and currency.

Confirmed against the actual code, not just the schema comment: this is a real, deliberate, load-bearing assumption, not an oversight to patch around. migration/transform_bank.py has no bank/currency column to read in the first place — DATOS I/DATOS E are fecha, tipo, num, concepto, ingreso/egreso, operado, notas, cantidad_en_letra, nothing else. And bank.service.ts's module doc-comment states outright: "SINGLE CURRENCY... bank_transactions has none, and every amountInWords on the egreso side is spelled out in PESOS. All figures in this module are MXN." Every method in that file — where(), totalsFor(), facets(), summary(), stats(), createMovement() — currently has zero notion of "which account." That's the actual surface area this feature touches, itemized below.

Data model changes

model Bank {
  id       String        @id @default(uuid())
  name     String        @unique   // e.g. "Scotiabank", "Bank of America"
  country  String?                 // "MX" | "US" — informational
  accounts BankAccount[]

  @@map("banks")
}

/// One physical chequera. Currency is fixed per account (real bank
/// accounts don't mix currencies) — do NOT add a currency filter to
/// BankTransaction itself; it inherits the account's currency.
model BankAccount {
  id           String            @id @default(uuid())
  bankId       String
  bank         Bank              @relation(fields: [bankId], references: [id])
  label        String            // "Utilities operating (MXN)", "Seguros operating (USD)"
  currency     Currency
  businessLine TransactionDomain? // hint only, not enforced — a chequera can pay for more than one line
  active       Boolean           @default(true)
  movements    BankTransaction[]

  @@map("bank_accounts")
}

BankTransaction gains:

model BankTransaction {
  // ...existing fields...
  bankAccountId String
  bankAccount   BankAccount @relation(fields: [bankAccountId], references: [id])
}

bankAccountId should be required, not optional — a bank movement without a known account isn't meaningfully reconcilable. This means the migration step below has to run before the column goes non-null.

Migration of existing data

All 22,354 existing BankTransaction rows are SCOTHIA data — MXN, single bank. Before making bankAccountId required:

1. Insert one Bank row for Scotiabank, one BankAccount row under it (label: "Utilities — Scotiabank (MXN)", currency: MXN, businessLine: UTILITY).
2. Backfill every existing BankTransaction.bankAccountId to that account's id.
3. Add the second account ("Seguros — <bank TBD> (USD)") — needs the actual US bank name from Jorge, plus whether historical Seguros bank data exists anywhere to migrate (the current inventory has no Seguros bank register file — only SCOTHIA.mdb, which is Utilities' own book, per PLAN.md's source inventory). If no historical USD register exists, this account starts empty and only carries movements captured going forward.

The existing @@unique([legacySourceTable, legacyId]) on BankTransaction needs no change — every legacy row only ever belongs to the one Scotiabank account being backfilled in step 2, so provenance uniqueness still holds per-row regardless of how many accounts exist afterward.

Code touch points (bank.service.ts, bank.controller.ts)

This module currently has no filterable dimension at all beyond direction/cleared/date — every account-scoping change is additive, not a rewrite, but it touches every read method because two of them (facets(), summary()) bypass the Prisma query builder entirely and use hand-written $queryRaw template SQL:

• where() — trivial, add bankAccountId to the AND array like any other filter (Prisma builder, same pattern as direction/cleared).
• totalsFor() — takes the already-built where, so it inherits the scoping for free once list()/stats() pass a scoped where in.
• facets() — currently SELECT YEAR(transactionDate)... FROM bank_transactions WHERE voidedAt IS NULL with no account clause at all; needs AND bankAccountId = ${accountId} interpolated into the raw SQL (parameterized, not string-concatenated — this file already uses Prisma's tagged-template $queryRaw, which parameterizes automatically as long as the account id is passed as a template value, not spliced into the string by hand).
• summary() — same issue, in two raw queries (the yearly rollup and the monthly rollup when a year is selected) — both need the same AND bankAccountId = ${accountId} clause. Miss one and the "Resumen" tab's year list and its drill-down would scope to different accounts, which is a worse bug than not scoping at all (looks correct, silently wrong).
• stats() — currently calls totalsFor({}) (empty filter = every row). Needs totalsFor({ bankAccountId }); same for the count/bounds/ pending/transferred aggregates alongside it.
• createMovement() / voidMovement() — createMovement needs bankAccountId added to the data object (from the new required DTO field below); voidMovement needs no change — it already operates by row id, and a voided row's account never changes.

API surface changes

• bank.controller.ts: every route (list, summary, stats, facets) gains a required ?bankAccountId= query param, threaded through to the service methods above. Required, not optional with an "all accounts" default — summing MXN and USD registers together would repeat the exact currency-collapsing mistake the billing module's header comment explicitly warns against (912 customers with both-currency ledgers). There is no meaningful "no account selected" state once accounts exist, only "no account selected yet" while the UI loads its default.
• New bank/accounts sub-resource: GET /bank/accounts (list, any authenticated user — the account picker needs this before anything else can render), POST /bank/accounts / PATCH /bank/accounts/:id (bank:manage-accounts, MANAGER — creating/editing accounts is rarer and higher-stakes than posting movements).
• CreateBankMovementDto gains a required bankAccountId: string.

Web

• bank/page.tsx's own doc-comment currently states "Single currency (MXN) — the source has no currency column" as a design fact; that comment (and the assumption behind it) needs to be removed/rewritten as part of this change, not just the UI.
• /banco gains an account selector (tabs or a dropdown) at the top, scoping both the "Movimientos" and "Resumen por periodo" tabs — mirrors how /estado-cuenta already scopes by currency without ever summing across it. Every existing call site in lib/api.ts (listBankMovements, getBankStats, getBankSummary, getBankFacets, createBankMovement) needs the new bankAccountId parameter threaded through, and lib/types.ts's CreateBankMovementInput gains the field.
• New /banco/cuentas (or a section under /catalogos) for managing banks and accounts, gated the same way /catalogos already gates lookup management.

Abilities (new)

Ability	Min role	Notes
bank:manage-accounts	MANAGER	create/edit Bank/BankAccount rows

Open questions

• Confirm the actual US bank name/details for the Seguros account.
• Does Seguros have any historical bank register data to migrate, or does this start from zero on cutover?
• Should businessLine on BankAccount be enforced (a UTILITY account can't post an INSURANCE movement) or left as a soft hint? Recommend soft — the legacy single account already mixed concerns per PLAN.md's finding that TABLA RAMODOS wasn't a clean business-line split.

---

4. Customer-number recycling

Motivation

The physical folder system is organized by Customer number (DATGRAL.[NUM id] in the legacy data, currently only preserved as a CustomerLegacyRef string, not a first-class field). When a customer cancels, doesn't renew, or goes a year with no activity, staff currently manually hunt for such customers, purge their folder, and reuse the number for a new customer. The ask: keep the physical-folder-compatible sequential numbering, but automate the search for reusable numbers and auto-assign the lowest free one at creation — a Claude Code equivalent of "find the first empty spot."

Data model changes

model Customer {
  // ...existing fields...
  customerNumber   Int?      @unique   // the physical-folder number; null = not yet assigned (shouldn't happen post-migration) or released
  numberReleasedAt DateTime?           // non-null once the number has been freed for reuse; customerNumber is cleared at the same time (see below)
}

enum NumberReleaseReason {
  CANCELLED       // explicit non-renewal / service cancellation
  INACTIVITY      // >= 1 year with no ledger activity
  MANUAL
}

/// Audit trail for a recycled number, surviving the Customer row it came
/// from being archived/purged. customerId is nullable so history remains
/// readable even if the originating customer is later hard-deleted.
model CustomerNumberHistory {
  id             String               @id @default(uuid())
  customerNumber Int
  customerId     String?
  customer       Customer?            @relation(fields: [customerId], references: [id])
  assignedAt     DateTime
  releasedAt     DateTime?
  releaseReason  NumberReleaseReason?
  releasedById   String?

  @@index([customerNumber])
  @@map("customer_number_history")
}

Backfill

At implementation time, backfill customerNumber from the existing CustomerLegacyRef rows where sourceSystem = "utilities" AND sourceTable = "DATGRAL" (the legacy NUM id — already migrated, just not promoted to a first-class column). Insurance-only customers (no utilities DATGRAL row) won't have a legacy number; decide at build time whether they get one retroactively assigned or stay null until they need one (recommend: assign one on demand, the first time anyone needs to give them a physical folder — not retroactively for all 510 insurance-only customers at once).

This backfill isn't a straight cast of every legacyId to Int. Checked against migration/transform_customers.py: for a utilities DATGRAL row, legacyId is set to nid or f"rownum_{len(customers)}" — nid is the real NUM id only when the source row actually had one; ~140 utilities rows had a blank NUM id (the same "blank name" data quality issue the same script recovers names for) and got a synthetic rownum_N placeholder instead, which is not a physical-folder number and must not be cast into customerNumber. Insurance-side refs have the same pattern (insrow_N placeholders). The backfill query needs an explicit numeric filter (legacyId REGEXP '^[0-9]+$', or equivalent), and every row that fails it is exactly the "insurance-only or blank-NUM id" case that falls through to on-demand assignment above, not an error to chase down.

customers.service.ts's list()/detail() select blocks don't include customerNumber today (only name, nameSource, contact fields, counts) — it needs adding to both, plus to the /clientes list-page columns and the customer detail header, since staff read this number constantly for the physical folder. list()'s search (where.OR) already matches legacyRefs.some.legacyId.contains as a fallback for finding someone by their old number; once customerNumber is first-class, add a direct { customerNumber: Number(query) } branch when the query parses as an integer, so a numeric search hits the fast indexed column instead of the join.

Eligibility detection (the automation)

This is explicitly framed as surfacing candidates for staff review, not auto-purging — the actual release/reuse decision stays a human action, matching how the office works today; only the search is automated.

• New endpoint GET /customers/recycling-candidates — customers where either:

  • CANCELLED: no active Policy (not archived, policyTo in the past with no renewal) and no active PropertyService, or
  • INACTIVITY: MAX(Transaction.transactionDate) across all their transactions is more than 1 year ago (or no transactions at all and customerSince is more than 1 year ago).

  This can be a plain query (no new job/queue needed — it's a read, not a mutation) run on-demand when staff open a "Clientes para reciclar" screen, the same way /billing/balances is computed live rather than materialized.

• New endpoint POST /customers/:id/release-number (customer:recycle, MANAGER). Body: { reason: NumberReleaseReason }.

  • Closes the open CustomerNumberHistory row (releasedAt = now, releaseReason, releasedById).
  • Sets Customer.customerNumber = null, numberReleasedAt = now.
  • Archives the customer (archivedAt = now) — does not hard-delete or scrub PII by default. See the purge question below.

Auto-assignment at creation

• customers.service.ts create path: before insert, compute SELECT MIN(n) candidate FROM (SELECT customerNumber+1 AS n FROM customers) WHERE n NOT IN (SELECT customerNumber FROM customers WHERE customerNumber IS NOT NULL) — i.e., the lowest positive integer not currently held by any customer (released numbers, being NULL again, automatically qualify; no separate "available pool" table needed, which keeps this consistent with "vacancy = not currently claimed" rather than a second source of truth that can drift). Simplify at build time with whatever the DB makes cheapest (a gaps-and-islands query, or maintaining a running MAX + a small released-numbers cache — pick based on real customer-count scale, which is ~1,700, trivially small for a live scan). Open a new CustomerNumberHistory row (assignedAt = now) for the new assignment.
• Concurrency: customers.service.ts's create() today is a single unguarded prisma.customer.create() — no transaction, no locking, which is fine for arbitrary fields but not for a "pick the lowest unclaimed integer" computation, where two staff creating a customer at the same moment can both compute the same candidate number before either insert lands. The customerNumber unique constraint turns that race into a Prisma unique-violation error rather than silent data corruption, but the create path needs to actually handle it — wrap the compute-and-insert in a prisma.$transaction and retry once on a unique-constraint failure (catch P2002 on customerNumber, recompute, re-insert), rather than letting the second staff member's creation just fail.
• Web: /clientes/nuevo (CustomerForm.tsx) shows the assigned number as soon as the form loads (read-only, "Número de cliente: 214 (reciclado)" if it's a reused slot, so staff know to expect the old physical folder) — server-assigns it on submit, doesn't let staff type an arbitrary one, which is what prevents the collisions manual assignment risks today. CreateCustomerDto deliberately gains no customerNumber field — the whole point is the client can't set it.

The purge question — needs Jorge's decision

The office's paper-world habit is literally "purge their history, info, etc." when recycling a folder. This codebase's established convention is the opposite — never hard-delete migrated/business data, only archive (archivedAt), specifically so mistakes are reversible and there's always an audit trail (see Customer.archivedAt, Policy.archivedAt, Property.archivedAt, and the OpsJob/ActivityLog audit models already in the schema).

Recommend: archive by default, never hard-delete. The customerNumber release already solves the actual operational need (the number is free to reuse); keeping the old customer's data around under a freed number costs nothing and preserves history for the inevitable case where "definitely cancelled" turns out to be wrong. If Jorge specifically wants literal data purge (e.g. for a data-retention/privacy policy reason, not just paper-world habit), that should be a separate, explicit, ADMIN-only action (customer:purge) taken well after release — not bundled into release-number — so the two decisions ("this number is reusable" vs. "permanently destroy this person's records") aren't accidentally coupled.

Abilities (new)

Ability	Min role	Notes
customer:recycle	MANAGER	flag a candidate reviewed, release their number, archive the record
customer:purge	ADMIN	only if Jorge wants literal PII destruction, kept separate from release

Open questions

• Confirm the "1 year of no activity" clock: measured from last Transaction.transactionDate, or should a customer with an expired but never-renewed policy count as cancelled immediately rather than waiting out the year? (Spec above treats these as two independent triggers, CANCELLED vs. INACTIVITY — confirm that's the right split.)
• Does Jorge want true data purge at all, or is archive-and-hide sufficient? (See above — recommend archive-only unless there's a compliance reason for real deletion.)
• Should insurance-only customers (no legacy NUM id) share the same numbering sequence as utilities customers, or get their own? Recommend one shared sequence — it's one physical-folder system per the notes, not two.

---

Build sequencing

1. §1.1 + §1.2 + §1.3 (receipt capture completion) — smallest, builds directly on existing billing/ code, no new tables. Ship first; it's also a prerequisite for §2.
2. §4 (customer-number recycling) — independent of the others, touches customers/ only. Can be built in parallel with §1.
3. §3 (multi-bank chequera) — independent of §1/§2, touches bank/ only. Needs the US bank name from Jorge before the migration step can run; the schema/API work can start before that answer arrives.
4. §2 (PDF/OCR auto-capture) — largest, depends on §1 being done (it posts through the batch-capture path) and on the OCR-provider decision. Build last, and prototype the extraction accuracy against a handful of real CFE statements before committing to the provider choice.

Open questions to take back to Jorge (collected)

• OCR provider/budget for §2 (self-hosted vs. managed API, given 300+ pages/month/company).
• Whether source PDFs arrive pre-split per customer or as one bundled file needing page-range detection (§2).
• Whether "Clave Catastral" and the already-migrated PREDIAL-sourced PROPERTY_TAX.accountNumber are the same number — blocks OCR matching for predial statements specifically until confirmed (§2).
• Whether phone billing is really one service per phone number on file, or one per property regardless of how many numbers are recorded — decides how the new TELEPHONE service kind gets backfilled (§2).
• The actual bank name/currency/details for the Seguros USD account, and whether any historical Seguros bank data exists to migrate (§3).
• Whether BankAccount.businessLine should be enforced or a soft hint (§3).
• The exact "1 year inactivity" / "cancelled" recycling triggers (§4).
• Whether customer-number recycling should ever include true data purge, or archive-and-reuse-the-number is sufficient (§4).