rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add Phase 4 architecture and standards

Browse Source 
- 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>
This commit is contained in:
Adrian Flores Cortes 2026-01-27 02:31:39 -06:00
parent ec43d9c6cd
commit 457ff6b620
4 changed files with 2156 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

365
docs/10-arquitectura/FLUJO-PRINCIPAL-TRANSPORTE.md Normal file
View File

@ -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*

492
docs/30-integraciones/INTEGRACIONES-EXTERNAS.md Normal file
View File

@ -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*

633
docs/40-estandares/ESPECIFICACION-KPIS.yml Normal file
View File

@ -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

666
docs/40-estandares/MATRIZ-RBAC-TRANSPORTISTAS.yml Normal file
View File

@ -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