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>
This commit is contained in:
Michilis
co-authored by
Claude Opus 5
Claude Opus 5
parent
0d7651b17c
commit
b074456b70
@@ -1,16 +1,25 @@
|
||||
import type { z } from 'zod';
|
||||
import {
|
||||
type ClassificationPatchInput,
|
||||
type ConsentInput,
|
||||
DataExportDto,
|
||||
type DeleteAccountInput,
|
||||
DependentDto,
|
||||
type DependentInput,
|
||||
DocumentDto,
|
||||
DocumentListDto,
|
||||
type DocumentListQuery,
|
||||
type DocumentPatchInput,
|
||||
IngestErrorDto,
|
||||
LookupDto,
|
||||
type ManualDocumentInput,
|
||||
NotificationPrefsDto,
|
||||
type NotificationPrefsInput,
|
||||
OkDto,
|
||||
ProfileDto,
|
||||
type ProfileInput,
|
||||
type RejectInput,
|
||||
ScanResultDto,
|
||||
} from './dto';
|
||||
import { ApiError, ErrorEnvelope } from './errors';
|
||||
|
||||
@@ -38,6 +47,22 @@ export function createApiClient(options: ApiClientOptions = {}) {
|
||||
const baseUrl = (options.baseUrl ?? '').replace(/\/$/, '');
|
||||
const doFetch = options.fetch ?? globalThis.fetch;
|
||||
|
||||
/** Multipart, so the browser sets the boundary. Never set content-type by hand here. */
|
||||
async function requestForm<T>(path: string, form: FormData, schema: z.ZodType<T>): Promise<T> {
|
||||
const url = `${baseUrl}/api${path}`;
|
||||
const response = await doFetch(baseUrl ? url : `/api${path}`, {
|
||||
method: 'POST',
|
||||
headers: { accept: 'application/json', ...options.headers },
|
||||
credentials: 'include',
|
||||
body: form,
|
||||
});
|
||||
|
||||
const text = await response.text();
|
||||
const json: unknown = text.length > 0 ? safeJson(text) : undefined;
|
||||
if (!response.ok) throw toApiError(response.status, json);
|
||||
return schema.parse(json);
|
||||
}
|
||||
|
||||
async function request<T>(
|
||||
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
|
||||
path: string,
|
||||
@@ -106,6 +131,43 @@ export function createApiClient(options: ApiClientOptions = {}) {
|
||||
deleteAccount: (body: DeleteAccountInput) =>
|
||||
request('DELETE', '/me/account', { schema: OkDto, body }),
|
||||
|
||||
// Documents
|
||||
scanDocument: (file: File, qrPayload?: string | null) => {
|
||||
const form = new FormData();
|
||||
form.set('file', file);
|
||||
if (qrPayload) form.set('qrPayload', qrPayload);
|
||||
return requestForm('/documents/scan', form, ScanResultDto);
|
||||
},
|
||||
createManualDocument: (body: ManualDocumentInput) =>
|
||||
request('POST', '/documents/manual', { schema: DocumentDto, body }),
|
||||
listDocuments: (query: DocumentListQuery, signal?: AbortSignal) =>
|
||||
request('GET', '/documents', {
|
||||
schema: DocumentListDto,
|
||||
query: query as Record<string, string | undefined>,
|
||||
...(signal ? { signal } : {}),
|
||||
}),
|
||||
getDocument: (id: string, signal?: AbortSignal) =>
|
||||
request('GET', `/documents/${encodeURIComponent(id)}`, {
|
||||
schema: DocumentDto,
|
||||
...(signal ? { signal } : {}),
|
||||
}),
|
||||
patchDocument: (id: string, body: DocumentPatchInput) =>
|
||||
request('PATCH', `/documents/${encodeURIComponent(id)}`, { schema: DocumentDto, body }),
|
||||
confirmDocument: (id: string) =>
|
||||
request('POST', `/documents/${encodeURIComponent(id)}/confirm`, { schema: DocumentDto }),
|
||||
rejectDocument: (id: string, body: RejectInput) =>
|
||||
request('POST', `/documents/${encodeURIComponent(id)}/reject`, { schema: DocumentDto, body }),
|
||||
patchClassification: (id: string, body: ClassificationPatchInput) =>
|
||||
request('PATCH', `/documents/${encodeURIComponent(id)}/classification`, {
|
||||
schema: DocumentDto,
|
||||
body,
|
||||
}),
|
||||
listIngestErrors: (signal?: AbortSignal) =>
|
||||
request('GET', '/documents/errors', {
|
||||
schema: IngestErrorDto.array(),
|
||||
...(signal ? { signal } : {}),
|
||||
}),
|
||||
|
||||
// Notifications
|
||||
getNotificationPrefs: (signal?: AbortSignal) =>
|
||||
request('GET', '/me/notification-prefs', {
|
||||
|
||||
@@ -1,5 +1,17 @@
|
||||
import { z } from 'zod';
|
||||
import { DocType, IrpCategory, LocaleCode, ObligationCode, TaxpayerKind } from './enums';
|
||||
import {
|
||||
Direction,
|
||||
DocKind,
|
||||
DocSource,
|
||||
DocStatus,
|
||||
DocType,
|
||||
IrpCategory,
|
||||
LocaleCode,
|
||||
ObligationCode,
|
||||
SupplierRegimeHint,
|
||||
TaxpayerKind,
|
||||
VerificationStatus,
|
||||
} from './enums';
|
||||
|
||||
/**
|
||||
* DTO schemas are added as their phase lands. Field names come from CONTRACTS.md
|
||||
@@ -112,6 +124,129 @@ export type DataExportDto = z.infer<typeof DataExportDto>;
|
||||
export const DeleteAccountInput = z.object({ confirmText: z.string() });
|
||||
export type DeleteAccountInput = z.infer<typeof DeleteAccountInput>;
|
||||
|
||||
export const ClassificationDto = z.object({
|
||||
ivaCreditEligible: z.boolean(),
|
||||
ivaCreditAmount: z.number().int(),
|
||||
irpCategory: z.union([IrpCategory, z.literal('none')]),
|
||||
irpDeductibleAmount: z.number().int(),
|
||||
dependentId: z.string().nullable(),
|
||||
confidence: z.number(),
|
||||
decidedBy: z.enum(['auto', 'user', 'staff']),
|
||||
rulesVersion: z.string(),
|
||||
/** Reason codes from packages/rules, localized by the UI. */
|
||||
reasons: z.array(z.string()),
|
||||
});
|
||||
export type ClassificationDto = z.infer<typeof ClassificationDto>;
|
||||
|
||||
export const DocumentDto = z.object({
|
||||
id: z.string(),
|
||||
source: DocSource,
|
||||
status: DocStatus,
|
||||
cdc: z.string().nullable(),
|
||||
docKind: DocKind,
|
||||
direction: Direction,
|
||||
emitterRuc: z.string(),
|
||||
emitterDv: z.string().nullable(),
|
||||
emitterName: z.string(),
|
||||
receiverDoc: z.string().nullable(),
|
||||
issueDate: z.string(),
|
||||
currency: z.literal('PYG'),
|
||||
total: z.number().int(),
|
||||
amountIva10: z.number().int(),
|
||||
amountIva5: z.number().int(),
|
||||
amountExenta: z.number().int(),
|
||||
iva10: z.number().int(),
|
||||
iva5: z.number().int(),
|
||||
supplierRegimeHint: SupplierRegimeHint,
|
||||
verifiedDnit: z.boolean(),
|
||||
verificationStatus: VerificationStatus,
|
||||
fileUrl: z.string().nullable(),
|
||||
classification: ClassificationDto.nullable(),
|
||||
createdAt: z.string(),
|
||||
confirmedAt: z.string().nullable(),
|
||||
/** Present only on a scan that collapsed into an existing document. */
|
||||
merged: z.boolean().optional(),
|
||||
});
|
||||
export type DocumentDto = z.infer<typeof DocumentDto>;
|
||||
|
||||
/** A scan with no QR and no OCR configured: the client opens the manual form. */
|
||||
export const NeedsManualDto = z.object({
|
||||
needsManual: z.literal(true),
|
||||
fileId: z.string(),
|
||||
});
|
||||
export type NeedsManualDto = z.infer<typeof NeedsManualDto>;
|
||||
|
||||
export const ScanResultDto = z.union([DocumentDto, NeedsManualDto]);
|
||||
export type ScanResultDto = z.infer<typeof ScanResultDto>;
|
||||
|
||||
export const ManualDocumentInput = z.object({
|
||||
fileId: z.string().nullable().optional(),
|
||||
direction: Direction.default('purchase'),
|
||||
docKind: DocKind.default('factura'),
|
||||
emitterRuc: z.string().trim().min(1).max(20),
|
||||
emitterDv: z.string().trim().max(2).nullable().optional(),
|
||||
emitterName: z.string().trim().min(1).max(200),
|
||||
issueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
|
||||
total: z.number().int().min(0),
|
||||
amountIva10: z.number().int().min(0).default(0),
|
||||
amountIva5: z.number().int().min(0).default(0),
|
||||
amountExenta: z.number().int().min(0).default(0),
|
||||
iva10: z.number().int().min(0).default(0),
|
||||
iva5: z.number().int().min(0).default(0),
|
||||
supplierRegimeHint: SupplierRegimeHint.default('unknown'),
|
||||
});
|
||||
export type ManualDocumentInput = z.infer<typeof ManualDocumentInput>;
|
||||
|
||||
export const DocumentPatchInput = ManualDocumentInput.partial().omit({ fileId: true });
|
||||
export type DocumentPatchInput = z.infer<typeof DocumentPatchInput>;
|
||||
|
||||
export const ClassificationPatchInput = z.object({
|
||||
irpCategory: z.union([IrpCategory, z.literal('none')]).optional(),
|
||||
ivaCreditEligible: z.boolean().optional(),
|
||||
dependentId: z.string().nullable().optional(),
|
||||
});
|
||||
export type ClassificationPatchInput = z.infer<typeof ClassificationPatchInput>;
|
||||
|
||||
export const RejectInput = z.object({
|
||||
reason: z.enum(['not_mine', 'duplicate', 'other']),
|
||||
});
|
||||
export type RejectInput = z.infer<typeof RejectInput>;
|
||||
|
||||
export const DocumentListQuery = z.object({
|
||||
month: z.string().regex(/^\d{4}-\d{2}$/).optional(),
|
||||
direction: Direction.optional(),
|
||||
category: z.union([IrpCategory, z.literal('none')]).optional(),
|
||||
status: DocStatus.optional(),
|
||||
q: z.string().trim().max(200).optional(),
|
||||
cursor: z.string().optional(),
|
||||
});
|
||||
export type DocumentListQuery = z.infer<typeof DocumentListQuery>;
|
||||
|
||||
/** Lists use cursor pagination with a page size of 50 (CONTRACTS.md section 1). */
|
||||
export const PAGE_SIZE = 50;
|
||||
|
||||
export function listDto<T extends z.ZodType>(item: T) {
|
||||
return z.object({
|
||||
items: z.array(item),
|
||||
total: z.number().int(),
|
||||
cursor: z.string().optional(),
|
||||
});
|
||||
}
|
||||
|
||||
export const DocumentListDto = listDto(DocumentDto);
|
||||
export type DocumentListDto = z.infer<typeof DocumentListDto>;
|
||||
|
||||
export const IngestErrorDto = z.object({
|
||||
id: z.string(),
|
||||
userId: z.string().nullable(),
|
||||
documentId: z.string().nullable(),
|
||||
stage: z.enum(['qr_parse', 'ocr', 'dedupe', 'verify', 'job', 'other']),
|
||||
message: z.string(),
|
||||
status: z.enum(['open', 'resolved']),
|
||||
createdAt: z.string(),
|
||||
});
|
||||
export type IngestErrorDto = z.infer<typeof IngestErrorDto>;
|
||||
|
||||
export const OkDto = z.object({ ok: z.literal(true) });
|
||||
export type OkDto = z.infer<typeof OkDto>;
|
||||
|
||||
|
||||
@@ -32,6 +32,19 @@ export {
|
||||
LookupDto,
|
||||
DataExportDto,
|
||||
DeleteAccountInput,
|
||||
ClassificationDto,
|
||||
DocumentDto,
|
||||
NeedsManualDto,
|
||||
ScanResultDto,
|
||||
ManualDocumentInput,
|
||||
DocumentPatchInput,
|
||||
ClassificationPatchInput,
|
||||
RejectInput,
|
||||
DocumentListQuery,
|
||||
DocumentListDto,
|
||||
IngestErrorDto,
|
||||
PAGE_SIZE,
|
||||
listDto,
|
||||
OkDto,
|
||||
HealthDto,
|
||||
ReadyDto,
|
||||
|
||||
@@ -301,6 +301,58 @@ export const en: Record<MessageKey, string> = {
|
||||
"common.saving": "Saving...",
|
||||
"common.skip": "Skip",
|
||||
|
||||
// Scan, bandeja and documents (phase 3)
|
||||
"scan.title": "Scan",
|
||||
"scan.torch": "Torch",
|
||||
"scan.shutter": "Take the photo",
|
||||
"scan.cameraDenied": "We could not open the camera. You can still upload a photo.",
|
||||
"scan.uploading": "Uploading...",
|
||||
"scan.result.title": "Got it, we read it",
|
||||
"scan.result.emitter": "Issuer",
|
||||
"scan.result.date": "Date",
|
||||
"scan.result.total": "Total",
|
||||
"scan.needsManual": "We could not find the QR. Fill in the details and we will attach your photo.",
|
||||
"scan.another": "Scan another",
|
||||
"scan.goToBandeja": "Go to the inbox",
|
||||
"manual.direction": "Is this a purchase or a sale of yours?",
|
||||
"manual.direction.purchase": "Purchase",
|
||||
"manual.direction.sale": "Sale",
|
||||
"manual.ivaSplit.help": "We work the IVA out from the total. If your factura splits it differently, correct it.",
|
||||
"manual.iva10": "IVA 10%",
|
||||
"manual.iva5": "IVA 5%",
|
||||
"manual.exenta": "Exempt",
|
||||
"manual.regime": "Supplier regime",
|
||||
"manual.regime.normal": "Normal",
|
||||
"manual.regime.resimple": "RESIMPLE",
|
||||
"manual.regime.unknown": "Not sure",
|
||||
"manual.submit": "Save factura",
|
||||
"bandeja.count": "{count} to review",
|
||||
"bandeja.swipeHint": "Swipe right to confirm, left to change the category.",
|
||||
"bandeja.keyboardHint": "With a keyboard: J and K to move, Enter to confirm, 1 to 8 for the category, X to discard.",
|
||||
"bandeja.category": "Category",
|
||||
"bandeja.confidence.high": "High confidence",
|
||||
"bandeja.confidence.low": "Worth a look",
|
||||
"bandeja.whyThis": "Why this category?",
|
||||
"docs.empty": "You have not added any documents yet.",
|
||||
"docs.emptyCta": "Scan the first one",
|
||||
"docs.filter.all": "All",
|
||||
"docs.filter.direction": "Type",
|
||||
"docs.filter.status": "Status",
|
||||
"docs.monthTotal": "Month total",
|
||||
"docs.count": "{count} documents",
|
||||
"docs.detail.title": "Document",
|
||||
"docs.detail.ivaCredit": "IVA credit",
|
||||
"docs.detail.deductible": "Deductible for IRP",
|
||||
"docs.detail.notDeductible": "Not deductible",
|
||||
"docs.detail.source.scan_qr": "Scanned from a QR",
|
||||
"docs.detail.source.scan_ocr": "Read from a photo",
|
||||
"docs.detail.source.manual": "Entered by hand",
|
||||
"docs.errors.title": "Some could not be processed",
|
||||
"docs.errors.retry": "Enter it by hand",
|
||||
"status.needs_review": "To review",
|
||||
"status.confirmed": "Confirmed",
|
||||
"status.rejected": "Discarded",
|
||||
|
||||
// Chrome (es.extra.ts)
|
||||
"common.language": "Language",
|
||||
"common.languageEs": "Español",
|
||||
|
||||
@@ -102,6 +102,58 @@ export const esExtra = {
|
||||
"common.saving": "Guardando...",
|
||||
"common.skip": "Omitir",
|
||||
|
||||
// Scan, bandeja and documents (phase 3)
|
||||
"scan.title": "Escanear",
|
||||
"scan.torch": "Linterna",
|
||||
"scan.shutter": "Sacar la foto",
|
||||
"scan.cameraDenied": "No pudimos abrir la camara. Podés subir una foto igual.",
|
||||
"scan.uploading": "Subiendo...",
|
||||
"scan.result.title": "Listo, la leimos",
|
||||
"scan.result.emitter": "Emisor",
|
||||
"scan.result.date": "Fecha",
|
||||
"scan.result.total": "Total",
|
||||
"scan.needsManual": "No encontramos el QR. Completá los datos y adjuntamos tu foto.",
|
||||
"scan.another": "Escanear otra",
|
||||
"scan.goToBandeja": "Ir a la bandeja",
|
||||
"manual.direction": "¿Es una compra o una venta tuya?",
|
||||
"manual.direction.purchase": "Compra",
|
||||
"manual.direction.sale": "Venta",
|
||||
"manual.ivaSplit.help": "Calculamos el IVA sobre el total. Si tu factura tiene otro reparto, corregilo.",
|
||||
"manual.iva10": "IVA 10%",
|
||||
"manual.iva5": "IVA 5%",
|
||||
"manual.exenta": "Exentas",
|
||||
"manual.regime": "Regimen del proveedor",
|
||||
"manual.regime.normal": "Normal",
|
||||
"manual.regime.resimple": "RESIMPLE",
|
||||
"manual.regime.unknown": "No se",
|
||||
"manual.submit": "Guardar factura",
|
||||
"bandeja.count": "{count} por revisar",
|
||||
"bandeja.swipeHint": "Deslizá a la derecha para confirmar, a la izquierda para cambiar la categoria.",
|
||||
"bandeja.keyboardHint": "Con teclado: J y K para moverte, Enter para confirmar, 1 a 8 para la categoria, X para descartar.",
|
||||
"bandeja.category": "Categoria",
|
||||
"bandeja.confidence.high": "Alta confianza",
|
||||
"bandeja.confidence.low": "Revisar",
|
||||
"bandeja.whyThis": "¿Por que esta categoria?",
|
||||
"docs.empty": "Todavia no cargaste ningun comprobante.",
|
||||
"docs.emptyCta": "Escanear el primero",
|
||||
"docs.filter.all": "Todos",
|
||||
"docs.filter.direction": "Tipo",
|
||||
"docs.filter.status": "Estado",
|
||||
"docs.monthTotal": "Total del mes",
|
||||
"docs.count": "{count} comprobantes",
|
||||
"docs.detail.title": "Comprobante",
|
||||
"docs.detail.ivaCredit": "Credito de IVA",
|
||||
"docs.detail.deductible": "Deducible de IRP",
|
||||
"docs.detail.notDeductible": "No deducible",
|
||||
"docs.detail.source.scan_qr": "Escaneada por QR",
|
||||
"docs.detail.source.scan_ocr": "Leida de una foto",
|
||||
"docs.detail.source.manual": "Cargada a mano",
|
||||
"docs.errors.title": "No pudimos procesar algunas",
|
||||
"docs.errors.retry": "Cargala a mano",
|
||||
"status.needs_review": "Por revisar",
|
||||
"status.confirmed": "Confirmada",
|
||||
"status.rejected": "Descartada",
|
||||
|
||||
// Chrome
|
||||
"common.language": "Idioma",
|
||||
"common.languageEs": "Español",
|
||||
|
||||
Reference in New Issue
Block a user