1. Interacción en Frontend: El analista abre el modal de registro de pago en Pagos.tsx, ingresa ID de factura, monto, fecha, método y referencia.
2. Envío HTTP: Axios intercepta la petición, añade el token en la cabecera Authorization: Bearer <JWT> y envía un POST /cartera/recaudos.
3. Autenticación & Aislamiento: Flask-JWT-Extended valida la firma del token. El middleware tenant.py extrae la empresa_id del usuario autenticado.
4. Validación de Esquema: Marshmallow (PagoSchema) valida que los campos requeridos y tipos numéricos sean válidos.
5. Lógica Financiera (CarteraService): Se consulta la factura en base de datos verificando que pertenezca a la empresa_id. Se resta el monto pagado de saldo_pendiente. Si el saldo es ≤ 0, el estado de la factura cambia automáticamente a EstadoFactura.PAGADA.
6. Persistencia: SQLAlchemy persiste el nuevo registro en la tabla pagos y confirma la transacción en una sola operación atómica.
7. Respuesta: El backend retorna status 201 Created con el ID del pago generado; la interfaz en React notifica con un Toast de éxito y refresca el tablero.

Application Factory: La función create_app() en app/__init__.py inicializa dinámicamente extensiones, modelos, namespaces de RESTX y comandos CLI, permitiendo inyectar configuraciones independientes para pruebas unitarias.

Clean Architecture en IA: El módulo de IA implementa separación estricta entre capa de presentación (Controllers RESTX), Casos de Uso (Services), Acceso a Datos (Repositories) y Algoritmos de Machine Learning (ML Features).

Scoped Session de SQLAlchemy: Manejo de sesiones de base de datos thread-safe con db_session = scoped_session(sessionmaker()).

La autenticación en Deilify está basada en Flask-JWT-Extended. Al iniciar sesión exitosamente en /auth/login, se genera un token con la siguiente estructura de payload:

{
  "sub": "1",                 // ID del usuario (identity)
  "role": "ADMIN",            // Rol del usuario: "ADMIN" o "USER"
  "empresa_id": 1,            // Tenant ID al que pertenece el usuario
  "exp": 1726358400           // Tiempo de expiración (1 día por configuración)
}

En app/middleware/tenant.py, la función get_empresa_id_from_jwt() asegura que ninguna consulta acceda a información de otra empresa:

def get_empresa_id_from_jwt():
    claims = get_jwt()
    emp_id = claims.get("empresa_id")
    if emp_id is not None:
        return int(emp_id)
    # Soporte para identidad directa o fallback controlado en tests
    ...

El frontend utiliza la Context API de React con persistencia local:

• deilify_token: Almacena el JWT en localStorage (o sessionStorage si no se selecciona "Recordar").
• deilify_user: Datos del usuario en sesión (nombre, email, rol).
• deilify_company: Información básica de la empresa (nombre, NIT).
• hasRole('ADMIN'): Utilidad para verificar privilegios en vistas protegidas.

En desarrollo, el backend ejecuta Base.metadata.create_all(bind=engine) en app/__init__.py, asegurando que las tablas se creen automáticamente si no existen.

Para entornos de producción y control formal de cambios, se utiliza Alembic configurado en alembic.ini con scripts en migrations/versions/.

1. Se invoca POST /api/v1/ai/predict/<client_id>.
2. Se valida que el cliente exista y pertenezca a la empresa del token JWT.
3. Se busca el modelo marcado como is_active = True en la tabla ai_models.
4. Se carga el clasificador serializado desde el archivo .joblib mediante joblib.load().
5. Se extraen las 13 características del cliente en tiempo real a partir de sus facturas vigentes e históricas.
6. El modelo computa clf.predict_proba() para obtener la probabilidad de mora.
7. Se escala la probabilidad a un score entero entre 0 y 100.
8. Se categoriza el nivel de riesgo y se formula una recomendación accionable.
9. Se persiste el log en la tabla prediction_logs para trazabilidad y auditoría.

La función determine_target(features) clasifica al cliente con etiqueta de riesgo target = 1 si cumple cualquiera de las siguientes condiciones empíricas:

if features["facturas_vencidas"] > 0 or features["max_dias_mora"] > 30 or features["promedio_dias_pago"] > 15:
    return 1  # Cliente en mora / riesgo
return 0      # Cliente al día / bajo riesgo

Ejemplo de Dictamen Generado Automáticamente por el Backend:

"El cliente Distribuidora del Norte S.A.S. tiene un límite de crédito de $10,000,000.00 con plazo de 30 días. Actualmente posee 2 factura(s) vencida(s) con un retraso máximo de 45 días, lo cual representa un riesgo directo de mora. Históricamente presenta un promedio de demora en sus pagos de 18.5 días. Su saldo pendiente actual ($8,500,000.00) consume un porcentaje crítico de su límite de crédito (85.0%)."

• Desfase en Listado de Facturas: Facturas.tsx llama a carteraService.getDashboard() esperando encontrar un arreglo data.facturas para alimentar la tabla principal. Sin embargo, /cartera/dashboard retorna únicamente agregados estadísticos (cartera vencida, DSO y distribución por edades). Se requiere implementar GET /cartera/facturas en el backend.
• Nombre de campo en Recaudos: En Pagos.tsx el formulario envía referencia, mientras que el esquema del backend (PagoSchema) espera transaccion_id. Se recomienda mapear transaccion_id: parsed.data.referencia.
• Rutas huérfanas en Frontend: Los archivos CarteraModule.tsx, GestionCobros.tsx y Reportes.tsx son placeholders que reexportan otros componentes. No están enlazados en el menú lateral principal.

Variables del Backend (back-deilify):

FLASK_DEBUG=1
SECRET_KEY=clave-secreta-para-sesiones-flask
JWT_SECRET_KEY=clave-secreta-para-firmar-tokens-jwt
SQLALCHEMY_DATABASE_URI=sqlite:///deilify.db  # O postgresql://user:pass@host:5432/dbname

Variables del Frontend (deilify-frontend):

VITE_API_URL=http://localhost:5000
VITE_API_TIMEOUT=15000

1. Fusionar cambios de develop a main en back-deilify: Actualmente la rama main carece de los módulos de auth, usuarios y clientes que ya están terminados en develop. Se debe realizar el Merge Request para que producción coincida con el desarrollo.
2. Crear endpoint GET /cartera/facturas: Permitir al frontend listar todas las facturas de la empresa paginadas con filtros por estado (PAGADA, PENDIENTE, VENCIDA) y cliente, resolviendo el desfase en Facturas.tsx.
3. Crear endpoint GET /cartera/pagos: Exponer el historial general de recaudos de la empresa para poblar directamente la vista Pagos.tsx.
4. Alinear campo transaccion_id en Pagos.tsx: Ajustar el modal de registro de pagos para que envíe transaccion_id en lugar de referencia.

1. Implementar Módulo de Acuerdos de Pago (Refinanciación): Completar el archivo app/models/acuerdo_pago.py con tabla de acuerdos, cuotas e integración con facturas refinanciadas.
2. Exportación de Reportes Financieros: Desarrollar generador de reportes PDF y Excel en app/api/reportes para estados de cuenta de cartera y recaudos mensuales.
3. Configuración de Producción con Gunicorn & Docker: Llenar el archivo Dockerfile (actualmente en 0 bytes) y definir docker-compose.yml orquestando API, PostgreSQL y Frontend Nginx.

1. Reentrenamiento Periódico Automatizado de IA: Configurar un Celery Beat o cron job para reentrenar los modelos de mora trimestralmente a medida que ingresan nuevos recaudos.
2. Auditoría Completa de Modificaciones: Implementar middleware de logging estructurado que grabe snapshots de cambios críticos en cartera.