# REQUERIMIENTOS - MAE-018: Reportes y KPIs

**Modulo:** MAE-018
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 6
**Version:** 1.0.0

---

## Requerimientos Funcionales

### RF-6.1: KPIs Operativos

**KPI 1: On-Time Pickup (OTP)**
- Formula: (Pickups a tiempo / Total pickups) × 100
- Meta tipica: >= 95%
- Dimension: Por cliente, ruta, operador

**KPI 2: On-Time Delivery (OTD)**
- Formula: (Entregas a tiempo / Total entregas) × 100
- Meta tipica: >= 95%
- Dimension: Por cliente, ruta, operador

**KPI 3: OTIF (On Time In Full)**
- Formula: (Entregas a tiempo Y completas / Total) × 100
- Meta tipica: >= 92%
- Considera: Tiempo + cantidad correcta + sin dano

**KPI 4: Detention Time**
- Formula: Tiempo en carga/descarga - Tiempo tolerancia
- Meta tipica: <= 2 horas promedio
- Impacto: Costos adicionales

**Tablas fuente:**
- `transport.viajes`
- `tracking.eventos_tracking`

---

### RF-6.2: KPIs de Costos y Rentabilidad

**KPI 5: Costo por Kilometro**
- Formula: Costo total viaje / km recorridos
- Incluye: Combustible + peajes + viaticos + mantenimiento
- Dimension: Por unidad, ruta, cliente

**KPI 6: Costo por Viaje**
- Formula: Suma de todos los costos del viaje
- Desglose: Fijos + variables

**KPI 7: Margen por Cliente/Ruta**
- Formula: (Ingreso - Costo) / Ingreso × 100
- Meta tipica: >= 15%
- Alerta: Si < 10%

**Tablas fuente:**
- `fuel.cargas_combustible`
- `fuel.cruces_peaje`
- `fuel.gastos_viaje`
- `billing.facturas`

---

### RF-6.3: KPIs de Flota

**KPI 8: Disponibilidad de Flota**
- Formula: (Unidades disponibles / Total unidades) × 100
- Excluye: En taller, bloqueadas
- Meta tipica: >= 85%

**KPI 9: MTBF (Mean Time Between Failures)**
- Formula: Tiempo total operacion / Numero de fallas
- Dimension: Por tipo de unidad

**KPI 10: MTTR (Mean Time To Repair)**
- Formula: Tiempo total reparacion / Numero de OTs
- Meta tipica: <= 24 horas

**Tablas fuente:**
- `fleet.unidades`
- `maintenance.ordenes_trabajo`

---

### RF-6.4: KPIs de Combustible

**KPI: Rendimiento km/litro**
- Formula: km recorridos / litros consumidos
- Dimension: Por unidad, operador
- Comparar vs esperado

**KPI: Costo Combustible / Ingreso**
- Formula: (Gasto combustible / Ingreso) × 100
- Meta tipica: <= 30%

**Tablas fuente:**
- `fuel.cargas_combustible`
- `fuel.control_rendimiento`

---

### RF-6.5: KPIs de Incidencias

**KPI: Incidencias por 100 viajes**
- Formula: (Incidencias / Viajes) × 100
- Dimension: Por tipo, cliente, operador
- Meta tipica: <= 3%

**KPI: Costo de Reclamos**
- Formula: Suma de costos por incidencias
- Dimension: Por periodo, cliente

**Tablas fuente:**
- `tracking.incidencias`
- `tracking.costos_incidencia`

---

### RF-6.6: KPIs de Cumplimiento

**KPI: Cumplimiento Documental**
- Formula: (Docs vigentes / Docs requeridos) × 100
- Aplica a: Unidades, operadores, carriers
- Meta: 100%

**KPI: Cumplimiento HOS**
- Formula: (Dias sin exceso / Dias totales) × 100
- Meta: >= 98%

**Tablas fuente:**
- `fleet.documentos_unidad`
- `compliance.registros_hos`

---

## Dashboards Requeridos

### Dashboard Ejecutivo
- KPIs principales con semaforo
- Tendencias (ultimos 12 meses)
- Top/Bottom performers
- Alertas activas

### Dashboard Operaciones
- Viajes en curso
- OTIF del dia/semana/mes
- Incidencias pendientes
- Detention acumulado

### Dashboard Flota
- Disponibilidad actual
- Unidades en taller
- Proximos mantenimientos
- Documentos por vencer

### Dashboard Financiero
- Ingresos vs Costos
- Margen por cliente
- Cuentas por cobrar
- Rentabilidad por ruta

---

## Requerimientos No Funcionales

### RNF-001: Performance
- Dashboards cargan < 5 segundos
- Precalculo de metricas (vistas materializadas)

### RNF-002: Exportacion
- Excel, PDF, CSV
- Programacion de envio automatico

### RNF-003: Personalizacion
- Filtros por periodo, cliente, ruta
- Dashboards personalizables por usuario

---

## Matriz de Trazabilidad

| RF | KPIs | Historias |
|----|------|-----------|
| RF-6.1 | OTP, OTD, OTIF, Detention | US-MAE018-002 |
| RF-6.2 | Costo/km, Margen | US-MAE018-001 |
| RF-6.3 | Disponibilidad, MTBF, MTTR | US-MAE018-002 |
| RF-6.4 | km/litro, Costo comb. | US-MAE018-002 |
| RF-6.5 | Incidencias/100 | US-MAE018-002 |
| RF-6.6 | Cumplimiento doc, HOS | US-MAE018-002 |

---

*REQUERIMIENTOS MAE-018 - ERP Transportistas v1.0.0*