Conversor de estados de cuenta bancarios
Convierte estados de cuenta bancarios en PDF a movimientos estructurados y archivos Excel/CSV, validando que lo extraído cuadre con lo que declara el documento.
No es un conversor genérico de PDF. Solo procesa estados de cuenta que superen la detección de una plantilla compatible; un archivo no reconocido se rechaza en vez de intentar "rescatar" filas.
Empezar
.\instalar.ps1 # dependencias y configuración local
.\ejecutar.ps1 # levanta los tres servicios
El segundo imprime la URL y la credencial. Detalle completo, modos y problemas comunes en EJECUTAR.md.
Qué hace
PDF ──► detección de plantilla ──► extracción ──► validación ──► XLSX + CSV
(BCP, Interbank, BBVA, Banco de (invariantes,
la Nación o genérica) reconciliación)
Bancos soportados
| Banco | Extractor | Validado con un documento real |
|---|
| BCP | bcp-coordinate-v1 | Sí |
| Interbank | interbank-savings-v1 | Sí, solo cuenta de ahorro en soles |
| Banco de la Nación | banco-nacion-v1 | Sí, solo cuenta corriente en soles |
| BBVA | bbva-account-v1 | Sí, cuenta corriente en soles y dólares, y ahorro en soles |
| Scotiabank y otros | generic-table-v1 | Respaldo: solo reconcilia si el documento trae columna de saldo |
El banco no se elige: el worker detecta la plantilla por su cuenta, así que un documento se procesa con su extractor aunque en la interfaz se marque otro. Un banco «validado» lo está con las muestras que aparecen en la tabla; otra variante de cuenta puede cambiar la plantilla, y entonces el resultado queda en NEEDS_REVIEW en vez de dar cifras equivocadas.
Una extracción no se da por buena solo porque produjo filas: tiene que pasar invariantes (totales por página, balance del documento, campos de movimiento) y las advertencias viajan en la respuesta.
Arquitectura
Tres piezas con responsabilidades separadas:
| Pieza | Tecnología | De qué es dueña |
|---|
backend/pdf-worker | Python, FastAPI, Celery | Todo lo que sabe de PDF, bancos y Excel. No conoce PostgreSQL ni S3 |
backend/api-backend | NestJS, Prisma | Autoriza, orquesta y persiste. Nunca abre un PDF |
frontend | React, Vite, TypeScript | Carga, seguimiento y descarga |
El frontend habla solo con la API; la API es lo único que habla con el worker.
Acceso
Cada persona entra con su propio usuario y contraseña. No hay registro abierto: las cuentas las crea un administrador, desde la sección Usuarios, eligiendo siempre rol y membresía.
| Rol | Rango | Qué puede hacer |
|---|
SUPER_ADMIN (Superadministrador) | 100 | Todo lo del administrador, y además eliminar o degradar administradores |
ADMIN (Administrador) | 50 | Crea cuentas de usuario y de administrador, cambia nombre, correo, contraseña y membresía, desactiva y elimina usuarios. Además procesa documentos |
MEMBER (Usuario) | 10 | Procesa documentos con las vistas y límites de su membresía |
Solo se gestionan cuentas de rango inferior; entre iguales, solo lo reversible (datos, membresía, acceso, contraseña). Un administrador no elimina ni degrada a otro; un superadministrador sí. Eliminar un usuario borra también sus documentos.
| Membresía | Vistas | Documentos guardados | Páginas por PDF |
|---|
| Básica | Solo conversión | 3 | 15 |
| Atlas | Conversión, Historial, Centro Financiero, Calendario | 20 | Sin límite |
La membresía de un usuario normal tiene fecha de vencimiento, que el administrador fija al darlo de alta y ve en cada cuenta; al vencer, la persona entra y conserva lo suyo, pero no convierte hasta que la renueven. Los administradores no vencen. Cada persona puede borrar sus documentos del historial (uno o todos), con sus archivos. Ver ADR-0017.
Roles, permisos, membresías y sus límites son catálogos en la base: crear o mejorar uno es una migración de datos, sin cambiar código. Detalles en ADR-0016 (que amplía ADR-0008).
Cuando algo pasa, la pantalla lo avisa: qué pasó, por qué, qué hacer y, si es un error, su tipo, código, referencia y hora, con el teléfono de soporte (SUPPORT_PHONE) para dictarlos.
La sesión vive en una cookie httpOnly, así que ningún script de la página puede leerla. El token es opaco y tiene fila propia en la base: revocar el acceso o cerrar sesión surte efecto en la petición siguiente, sin esperar a que caduque nada. Detalles en ADR-0005.
Persistencia
PostgreSQL es obligatorio. Ahí viven las personas, sus sesiones, el estado de los trabajos y la auditoría; los archivos van a disco tras el adaptador de almacenamiento.
Existió un modo sin base de datos que no guardaba nada. Se retiró al añadir identidad de usuarios, porque sin base no hay dónde guardar personas y quedaba sin inicio de sesión: ADR-0006 explica por qué y qué queda pendiente a cambio.
El esquema aplica minimización: no existe tabla de movimientos bancarios. Se guardan identificadores, estados, conteos y códigos, nunca los importes ni las descripciones extraídas (ADR-0002).
Y los archivos no se acumulan: cada persona conserva los documentos que permite su membresía (Básica 3, Atlas 20); al superarlo elige cuál se reemplaza —por defecto, el más antiguo— y se borra entero: PDF de origen, resultados y fila. Ver ADR-0007 y ADR-0016.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
