# US-MAI014-003: Evaluar desempeno (scorecard)

**ID:** US-MAI014-003
**Modulo:** MAI-014 (Carriers)
**Prioridad:** Media
**Story Points:** 5

---

## Historia de Usuario

**Como** carrier manager
**Quiero** evaluar el desempeno de los carriers con metricas objetivas
**Para** tomar decisiones de asignacion basadas en datos

---

## Criterios de Aceptacion

### CA-001: Calcular metricas automaticas
**Dado** que los carriers completan viajes
**Cuando** se cierra el periodo
**Entonces** se calculan metricas de puntualidad, incidencias, POD

### CA-002: Generar puntaje global
**Dado** que hay metricas con pesos definidos
**Cuando** se calcula el scorecard
**Entonces** se obtiene puntaje de 0-100

### CA-003: Categorizar carriers
**Dado** que hay rangos de puntaje
**Cuando** se evalua
**Entonces** se asigna categoria (A, B, C, D)

### CA-004: Comparar carriers
**Dado** que tengo multiples carriers
**Cuando** consulto el ranking
**Entonces** veo comparativo ordenado por score

### CA-005: Tomar acciones por desempeno
**Dado** que un carrier tiene mal desempeno
**Cuando** cae a categoria D
**Entonces** se notifica para revision o suspension

---

## Mockup / UI

### Scorecard de Carrier

```
+----------------------------------------------------------+
| SCORECARD - Transportes del Norte                        |
+----------------------------------------------------------+
|                                                          |
|  Periodo: Enero 2026                                    |
|  Categoria: [A] EXCELENTE                               |
|  Puntaje global: 92 / 100                               |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  DESGLOSE DE METRICAS                                   |
|                                                          |
|       Puntualidad (30%) ████████████████████ 95%       |
|       Incidencias (25%) ██████████████████ 90%         |
|         Calidad POD (15%) ███████████████████ 92%       |
|        Documentos (15%) █████████████████████ 98%      |
|             Precio (15%) ████████████████ 85%           |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  DETALLE POR METRICA                                    |
|                                                          |
|  PUNTUALIDAD (95%)                                      |
|  Viajes a tiempo: 38 de 40                             |
|  Retrasos: 2 (promedio 45 min)                         |
|                                                          |
|  INCIDENCIAS (90%)                                      |
|  Viajes sin incidencia: 36 de 40                       |
|  Incidencias reportadas: 4 (2 menores, 2 medias)       |
|                                                          |
|  CALIDAD POD (92%)                                      |
|  POD completos a tiempo: 37 de 40                      |
|  POD tardios: 3 (promedio 8 horas despues)             |
|                                                          |
|  DOCUMENTOS (98%)                                       |
|  Dias con documentos vigentes: 29 de 30                |
|  Alertas de vencimiento: 1                             |
|                                                          |
|  PRECIO (85%)                                           |
|  Tarifa promedio: $14,200                              |
|  vs Promedio mercado: +5%                              |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  EVOLUCION ULTIMOS 6 MESES                              |
|                                                          |
|  100|                                    *              |
|   90|          *     *     *     *                      |
|   80|     *                                             |
|   70|                                                   |
|     +-----+-----+-----+-----+-----+-----+              |
|      Ago   Sep   Oct   Nov   Dic   Ene                 |
|                                                          |
|  Tendencia: ESTABLE                                    |
|                                                          |
+----------------------------------------------------------+
```

### Ranking de Carriers

```
+----------------------------------------------------------+
| RANKING DE CARRIERS - Enero 2026                         |
+----------------------------------------------------------+
|                                                          |
|  [Filtrar por categoria: Todos v]  [Exportar]           |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  | # | Carrier             | Score | Cat | Viajes |Tend|
|  |---|---------------------|-------|-----|--------|----||
|  | 1 | Trans. del Norte    |  92   | [A] |   40   | =  ||
|  | 2 | Carga Segura        |  89   | [B] |   28   | ^  ||
|  | 3 | Logistica Express   |  85   | [B] |   35   | =  ||
|  | 4 | Fletes Premium      |  82   | [B] |   22   | v  ||
|  | 5 | Envios Rapidos      |  78   | [C] |   18   | v  ||
|  | 6 | Trans. Economicos   |  72   | [C] |   45   | =  ||
|  | 7 | Fletes del Bajio    |  68   | [D] |   12   | v  ||
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  ALERTAS                                                |
|                                                          |
|  [!] Fletes del Bajio: Categoria D por 2 meses         |
|      consecutivos. Revisar para suspension.            |
|                                                          |
|  [!] Fletes Premium: Tendencia a la baja. Monitorear.  |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  RESUMEN                                                |
|                                                          |
|  Total carriers activos: 7                             |
|  Score promedio: 81                                    |
|  Categoria A: 1 (14%)                                  |
|  Categoria B: 3 (43%)                                  |
|  Categoria C: 2 (29%)                                  |
|  Categoria D: 1 (14%)                                  |
|                                                          |
+----------------------------------------------------------+
```

---

## Calculo del Scorecard

| Metrica | Peso | Formula |
|---------|------|---------|
| Puntualidad | 30% | (Entregas a tiempo / Total) × 100 |
| Incidencias | 25% | 100 - (Incidencias × 2.5) |
| Calidad POD | 15% | (POD completos < 24h / Total) × 100 |
| Documentos | 15% | (Dias docs vigentes / Dias periodo) × 100 |
| Precio | 15% | 100 - (% diferencia vs mercado × 2) |

**Puntaje global:**
```
Score = (Puntualidad × 0.30) + (Incidencias × 0.25) +
        (POD × 0.15) + (Documentos × 0.15) + (Precio × 0.15)
```

---

## Notas Tecnicas

- Tabla: `carriers.evaluaciones_carrier`
- Tabla: `carriers.metricas_periodo`
- Job: `calculate-carrier-scorecard.job.ts` (mensual)
- Dashboard con Chart.js

---

## Definicion de Done

- [ ] Calculo automatico de metricas
- [ ] Generacion de puntaje global
- [ ] Categorizacion A/B/C/D
- [ ] Ranking comparativo
- [ ] Grafico de evolucion
- [ ] Alertas por mal desempeno
- [ ] Tests de calculo de scorecard