FacturOCR

SaaS de OCR + contabilización de facturas para asesorías españolas. Los clientes suben los PDFs de sus facturas, el sistema extrae los campos fiscales (NIF, fechas, IVA, IRPF...) y los gestores los validan antes de exportar a programas contables tipo A3 Asesor.

⚠️ Este Next.js está modificado respecto a la versión estándar. Antes de tocar APIs internas, lee la guía relevante en node_modules/next/dist/docs/ o consulta AGENTS.md.

Stack

Capa	Tecnología
Frontend / Backend	Next.js 16 (App Router, Server Actions)
Lenguaje	TypeScript (strict)
Estilos	Tailwind CSS 4
ORM	Prisma 7.5 + @prisma/adapter-pg
Base de datos	PostgreSQL (Supabase)
Auth	NextAuth v5 (credentials + bcryptjs)
OCR	Gemini API (PDF e imágenes) + parser propio para XML Facturae
Storage de PDFs	Supabase Storage
Email	Resend
Deploy	Vercel
Tests	Vitest (unit) + Playwright (e2e)

Roles

• ADMIN — Pertenece a una asesoría (AdvisoryFirm). Acceso total (clientes, gestores, lotes, exportar, auditoría, ajustes).
• WORKER — Gestor de la asesoría. Solo ve los clientes que tiene asignados (WorkerClientAssignment).
• CLIENT — Cliente final. Solo sube facturas y ve las suyas.

Setup

Requisitos

• Node 20+
• Cuenta Supabase (DB + Storage)
• Clave de la API de Gemini (AI Studio) con la facturación activa.
• Cuenta Resend (opcional en dev — si falta, los emails se loguean en consola).

Instalación

git clone <repo>
cd invoice-saas
npm install
cp .env.example .env       # rellenar las variables
npx prisma migrate deploy  # aplicar migraciones a la BD
npx tsx scripts/bootstrap-admin.ts  # crear primer admin
npm run dev

Abrir http://localhost:3000 y entrar con las credenciales del admin que creó el script.

Variables de entorno

Las explica en detalle .env.example. Resumen:

Variable	Para qué
DATABASE_URL	Conexión a Postgres
AUTH_SECRET	Firma de JWTs de NextAuth
NEXTAUTH_URL	URL pública (emails, callbacks)
S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, S3_FORCE_PATH_STYLE	Storage de PDFs (Garage / S3-compatible)
GEMINI_API_KEY, GEMINI_MODEL	OCR (Gemini). Obligatoria para PDF e imágenes
OCR_CONCURRENCY	Análisis a la vez en el proceso (4 por defecto); lo demás espera en «Subida»
RESEND_API_KEY, EMAIL_FROM	Emails transaccionales
CRON_SECRET	Protege endpoints /api/cron/*

Comandos

npm run dev          # dev server (puerto 3000)
npm run build        # prisma generate + next build
npm start            # producción local

npm run lint         # ESLint
npm test             # Vitest (unit, tests/unit; sin BD, corren en el build de Docker)
npm run test:watch   # Vitest watch
npm run test:integration  # Vitest contra un Postgres de pruebas (ver abajo)
npm run test:e2e     # Playwright (tests/e2e)

# Prisma
npx prisma migrate dev      # crear y aplicar nueva migración
npx prisma migrate deploy   # aplicar migraciones existentes
npx prisma studio           # GUI de la BD

Estructura del repo

src/
├── app/                       # App Router
│   ├── (login)/               # Login, forgot/reset password
│   ├── dashboard/
│   │   ├── admin/             # Vistas de ADMIN
│   │   ├── worker/            # Vistas de WORKER (gestores)
│   │   └── client/            # Vistas de CLIENT
│   ├── api/
│   │   ├── invoices/          # CRUD facturas + procesado OCR
│   │   ├── export/            # Generación de Excel A3
│   │   ├── admin/             # Verify audit, reset demo
│   │   └── cron/              # Cron jobs (Vercel)
│   └── legal/                 # Aviso legal
├── components/                # UI reutilizable
├── lib/
│   ├── auth.ts                # Config NextAuth
│   ├── prisma.ts              # Cliente Prisma singleton
│   ├── ocr.ts                 # Tipos del OCR + parser XML Facturae
│   ├── ocrLlm.ts              # Extracción con Gemini (PDF e imágenes)
│   ├── processInvoice.ts      # Orquesta OCR → BD + pre-fill
│   ├── auditLog.ts            # Cadena de hash SHA-256
│   ├── exportFormats.ts       # Generador Excel A3
│   ├── reviewQueue.ts         # Cola "siguiente factura"
│   ├── validators.ts          # parseTaxId, retentions, etc.
│   ├── invoiceStatuses.ts     # Estados canonicos del flujo
│   ├── boundingBoxes.ts       # Resaltado OCR en visor PDF
│   ├── demoSeed.ts            # Reset demo
│   ├── email.ts               # Plantillas Resend
│   ├── rateLimit.ts           # Limit en memoria (login)
│   └── supabase.ts            # Cliente Storage admin
├── hooks/                     # React hooks
└── types/                     # Tipos compartidos

prisma/
├── schema.prisma              # Modelo de datos
└── migrations/                # Migraciones SQL

scripts/                       # Scripts operacionales (bootstrap admin,
                                # seed demo, capturar screenshots...)

tests/
├── unit/                      # Vitest, sin BD (barrera del build)
├── integration/               # Vitest contra Postgres de pruebas
└── e2e/                       # Playwright

Tests de integración

Van contra un Postgres de pruebas, nunca contra el de DATABASE_URL (en local, Supabase): la URL sale solo de TEST_DATABASE_URL. Cada test la vacía, así que tiene que ser una base de datos vacía la primera vez y con nombre de pruebas (facturocr_test); si no, el harness no arranca.

# Postgres local con Docker (o createdb facturocr_test en uno instalado)
docker run -d --name facturocr-test -p 55432:5432 \
  -e POSTGRES_PASSWORD=test -e POSTGRES_DB=facturocr_test postgres:16

export TEST_DATABASE_URL=postgresql://postgres:[email protected]:55432/facturocr_test
npm run test:integration   # aplica las migraciones y ejecuta tests/integration

This is the beginning of the README. Read the rest at the original. Read the full README ↗