Adrian Flores Cortes 457ff6b620 docs: Add Phase 4 architecture and standards

- FLUJO-PRINCIPAL-TRANSPORTE.md: End-to-end transport workflow
  - 8 phases from OT capture to collection
  - State machine diagram
  - Actors and integrations per phase

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

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

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-27 02:31:39 -06:00

19 KiB

Raw Permalink Blame History

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

19 KiB Raw Permalink Blame History