# ESPECIFICACION DE KPIs - ERP Transportistas
# Version: 1.0.0
# Fecha: 2026-01-27
# Descripcion: Formulas de calculo, tablas fuente, periodicidad y umbrales

---

# CATEGORIAS DE KPIs

categorias:
  - id: OPERATIVOS
    nombre: KPIs Operativos
    descripcion: Miden el desempeno de las operaciones de transporte
    dashboard: Dashboard Operaciones

  - id: FLOTA
    nombre: KPIs de Flota
    descripcion: Miden disponibilidad y eficiencia de la flota
    dashboard: Dashboard Flota

  - id: FINANCIEROS
    nombre: KPIs Financieros
    descripcion: Miden rentabilidad y costos
    dashboard: Dashboard Ejecutivo / Financiero

  - id: COMBUSTIBLE
    nombre: KPIs de Combustible
    descripcion: Miden consumo y eficiencia de combustible
    dashboard: Dashboard Flota

  - id: CALIDAD
    nombre: KPIs de Calidad
    descripcion: Miden incidencias y reclamaciones
    dashboard: Dashboard Operaciones

  - id: COMPLIANCE
    nombre: KPIs de Cumplimiento
    descripcion: Miden cumplimiento normativo y documental
    dashboard: Dashboard Flota

---

# DEFINICION DE KPIs

kpis:
  # ====================================
  # KPIs OPERATIVOS
  # ====================================

  - id: KPI-OTP
    nombre: On-Time Pickup (OTP)
    categoria: OPERATIVOS
    descripcion: Porcentaje de recolecciones realizadas a tiempo
    formula:
      numerador: "COUNT(*) WHERE fecha_hora_llegada_carga <= fecha_hora_cita_carga"
      denominador: "COUNT(*) total pickups del periodo"
      resultado: "(numerador / denominador) * 100"
    tablas_fuente:
      - tracking.eventos_tracking (tipo_evento IN ('LLEGADA_CARGA'))
      - transport.ordenes_transporte (fecha_hora_cita_carga)
    dimensiones:
      - cliente_id
      - ruta_id
      - operador_id
      - carrier_id
    periodicidad: DIARIO
    actualizacion: Cada 15 minutos
    unidad: Porcentaje
    meta_default: 95
    umbrales:
      verde: ">= 95"
      amarillo: ">= 90 AND < 95"
      rojo: "< 90"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-OTD
    nombre: On-Time Delivery (OTD)
    categoria: OPERATIVOS
    descripcion: Porcentaje de entregas realizadas a tiempo
    formula:
      numerador: "COUNT(*) WHERE fecha_hora_entrega <= fecha_hora_cita_entrega"
      denominador: "COUNT(*) total entregas del periodo"
      resultado: "(numerador / denominador) * 100"
    tablas_fuente:
      - tracking.eventos_tracking (tipo_evento = 'ENTREGADO')
      - transport.ordenes_transporte (fecha_hora_cita_entrega)
    dimensiones:
      - cliente_id
      - ruta_id
      - operador_id
      - carrier_id
    periodicidad: DIARIO
    actualizacion: Cada 15 minutos
    unidad: Porcentaje
    meta_default: 95
    umbrales:
      verde: ">= 95"
      amarillo: ">= 90 AND < 95"
      rojo: "< 90"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-OTIF
    nombre: On Time In Full (OTIF)
    categoria: OPERATIVOS
    descripcion: Porcentaje de entregas a tiempo, completas y sin dano
    formula:
      numerador: "COUNT(*) WHERE on_time = true AND in_full = true AND sin_dano = true"
      denominador: "COUNT(*) total entregas del periodo"
      resultado: "(numerador / denominador) * 100"
      notas: |
        on_time = fecha_hora_entrega <= fecha_hora_cita_entrega
        in_full = cantidad_entregada >= cantidad_solicitada
        sin_dano = NOT EXISTS incidencia tipo DANO
    tablas_fuente:
      - tracking.eventos_tracking
      - transport.ordenes_transporte
      - tracking.incidencias
    dimensiones:
      - cliente_id
      - ruta_id
      - operador_id
    periodicidad: DIARIO
    actualizacion: Cada 15 minutos
    unidad: Porcentaje
    meta_default: 92
    umbrales:
      verde: ">= 92"
      amarillo: ">= 88 AND < 92"
      rojo: "< 88"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-DETENTION
    nombre: Detention Time (Tiempo de Espera)
    categoria: OPERATIVOS
    descripcion: Tiempo promedio de espera en carga/descarga
    formula:
      valor: "AVG(tiempo_real_carga_descarga - tiempo_tolerancia)"
      condicion: "WHERE tiempo_real > tiempo_tolerancia"
      resultado: "Promedio en horas"
    tablas_fuente:
      - tracking.eventos_tracking (LLEGADA_CARGA, FIN_CARGA, LLEGADA_DESTINO, FIN_DESCARGA)
      - billing.tarifas_cliente (tiempo_tolerancia)
    dimensiones:
      - cliente_id
      - ubicacion_id (origen o destino)
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Horas
    meta_default: 2.0
    umbrales:
      verde: "<= 2.0"
      amarillo: "> 2.0 AND <= 3.0"
      rojo: "> 3.0"
    tendencia:
      periodos: 12
      unidad_periodo: SEMANAS

  - id: KPI-VIAJES-DIA
    nombre: Viajes por Dia
    categoria: OPERATIVOS
    descripcion: Promedio de viajes completados por dia
    formula:
      valor: "COUNT(viajes completados) / dias del periodo"
    tablas_fuente:
      - transport.viajes (estado = 'ENTREGADO' o posterior)
    dimensiones:
      - ninguna (global)
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Numero
    meta_default: 12
    umbrales:
      verde: ">= meta"
      amarillo: ">= meta * 0.9 AND < meta"
      rojo: "< meta * 0.9"

  # ====================================
  # KPIs DE FLOTA
  # ====================================

  - id: KPI-DISPONIBILIDAD
    nombre: Disponibilidad de Flota
    categoria: FLOTA
    descripcion: Porcentaje de unidades disponibles para operar
    formula:
      numerador: "COUNT(*) WHERE estado IN ('DISPONIBLE', 'EN_VIAJE')"
      denominador: "COUNT(*) total unidades activas"
      resultado: "(numerador / denominador) * 100"
    tablas_fuente:
      - fleet.unidades (estado)
    dimensiones:
      - tipo_unidad
      - base_id
    periodicidad: TIEMPO_REAL
    actualizacion: Cada 5 minutos
    unidad: Porcentaje
    meta_default: 85
    umbrales:
      verde: ">= 85"
      amarillo: ">= 80 AND < 85"
      rojo: "< 80"
    tendencia:
      periodos: 30
      unidad_periodo: DIAS

  - id: KPI-MTBF
    nombre: Mean Time Between Failures (MTBF)
    categoria: FLOTA
    descripcion: Tiempo promedio entre fallas mecanicas
    formula:
      valor: "SUM(horas_operacion) / COUNT(fallas)"
      condicion: "WHERE tipo_ot = 'CORRECTIVO'"
    tablas_fuente:
      - fleet.unidades (horas_operacion, km_actual)
      - maintenance.ordenes_trabajo (tipo, fecha_ingreso)
    dimensiones:
      - tipo_unidad
      - modelo_marca
    periodicidad: MENSUAL
    actualizacion: Diario
    unidad: Dias
    meta_default: 30
    umbrales:
      verde: ">= 30"
      amarillo: ">= 20 AND < 30"
      rojo: "< 20"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-MTTR
    nombre: Mean Time To Repair (MTTR)
    categoria: FLOTA
    descripcion: Tiempo promedio de reparacion
    formula:
      valor: "AVG(fecha_salida - fecha_ingreso)"
      condicion: "WHERE tipo_ot = 'CORRECTIVO' AND estado = 'CERRADA'"
    tablas_fuente:
      - maintenance.ordenes_trabajo
    dimensiones:
      - tipo_unidad
      - taller_id
    periodicidad: MENSUAL
    actualizacion: Diario
    unidad: Horas
    meta_default: 24
    umbrales:
      verde: "<= 24"
      amarillo: "> 24 AND <= 48"
      rojo: "> 48"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-CUMPL-PREVENTIVO
    nombre: Cumplimiento Plan Preventivo
    categoria: FLOTA
    descripcion: Porcentaje de mantenimientos preventivos ejecutados a tiempo
    formula:
      numerador: "COUNT(*) WHERE fecha_ejecucion <= fecha_programada"
      denominador: "COUNT(*) total preventivos programados"
      resultado: "(numerador / denominador) * 100"
    tablas_fuente:
      - maintenance.plan_mantenimiento
      - maintenance.ordenes_trabajo
    dimensiones:
      - tipo_servicio
      - unidad_id
    periodicidad: MENSUAL
    actualizacion: Diario
    unidad: Porcentaje
    meta_default: 95
    umbrales:
      verde: ">= 95"
      amarillo: ">= 85 AND < 95"
      rojo: "< 85"

  # ====================================
  # KPIs FINANCIEROS
  # ====================================

  - id: KPI-MARGEN
    nombre: Margen Bruto
    categoria: FINANCIEROS
    descripcion: Margen de rentabilidad sobre ingresos
    formula:
      valor: "((ingreso_total - costo_total) / ingreso_total) * 100"
    tablas_fuente:
      - billing.facturas (monto_total)
      - fuel.gastos_viaje
      - fuel.cargas_combustible
      - maintenance.ordenes_trabajo (costo)
    dimensiones:
      - cliente_id
      - ruta_id
      - unidad_id
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Porcentaje
    meta_default: 15
    umbrales:
      verde: ">= 15"
      amarillo: ">= 12 AND < 15"
      rojo: "< 12"
    tendencia:
      periodos: 12
      unidad_periodo: MESES
    alerta_critica:
      condicion: "< 10"
      mensaje: "Margen critico - revisar costos"

  - id: KPI-COSTO-KM
    nombre: Costo por Kilometro
    categoria: FINANCIEROS
    descripcion: Costo operativo promedio por kilometro recorrido
    formula:
      valor: "SUM(costos) / SUM(km_recorridos)"
      costos_incluidos:
        - combustible
        - peajes
        - mantenimiento
        - salario_operador (prorrateado)
        - seguro (prorrateado)
    tablas_fuente:
      - fuel.cargas_combustible
      - fuel.cruces_peaje
      - fuel.gastos_viaje
      - maintenance.ordenes_trabajo
      - transport.viajes (km_real)
    dimensiones:
      - unidad_id
      - ruta_id
      - tipo_carga
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Pesos/km
    meta_default: 13.00
    umbrales:
      verde: "<= 13.00"
      amarillo: "> 13.00 AND <= 15.00"
      rojo: "> 15.00"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-COSTO-VIAJE
    nombre: Costo por Viaje
    categoria: FINANCIEROS
    descripcion: Costo total promedio por viaje
    formula:
      valor: "SUM(costos_viaje) / COUNT(viajes)"
    tablas_fuente:
      - fuel.cargas_combustible (viaje_id)
      - fuel.cruces_peaje (viaje_id)
      - fuel.gastos_viaje (viaje_id)
    dimensiones:
      - cliente_id
      - ruta_id
      - tipo_carga
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Pesos
    meta_default: null  # Varia segun ruta
    comparativo: "vs tarifa"

  # ====================================
  # KPIs DE COMBUSTIBLE
  # ====================================

  - id: KPI-KM-LITRO
    nombre: Rendimiento km/litro
    categoria: COMBUSTIBLE
    descripcion: Kilometros recorridos por litro de combustible
    formula:
      valor: "SUM(km_recorridos) / SUM(litros_cargados)"
    tablas_fuente:
      - fuel.cargas_combustible
      - fuel.control_rendimiento
      - transport.viajes (km_real)
    dimensiones:
      - unidad_id
      - operador_id
      - ruta_id
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: km/litro
    meta_default: null  # Varia segun tipo unidad
    meta_por_tipo:
      tractocamion_5ejes: 2.8
      tractocamion_6ejes: 2.5
      camion_3_5ton: 8.0
      camioneta: 10.0
    umbrales:
      verde: ">= meta_tipo * 0.95"
      amarillo: ">= meta_tipo * 0.85 AND < meta_tipo * 0.95"
      rojo: "< meta_tipo * 0.85"
    alerta_antifraude:
      condicion: "< meta_tipo * 0.70"
      mensaje: "Rendimiento anomalo - posible fuga o robo"

  - id: KPI-COSTO-COMB-INGRESO
    nombre: Costo Combustible vs Ingreso
    categoria: COMBUSTIBLE
    descripcion: Porcentaje del ingreso destinado a combustible
    formula:
      valor: "(gasto_combustible / ingreso_total) * 100"
    tablas_fuente:
      - fuel.cargas_combustible
      - billing.facturas
    dimensiones:
      - cliente_id
      - ruta_id
    periodicidad: MENSUAL
    actualizacion: Diario
    unidad: Porcentaje
    meta_default: 30
    umbrales:
      verde: "<= 30"
      amarillo: "> 30 AND <= 35"
      rojo: "> 35"

  # ====================================
  # KPIs DE CALIDAD / INCIDENCIAS
  # ====================================

  - id: KPI-INCIDENCIAS-100
    nombre: Incidencias por 100 Viajes
    categoria: CALIDAD
    descripcion: Tasa de incidencias por cada 100 viajes
    formula:
      valor: "(COUNT(incidencias) / COUNT(viajes)) * 100"
    tablas_fuente:
      - tracking.incidencias
      - transport.viajes
    dimensiones:
      - tipo_incidencia
      - cliente_id
      - operador_id
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Porcentaje
    meta_default: 3
    umbrales:
      verde: "<= 3"
      amarillo: "> 3 AND <= 5"
      rojo: "> 5"
    tendencia:
      periodos: 12
      unidad_periodo: MESES

  - id: KPI-COSTO-RECLAMOS
    nombre: Costo de Reclamos
    categoria: CALIDAD
    descripcion: Monto total de reclamos pagados
    formula:
      valor: "SUM(monto_reclamo) WHERE estado = 'PAGADO'"
    tablas_fuente:
      - tracking.incidencias
      - tracking.costos_incidencia
    dimensiones:
      - tipo_incidencia
      - cliente_id
      - responsable (operador, carrier, empresa)
    periodicidad: MENSUAL
    actualizacion: Diario
    unidad: Pesos
    meta_default: null  # Varia segun volumen
    comparativo: "vs mes anterior"

  # ====================================
  # KPIs DE COMPLIANCE
  # ====================================

  - id: KPI-CUMPL-DOCUMENTAL
    nombre: Cumplimiento Documental
    categoria: COMPLIANCE
    descripcion: Porcentaje de documentos vigentes
    formula:
      numerador: "COUNT(*) WHERE fecha_vencimiento > NOW()"
      denominador: "COUNT(*) total documentos requeridos"
      resultado: "(numerador / denominador) * 100"
    tablas_fuente:
      - fleet.documentos_unidad
      - fleet.documentos_operador
      - carriers.documentos_carrier
    dimensiones:
      - tipo_entidad (unidad, operador, carrier)
      - tipo_documento
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Porcentaje
    meta_default: 100
    umbrales:
      verde: "= 100"
      amarillo: ">= 95 AND < 100"
      rojo: "< 95"
    alerta:
      condicion: "documento vence en <= 15 dias"
      accion: "Notificar responsable"

  - id: KPI-CUMPL-HOS
    nombre: Cumplimiento HOS (Horas de Servicio)
    categoria: COMPLIANCE
    descripcion: Porcentaje de dias sin exceso de horas de servicio
    formula:
      numerador: "COUNT(dias) WHERE no_hay_exceso_hos"
      denominador: "COUNT(dias) total operados"
      resultado: "(numerador / denominador) * 100"
    tablas_fuente:
      - compliance.registros_hos
    dimensiones:
      - operador_id
    periodicidad: DIARIO
    actualizacion: Cada hora
    unidad: Porcentaje
    meta_default: 98
    umbrales:
      verde: ">= 98"
      amarillo: ">= 95 AND < 98"
      rojo: "< 95"
    alerta_critica:
      condicion: "exceso > 2 horas en un dia"
      mensaje: "Violacion HOS critica - NOM-087"

---

# VISTAS MATERIALIZADAS RECOMENDADAS

vistas_materializadas:
  - nombre: mv_kpi_diario_operativo
    descripcion: KPIs operativos calculados por dia
    columnas:
      - fecha
      - cliente_id
      - otp
      - otd
      - otif
      - detention_avg
      - viajes_completados
    actualizacion: Cada 15 minutos

  - nombre: mv_kpi_diario_financiero
    descripcion: KPIs financieros calculados por dia
    columnas:
      - fecha
      - cliente_id
      - ruta_id
      - ingreso
      - costo
      - margen
      - costo_km
    actualizacion: Cada hora

  - nombre: mv_kpi_mensual_flota
    descripcion: KPIs de flota por mes
    columnas:
      - anio_mes
      - unidad_id
      - disponibilidad_prom
      - mtbf
      - mttr
      - km_recorridos
      - km_litro
    actualizacion: Diario

  - nombre: mv_kpi_mensual_carrier
    descripcion: Scorecard de carriers por mes
    columnas:
      - anio_mes
      - carrier_id
      - otif
      - incidencias
      - costo_promedio
      - categoria (A/B/C/D)
    actualizacion: Diario

---

# JOBS DE CALCULO

jobs:
  - nombre: job_calcular_kpis_diarios
    descripcion: Calcula KPIs del dia anterior
    horario: "0 2 * * *"  # 2:00 AM diario
    kpis:
      - KPI-OTP
      - KPI-OTD
      - KPI-OTIF
      - KPI-DETENTION
      - KPI-VIAJES-DIA
      - KPI-MARGEN
      - KPI-COSTO-KM

  - nombre: job_calcular_kpis_mensuales
    descripcion: Calcula KPIs del mes anterior
    horario: "0 4 1 * *"  # 4:00 AM dia 1 de cada mes
    kpis:
      - KPI-MTBF
      - KPI-MTTR
      - KPI-CUMPL-PREVENTIVO
      - KPI-COSTO-COMB-INGRESO

  - nombre: job_actualizar_vistas
    descripcion: Refresca vistas materializadas
    horario: "*/15 * * * *"  # Cada 15 minutos
    vistas:
      - mv_kpi_diario_operativo
      - mv_kpi_diario_financiero

  - nombre: job_alertas_documentos
    descripcion: Envia alertas de documentos por vencer
    horario: "0 8 * * *"  # 8:00 AM diario
    accion: Notificar documentos que vencen en <= 15 dias

---

# NOTAS DE IMPLEMENTACION

notas:
  - "Las vistas materializadas mejoran performance en dashboards"
  - "Los jobs nocturnos evitan carga en horario operativo"
  - "Las alertas criticas generan notificacion inmediata"
  - "Los umbrales son configurables por cliente/empresa"
  - "Las tendencias usan datos historicos de 12 periodos"
  - "Las dimensiones permiten drill-down en dashboards"

# FIN ESPECIFICACION KPIs