Generación de Deuda

El sistema de gestión de deuda es un mecanismo automatizado que evalúa y procesa la responsabilidad financiera de los usuarios cuando no recogen sus pedidos. El sistema aplica reglas específicas para determinar si se debe generar deuda, cancelar deuda existente, o aplicar compensaciones automáticas basándose en el historial del usuario.

Funcionalidad Principal

1. Evaluación de Deuda (evaluate_debt)

Propósito

Evalúa si un usuario frecuente puede tener su deuda cancelada después de un pedido no completado, basándose en su historial de compras de los últimos 3 meses

Condiciones Previas Obligatorias

Regla 1: Status del Pedido

Condición: order.status = "4" (UNFULFILLED_BY_USER)
Propósito: Solo evalúa pedidos donde la responsabilidad es del usuario

Regla 2: Tipo de Pago

Condición: order.payment_type = "1" (Efectivo/Tarjeta Diferida)
Propósito: Solo aplica a pagos que pueden generar deuda

Regla 3: Usuario Recurrente

Condición: is_first_order = False
Propósito: Usuarios nuevos no califican para evaluación de deuda

Regla 4: Costo Real del Pedido

Condición: order.cost > 0
Propósito: Pedidos pagados 100% con promos/créditos no generan deuda

Lógica de Evaluación Histórica

Período de Análisis:

• Ventana temporal: Últimos 3 meses desde updated_at
• Órdenes consideradas: Solo status "1" (COMPLETED)
• Métrica: Suma total del campo cost de órdenes completadas

Cálculo de Elegibilidad:

Fórmula: (order.cost / sum_completed_orders_3_months) * 100

Ejemplo:
- Pedido actual: $100
- Total completados 3 meses: $2000
- Resultado: (100 / 2000) * 100 = 5%

Criterios de Decisión

Caso 1: Sin Órdenes Históricas

Condición: sum_completed_orders = null
Resultado: return False (no cancela deuda)
Razón: Sin historial para evaluar frecuencia

Caso 2: Porcentaje ≤ 10%

Condición: (costo_actual / suma_3_meses) * 100 ≤ 10
Resultado: return True (cancela deuda)
Interpretación: Pedido representa ≤10% del gasto habitual

Caso 3: Porcentaje > 10%

Condición: (costo_actual / suma_3_meses) * 100 > 10
Resultado: return False (mantiene deuda)
Interpretación: Pedido es significativo vs patrón de gasto

2. Generación de Deuda (generate_debt)

Propósito

Procesa la deuda de un usuario después de un pedido no completado, aplicando lógica de cancelación, generación o compensación automática.

Flujo de Procesamiento

Validación Inicial:

Verificación: unfulfilled_order es instancia de UnfulfilledOrder
Condición de salida rápida: is_first_order = True → return False
Razón: Usuarios nuevos no generan deuda en primer pedido

Escenario 1: Evaluación Positiva (Cancelación de Deuda)

Condición: evaluate_debt() retorna True

Proceso de Cancelación:
1. current_debt = self.debt (obtiene deuda actual)
2. remove_debt(amount=current_debt, source=FORGIVEN_DEBT)
3. send_push_notification_for_cancel_debt()

Resultado:
- Deuda existente se cancela completamente
- Usuario recibe notificación de perdón de deuda
- return False (no se genera nueva deuda)

Escenario 2: Generación de Deuda

Condición: evaluate_debt() retorna False

Paso 1: Creación de Deuda

Cálculo: new_debt = current_debt + unfulfilled_order.cost
Registro: add_debt(amount=new_debt, source=UNFULFILLED_ORDER)

Paso 2: Compensación Automática con Créditos

Condición: current_credits > 0 AND debt > 0

Lógica de Compensación:
├── debt_to_remove = min(current_credits, current_debt)
├── remove_debt(amount=debt_to_remove, source=AUTO_CREDITS_COLLECTED)
├── remove_credits(amount=debt_to_remove, source=AUTO_CREDITS_COLLECTED)
└── send_notification_for_debt_charge_with_credits()

Escenarios:
• Créditos >= Deuda: Deuda se paga completamente
• Créditos < Deuda: Deuda se reduce parcialmente

Paso 3: Registro de Eventos

Condición: current_balance > 0 (queda deuda pendiente)

Acción: register_event_drip_order(
  action=ORDER_UNFULFILLED_BY_USER,
  debtlogs=debtlogs
)
Propósito: Marketing automation para seguimiento

4. Países Donde Se Aplica el Flujo de Deuda

Confirmados por Análisis del Código:

1. MÉXICO (MX):

• ✅ update_unfulfilled.py (global)

• ✅ update_unfulfilled_every_6hours.py (específico MX)

• ✅ APIs de usuario y admin

1. CHILE (CL):

• ✅ update_unfulfilled.py (global)

• ✅ APIs de usuario y admin

• ❌ cencosud_unfulfilled.py NO usa generate_debt

1. ARGENTINA (AR):

• ✅ update_unfulfilled.py (global)

• ✅ APIs de usuario y admin

• ❌ cencosud_unfulfilled.py NO usa generate_debt

1. OTROS PAÍSES:

• ✅ Cualquier país donde opere Cheaf a través del comando global update_unfulfilled.py

Impacto en el Negocio

Beneficios del Sistema

Gestión Inteligente de Riesgo

• Usuarios frecuentes: Perdón automático para clientes leales
• Patrones de gasto: Considera contexto histórico vs pedido puntual
• Compensación automática: Usa créditos disponibles para saldar deudas

Experiencia del Usuario

• Flexibilidad: Perdón de deuda para usuarios regulares
• Transparencia: Notificaciones sobre todos los movimientos
• Automatización: Sin intervención manual requerida

Casos de Uso Típicos

Escenario A: Usuario Frecuente - Pedido Pequeño

Contexto: Usuario gasta $2000/mes, no recoge pedido de $150
Cálculo: (150/6000) * 100 = 2.5% ≤ 10%
Resultado: Deuda cancelada, usuario mantiene buena experiencia

Escenario B: Usuario Regular - Pedido Significativo

Contexto: Usuario gasta $500/mes, no recoge pedido de $200
Cálculo: (200/1500) * 100 = 13.3% > 10%
Resultado: Deuda generada, pero compensada con créditos disponibles

Escenario C: Usuario Nuevo

Contexto: Primer pedido no recogido
Resultado: No genera deuda (beneficio de la duda)

Reglas de Negocio Específicas

Filosofía de Gestión

• Cliente nuevo: Beneficio de la duda en primer pedido
• Cliente frecuente: Tolerancia basada en historial
• Compensación justa: Uso automático de créditos disponibles

Umbrales y Parámetros

• Período histórico: 3 meses exactos
• Umbral de perdón: 10% del gasto histórico
• Prioridad de pago: Créditos disponibles antes que deuda pendiente

Tipos de Fuente (Source) para Logs

• FORGIVEN_DEBT: Deuda perdonada por evaluación positiva
• UNFULFILLED_ORDER: Deuda generada por pedido no recogido
• AUTO_CREDITS_COLLECTED: Compensación automática con créditos

Consideraciones Técnicas

Transaccionalidad

• Operaciones atómicas: Uso de transaction.atomic() para consistencia
• Rollback automático: En caso de error, se revierten todos los cambios
• Logging detallado: Registro de cada paso para auditoría

Manejo de Errores

• Validación de tipos: Verificación de instancia UnfulfilledOrder
• Captura de excepciones: Logging de errores sin detener el proceso
• Estados consistentes: Garantía de integridad de datos

Dependencias del Sistema

• Modelos: CreditsLogs, DebtLogs, Order, UnfulfilledOrder
• Servicios: Sistema de notificaciones push
• Eventos: Marketing automation para seguimiento

Métricas y Seguimiento

Indicadores de Gestión

• Tasa de perdón de deuda: % de evaluaciones positivas
• Compensación automática: Monto de créditos utilizados
• Deuda generada neta: Deuda final después de compensaciones
• Distribución por usuario: Nuevos vs frecuentes vs regulares

Eventos Registrados

• Perdón de deuda: Cancelación por evaluación positiva
• Generación de deuda: Nueva deuda por pedido no recogido
• Compensación automática: Uso de créditos para pago
• Marketing events: Para seguimiento de usuarios con deuda

Impacto en Otros Sistemas

Integración con Comandos de Resolución

• update_unfulfilled: Utiliza generate_debt() para pagos con crédito
• cencosud_unfulfilled: No utiliza este sistema (manejo directo)
• update_unfulfilled_every_6hours: No implementa gestión de deuda

Flujo de Notificaciones

• Perdón de deuda: Notificación positiva al usuario
• Cargo con créditos: Notificación informativa sobre uso automático
• Deuda pendiente: Registro para seguimiento de marketing

Esta gestión inteligente de deuda balancea la experiencia del usuario con la protección del negocio, aplicando reglas justas basadas en el comportamiento histórico y proporcionando compensaciones automáticas cuando es apropiado.