phase-3: ingestion, from a QR in the camera to a card in the bandeja

The whole pipeline: storage behind one driver interface (local disk and S3),
a portable job queue with a poller, QR and CDC parsing, OCR through the
Anthropic API, dedupe, manual entry, and the bandeja that turns all of it into
one decision per card.

Scanning tries the trustworthy door first: a QR is parsed and prefilled from
its CDC; a photo without one is queued for OCR when a key is configured and
otherwise opens the manual form against the stored file. A QR that will not
parse records an ingest error and falls through rather than losing the photo.

Job claiming is the only dialect divergence, as SPEC allows: FOR UPDATE SKIP
LOCKED on Postgres, a conditional UPDATE against SQLite's single writer. Retry
backoff follows SPEC exactly and a job abandoned by a killed process returns to
the queue once its lock goes stale, which is the phase 3 acceptance case.

OCR uses structured outputs rather than parsing prose, so the model cannot
return anything but the RULES.md schema, and every field is nullable because
unreadable is a real answer.

Web: scan with live QR decoding (BarcodeDetector, ZXing fallback, wasm served
from our own origin), manual entry with the IVA split worked out from the
total, the bandeja with swipe, buttons and keyboard all doing the same thing,
and the documents list and detail with an editable classification.

The seed now carries Maria's 34 purchases and 8 sales and Carlos's 6, all
classified through the real rules, plus the two open ingest errors.

Two defects found and fixed with tests: seeded documents could be dated in the
future, which would corrupt any projection computed from them, and the category
buttons announced their keyboard shortcut as part of their name.

255 vitest tests, 37 Playwright tests, rules coverage still 100%, typecheck and
lint clean.

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

e2e/ingestion.spec.ts

@@ -0,0 +1,143 @@
+import { fileURLToPath } from 'node:url';
+import { es } from '@impuestos/i18n';
+import { expect, test, type Page } from '@playwright/test';
+
+/**
+ * Golden paths 2 and 3 (SPEC.md section 13). Both run through the real UI: the browser
+ * decodes the fixture's QR itself, uploads the image, and the document comes back through
+ * the same pipeline a phone would use.
+ */
+
+// Serial: these tests confirm and reject out of one account's bandeja, so running two of
+// them at once has each pulling cards out from under the other.
+test.describe.configure({ mode: 'serial' });
+
+const fixture = (name: string) =>
+  fileURLToPath(new URL(`../fixtures/${name}.png`, import.meta.url));
+
+async function signIn(page: Page): Promise<void> {
+  await page.goto('/es/login');
+  await page.getByLabel(es['auth.register.email']).fill('maria@demo.local');
+  await page.getByLabel(es['auth.login.password']).fill('demo-maria-1');
+  await page.getByRole('button', { name: es['auth.login.submit'] }).click();
+  await expect(page).toHaveURL(/\/es\/inicio$/);
+}
+
+/**
+ * These confirm and reject documents out of one shared demo account, so running them in
+ * two projects at once has the two workers racing for the same card. They run on desktop
+ * only; bandeja rendering on a phone viewport is covered by bandeja.spec.ts, which reads
+ * and never mutates.
+ */
+test.describe('golden path 2: scan a QR comprobante and confirm it', () => {
+  test.beforeEach(() => {
+    test.skip(test.info().project.name !== 'desktop', 'mutates shared seed data');
+  });
+
+  test('reads the fixture, then confirms it out of the bandeja', async ({ page }) => {
+    await signIn(page);
+    await page.goto('/es/escanear');
+
+    // "Subir archivo" is the same code path as the camera: decode, then upload.
+    await page.locator('input[type="file"]').setInputFiles(fixture('factura-qr-supermercado'));
+
+    // Whether this is the first scan of the fixture or a repeat depends on what the
+    // stack has seen before, and path 2 is about the data, not about which of the two
+    // headings appears. The duplicate case has its own test below.
+    await expect(page.getByText(es['scan.registered'])).toBeVisible({ timeout: 20_000 });
+
+    // A QR carries the emitter's RUC but not its name, so that is what is shown.
+    await expect(page.getByText('RUC 80011223')).toBeVisible();
+    await expect(page.getByText('Gs. 385.000')).toBeVisible();
+    // Exact: the duplicate note also names the date, in a sentence.
+    await expect(page.getByText('14 de agosto', { exact: true })).toBeVisible();
+
+    await page.getByRole('link', { name: es['scan.goToBandeja'] }).click();
+    await expect(page).toHaveURL(/\/es\/bandeja$/);
+
+    const card = page.getByTestId('bandeja-card');
+    await expect(card).toBeVisible();
+    const emitter = (await card.locator('p').first().textContent()) ?? '';
+    await page.getByRole('button', { name: es['bandeja.confirm'] }).click();
+
+    // The confirmed card leaves the stack.
+    await expect(async () => {
+      const next = await page.getByTestId('bandeja-card').locator('p').first().textContent();
+      expect(next).not.toBe(emitter);
+    }).toPass({ timeout: 10_000 });
+  });
+
+  // CONTRACTS.md 5.1, through the UI this time. Scanning twice inside the test makes the
+  // second outcome deterministic whatever the stack has seen before.
+  test('scanning the same fixture twice says so instead of duplicating it', async ({ page }) => {
+    await signIn(page);
+
+    await page.goto('/es/escanear');
+    await page.locator('input[type="file"]').setInputFiles(fixture('factura-qr-farmacia'));
+    await expect(page.getByText(es['scan.registered'])).toBeVisible({ timeout: 20_000 });
+
+    await page.goto('/es/escanear');
+    await page.locator('input[type="file"]').setInputFiles(fixture('factura-qr-farmacia'));
+    await expect(page.getByRole('heading', { name: es['scan.duplicate.title'] })).toBeVisible({
+      timeout: 20_000,
+    });
+    await expect(page.getByText(es['scan.duplicate.body'].split('{')[0] as string)).toBeVisible();
+  });
+
+  test('a photo with no QR sends you to the manual form with the file attached', async ({ page }) => {
+    await signIn(page);
+    await page.goto('/es/escanear');
+    await page.locator('input[type="file"]').setInputFiles(fixture('factura-sin-qr-ferreteria'));
+
+    await expect(page).toHaveURL(/\/es\/comprobantes\/nuevo\?fileId=/, { timeout: 20_000 });
+    await expect(page.getByText(es['scan.needsManual'])).toBeVisible();
+  });
+});
+
+test.describe('golden path 3: enter a factura by hand and change its category', () => {
+  test.beforeEach(() => {
+    test.skip(test.info().project.name !== 'desktop', 'mutates shared seed data');
+  });
+
+  test('saves it, classifies it, and takes a correction', async ({ page }) => {
+    await signIn(page);
+    await page.goto('/es/comprobantes/nuevo');
+
+    // The dedupe key is the issuer, the date and the total, not the name, so the total
+    // has to differ per run or this correctly merges into a previous run's document.
+    const emitter = `PANADERIA PRUEBA ${Date.now()}`;
+    const total = 170_000 + (Date.now() % 9_000);
+    await page.getByLabel(es['manual.emitterRuc']).fill('80022114-1');
+    await page.getByLabel(es['manual.emitterName']).fill(emitter);
+    await page.getByLabel(es['manual.total']).fill(String(total));
+    await page.getByRole('button', { name: es['manual.submit'] }).click();
+
+    await expect(page).toHaveURL(/\/es\/bandeja$/, { timeout: 15_000 });
+
+    // PANADERIA is an alimentacion keyword, so that is what the rules suggested.
+    const card = page.getByTestId('bandeja-card');
+    await expect(card).toContainText(emitter);
+    await expect(card).toContainText(es['categories.alimentacion']);
+
+    // Correct it to Salud, which is the user overriding the classifier.
+    await page.getByRole('button', { name: es['scan.result.changeCat'] }).click();
+    await page.getByRole('button', { name: es['categories.salud'] }).click();
+    await expect(card).toContainText(es['categories.salud']);
+
+    await page.getByRole('button', { name: es['bandeja.confirm'] }).click();
+
+    // The correction survives into the document detail.
+    await page.goto('/es/comprobantes');
+    await page.getByRole('link').filter({ hasText: emitter }).first().click();
+    await expect(page.getByTestId('document-category')).toHaveText(es['categories.salud']);
+  });
+
+  test('refuses a RUC whose check digit does not match', async ({ page }) => {
+    await signIn(page);
+    await page.goto('/es/comprobantes/nuevo');
+
+    await page.getByLabel(es['manual.emitterRuc']).fill('4123456-9');
+    await expect(page.getByText(es['landing.invalidDoc'])).toBeVisible();
+    await expect(page.getByRole('button', { name: es['manual.submit'] })).toBeDisabled();
+  });
+});