RF15: Sistema registra datos de cuentas bancarias
Descripción
El sistema registra y sincroniza los datos de las cuentas bancarias conectadas (número de cuenta, saldo, institución) y sus movimientos, para alimentar el dashboard y el análisis financiero.
Es un proceso desencadenado por la conexión (RF14) y por sincronizaciones periódicas. Los campos críticos (account_number, balance, amount, merchant) se persisten con cifrado de campo AES-256-GCM con clave por usuario (Cifrado §4.2).
| Campo | Valor |
|---|---|
| Módulo | Finance Data Collection (FDC) Module |
| Actor | Sistema (job de sincronización) / Agregador bancario |
| Endpoint | Interno: worker de sincronización + webhook del agregador |
| Precondiciones | Existe una conexión bancaria activa con token válido |
| Prioridad | Alta (MVP) |
| Etapa | MBI |
| Requisitos relacionados | RF14, RF12, RF18, RF19 |
Reglas de negocio
- RN-15.1 — Cada cuenta y movimiento se asocia al
user_iddueño de la conexión. - RN-15.2 — Los movimientos se deduplican por identificador externo del proveedor (idempotencia ante reprocesos).
- RN-15.3 —
account_number,balance,amount,merchant,descriptionse cifran a nivel de campo. - RN-15.4 — Si el token está expirado/revocado, el job marca la conexión como "requiere reconexión" y no falla en cascada.
- RN-15.5 — Los movimientos importados se clasifican (categoría) para el análisis posterior (insumo de IA).
Validaciones de entrada
| Campo | Reglas | Comportamiento |
|---|---|---|
externalAccountId | Obligatorio. | Clave para upsert de cuenta. |
externalTxId | Obligatorio. | Deduplicación de movimientos. |
amount | Numérico, 2 decimales. | Se cifra; signo según ingreso/gasto. |
currency | ISO 4217 (default MXN). | Se valida contra catálogo. |
El payload del webhook se valida (firma del proveedor) antes de procesarlo; inserciones parametrizadas, sin inyección SQL.
Criterios de aceptación
Escenario 1: Sincronización inicial exitosa
Dado que se acaba de crear una conexión bancaria activa, Cuando corre la sincronización, Entonces el sistema registra las cuentas con saldo y los movimientos disponibles, Y cifra los campos sensibles, Y los movimientos quedan disponibles en el dashboard.
Escenario 2: Movimientos duplicados
Dado que un movimiento ya fue importado (mismo externalTxId),
Cuando vuelve a llegar en una sincronización,
Entonces el sistema no lo duplica (upsert idempotente).
Escenario 3: Token expirado durante la sincronización
Dado que el token bancario expiró, Cuando el job intenta sincronizar, Entonces marca la conexión como "requiere reconexión", Y notifica al usuario sin romper el resto de sus datos.
Escenario 4: Webhook con firma inválida (seguridad)
Dado que llega un webhook del agregador con firma inválida, Cuando el sistema lo recibe, Entonces lo rechaza sin procesar el payload.
Criterios no funcionales
- Campos financieros cifrados a nivel de columna.
- El job es reanudable e idempotente.
- Comunicación TLS 1.2+; tokens nunca en logs.