feat(billing): receipt capture — outstanding workflow, batch by check, reconciliation

Implements docs/RECEIPT_CAPTURE_SPEC.md §1, the legacy "Editor"
replacement, on top of the single-movement capture from plan step 6.
No new abilities: batching and resolving are both capturing.

- outstanding (legacy NOPAGO): capture flag, ?outstanding= filter, and
  POST /billing/:id/resolve-outstanding (gated ledger:create, not
  ledger:void — resolving completes a capture rather than reversing
  one). Outstanding rows are excluded from every balance aggregate,
  matching the legacy SALDOS ULTIMO 0 query's HAVING NOPAGO = 0, but
  still count in the movement browser's filtered totals.
- POST /billing/batch: many customers' receipts against one check, in
  one $transaction. Deliberately not a persisted batch entity —
  checkNumber is already a column and grouping by it answers every
  legacy by-check query.
- GET /billing/by-check + a cheque-count report, replacing REPORTE
  CHEQUE COUNT / REPORTE POR CHEQUE / EDITA CHEQUE ALF|COUNT|NUM. Print,
  PDF, CSV and XLSX come free from the existing /reportes/:slug machinery.
- Web: /estado-cuenta/lote (the Editor screen, with live reconciliation
  against the physical check amount), an "Estado de pago" filter, a
  "sin fondos" row tag and a Resolver dialog, plus a top-level "Captura"
  nav entry.

Integration seam for the OCR auto-capture module (spec §2), which is
required to post through createBatch rather than writing Transaction
rows itself: items[i] maps to lines[i] so postedTransactionId can be
zipped back on; opts.refs[i] stamps captureRef with a duplicate-post
guard that a voided row deliberately does not block; opts.source is
service-level only, so an HTTP client cannot label hand-keyed rows as
machine-captured. captureSource/captureRef are nullable so the 40,136
migrated rows stay NULL rather than being mislabelled.

Fixes two pre-existing bugs found while building this:

- statement() filtered legacySourceTable with `notIn`, which compiles to
  SQL NOT IN — and `NULL NOT IN (...)` is NULL, so every app-captured
  movement was invisible on the customer statement (438 rows in the
  movement browser vs 392 on the statement) while showing everywhere
  else. This would have made the whole capture feature look broken.
- The balances count query omitted the void filter its own page query
  applied, so the total disagreed with the rows.

Nav highlighting now resolves by longest match; the previous
first-startsWith logic lit up both the parent and any nested entry.

Verified end-to-end against the dev DB, API and browser; all test rows
removed afterwards. Also corrects RESUME.md, which documented the dev
ports as :3001/:3000 — they are :4501/:4500, from the env files.

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

apps/web/src/lib/api.ts

@@ -13,11 +13,15 @@ import type {
   BankSort,
   BankStats,
   BankSummary,
+  BatchCreateInput,
+  BatchCreateResponse,
   BillingFacets,
   BillingStats,
   BusinessLine,
+  ByCheckResponse,
   CreateBankMovementInput,
   CreateMovementInput,
+  ResolveOutstandingInput,
   CustomerDetail,
   CustomerInput,
   CustomerListResponse,
@@ -484,6 +488,10 @@ export interface MovementQuery {
   typeId?: string;
   source?: string;
   customerId?: string;
+  /** Restrict to captured-but-unpaid rows (the NOPAGO worklist). */
+  outstanding?: boolean;
+  /** Exact check number — the by-check reconciliation lookup. */
+  checkNumber?: string;
   /** `YYYY-MM-DD`, inclusive on both ends. */
   from?: string;
   to?: string;
@@ -501,6 +509,8 @@ export function listMovements(q: MovementQuery): Promise<MovementListResponse> {
   if (q.typeId) params.set("typeId", q.typeId);
   if (q.source) params.set("source", q.source);
   if (q.customerId) params.set("customerId", q.customerId);
+  if (q.outstanding !== undefined) params.set("outstanding", String(q.outstanding));
+  if (q.checkNumber) params.set("checkNumber", q.checkNumber);
   if (q.from) params.set("from", q.from);
   if (q.to) params.set("to", q.to);
   if (q.sort) params.set("sort", q.sort);
@@ -559,6 +569,36 @@ export function voidMovement(id: string): Promise<Transaction> {
   return apiFetch<Transaction>(`/billing/${id}/void`, { method: "POST" });
 }
 
+/** Capture many customers' receipts against one check, in one transaction. The
+ *  returned `items` are positionally parallel to `input.lines`. */
+export function createMovementBatch(
+  input: BatchCreateInput,
+): Promise<BatchCreateResponse> {
+  return apiFetch<BatchCreateResponse>("/billing/batch", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** Clear an outstanding (NOPAGO) row: stamps the check number + resolution date
+ *  and starts counting it toward the balance. 400 if not outstanding or voided. */
+export function resolveOutstanding(
+  id: string,
+  input: ResolveOutstandingInput,
+): Promise<Transaction> {
+  return apiFetch<Transaction>(`/billing/${id}/resolve-outstanding`, {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** Everything captured against one check, with its reconciliation total. */
+export function getByCheck(checkNumber: string): Promise<ByCheckResponse> {
+  return apiFetch<ByCheckResponse>(
+    `/billing/by-check?checkNumber=${encodeURIComponent(checkNumber)}`,
+  );
+}
+
 /* ------------------------------------------------- Bank register (chequera) */
 
 export interface BankQuery {

apps/web/src/lib/types.ts

@@ -718,6 +718,9 @@ export interface Movement {
   type: TransactionType | null;
   /** App-voided (`voidedAt` set). UI strikes; totals exclude. */
   voided: boolean;
+  /** Legacy "NOPAGO": captured but unpaid (no funds). Shown tagged, and kept
+   *  out of every balance until resolved via resolveOutstanding(). */
+  outstanding?: boolean;
 }
 
 /** Payload for POST /billing — a new ledger movement. Sign convention: negative
@@ -733,6 +736,73 @@ export interface CreateMovementInput {
   reference?: string;
   checkNumber?: string;
   message?: string;
+  /** Legacy NOPAGO — captured but unpaid; excluded from balances until resolved. */
+  outstanding?: boolean;
+}
+
+/** One customer's line inside a check batch; check-level fields sit on the parent. */
+export interface BatchLineInput {
+  customerId: string;
+  amount: number;
+  reference?: string;
+  period?: string;
+  message?: string;
+  outstanding?: boolean;
+}
+
+/** Payload for POST /billing/batch — many receipts cut against one check. */
+export interface BatchCreateInput {
+  domain: TransactionDomain;
+  transactionDate: string;
+  checkNumber: string;
+  currency?: Currency;
+  typeId?: string;
+  lines: BatchLineInput[];
+}
+
+export interface BatchCreateResponse {
+  /** Positionally parallel to the submitted `lines`. */
+  items: Transaction[];
+  checkNumber: string;
+  currency: LedgerCurrency;
+  source: "MANUAL" | "BATCH" | "OCR";
+  count: number;
+  outstandingCount: number;
+  /** Excludes outstanding lines — this is the figure to reconcile against the
+   *  physical check. */
+  total: string;
+}
+
+/** Payload for POST /billing/:id/resolve-outstanding. */
+export interface ResolveOutstandingInput {
+  checkNumber: string;
+  resolvedDate: string;
+}
+
+export interface ByCheckItem {
+  id: string;
+  transactionDate: string | null;
+  domain: TransactionDomain;
+  amount: string;
+  currency: LedgerCurrency;
+  direction: LedgerDirection;
+  reference: string | null;
+  period: string | null;
+  message: string | null;
+  outstanding: boolean;
+  type: TransactionType | null;
+  customerId: string;
+  customerName: string;
+  customerNameSource: string | null;
+}
+
+/** GET /billing/by-check — everything cut against one check, for reconciliation. */
+export interface ByCheckResponse {
+  checkNumber: string;
+  items: ByCheckItem[];
+  count: number;
+  outstandingCount: number;
+  totals: { currency: LedgerCurrency; total: string; count: number }[];
 }
 
 export interface MovementListItem extends Movement {