erp-transportistas-v2/docs/40-estandares/ESPECIFICACION-KPIS.yml
Adrian Flores Cortes 457ff6b620 docs: Add Phase 4 architecture and standards
- FLUJO-PRINCIPAL-TRANSPORTE.md: End-to-end transport workflow
  - 8 phases from OT capture to collection
  - State machine diagram
  - Actors and integrations per phase

- INTEGRACIONES-EXTERNAS.md: External integrations spec
  - GPS/Telematics (Geotab, CalAmp, Samsara, etc.)
  - PAC CFDI (Finkok, Facturama) with Carta Porte 3.1
  - Geocoding/Routing (Google, HERE, Mapbox)
  - WhatsApp/SMS notifications
  - TAG/IAVE toll integration
  - Banking (SPEI/CIE)

- MATRIZ-RBAC-TRANSPORTISTAS.yml: 16 roles with permissions
  - Permissions per module (MAI-001 to MAE-018)
  - Data restrictions per role
  - Critical actions requiring authorization

- ESPECIFICACION-KPIS.yml: 17 KPIs defined
  - Formulas, source tables, thresholds
  - Operational, fleet, financial, fuel, quality, compliance
  - Materialized views and calculation jobs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 02:31:39 -06:00

634 lines
17 KiB
YAML

# 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