Plan BFF Gateway para Onboarding Flutter - MPAY

Versión: 1.0 | Fecha: Enero 2025 | Autor: Tech Lead

1. Resumen Ejecutivo

Crear un Backend for Frontend (BFF) en .NET 8.0 que actúe como proxy inteligente entre Flutter y los servicios existentes de MPAY, permitiendo:

Reutilizar 100% de la lógica existente (back-office + api-laravel)
Cero modificaciones a los sistemas actuales
Optimizar respuestas para consumo móvil
Retrocompatibilidad total con el flujo web (Next.js sigue funcionando igual)

2. Arquitectura Propuesta

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│   ┌──────────────┐          ┌──────────────┐                            │
│   │  ONBOARDING  │          │  ONBOARDING  │                            │
│   │  (Next.js)   │          │  (Flutter)   │                            │
│   └──────┬───────┘          └──────┬───────┘                            │
│          │                         │                                     │
│          │ Directo                 │                                     │
│          │                         ▼                                     │
│          │              ┌─────────────────────┐                         │
│          │              │   BFF GATEWAY       │  ← NUEVO (.NET 8.0)     │
│          │              │   Puerto: 5000      │                         │
│          │              │                     │                         │
│          │              │  • Proxy inteligente│                         │
│          │              │  • Stateless        │                         │
│          │              │  • Agregación       │                         │
│          │              │  • Transformación   │                         │
│          │              └──────────┬──────────┘                         │
│          │                         │                                     │
│          │                         │ HTTP Client                        │
│          │                         ▼                                     │
│          │     ┌───────────────────────────────────────┐                │
│          └────▶│         BACK-OFFICE (Laravel)        │◀── Sin cambios │
│                │         Puerto: 80                    │                │
│                └───────────────────┬───────────────────┘                │
│                                    │                                     │
│                          ┌─────────▼─────────┐                          │
│                          │   API-LARAVEL     │◀── Sin cambios           │
│                          │   Puerto: 8051    │                          │
│                          └───────────────────┘                          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Principios Clave

Proxy Transparente: BFF consume endpoints existentes de MPAY
Zero Changes: No se modifica back-office ni api-laravel
Stateless: Sin Redis ni estado externo - usa token de MPAY
Agregación: Un endpoint BFF puede combinar múltiples llamadas
Cache Simple: Solo IMemoryCache para datos estáticos (opcional)

3. Ubicación en el Monorepo

mpay/
├── api-laravel/          # Sin cambios
├── back-office/          # Sin cambios
├── onboarding/           # Sin cambios (Next.js)
├── database-laravel/     # Sin cambios
├── documents-ocr/        # Sin cambios
│
└── bff-onboarding/       # [NUEVO] BFF Gateway .NET 8.0
    ├── src/
    │   └── BFF.Onboarding.API/
    │       ├── Controllers/     # Auth, Flow, Config, Calculator
    │       ├── Services/        # MPayProxy
    │       ├── Models/          # DTOs Request/Response
    │       └── Middleware/      # Auth, Logging
    ├── tests/
    ├── Dockerfile
    └── kubernetes/

4. Mapeo de Endpoints BFF → MPAY

4.1 Autenticación

BFF Endpoint	Método	MPAY Endpoint	Notas
`/api/v1/auth/document`	POST	`GET /api/v1/customers/by-document`	Verificar si existe
`/api/v1/auth/register`	POST	`POST /api/v1/equifax/customers`	Crear cliente
`/api/v1/auth/send-otp`	POST	`POST /api/v1/equifax/customers/validate-phone`	Enviar código
`/api/v1/auth/verify-otp`	POST	`POST /api/v1/equifax/customers/verify-phone`	Verificar código

4.2 Flujo de Onboarding

BFF Endpoint	Método	MPAY Endpoint	Notas
`/api/v1/flow/status`	GET	`GET /customer-equifax-step` + `GET /profile`	Agregación
`/api/v1/flow/consent`	POST	`POST /api/v1/equifax/save-signature`	Proxy
`/api/v1/flow/personal-info`	POST	`POST /api/v1/equifax/save-personal-information`	Proxy
`/api/v1/flow/work-info`	POST	`POST /api/v1/equifax/save-work-information`	Proxy
`/api/v1/flow/documents`	POST	`POST /api/v1/equifax/save-documents`	Multipart
`/api/v1/flow/references`	POST	`POST /api/v1/equifax/save-references`	Proxy
`/api/v1/flow/evaluate`	POST	`POST /api/v1/equifax/process-approval`	Async
`/api/v1/flow/evaluation-result`	GET	`GET /api/v1/equifax/customer-equifax-step`	Polling
`/api/v1/flow/appeal`	POST	`POST /api/v1/equifax/save-appeal`	Multipart

4.3 Utilidades

BFF Endpoint	Método	MPAY Endpoint	Notas
`/api/v1/calculator/amortization`	GET	`GET /api/v1/equifax/amortization`	Proxy directo
`/api/v1/config/periods`	GET	`GET /api/v1/equifax/periods-active`	IMemoryCache 10min
`/api/v1/config/countries`	GET	Local	Hardcoded SV/HN

5. Capacidades del BFF

5.1 Agregación de Endpoints

GET /api/v1/flow/status (BFF)
    │
    ├──▶ GET /api/v1/equifax/customer-equifax-step (MPAY)
    ├──▶ GET /api/v1/equifax/profile (MPAY)
    └──▶ GET /api/v1/equifax/periods-active (MPAY) [condicional]

    ⬇️ Combina en una sola respuesta optimizada para Flutter

5.2 Transformación de Respuestas

MPAY Response	BFF Response
Múltiples campos anidados	Estructura plana para Flutter
Campos en snake_case	Campos en camelCase
Sin progreso	Con `progressPercentage` calculado
Estados como strings	Estados con códigos numéricos

5.3 Estrategia de Cache (Simplificada)

Dato	Estrategia
Configuración países	Hardcoded en código
Períodos disponibles	IMemoryCache 10 min (opcional)
Todo lo demás	Sin cache - proxy directo

Nota: El BFF es stateless. La autenticación usa el token de MPAY que se propaga en cada request.

6. Dependencias

Existentes (Sin Cambios)

Servicio	Uso	Estado
Back-Office (Laravel)	Toda la lógica de Equifax	✅ Sin cambios
API-Laravel	Validación de clientes	✅ Sin cambios
MySQL	BD existente	✅ Sin acceso directo

Nuevas (Mínimas)

Componente	Descripción
BFF .NET 8.0	Servicio gateway
IMemoryCache	Cache in-memory nativo de .NET (opcional)

Paquetes .NET Requeridos

<PackageReference Include="Microsoft.Extensions.Http" />
<PackageReference Include="Polly.Extensions.Http" />  <!-- Retry policies -->
<PackageReference Include="Swashbuckle.AspNetCore" /> <!-- Swagger -->

Sin Redis ni dependencias externas de estado.

7. Plan de Implementación

Fase 1: Scaffold y Autenticación

Duración: 2 días

Tareas:

Crear proyecto .NET 8.0 con estructura básica
Configurar HTTP Clients con Polly (retry/timeout)
Implementar MPayProxyService
Crear AuthController (4 endpoints)
Dockerfile y Kubernetes manifests

Entregables:

/api/v1/auth/document
/api/v1/auth/register
/api/v1/auth/send-otp
/api/v1/auth/verify-otp

Fase 2: Flujo de Onboarding

Duración: 3 días

Tareas:

Implementar FlowController (9 endpoints)
Agregación en /flow/status
Manejo de multipart para documentos y apelación
Lógica de polling para evaluación

Entregables:

/api/v1/flow/status (agregación)
/api/v1/flow/consent
/api/v1/flow/personal-info
/api/v1/flow/work-info
/api/v1/flow/documents
/api/v1/flow/references
/api/v1/flow/evaluate
/api/v1/flow/evaluation-result
/api/v1/flow/appeal

Fase 3: Utilidades y Config

Duración: 1 día

Tareas:

ConfigController (períodos hardcoded, países)
CalculatorController (proxy a amortización)
Cache opcional con IMemoryCache

Entregables:

/api/v1/calculator/amortization
/api/v1/config/periods
/api/v1/config/countries

Fase 4: Testing y Documentación

Duración: 2 días

Tareas:

Tests unitarios e integración
Documentación Swagger/OpenAPI
Postman collection
README y guía de deploy

Entregables:

Suite de tests (>80% coverage)
Swagger UI
Postman collection
Documentación

8. Cronograma

Semana 1:
├── Día 1-2: Scaffold + Auth Module
├── Día 3-4: Flow Module
└── Día 5:   Flow Module (completar)

Semana 2:
├── Día 1:   Utilidades + Config
├── Día 2-3: Testing + Documentación
└── Día 4-5: QA + Deploy staging

Total: 8-10 días laborales (con automatización AI)

9. Estimaciones con AI (Claude Code Opus 4.5)

Componente	Manual	Con AI	Ahorro
Scaffold proyecto	4h	1h	75%
Módulo Auth (4 endpoints)	8h	2h	75%
Módulo Flow (9 endpoints)	16h	4h	75%
Utilidades + Config	4h	1h	75%
Testing + Docs	8h	2h	75%
TOTAL	40h	10h	75%

10. Riesgos y Mitigaciones

Riesgo	Prob.	Impacto	Mitigación
Latencia adicional (hop extra)	Media	Bajo	Conexiones persistentes, sin cache innecesario
Cambios en endpoints MPAY	Baja	Alto	Tests de contrato, alertas
Token propagation issues	Media	Alto	Middleware robusto, logging
Timeout en evaluación crediticia	Media	Medio	Polling con retry, UI de espera

11. Ventajas del Enfoque

Técnicas

Zero MPAY Changes - No se toca código existente
Stateless - Sin Redis, sin estado externo
Simple - Solo proxy + transformación
Testeable - Fácil de probar en aislamiento

De Negocio

Time to Market - ~2 semanas de implementación
Bajo Riesgo - Sistema actual no se afecta
Rollback Fácil - Solo quitar BFF si hay problemas
Retrocompatibilidad - Web sigue funcionando igual

12. Métricas de Éxito

Métrica	Objetivo
Latencia adicional BFF	< 50ms
Disponibilidad	99.9%
Cobertura de tests	> 80%
Tiempo implementación	< 2 semanas

13. Checklist de Entrega

Pre-Deploy

Post-Deploy

Monitoreo activo
Alertas configuradas
Runbook documentado

14. Próximos Pasos

Aprobación del plan
Crear bff-onboarding/ en monorepo
Scaffold con Claude Code
Implementación por fases
QA en staging
Deploy a producción

Referencias

Documento	Ubicación
Arquitectura Equifax	`docs/EQUIFAX_ARCHITECTURE.md`
Arquitectura MPAY	`docs/ARCHITECTURE.md`
Rutas actuales	`back-office/routes/api/v1/equifax.php`
Servicios frontend	`onboarding/src/services/steps.service.ts`

Elaborado por: Tech Lead | Fecha: Enero 2025

jluisflo/PLAN_ONBOARDING_FLUTTER_BFF.md

Select an option

No results found

Select an option

No results found

Plan BFF Gateway para Onboarding Flutter - MPAY

1. Resumen Ejecutivo

2. Arquitectura Propuesta

Principios Clave

3. Ubicación en el Monorepo

4. Mapeo de Endpoints BFF → MPAY

4.1 Autenticación

4.2 Flujo de Onboarding

4.3 Utilidades

5. Capacidades del BFF

5.1 Agregación de Endpoints

5.2 Transformación de Respuestas

5.3 Estrategia de Cache (Simplificada)

6. Dependencias

Existentes (Sin Cambios)

Nuevas (Mínimas)

Paquetes .NET Requeridos

7. Plan de Implementación

Fase 1: Scaffold y Autenticación

Fase 2: Flujo de Onboarding

Fase 3: Utilidades y Config

Fase 4: Testing y Documentación

8. Cronograma

9. Estimaciones con AI (Claude Code Opus 4.5)

10. Riesgos y Mitigaciones

11. Ventajas del Enfoque

Técnicas

De Negocio

12. Métricas de Éxito

13. Checklist de Entrega

Pre-Deploy

Post-Deploy

14. Próximos Pasos

Referencias