# Migración a Scoring Module v1

## Introducción

Este documento describe los cambios en la estructura de respuesta del **credit check** tras la migración al **scoring module v1** que integra múltiples proveedores (Indika y Experian).

## Cambios en la Respuesta

### Antes (CreditClient legacy)

```json
{
  "credit_result": {
    "status_code": 200,
    "result_operation": "Aprobado"
  }
}
```

### Después (Scoring Module v1)

```json
{
  "credit_result": {
    "status_code": 200,
    "result_operation": "Aprobado",
    "result_code": 1,
    "raw": {
      "RequestForAdmissionResult": {
        "GetAdmissionReportResult": {
          "EvaluationResult": {
            "ResultCode": 1,
            "Description": "APTO"
          }
        }
      }
    }
  }
}
```

## Nuevos Campos

### `result_code` (integer)

Código numérico del resultado del scoring que facilita la toma de decisiones programática:

| Código | Significado | Acción Recomendada |
|--------|-------------|-------------------|
| 1 | Aprobado | Continuar con el proceso de contratación |
| 2 | Revisión Manual | Análisis manual requerido (score límite o datos incompletos) |
| 3 | Denegado | No proceder con la contratación |
| 4 | Revisión Manual (con error) | Revisión manual por error en scoring |

### `raw` (object)

Respuesta completa del proveedor de scoring (Indika o Experian). Contiene:

- **Detalles completos** de la evaluación crediticia
- **Score numérico** y métricas adicionales (cuando aplica)
- **Motivos de rechazo** o alertas específicas
- **Metadatos** del proveedor utilizado

> **Importante**: La estructura de `raw` varía según el proveedor. No utilice este campo para lógica de negocio crítica; use `result_code` en su lugar.

## Compatibilidad

### Campos Existentes (No Cambian)

- `status_code`: HTTP status code (200 para éxito, 4xx/5xx para error)
- `result_operation`: Texto descriptivo ("Aprobado", "Revisión Manual", "Denegado", "Desconocido")

### Migración de Código

Si su código **solo verifica `result_operation`**, seguirá funcionando sin cambios:

```python
# ✅ Este código sigue funcionando
if credit_result["result_operation"] == "Aprobado":
    procesar_contrato()
```

Si desea aprovechar los **nuevos campos**, puede actualizar su código:

```python
# ✨ Código mejorado con result_code
result_code = credit_result.get("result_code")

if result_code == 1:
    # Aprobado automáticamente
    procesar_contrato()
elif result_code in [2, 4]:
    # Revisión manual requerida
    enviar_a_revision_manual(credit_result["raw"])
elif result_code == 3:
    # Denegado automáticamente
    rechazar_contrato()
else:
    # Fallback para código legacy sin result_code
    if credit_result["result_operation"] == "Aprobado":
        procesar_contrato()
```

## Casos de Uso del Campo `raw`

### 1. Auditoría Completa

Guardar la respuesta completa del proveedor para trazabilidad:

```python
import json

# Guardar en base de datos o logs
scoring_audit = {
    "request_id": 408,
    "timestamp": datetime.utcnow(),
    "result_code": credit_result["result_code"],
    "provider_response": credit_result["raw"]
}
db.insert("scoring_audit", scoring_audit)
```

### 2. Análisis de Métricas Avanzadas

Extraer score numérico y otros detalles (ejemplo con Indika):

```python
# Ejemplo: Extraer score numérico de Indika
try:
    raw_data = credit_result["raw"]
    evaluation = raw_data["RequestForAdmissionResult"]["GetAdmissionReportResult"]["EvaluationResult"]
    
    result_code = evaluation["ResultCode"]
    description = evaluation["Description"]
    
    # Algunos proveedores incluyen score numérico
    if "Score" in evaluation:
        numeric_score = evaluation["Score"]
        print(f"Score numérico: {numeric_score}")
    
except KeyError:
    # Estructura diferente o campo no disponible
    pass
```

### 3. Debugging de Casos Específicos

Investigar por qué un scoring fue denegado o requiere revisión:

```python
# Logging detallado para debugging
if credit_result["result_code"] == 3:
    logger.error(
        f"Scoring denegado para request_id={request_id}",
        extra={
            "raw_response": json.dumps(credit_result["raw"], indent=2),
            "result_operation": credit_result["result_operation"]
        }
    )
```

### 4. Integración con JavaScript (Frontend)

Procesar callbacks en aplicaciones frontend:

```javascript
// Procesar callback del scoring
function procesarCallback(data) {
    const creditResult = data.credit_result;
    const resultCode = creditResult.result_code;
    
    switch (resultCode) {
        case 1:
            mostrarMensaje("✅ Contrato aprobado automáticamente");
            break;
        case 2:
        case 4:
            mostrarMensaje("⚠️ Revisión manual requerida");
            // Enviar raw a sistema de revisión
            enviarARevision(creditResult.raw);
            break;
        case 3:
            mostrarMensaje("❌ Contrato denegado");
            break;
        default:
            // Fallback para sistemas legacy
            if (creditResult.result_operation === "Aprobado") {
                mostrarMensaje("✅ Contrato aprobado");
            }
    }
}
```

## Recomendaciones

### ✅ Hacer

- **Usar `result_code`** para lógica de negocio y decisiones automatizadas
- **Usar `result_operation`** para mensajes al usuario
- **Guardar `raw`** para auditoría y análisis posterior
- **Manejar casos legacy** donde `result_code` no existe (validación hacia atrás)

### ❌ Evitar

- **No usar `raw`** para lógica de negocio crítica (la estructura puede cambiar)
- **No asumir** que `raw` siempre tendrá la misma estructura (depende del proveedor)
- **No hacer parsing profundo** de `raw` sin manejo de errores (KeyError, estructura variable)

## Proveedores Soportados

El scoring module v1 integra los siguientes proveedores:

1. **Indika v1**: Proveedor principal para scoring crediticio
2. **Experian v1**: Proveedor alternativo con fallback automático

El sistema **selecciona automáticamente** el proveedor más apropiado según:
- Configuración del canal
- Tipo de cliente (particular, autónomo, empresa)
- Disponibilidad del proveedor
- Reglas de fallback configuradas

## Soporte

Para dudas o problemas relacionados con la migración:

- **Documentación técnica**: `/hers/scoring/README.md`
- **API Reference**: Swagger UI en `/apidocs/`
- **Logs de scoring**: Revisar `hers.logs` con filtro `scoring` o `RiskManagement`

---

**Versión del documento**: 1.0  
**Última actualización**: Mayo 2025  
**Aplica desde**: Scoring Module v1 (migración desde CreditClient legacy)