diff --git a/docs/10-arquitectura/FLUJO-PRINCIPAL-TRANSPORTE.md b/docs/10-arquitectura/FLUJO-PRINCIPAL-TRANSPORTE.md new file mode 100644 index 0000000..81cdf9c --- /dev/null +++ b/docs/10-arquitectura/FLUJO-PRINCIPAL-TRANSPORTE.md @@ -0,0 +1,365 @@ +# Flujo Principal de Transporte - End to End + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 +**Modulos involucrados:** MAI-003 a MAI-010, MAE-016 + +--- + +## Diagrama del Flujo Principal + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ FLUJO PRINCIPAL DE TRANSPORTE │ +└─────────────────────────────────────────────────────────────────────────────────┘ + + CLIENTE COMERCIAL OPERACIONES FLOTA/MANTO ADMINISTRACION + │ │ │ │ │ + ▼ ▼ ▼ │ │ +┌───────┐ ┌──────────┐ ┌───────────┐ │ │ +│Solicita│──────────▶│ Captura │────────▶│ Planeacion│ │ │ +│Servicio│ │ OT │ │ TMS │ │ │ +└───────┘ └──────────┘ └───────────┘ │ │ + MAI-002 MAI-003 MAI-004 │ │ + │ │ │ + ▼ ▼ │ + ┌───────────────┐ ┌───────────────┐ │ + │ Asigna │────▶│ Verifica │ │ + │ Recursos │ │ Disponibilidad│ │ + └───────────────┘ └───────────────┘ │ + MAI-004 MAI-011 │ + │ │ │ + ▼ │ │ + ┌───────────────┐ │ │ + │ Despacho │◀────────────┘ │ + │ (Checklist) │ │ + └───────────────┘ │ + MAI-005 │ + │ │ + ▼ │ + ┌───────────────┐ │ + │ Tracking │ │ + │ (En Ruta) │ │ + └───────────────┘ │ + MAI-006 │ + │ │ + ▼ │ + ┌───────────────┐ │ + │ POD │ │ + │ (Entrega) │ │ + └───────────────┘ │ + MAI-007 │ + │ │ + ┌───────────────────┼───────────────────┐ │ + ▼ │ ▼ │ + ┌───────────────┐ │ ┌───────────────┐ │ + │ Incidencias │ │ │ Carta Porte │ │ + │ (Si aplica) │ │ │ (CFDI) │ │ + └───────────────┘ │ └───────────────┘ │ + MAI-008 │ MAE-016 │ + │ │ │ │ + └───────────────────┼───────────────────┘ │ + ▼ │ + ┌───────────────┐ │ + │ Cierre │ │ + │ Viaje │ │ + └───────────────┘ │ + MAI-007 │ + │ │ + ▼ ▼ + ┌───────────────┐ ┌───────────────┐ + │ Facturacion │────────────────────────▶│ Cobranza │ + │ Transporte │ │ CxC │ + └───────────────┘ └───────────────┘ + MAI-009 (heredado) + │ + ▼ + ┌───────────────┐ + │ Liquidacion │ + │ Operador │ + └───────────────┘ + MAI-010 +``` + +--- + +## Fases del Proceso + +### Fase 1: Captacion y Captura + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 1.1 | Cliente | MAI-002 | Solicita servicio | Requerimiento informal | Solicitud registrada | +| 1.2 | Comercial | MAI-003 | Captura OT | Solicitud + Datos carga | OT en status BORRADOR | +| 1.3 | Comercial | MAI-003 | Valida datos | OT | OT validada | +| 1.4 | Comercial | MAI-003 | Aplica tarifa | OT + Contrato | OT con precio | +| 1.5 | Comercial | MAI-003 | Confirma OT | OT completa | OT en status CONFIRMADA | + +**Validaciones obligatorias:** +- Cliente activo y sin bloqueo crediticio +- Tarifa vigente para el lane +- Direcciones geocodificadas +- Restricciones de carga identificadas + +--- + +### Fase 2: Planeacion + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 2.1 | Planeador | MAI-004 | Revisa OTs pendientes | Pool OTs confirmadas | Lista priorizada | +| 2.2 | Planeador | MAI-004 | Consolida carga | OTs compatibles | Embarque(s) | +| 2.3 | Planeador | MAI-004 | Consulta disponibilidad | Requerimientos | Lista unidades/operadores | +| 2.4 | Planeador | MAI-004 | Asigna recursos | Embarque + Recursos | Viaje planeado | +| 2.5 | Sistema | MAI-004 | Calcula ruta/ETA | Origen/Destino | Ruta optima | + +**Criterios de asignacion:** +- Tipo de equipo requerido (caja seca, refrigerada, etc.) +- Capacidad disponible +- Ubicacion actual del equipo +- Licencias del operador (hazmat, liquidos, etc.) +- Restricciones horarias cliente +- Costo vs rentabilidad + +--- + +### Fase 3: Despacho + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 3.1 | Operador | MAI-005 | Recibe asignacion | Viaje asignado | Notificacion app | +| 3.2 | Operador | MAI-005 | Ejecuta checklist pre-viaje | Lista verificacion | Checklist completado | +| 3.3 | Vigilancia | MAI-005 | Verifica sellos | Numeros sellos | Sellos registrados | +| 3.4 | Operador | MAI-005 | Captura evidencias carga | Fotos + Documentos | Evidencias en sistema | +| 3.5 | Operador | MAI-005 | Confirma salida | Viaje listo | Viaje DESPACHADO | + +**Checklist pre-viaje obligatorio:** +- Documentos del operador (licencia, certificaciones) +- Documentos unidad (póliza, verificación, permisos) +- Estado físico unidad (llantas, luces, frenos) +- Combustible suficiente +- GPS/telemática funcionando +- App móvil con conexión + +--- + +### Fase 4: Tracking + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 4.1 | Sistema | MAI-006 | Recibe posiciones GPS | Señal telemática | Ubicación actualizada | +| 4.2 | Sistema | MAI-006 | Detecta geocercas | Posición + Geocercas | Eventos automaticos | +| 4.3 | Sistema | MAI-006 | Calcula ETA dinámico | Posición + Tráfico | ETA actualizado | +| 4.4 | Sistema | MAI-006 | Genera alertas | Eventos + Reglas | Notificaciones | +| 4.5 | Torre Control | MAI-006 | Monitorea viajes | Dashboard tiempo real | Decisiones operativas | + +**Eventos de tracking:** +- `SALIDA_ORIGEN` - Inicio del viaje +- `LLEGADA_CARGA` - Arribo a punto de carga +- `INICIO_CARGA` - Comienza proceso carga +- `FIN_CARGA` - Termina carga +- `SALIDA_CARGA` - Sale de punto de carga +- `EN_RUTA` - En tránsito +- `LLEGADA_DESTINO` - Arribo a destino +- `INICIO_DESCARGA` - Comienza descarga +- `FIN_DESCARGA` - Termina descarga +- `ENTREGADO` - POD capturado + +--- + +### Fase 5: Entrega (POD) + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 5.1 | Operador | MAI-007 | Llega a destino | Viaje en curso | Evento LLEGADA | +| 5.2 | Operador | MAI-007 | Inicia descarga | Autorización | Evento INICIO_DESCARGA | +| 5.3 | Operador | MAI-007 | Captura POD | Firma + Fotos | Evidencia entrega | +| 5.4 | Sistema | MAI-007 | Valida POD | Datos POD | POD completo | +| 5.5 | Sistema | MAI-007 | Registra tiempos | Timestamps | Detention calculado | + +**Elementos POD obligatorios:** +- Firma del receptor (digital) +- Nombre del receptor +- Fecha/hora entrega +- Fotos de descarga +- Número de remisión/acuse +- Observaciones (si aplica) + +--- + +### Fase 6: Cierre de Viaje + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 6.1 | Sistema | MAI-007 | Consolida datos | POD + Tracking | Resumen viaje | +| 6.2 | Sistema | MAI-007 | Calcula tiempos reales | Eventos | Métricas operativas | +| 6.3 | Sistema | MAI-007 | Verifica incidencias | Viaje | Lista incidencias | +| 6.4 | Operaciones | MAI-007 | Aprueba cierre | Viaje completo | Viaje CERRADO | +| 6.5 | Sistema | MAE-016 | Genera Carta Porte | Datos viaje | CFDI timbrado | + +**Datos consolidados:** +- km reales vs planeados +- Tiempo real vs planeado +- Combustible consumido +- Gastos del viaje +- Incidencias registradas +- Performance OTIF + +--- + +### Fase 7: Facturacion + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 7.1 | Sistema | MAI-009 | Genera pre-factura | Viaje cerrado | Líneas facturables | +| 7.2 | Sistema | MAI-009 | Aplica tarifas | Contrato cliente | Montos calculados | +| 7.3 | Sistema | MAI-009 | Calcula recargos | Eventos viaje | Cargos adicionales | +| 7.4 | Facturacion | MAI-009 | Valida y ajusta | Pre-factura | Factura lista | +| 7.5 | Sistema | MAI-009 | Timbra CFDI | Factura + Carta Porte | CFDI con complemento | +| 7.6 | Sistema | MAI-009 | Envía al cliente | CFDI timbrado | Factura entregada | + +**Recargos automaticos:** +- Fuel Surcharge (por variación precio diesel) +- Detention (tiempo espera excedido) +- Accessorials (servicios adicionales) +- Demurrage (estadía en puerto) +- Stop-off charges (paradas adicionales) + +--- + +### Fase 8: Liquidacion + +| Paso | Actor | Modulo | Accion | Entrada | Salida | +|------|-------|--------|--------|---------|--------| +| 8.1 | Sistema | MAI-010 | Calcula comision | Viaje cerrado | Monto comisión | +| 8.2 | Sistema | MAI-010 | Aplica deducciones | Gastos + Anticipos | Neto a pagar | +| 8.3 | Sistema | MAI-010 | Genera liquidacion | Cálculos | Documento liquidación | +| 8.4 | Operador | MAI-010 | Acepta liquidacion | Documento | Liquidación aprobada | +| 8.5 | Tesorería | MAI-010 | Procesa pago | Liquidación | Pago realizado | + +--- + +## Estados del Viaje + +``` + ┌───────────┐ + │ │ + ┌─────│ BORRADOR │─────┐ + │ │ │ │ + │ └───────────┘ │ Cancelar + Confirmar │ │ + │ │ ▼ + │ │ ┌───────────┐ + │ │ │ CANCELADO │ + │ │ └───────────┘ + ▼ │ + ┌───────────┐ │ + │ CONFIRMADA│◀──────┘ + └───────────┘ + │ + Planear + │ + ▼ + ┌───────────┐ + │ PLANEADO │ + └───────────┘ + │ + Despachar + │ + ▼ + ┌───────────┐ + │DESPACHADO │ + └───────────┘ + │ + En ruta + │ + ▼ + ┌───────────┐ + │EN_TRANSITO│ + └───────────┘ + │ + Llegada destino + │ + ▼ + ┌───────────┐ + │EN_DESTINO │ + └───────────┘ + │ + POD capturado + │ + ▼ + ┌───────────┐ + │ ENTREGADO │ + └───────────┘ + │ + Aprobar cierre + │ + ▼ + ┌───────────┐ + │ CERRADO │ + └───────────┘ + │ + Facturar + │ + ▼ + ┌───────────┐ + │ FACTURADO │ + └───────────┘ + │ + Cobrar + │ + ▼ + ┌───────────┐ + │ COBRADO │ + └───────────┘ +``` + +--- + +## Actores del Proceso + +| Actor | Rol | Modulos principales | +|-------|-----|---------------------| +| Cliente/Shipper | Solicita servicios, recibe facturas | Portal (MAI-015) | +| Comercial/Ventas | Captura OTs, gestiona clientes | MAI-002, MAI-003 | +| Planeador | Planifica viajes, asigna recursos | MAI-004 | +| Despachador | Libera unidades, verifica checklists | MAI-005 | +| Torre de Control | Monitorea viajes en tiempo real | MAI-006 | +| Operador/Chofer | Ejecuta viajes, captura POD | App móvil | +| Facturador | Genera y timbra CFDI | MAI-009, MAE-016 | +| Liquidador | Calcula pagos a operadores | MAI-010 | +| Jefe Flota | Gestiona unidades y mantenimiento | MAI-011, MAI-013 | +| Administrador | Configura sistema, reportes | MAE-018 | + +--- + +## Integraciones en el Flujo + +| Punto del flujo | Integracion | Proposito | +|-----------------|-------------|-----------| +| Captura OT | API Geocoding | Validar direcciones | +| Planeacion | API Routing | Calcular ruta óptima | +| Despacho | GPS/Telemática | Iniciar tracking | +| Tracking | GPS/Telemática | Posiciones tiempo real | +| POD | App móvil | Captura evidencias | +| Facturacion | PAC (SAT) | Timbrado CFDI | +| Notificaciones | WhatsApp/SMS | Alertas clientes | + +--- + +## Tiempos Tipicos por Fase + +| Fase | Tiempo tipico | SLA recomendado | +|------|---------------|-----------------| +| Captura OT | 15-30 min | < 1 hora | +| Planeacion | 30-60 min | < 2 horas | +| Despacho | 30-60 min | < 1 hora | +| Tracking | Variable (viaje) | N/A | +| POD | 15-30 min | < 30 min | +| Cierre | 1-4 horas | < 24 horas | +| Facturacion | 1-2 dias | < 48 horas | +| Liquidacion | Semanal/Quincenal | Segun politica | + +--- + +*FLUJO PRINCIPAL TRANSPORTE v1.0.0 - ERP Transportistas* diff --git a/docs/30-integraciones/INTEGRACIONES-EXTERNAS.md b/docs/30-integraciones/INTEGRACIONES-EXTERNAS.md new file mode 100644 index 0000000..5bd3156 --- /dev/null +++ b/docs/30-integraciones/INTEGRACIONES-EXTERNAS.md @@ -0,0 +1,492 @@ +# Integraciones Externas - ERP Transportistas + +**Version:** 1.0.0 +**Fecha:** 2026-01-27 + +--- + +## Resumen de Integraciones + +| Categoria | Proveedor | Proposito | Prioridad | +|-----------|-----------|-----------|-----------| +| GPS/Telematica | Varios | Tracking tiempo real | P0 | +| PAC (CFDI) | Varios | Timbrado fiscal | P0 | +| Geocoding/Mapas | Google/Here/Mapbox | Rutas y direcciones | P0 | +| Mensajeria | WhatsApp/SMS | Notificaciones | P1 | +| Combustible | TAG/IAVE | Peajes automaticos | P2 | +| Bancos | SPEI/CIE | Cobranza/Pagos | P2 | + +--- + +## 1. GPS y Telematica + +### 1.1 Proposito +Recibir posiciones de unidades en tiempo real para tracking, geocercas y alertas. + +### 1.2 Proveedores Soportados + +| Proveedor | Protocolo | Frecuencia | Datos | +|-----------|-----------|------------|-------| +| Geotab | API REST | 30 seg | Posicion, velocidad, eventos motor | +| CalAmp | Push HTTP | 60 seg | Posicion, velocidad, odometro | +| Queclink | TCP/IP | 30 seg | Posicion, velocidad, bateria | +| Teltonika | TCP/IP | Variable | Posicion, sensores | +| Omnitracs | API REST | 60 seg | Posicion, HOS, mensajes | +| Samsara | Webhooks | 30 seg | Posicion, combustible, DVIR | + +### 1.3 Arquitectura de Integracion + +``` +┌──────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Unidad │────▶│ Proveedor │────▶│ ERP Backend │ +│ (GPS/AVL) │ │ Telematica │ │ (Webhook/API) │ +└──────────────┘ └─────────────────┘ └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ Redis │ + │ (Cache tiempo │ + │ real) │ + └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ PostgreSQL │ + │ + TimescaleDB │ + └─────────────────┘ +``` + +### 1.4 Modelo de Datos Recibidos + +```typescript +interface PosicionGPS { + unidad_id: string; // ID interno o IMEI + timestamp: Date; // UTC + latitud: number; // -90 a 90 + longitud: number; // -180 a 180 + velocidad_kmh: number; // km/h + rumbo: number; // 0-360 grados + odometro_km?: number; // km totales + nivel_combustible?: number; // 0-100% + motor_encendido?: boolean; + eventos?: string[]; // Alertas del dispositivo +} +``` + +### 1.5 Tabla de Mapeo Unidad-Dispositivo + +```sql +-- tracking.dispositivos_gps +CREATE TABLE tracking.dispositivos_gps ( + id UUID PRIMARY KEY, + unidad_id UUID REFERENCES fleet.unidades(id), + proveedor_id UUID REFERENCES tracking.proveedores_telematica(id), + imei VARCHAR(20) NOT NULL, + numero_serie VARCHAR(50), + modelo VARCHAR(100), + activo BOOLEAN DEFAULT true, + ultima_posicion JSONB, + ultima_comunicacion TIMESTAMPTZ, + created_at TIMESTAMPTZ DEFAULT NOW() +); +``` + +### 1.6 Procesamiento de Eventos + +| Evento | Condicion | Accion | +|--------|-----------|--------| +| GEOCERCA_ENTRADA | Posicion dentro de poligono | Registrar evento, notificar | +| GEOCERCA_SALIDA | Posicion fuera de poligono | Registrar evento, notificar | +| EXCESO_VELOCIDAD | velocidad > limite_ruta | Alerta operaciones | +| MOTOR_APAGADO | motor_encendido = false en zona no autorizada | Alerta seguridad | +| SIN_COMUNICACION | > 30 min sin posicion | Alerta torre control | + +--- + +## 2. PAC - Proveedores Autorizados de Certificacion + +### 2.1 Proposito +Timbrado de CFDI (factura electronica) con Complemento Carta Porte 3.1. + +### 2.2 Proveedores Soportados + +| PAC | Metodo | Ambiente | Notas | +|-----|--------|----------|-------| +| Finkok | SOAP/REST | Sandbox + Produccion | Recomendado | +| Facturama | REST | Sandbox + Produccion | API moderna | +| SW Sapien | SOAP | Produccion | Economico alto volumen | +| Diverza | REST | Sandbox + Produccion | Buen soporte | +| TimbradoFiscal | SOAP | Produccion | Legacy | + +### 2.3 Flujo de Timbrado + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ ERP Backend │────▶│ Generador │────▶│ PAC │ +│ (Datos factura) │ │ XML CFDI │ │ (Timbrado) │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ SAT │ + │ (Validacion) │ + └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ CFDI Timbrado │ + │ (UUID, sello) │ + └─────────────────┘ +``` + +### 2.4 Datos Carta Porte 3.1 + +```typescript +interface CartaPorte31 { + // Ubicaciones + ubicaciones: { + tipo: 'Origen' | 'Destino'; + id_ubicacion: string; + rfc_remitente_destinatario: string; + nombre: string; + domicilio: DomicilioFiscal; + fecha_hora_salida_llegada: Date; + }[]; + + // Mercancias + mercancias: { + bienes_transp: string; // Clave SAT + descripcion: string; + cantidad: number; + clave_unidad: string; + peso_kg: number; + material_peligroso?: string; // Si aplica + embalaje?: string; + }[]; + + // Autotransporte + autotransporte: { + perm_sct: string; // Permiso SCT + num_permiso_sct: string; + config_vehicular: string; // Clave SAT + placa_vm: string; + anio_modelo_vm: number; + identificador_vehicular?: string; + remolques?: { + subtipo_rem: string; + placa: string; + }[]; + }; + + // Figura transporte (operador) + figura_transporte: { + tipo_figura: string; + rfc_figura: string; + nombre_figura: string; + num_licencia: string; + domicilio?: DomicilioFiscal; + }[]; +} +``` + +### 2.5 Validaciones Pre-Timbrado + +| Validacion | Campo | Regla | +|------------|-------|-------| +| RFC valido | rfc_emisor, rfc_receptor | Formato y lista negra SAT | +| CP vigente | codigo_postal | Catalogo SAT actualizado | +| Clave SAT | bienes_transp | Catalogo c_ClaveProdServCP | +| Permiso SCT | perm_sct + num_permiso | Formato valido | +| Peso total | suma mercancias | <= capacidad unidad | +| Config vehicular | config_vehicular | Match con unidad registrada | + +--- + +## 3. Geocoding y Mapas + +### 3.1 Proposito +- Validar y geocodificar direcciones +- Calcular rutas optimas +- Estimar distancias y tiempos +- Visualizar tracking en mapa + +### 3.2 Proveedores Soportados + +| Proveedor | Servicios | Costo | Uso recomendado | +|-----------|-----------|-------|-----------------| +| Google Maps | Geocoding, Directions, Places | $$$$ | Alta precision | +| HERE | Geocoding, Routing, Traffic | $$$ | Transporte pesado | +| Mapbox | Geocoding, Directions | $$ | Alto volumen | +| OpenRouteService | Routing | $ | Optimizacion | +| OSRM | Routing local | Gratis | Self-hosted | + +### 3.3 API de Geocoding + +```typescript +interface GeocodingRequest { + direccion: string; // Texto libre + // o componentes: + calle?: string; + numero_exterior?: string; + colonia?: string; + municipio?: string; + estado?: string; + codigo_postal?: string; + pais?: string; +} + +interface GeocodingResponse { + latitud: number; + longitud: number; + direccion_formateada: string; + precision: 'ROOFTOP' | 'RANGE_INTERPOLATED' | 'GEOMETRIC_CENTER' | 'APPROXIMATE'; + componentes: { + calle: string; + numero: string; + colonia: string; + municipio: string; + estado: string; + codigo_postal: string; + pais: string; + }; +} +``` + +### 3.4 API de Routing + +```typescript +interface RoutingRequest { + origen: { lat: number; lng: number }; + destino: { lat: number; lng: number }; + waypoints?: { lat: number; lng: number }[]; + tipo_vehiculo: 'truck' | 'trailer' | 'car'; + restricciones?: { + evitar_casetas?: boolean; + evitar_autopistas?: boolean; + peso_bruto_kg?: number; + altura_m?: number; + longitud_m?: number; + materiales_peligrosos?: boolean; + }; + optimizar_por?: 'distancia' | 'tiempo' | 'costo'; +} + +interface RoutingResponse { + distancia_km: number; + duracion_minutos: number; + duracion_trafico_minutos?: number; + costo_casetas?: number; + geometria: string; // Polyline encoded + pasos: { + instruccion: string; + distancia_km: number; + duracion_min: number; + coordenadas: { lat: number; lng: number }; + }[]; +} +``` + +### 3.5 Cache de Rutas + +```sql +-- transport.cache_rutas +CREATE TABLE transport.cache_rutas ( + id UUID PRIMARY KEY, + origen_hash VARCHAR(32), -- MD5 de coordenadas + destino_hash VARCHAR(32), + tipo_vehiculo VARCHAR(20), + distancia_km DECIMAL(10,2), + duracion_minutos INTEGER, + costo_casetas DECIMAL(10,2), + geometria TEXT, + proveedor VARCHAR(50), + created_at TIMESTAMPTZ DEFAULT NOW(), + expires_at TIMESTAMPTZ, + UNIQUE(origen_hash, destino_hash, tipo_vehiculo) +); +``` + +--- + +## 4. Mensajeria (WhatsApp/SMS) + +### 4.1 Proposito +Notificaciones automaticas a clientes y operadores. + +### 4.2 Proveedores + +| Proveedor | Canal | Uso | +|-----------|-------|-----| +| Twilio | WhatsApp + SMS | Notificaciones bidireccionales | +| MessageBird | WhatsApp + SMS | Alto volumen | +| Infobip | WhatsApp + SMS | Enterprise | +| Meta Business | WhatsApp directo | Templates aprobados | + +### 4.3 Plantillas de Mensajes + +| Evento | Destinatario | Template | +|--------|--------------|----------| +| OT Confirmada | Cliente | "Su orden de transporte #{{ot_folio}} ha sido confirmada. Recoleccion: {{fecha_pickup}}" | +| Viaje en Camino | Cliente | "Su embarque esta en camino. ETA: {{eta}}. Track: {{url_tracking}}" | +| Llegada Destino | Cliente | "Unidad {{placa}} ha llegado a destino. POD pendiente." | +| Entrega Completada | Cliente | "Entrega completada. POD: {{url_pod}}. Gracias por su preferencia." | +| Asignacion Viaje | Operador | "Nuevo viaje asignado: {{origen}} -> {{destino}}. Ver detalles en app." | +| Documento por Vencer | Operador | "Su {{documento}} vence en {{dias}} dias. Favor de renovar." | + +### 4.4 Webhook Respuestas + +```typescript +interface WhatsAppWebhook { + from: string; // Numero remitente + message_id: string; + timestamp: number; + type: 'text' | 'image' | 'document' | 'location'; + text?: { body: string }; + image?: { id: string; caption?: string }; + location?: { latitude: number; longitude: number }; + context?: { + message_id: string; // Mensaje al que responde + }; +} +``` + +--- + +## 5. TAG/IAVE (Peajes) + +### 5.1 Proposito +Registro automatico de cruces de peaje para control de gastos. + +### 5.2 Integracion + +| Sistema | Metodo | Datos | +|---------|--------|-------| +| IAVE | Portal web scraping | Movimientos por TAG | +| TAG Pase | API no oficial | Movimientos y saldo | +| Televia | Portal | Movimientos | + +### 5.3 Datos de Cruce + +```typescript +interface CrucePeaje { + tag_numero: string; + plaza: string; + carril: number; + fecha_hora: Date; + monto: number; + saldo_posterior: number; + tipo_vehiculo: string; +} +``` + +### 5.4 Conciliacion + +- Vincular TAG a unidad +- Importar movimientos diarios +- Comparar vs viajes activos +- Detectar anomalias (cruces sin viaje, rutas incorrectas) + +--- + +## 6. Bancos (SPEI/CIE) + +### 6.1 Proposito +- Recepcion de pagos de clientes +- Pagos a proveedores y operadores + +### 6.2 Integraciones + +| Banco | Servicio | Uso | +|-------|----------|-----| +| BBVA | CIE | Referencias de pago | +| Santander | CIE | Referencias de pago | +| Banorte | SPEI entrada | Notificacion pagos | +| STP | SPEI salida | Pagos dispersos | + +### 6.3 Flujo CIE (Cobro) + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ ERP Backend │────▶│ Banco (API) │────▶│ Genera CIE │ +│ (Monto + Cliente)│ │ │ │ (Referencia) │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ + Pago del cliente ◀───────┘ + │ + ▼ + ┌─────────────────┐ + │ Webhook pago │ + │ recibido │ + └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ Aplicar pago │ + │ automatico │ + └─────────────────┘ +``` + +--- + +## 7. Seguridad y Autenticacion + +### 7.1 Manejo de Credenciales + +```yaml +# Variables de entorno (NO en codigo) +GPS_PROVIDER_API_KEY: "encrypted_value" +PAC_USUARIO: "encrypted_value" +PAC_PASSWORD: "encrypted_value" +PAC_CERTIFICADO: "path_to_cert.cer" +PAC_LLAVE_PRIVADA: "path_to_key.key" +GOOGLE_MAPS_API_KEY: "encrypted_value" +TWILIO_ACCOUNT_SID: "encrypted_value" +TWILIO_AUTH_TOKEN: "encrypted_value" +``` + +### 7.2 Rate Limiting + +| Servicio | Limite | Accion | +|----------|--------|--------| +| Geocoding | 1000/min | Cola y retry | +| Routing | 500/min | Cache agresivo | +| Timbrado | Sin limite | Batch nocturno | +| WhatsApp | 1000/día por numero | Templates | + +### 7.3 Fallbacks + +| Servicio primario | Fallback | Condicion | +|-------------------|----------|-----------| +| Google Maps | HERE | Error o rate limit | +| PAC Finkok | PAC Facturama | Timeout | +| Twilio WhatsApp | Twilio SMS | Template rechazado | + +--- + +## 8. Monitoreo de Integraciones + +### 8.1 Health Checks + +```typescript +interface IntegrationHealth { + servicio: string; + status: 'UP' | 'DOWN' | 'DEGRADED'; + latencia_ms: number; + ultima_verificacion: Date; + errores_ultimas_24h: number; + tasa_exito: number; +} +``` + +### 8.2 Alertas + +| Condicion | Severidad | Accion | +|-----------|-----------|--------| +| Servicio DOWN > 5 min | CRITICA | Alerta inmediata | +| Latencia > 5s | WARNING | Notificar | +| Tasa error > 10% | WARNING | Investigar | +| Credencial expira < 7 dias | INFO | Recordatorio | + +--- + +*INTEGRACIONES EXTERNAS v1.0.0 - ERP Transportistas* diff --git a/docs/40-estandares/ESPECIFICACION-KPIS.yml b/docs/40-estandares/ESPECIFICACION-KPIS.yml new file mode 100644 index 0000000..09c32c3 --- /dev/null +++ b/docs/40-estandares/ESPECIFICACION-KPIS.yml @@ -0,0 +1,633 @@ +# 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 diff --git a/docs/40-estandares/MATRIZ-RBAC-TRANSPORTISTAS.yml b/docs/40-estandares/MATRIZ-RBAC-TRANSPORTISTAS.yml new file mode 100644 index 0000000..8bf5479 --- /dev/null +++ b/docs/40-estandares/MATRIZ-RBAC-TRANSPORTISTAS.yml @@ -0,0 +1,666 @@ +# MATRIZ RBAC - ERP Transportistas +# Version: 1.0.0 +# Fecha: 2026-01-27 +# Descripcion: Roles, permisos y accesos por modulo para el giro de transporte + +--- + +# ROLES DEL SISTEMA + +roles: + # Roles Administrativos + - id: ADMIN + nombre: Administrador del Sistema + descripcion: Acceso total a todas las funcionalidades + nivel: 100 + hereda_de: [] + + - id: GERENTE_GENERAL + nombre: Gerente General + descripcion: Vision ejecutiva, dashboards, aprobaciones de alto nivel + nivel: 90 + hereda_de: [] + + # Roles Comerciales + - id: GERENTE_COMERCIAL + nombre: Gerente Comercial + descripcion: Supervision de ventas, tarifas, clientes + nivel: 70 + hereda_de: [] + + - id: EJECUTIVO_CUENTA + nombre: Ejecutivo de Cuenta + descripcion: Gestion de clientes asignados, captura OTs + nivel: 50 + hereda_de: [] + + # Roles Operativos + - id: GERENTE_OPERACIONES + nombre: Gerente de Operaciones + descripcion: Supervision total de operaciones + nivel: 70 + hereda_de: [] + + - id: PLANEADOR + nombre: Planeador TMS + descripcion: Planeacion de viajes, asignacion de recursos + nivel: 50 + hereda_de: [] + + - id: DESPACHADOR + nombre: Despachador + descripcion: Liberacion de unidades, checklists + nivel: 40 + hereda_de: [] + + - id: TORRE_CONTROL + nombre: Torre de Control + descripcion: Monitoreo en tiempo real, atencion incidencias + nivel: 50 + hereda_de: [] + + # Roles de Flota + - id: JEFE_FLOTA + nombre: Jefe de Flota + descripcion: Gestion de unidades, operadores, mantenimiento + nivel: 60 + hereda_de: [] + + - id: COORDINADOR_MANTENIMIENTO + nombre: Coordinador de Mantenimiento + descripcion: Ordenes de trabajo, talleres, refacciones + nivel: 50 + hereda_de: [] + + # Roles Administrativos/Financieros + - id: GERENTE_ADMIN + nombre: Gerente Administrativo + descripcion: Supervision de facturacion, cobranza, pagos + nivel: 70 + hereda_de: [] + + - id: FACTURADOR + nombre: Facturador + descripcion: Generacion de facturas, timbrado CFDI + nivel: 40 + hereda_de: [] + + - id: LIQUIDADOR + nombre: Liquidador + descripcion: Calculo y pago de liquidaciones a operadores + nivel: 40 + hereda_de: [] + + - id: COBRANZA + nombre: Ejecutivo de Cobranza + descripcion: Seguimiento a cuentas por cobrar + nivel: 40 + hereda_de: [] + + # Roles Externos + - id: OPERADOR + nombre: Operador/Chofer + descripcion: Acceso app movil, captura POD + nivel: 20 + hereda_de: [] + + - id: CLIENTE_PORTAL + nombre: Cliente (Portal) + descripcion: Acceso portal cliente, tracking, documentos + nivel: 10 + hereda_de: [] + + - id: CARRIER_PORTAL + nombre: Carrier (Portal) + descripcion: Acceso portal carriers, asignaciones, POD + nivel: 15 + hereda_de: [] + +--- + +# MATRIZ DE PERMISOS POR MODULO + +permisos: + # MAI-001: Fundamentos (heredado) + MAI-001: + modulo: Fundamentos (Auth, Users, Roles) + permisos: + - permiso: users.view + descripcion: Ver listado de usuarios + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, GERENTE_COMERCIAL, GERENTE_ADMIN, JEFE_FLOTA] + + - permiso: users.create + descripcion: Crear nuevos usuarios + roles: [ADMIN, GERENTE_GENERAL] + + - permiso: users.edit + descripcion: Editar usuarios + roles: [ADMIN, GERENTE_GENERAL] + + - permiso: users.delete + descripcion: Eliminar usuarios + roles: [ADMIN] + + - permiso: roles.manage + descripcion: Gestionar roles y permisos + roles: [ADMIN] + + - permiso: settings.view + descripcion: Ver configuraciones + roles: [ADMIN, GERENTE_GENERAL] + + - permiso: settings.edit + descripcion: Editar configuraciones + roles: [ADMIN] + + # MAI-002: Clientes y Tarifas + MAI-002: + modulo: Clientes y Tarifas + permisos: + - permiso: clientes.view + descripcion: Ver clientes + roles: [ADMIN, GERENTE_GENERAL, GERENTE_COMERCIAL, GERENTE_OPERACIONES, EJECUTIVO_CUENTA, PLANEADOR, FACTURADOR, COBRANZA] + + - permiso: clientes.create + descripcion: Crear clientes + roles: [ADMIN, GERENTE_COMERCIAL, EJECUTIVO_CUENTA] + + - permiso: clientes.edit + descripcion: Editar clientes + roles: [ADMIN, GERENTE_COMERCIAL, EJECUTIVO_CUENTA] + + - permiso: clientes.credito + descripcion: Gestionar credito cliente + roles: [ADMIN, GERENTE_ADMIN, GERENTE_COMERCIAL] + + - permiso: tarifas.view + descripcion: Ver tarifas + roles: [ADMIN, GERENTE_COMERCIAL, EJECUTIVO_CUENTA, FACTURADOR] + + - permiso: tarifas.create + descripcion: Crear tarifas + roles: [ADMIN, GERENTE_COMERCIAL] + + - permiso: tarifas.edit + descripcion: Editar tarifas + roles: [ADMIN, GERENTE_COMERCIAL] + + - permiso: tarifas.aprobar + descripcion: Aprobar tarifas especiales + roles: [ADMIN, GERENTE_GENERAL, GERENTE_COMERCIAL] + + # MAI-003: Ordenes de Transporte + MAI-003: + modulo: Ordenes de Transporte + permisos: + - permiso: ot.view + descripcion: Ver ordenes de transporte + roles: [ADMIN, GERENTE_GENERAL, GERENTE_COMERCIAL, GERENTE_OPERACIONES, EJECUTIVO_CUENTA, PLANEADOR, DESPACHADOR, TORRE_CONTROL, FACTURADOR] + + - permiso: ot.create + descripcion: Crear OT + roles: [ADMIN, EJECUTIVO_CUENTA, PLANEADOR, CLIENTE_PORTAL] + + - permiso: ot.edit + descripcion: Editar OT + roles: [ADMIN, EJECUTIVO_CUENTA, PLANEADOR] + + - permiso: ot.cancel + descripcion: Cancelar OT + roles: [ADMIN, GERENTE_OPERACIONES, EJECUTIVO_CUENTA] + + - permiso: ot.confirmar + descripcion: Confirmar OT + roles: [ADMIN, EJECUTIVO_CUENTA, PLANEADOR] + + - permiso: ot.view_all + descripcion: Ver OTs de todos los clientes + roles: [ADMIN, GERENTE_COMERCIAL, GERENTE_OPERACIONES, PLANEADOR] + + # MAI-004: Planeacion TMS + MAI-004: + modulo: Planeacion TMS + permisos: + - permiso: planeacion.view + descripcion: Ver planeacion + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, PLANEADOR, DESPACHADOR, TORRE_CONTROL] + + - permiso: planeacion.planear + descripcion: Planear viajes + roles: [ADMIN, GERENTE_OPERACIONES, PLANEADOR] + + - permiso: planeacion.asignar + descripcion: Asignar recursos + roles: [ADMIN, GERENTE_OPERACIONES, PLANEADOR] + + - permiso: planeacion.reasignar + descripcion: Reasignar recursos en curso + roles: [ADMIN, GERENTE_OPERACIONES, PLANEADOR] + + - permiso: planeacion.consolidar + descripcion: Consolidar carga + roles: [ADMIN, PLANEADOR] + + # MAI-005: Despacho + MAI-005: + modulo: Despacho + permisos: + - permiso: despacho.view + descripcion: Ver viajes por despachar + roles: [ADMIN, GERENTE_OPERACIONES, PLANEADOR, DESPACHADOR, JEFE_FLOTA] + + - permiso: despacho.checklist + descripcion: Ejecutar checklist + roles: [ADMIN, DESPACHADOR, OPERADOR] + + - permiso: despacho.liberar + descripcion: Liberar viaje + roles: [ADMIN, DESPACHADOR] + + - permiso: despacho.sellos + descripcion: Registrar sellos + roles: [ADMIN, DESPACHADOR] + + - permiso: despacho.evidencias + descripcion: Capturar evidencias carga + roles: [ADMIN, DESPACHADOR, OPERADOR] + + # MAI-006: Tracking + MAI-006: + modulo: Tracking + permisos: + - permiso: tracking.view + descripcion: Ver tracking tiempo real + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, PLANEADOR, DESPACHADOR, TORRE_CONTROL, CLIENTE_PORTAL] + + - permiso: tracking.eventos + descripcion: Registrar eventos manuales + roles: [ADMIN, TORRE_CONTROL, OPERADOR] + + - permiso: tracking.alertas + descripcion: Gestionar alertas + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL] + + - permiso: tracking.geocercas + descripcion: Configurar geocercas + roles: [ADMIN, GERENTE_OPERACIONES] + + - permiso: tracking.historico + descripcion: Ver historico de tracking + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL] + + # MAI-007: POD y Cierre + MAI-007: + modulo: POD y Cierre + permisos: + - permiso: pod.view + descripcion: Ver PODs + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL, FACTURADOR, CLIENTE_PORTAL] + + - permiso: pod.capturar + descripcion: Capturar POD + roles: [ADMIN, OPERADOR, CARRIER_PORTAL] + + - permiso: pod.editar + descripcion: Editar POD + roles: [ADMIN, TORRE_CONTROL] + + - permiso: cierre.ejecutar + descripcion: Cerrar viaje + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL] + + - permiso: cierre.reabrir + descripcion: Reabrir viaje cerrado + roles: [ADMIN, GERENTE_OPERACIONES] + + # MAI-008: Incidencias + MAI-008: + modulo: Incidencias + permisos: + - permiso: incidencias.view + descripcion: Ver incidencias + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, TORRE_CONTROL, CLIENTE_PORTAL] + + - permiso: incidencias.crear + descripcion: Crear incidencia + roles: [ADMIN, TORRE_CONTROL, OPERADOR, CLIENTE_PORTAL] + + - permiso: incidencias.atender + descripcion: Atender incidencia + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL] + + - permiso: incidencias.resolver + descripcion: Resolver y cerrar + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL] + + - permiso: incidencias.impacto + descripcion: Registrar impacto economico + roles: [ADMIN, GERENTE_OPERACIONES, FACTURADOR] + + # MAI-009: Facturacion Transporte + MAI-009: + modulo: Facturacion Transporte + permisos: + - permiso: facturacion.view + descripcion: Ver facturas + roles: [ADMIN, GERENTE_GENERAL, GERENTE_ADMIN, FACTURADOR, COBRANZA, CLIENTE_PORTAL] + + - permiso: facturacion.generar + descripcion: Generar factura + roles: [ADMIN, FACTURADOR] + + - permiso: facturacion.timbrar + descripcion: Timbrar CFDI + roles: [ADMIN, FACTURADOR] + + - permiso: facturacion.cancelar + descripcion: Cancelar factura + roles: [ADMIN, GERENTE_ADMIN] + + - permiso: facturacion.recargos + descripcion: Ajustar recargos + roles: [ADMIN, GERENTE_ADMIN, FACTURADOR] + + - permiso: facturacion.notas + descripcion: Generar notas de credito + roles: [ADMIN, GERENTE_ADMIN, FACTURADOR] + + # MAI-010: Liquidaciones + MAI-010: + modulo: Liquidaciones + permisos: + - permiso: liquidaciones.view + descripcion: Ver liquidaciones + roles: [ADMIN, GERENTE_ADMIN, LIQUIDADOR, OPERADOR] + + - permiso: liquidaciones.generar + descripcion: Generar liquidacion + roles: [ADMIN, LIQUIDADOR] + + - permiso: liquidaciones.aprobar + descripcion: Aprobar liquidacion + roles: [ADMIN, GERENTE_ADMIN] + + - permiso: liquidaciones.deducciones + descripcion: Aplicar deducciones + roles: [ADMIN, LIQUIDADOR] + + - permiso: liquidaciones.pagar + descripcion: Procesar pago + roles: [ADMIN, GERENTE_ADMIN] + + # MAI-011: Gestion de Flota + MAI-011: + modulo: Gestion de Flota + permisos: + - permiso: flota.view + descripcion: Ver unidades y operadores + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, JEFE_FLOTA, PLANEADOR, DESPACHADOR, COORDINADOR_MANTENIMIENTO] + + - permiso: flota.unidades.create + descripcion: Crear unidades + roles: [ADMIN, JEFE_FLOTA] + + - permiso: flota.unidades.edit + descripcion: Editar unidades + roles: [ADMIN, JEFE_FLOTA] + + - permiso: flota.operadores.create + descripcion: Crear operadores + roles: [ADMIN, JEFE_FLOTA] + + - permiso: flota.operadores.edit + descripcion: Editar operadores + roles: [ADMIN, JEFE_FLOTA] + + - permiso: flota.documentos + descripcion: Gestionar documentos + roles: [ADMIN, JEFE_FLOTA] + + - permiso: flota.bloquear + descripcion: Bloquear unidad/operador + roles: [ADMIN, JEFE_FLOTA, GERENTE_OPERACIONES] + + # MAI-012: Combustible y Gastos + MAI-012: + modulo: Combustible y Gastos + permisos: + - permiso: combustible.view + descripcion: Ver registros combustible + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, JEFE_FLOTA, LIQUIDADOR] + + - permiso: combustible.registrar + descripcion: Registrar carga + roles: [ADMIN, OPERADOR] + + - permiso: combustible.alertas + descripcion: Gestionar alertas rendimiento + roles: [ADMIN, JEFE_FLOTA] + + - permiso: gastos.view + descripcion: Ver gastos de viaje + roles: [ADMIN, GERENTE_ADMIN, LIQUIDADOR] + + - permiso: gastos.registrar + descripcion: Registrar gastos + roles: [ADMIN, OPERADOR, DESPACHADOR] + + - permiso: gastos.aprobar + descripcion: Aprobar gastos + roles: [ADMIN, GERENTE_OPERACIONES, LIQUIDADOR] + + # MAI-013: Mantenimiento Flota + MAI-013: + modulo: Mantenimiento Flota + permisos: + - permiso: mantenimiento.view + descripcion: Ver ordenes de trabajo + roles: [ADMIN, GERENTE_OPERACIONES, JEFE_FLOTA, COORDINADOR_MANTENIMIENTO, PLANEADOR] + + - permiso: mantenimiento.programar + descripcion: Programar mantenimiento + roles: [ADMIN, JEFE_FLOTA, COORDINADOR_MANTENIMIENTO] + + - permiso: mantenimiento.ejecutar + descripcion: Ejecutar OT mantenimiento + roles: [ADMIN, COORDINADOR_MANTENIMIENTO] + + - permiso: mantenimiento.cerrar + descripcion: Cerrar OT + roles: [ADMIN, COORDINADOR_MANTENIMIENTO] + + - permiso: mantenimiento.refacciones + descripcion: Gestionar refacciones + roles: [ADMIN, COORDINADOR_MANTENIMIENTO] + + # MAI-014: Carriers (Terceros) + MAI-014: + modulo: Carriers (Terceros) + permisos: + - permiso: carriers.view + descripcion: Ver carriers + roles: [ADMIN, GERENTE_OPERACIONES, PLANEADOR] + + - permiso: carriers.create + descripcion: Registrar carrier + roles: [ADMIN, GERENTE_OPERACIONES] + + - permiso: carriers.edit + descripcion: Editar carrier + roles: [ADMIN, GERENTE_OPERACIONES] + + - permiso: carriers.documentos + descripcion: Gestionar documentos + roles: [ADMIN, GERENTE_OPERACIONES] + + - permiso: carriers.asignar + descripcion: Asignar viaje a carrier + roles: [ADMIN, PLANEADOR] + + - permiso: carriers.scorecard + descripcion: Ver scorecard + roles: [ADMIN, GERENTE_OPERACIONES, CARRIER_PORTAL] + + # MAI-015: Portal Cliente + MAI-015: + modulo: Portal Cliente + permisos: + - permiso: portal.tracking + descripcion: Ver tracking + roles: [CLIENTE_PORTAL] + + - permiso: portal.documentos + descripcion: Descargar documentos + roles: [CLIENTE_PORTAL] + + - permiso: portal.ot + descripcion: Crear OT + roles: [CLIENTE_PORTAL] + + - permiso: portal.reclamaciones + descripcion: Crear reclamaciones + roles: [CLIENTE_PORTAL] + + - permiso: portal.facturas + descripcion: Ver facturas + roles: [CLIENTE_PORTAL] + + # MAE-016: Carta Porte CFDI + MAE-016: + modulo: Carta Porte CFDI + permisos: + - permiso: cartaporte.view + descripcion: Ver cartas porte + roles: [ADMIN, GERENTE_ADMIN, FACTURADOR, DESPACHADOR] + + - permiso: cartaporte.generar + descripcion: Generar carta porte + roles: [ADMIN, FACTURADOR] + + - permiso: cartaporte.timbrar + descripcion: Timbrar CFDI + roles: [ADMIN, FACTURADOR] + + - permiso: cartaporte.cancelar + descripcion: Cancelar carta porte + roles: [ADMIN, GERENTE_ADMIN] + + # MAE-017: HOS y Bitacora + MAE-017: + modulo: HOS y Bitacora + permisos: + - permiso: hos.view + descripcion: Ver registros HOS + roles: [ADMIN, GERENTE_OPERACIONES, JEFE_FLOTA, TORRE_CONTROL] + + - permiso: hos.registrar + descripcion: Registrar HOS + roles: [ADMIN, OPERADOR] + + - permiso: hos.alertas + descripcion: Gestionar alertas + roles: [ADMIN, GERENTE_OPERACIONES, TORRE_CONTROL] + + - permiso: hos.bitacora + descripcion: Generar bitacora + roles: [ADMIN, JEFE_FLOTA, OPERADOR] + + - permiso: hos.auditoria + descripcion: Auditoria compliance + roles: [ADMIN, GERENTE_OPERACIONES] + + # MAE-018: Reportes y KPIs + MAE-018: + modulo: Reportes y KPIs + permisos: + - permiso: reportes.ejecutivo + descripcion: Dashboard ejecutivo + roles: [ADMIN, GERENTE_GENERAL] + + - permiso: reportes.operaciones + descripcion: Dashboard operaciones + roles: [ADMIN, GERENTE_OPERACIONES, PLANEADOR, TORRE_CONTROL] + + - permiso: reportes.flota + descripcion: Dashboard flota + roles: [ADMIN, JEFE_FLOTA, COORDINADOR_MANTENIMIENTO] + + - permiso: reportes.financiero + descripcion: Dashboard financiero + roles: [ADMIN, GERENTE_ADMIN, FACTURADOR, COBRANZA] + + - permiso: reportes.custom + descripcion: Reportes personalizados + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, GERENTE_COMERCIAL, GERENTE_ADMIN] + + - permiso: reportes.export + descripcion: Exportar reportes + roles: [ADMIN, GERENTE_GENERAL, GERENTE_OPERACIONES, GERENTE_COMERCIAL, GERENTE_ADMIN] + +--- + +# RESTRICCIONES ESPECIALES + +restricciones: + # Operador solo ve sus propios datos + - rol: OPERADOR + restriccion: DATOS_PROPIOS + descripcion: Solo accede a sus viajes, liquidaciones, HOS + + # Cliente solo ve datos de su empresa + - rol: CLIENTE_PORTAL + restriccion: DATOS_CLIENTE + descripcion: Solo accede a OTs, tracking, facturas de su empresa + + # Ejecutivo de cuenta solo ve sus clientes asignados + - rol: EJECUTIVO_CUENTA + restriccion: CLIENTES_ASIGNADOS + descripcion: Solo accede a clientes donde es el ejecutivo asignado + + # Carrier solo ve sus asignaciones + - rol: CARRIER_PORTAL + restriccion: DATOS_CARRIER + descripcion: Solo accede a viajes asignados y su scorecard + +--- + +# ACCIONES CRITICAS (REQUIEREN AUTORIZACION) + +acciones_criticas: + - accion: Cancelar factura timbrada + roles_autorizados: [ADMIN, GERENTE_ADMIN] + requiere_motivo: true + + - accion: Reabrir viaje cerrado + roles_autorizados: [ADMIN, GERENTE_OPERACIONES] + requiere_motivo: true + + - accion: Bloquear cliente por credito + roles_autorizados: [ADMIN, GERENTE_ADMIN, GERENTE_COMERCIAL] + requiere_motivo: true + + - accion: Eliminar unidad/operador + roles_autorizados: [ADMIN] + requiere_motivo: true + soft_delete: true + + - accion: Aprobar tarifa especial bajo costo + roles_autorizados: [ADMIN, GERENTE_GENERAL, GERENTE_COMERCIAL] + requiere_motivo: true + + - accion: Ajustar liquidacion aprobada + roles_autorizados: [ADMIN, GERENTE_ADMIN] + requiere_motivo: true + +--- + +# NOTAS + +notas: + - "ADMIN tiene acceso total a todas las funcionalidades" + - "Los permisos son acumulativos segun el nivel del rol" + - "Las restricciones de datos aplican automaticamente" + - "Las acciones criticas se registran en auditoria" + - "El sistema hereda roles/permisos base de erp-core" + +# FIN MATRIZ RBAC