Confianza Vecina - Sistema de Originación de Crédito

🎯 Descripción del Proyecto

Confianza Vecina es un sistema innovador de originación de crédito que conecta a tendero y cliente a través de WhatsApp, utilizando un modelo heurístico avanzado (Micro v2) que combina la confianza del tendero con evaluación psicométrica del cliente.

🏗️ Arquitectura

El sistema está compuesto por 3 componentes desacoplados:

1. Backend (API Central): Python + FastAPI + Modelo Heurístico Micro v2
2. Frontend-POS (Simulador): HTML/CSS/JavaScript
3. Bot WhatsApp: n8n.io + Twilio

🧠 Modelo de Puntuación Micro v2

Características del Modelo:

• Tipo: Heurística determinista (no ML)
• Categorías: A, B, C, D, E
• Puntaje: 0-1 (confianza)
• Cupo máximo: $50,000
• Componentes: Feature-based + Income-proxy

Campos de Evaluación:

Del Cliente (WhatsApp):

• psych_organized: 1-5 (organización personal)
• psych_plan: 1-5 (planificación financiera)
• telefono: Número de contacto
• direccion: Dirección (opcional)
• ingresos_mensuales: Ingresos (opcional)
• trabajo: Ocupación (opcional)

Del Tendero (POS):

• know_buyer: 0-5 (tiempo que conoce al cliente)
• buy_freq: 0-5 (frecuencia de compra)
• avg_purchase: Monto promedio de compra
• distance_km: Distancia en km (opcional)
• address_verified: Verificación de dirección (opcional)

Cálculo de Categorías:

• A: ≥ 0.85 (Excelente)
• B: ≥ 0.70 (Bueno)
• C: ≥ 0.50 (Regular)
• D: ≥ 0.30 (Riesgo)
• E: < 0.30 (Alto riesgo)

🚀 Instalación y Configuración

Backend

1. Activar el entorno virtual:

# Windows
env\Scripts\activate

# Linux/Mac
source env/bin/activate

2. Instalar dependencias:

pip install -r requirements.txt

3. Ejecutar el servidor:

python main.py

El servidor estará disponible en http://localhost:8000

Frontend-POS

1. Abrir frontend-pos/index.html en un navegador web
2. El simulador se conectará automáticamente al backend local

Frontend-WhatsApp (Simulador)

1. Abrir frontend-whatsapp/index.html en un navegador web
2. Simula la experiencia del bot de WhatsApp para el cliente

📋 Estado del Proyecto

• ✅ Fase 0: Cimientos y Configuración (Completada)
• ✅ Fase 1: Backend Core (Completada)
• ✅ Fase 2: Frontends (Completada)
• ✅ Fase 3: Integración E2E (Completada)
• ✅ Fase 4: Pulido y Preparación (Completada)

🛠️ Tecnologías Utilizadas

• Backend: Python, FastAPI, Pydantic, Uvicorn, NumPy, Pandas
• Modelo: Heurística Micro v2 (determinista)
• Frontend: HTML5, CSS3, JavaScript (Vanilla)
• QR: qrcode-generator
• Despliegue: Render
• Bot: n8n.io, Twilio WhatsApp API

📝 API Endpoints

Transacciones:

• POST /transactions/initiate - Iniciar proceso de crédito
• POST /transactions/validate_token - Validar token
• GET /transactions/{token}/status - Estado de la transacción

Webhooks:

• POST /webhooks/whatsapp - Datos del cliente (nuevo modelo)
• POST /webhooks/pos - Validación del tendero (nuevo modelo)

Sistema:

• GET / - Endpoint de bienvenida
• GET /health - Health check

🎮 Demo Completa

Prueba Rápida (5 minutos)

1. Ejecutar backend: python main.py
2. Abrir Frontend-POS: frontend-pos/index.html
3. Generar QR: Hacer clic en "Generar QR"
4. Simular cliente: Abrir frontend-whatsapp/index.html
5. Completar proceso: Seguir el flujo completo

Prueba Automatizada

# Ejecutar script de prueba E2E completo
python test_e2e.py

Datos de Prueba Sugeridos

Cliente Categoría A (Excelente):

• psych_organized: 5, psych_plan: 5
• know_buyer: 5, buy_freq: 5, avg_purchase: 150000
• Resultado esperado: Categoría A, Cupo $50,000

Cliente Categoría C (Regular):

• psych_organized: 3, psych_plan: 3
• know_buyer: 3, buy_freq: 2, avg_purchase: 50000
• Resultado esperado: Categoría C, Cupo $50,000

Cliente Categoría E (Riesgo):

• psych_organized: 1, psych_plan: 1
• know_buyer: 1, buy_freq: 1, avg_purchase: 10000
• Resultado esperado: Categoría E, Cupo $2,000

📊 Ejemplos de Respuesta del Modelo

{
  "category": "B",
  "score_conf": 0.7307,
  "risk_pct": 26.93,
  "debt_capacity_pct": 0.7307,
  "cupo_estimated": 50000.0,
  "raw_cupo": 182298.22,
  "comp_feature": 19350.97,
  "comp_income": 345245.47,
  "features": {
    "f_know_buyer": 0.8,
    "f_buy_freq": 0.6,
    "f_avg_purchase": 0.8148791049769151,
    "f_psych_organized": 0.75,
    "f_psych_plan": 0.5,
    "f_distance": 0.75,
    "f_address_verified": 1.0
  },
  "clients_per_day": 5,
  "income_proxy_daily": 375000.0
}

📋 Guion de Demo

Ver DEMO_SCRIPT.md para guion completo de presentación (10-15 minutos)

📄 Licencia

Proyecto desarrollado para el Hackathon SISTETIENDA