erp-transportistas-v2/docs/02-definicion-modulos/MAI-005-despacho/README.md

MAI-005: Despacho

Version: 1.0.0 Fecha: 2026-01-27 Estado: Diseño Prioridad: P0 (Crítico - Workflow + NOM-068 Compliance)

---

Descripción General

El módulo de Despacho es responsable de la liberación operativa del viaje, asegurando que todos los checklists, documentos, sellos y evidencias estén completos antes de que la unidad salga a ruta.

Problema que resuelve:

• Viajes que salen sin inspección pre-viaje (riesgo de accidentes)
• Falta de control de sellos de seguridad
• Documentación incompleta que genera problemas en ruta
• Incumplimiento de NOM-068 (condiciones físico-mecánicas)

---

Objetivos del Módulo

1. Checklist Pre-Viaje: Inspección documentada según NOM-068
2. Control de Sellos: Registro y evidencia de sellos de seguridad
3. Evidencias de Carga: Fotos del estado de la carga antes de salir
4. Kit Documental: Compilar todos los documentos necesarios
5. Liberación Oficial: Evento de "gate out" con timestamp y responsable

---

Alcance Funcional

Incluido

• Checklist de inspección pre-viaje parametrizable
• Control de sellos (asignación, fotos, verificación)
• Captura de evidencias de carga
• Compilación de kit documental digital
• Registro de salida (gate out)
• Validaciones de despacho
• Notificación de salida

Excluido

• Planeación y asignación (MAI-004)
• Tracking en ruta (MAI-006)
• Generación de Carta Porte (MAE-016)

---

Actores

Actor	Rol en el módulo
Operador	Ejecuta checklist, registra sellos, toma evidencias
Despachador	Valida checklist, autoriza salida
Vigilancia	Confirma salida física (gate out)
Sistema	Valida documentación, genera alertas

---

Flujo Principal

VIAJE PLANIFICADO
      │
      ▼
┌─────────────────────────────────────────┐
│ 1. CHECKLIST PRE-VIAJE                  │
│    - Operador inspecciona unidad        │
│    - Registra estado de cada punto      │
│    - Adjunta fotos si hay observaciones │
│    - Firma digital del checklist        │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 2. CONTROL DE SELLOS                    │
│    - Asignar números de sello           │
│    - Tomar foto de cada sello colocado  │
│    - Registrar ubicación del sello      │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 3. EVIDENCIAS DE CARGA                  │
│    - Fotos de la carga                  │
│    - Peso en báscula (si aplica)        │
│    - Firma de almacén                   │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 4. KIT DOCUMENTAL                       │
│    - Orden de viaje                     │
│    - Carta porte (si ya generada)       │
│    - Remisión/factura del cliente       │
│    - Permisos especiales                │
│    - Instrucciones de entrega           │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 5. VALIDACIÓN DE DESPACHO               │
│    ✓ Checklist completo                 │
│    ✓ Sellos registrados                 │
│    ✓ Documentos completos               │
│    ✓ Sin bloqueos de unidad/operador    │
└────────────────────┬────────────────────┘
                     │
              ┌──────┴──────┐
              │             │
              ▼             ▼
         [APROBADO]    [BLOQUEADO]
              │             │
              ▼             ▼
┌─────────────────┐  ┌─────────────────┐
│ 6. GATE OUT     │  │ Resolver y      │
│    - Timestamp  │  │ reintentar      │
│    - GPS        │  │                 │
│    - Responsable│  │                 │
└────────┬────────┘  └─────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│         VIAJE DESPACHADO                │
│    → Inicia Tracking (MAI-006)          │
└─────────────────────────────────────────┘

---

Datos del Módulo

Entidades Principales

Entidad	Descripción	Estado
ChecklistPreViaje	Inspección de unidad	NO IMPLEMENTADA
ItemChecklist	Puntos de inspección	NO IMPLEMENTADA
SelloViaje	Registro de sellos	NO IMPLEMENTADA
EvidenciaCarga	Fotos de la carga	NO IMPLEMENTADA
DespachoViaje	Registro de liberación	NO IMPLEMENTADA

Campos Clave Checklist

Campo	Tipo	Obligatorio	Descripción
viaje_id	UUID	Sí	Viaje asociado
tipo_checklist	ENUM	Sí	PRE_VIAJE, POST_VIAJE
operador_id	UUID	Sí	Quien ejecuta
fecha_ejecucion	TIMESTAMP	Sí	Cuándo se ejecutó
firma_operador	TEXT	Sí	Firma digital
status	ENUM	Sí	EN_PROCESO, APROBADO, RECHAZADO
items	JSONB	Sí	Detalle de puntos inspeccionados

---

Requerimientos Funcionales

Ver archivo: REQUERIMIENTOS.md

---

Compliance NOM-068

El módulo debe cumplir con NOM-068-SCT-2-2014:

• Checklist parametrizable según tipo de vehículo
• Puntos de inspección según norma (llantas, frenos, luces, etc.)
• Evidencia fotográfica de condiciones
• Bloqueo de salida si hay fallas críticas
• Registro auditable de inspecciones

---

Métricas del Módulo

KPI	Fórmula	Meta
Checklists completados	% viajes con checklist	100%
Tiempo de despacho	Avg(gate_out - inicio_checklist)	<45 min
Viajes bloqueados	% viajes con bloqueo	<5%
Sellos documentados	% viajes con sellos OK	100%

---

Dependencias

Este módulo depende de:

• MAI-004 (Planeación): Viajes planificados
• MAI-011 (Flota): Datos de unidad y operador
• MAE-016 (Carta Porte): Documento para kit

Otros módulos dependen de este:

• MAI-006 (Tracking): Inicia al despachar
• MAI-007 (POD): Viaje debe estar despachado

---

Historias de Usuario

Ver carpeta: historias-usuario/

US	Titulo	Prioridad	SP
US-MAI005-001	Ejecutar checklist pre-viaje	Alta	8
US-MAI005-002	Registrar sellos de seguridad	Alta	5
US-MAI005-003	Capturar evidencias de carga	Alta	5
US-MAI005-004	Compilar kit documental	Media	3
US-MAI005-005	Registrar salida (gate out)	Alta	5
US-MAI005-006	Sugerir mejor unidad para asignacion	Alta	8
US-MAI005-007	Dashboard de unidades en tiempo real	Alta	5
US-MAI005-008	Configurar reglas de asignacion	Media	5
US-MAI005-009	Reasignar viaje con motivo	Alta	5
US-MAI005-010	Consultar logs de despacho	Media	3

---

Algoritmo de Asignacion Inteligente

El Centro de Despacho implementa un algoritmo de asignacion inteligente que sugiere la mejor unidad disponible para cada viaje basandose en multiples criterios ponderados.

Funcion Principal: suggestBestAssignment()

La funcion suggestBestAssignment() analiza todas las unidades disponibles y calcula un score compuesto para cada una, retornando una lista ordenada de sugerencias con su puntuacion detallada.

interface AssignmentSuggestion {
  unitId: string;
  operatorId: string;
  totalScore: number;
  scoreBreakdown: {
    distance: number;      // 0-100 (peso 40%)
    capacity: number;      // 0-100 (peso 25%)
    availability: number;  // 0-100 (peso 20%)
    skills: number;        // 0-100 (peso 15%)
  };
  estimatedArrival: Date;
  distanceKm: number;
}

async function suggestBestAssignment(
  tripId: string,
  options?: {
    maxResults?: number;      // default: 5
    maxDistanceKm?: number;   // default: 50
    requiredSkills?: string[];
  }
): Promise<AssignmentSuggestion[]>;

Criterios de Scoring

Criterio	Peso	Calculo	Bonus/Penalidad
Distancia	40%	100 - (km * 2)	+10 si < 10km, -20 si > 25km
Capacidad	25%	Match con requerimiento	+10 si capacidad exacta
Disponibilidad	20%	Basado en turno activo	100 si disponible en turno
Skills/Certificaciones	15%	Match con requerimientos	+5 por cada skill adicional

Detalle de Calculo por Criterio

Distancia (40%)

• Base: max(0, 100 - (distanciaKm * 2))
• Bonus: +10 puntos si distancia < 10km (unidad cercana)
• Penalidad: -20 puntos si distancia > 25km (unidad lejana)
• Minimo: 0 puntos

Capacidad (25%)

• 100 puntos si capacidad >= requerimiento
• 0 puntos si capacidad < requerimiento
• Bonus: +10 puntos si capacidad coincide exactamente (evita sobre-capacidad)

Disponibilidad (20%)

• 100 puntos si unidad AVAILABLE y operador en turno activo
• 50 puntos si unidad disponible pero fuera de turno
• 0 puntos si unidad no disponible

Skills/Certificaciones (15%)

• Base: (skills coincidentes / skills requeridos) * 100
• Bonus: +5 puntos por cada skill adicional (max +20)
• Ejemplos de skills: HAZMAT, refrigerado, carga pesada, escolta

Formula Haversine

Para calcular la distancia entre la ubicacion actual de la unidad y el punto de origen del viaje, se utiliza la formula Haversine:

/**
 * Calcula la distancia en kilometros entre dos puntos geograficos
 * usando la formula Haversine.
 */
function calculateHaversineDistance(
  lat1: number,
  lon1: number,
  lat2: number,
  lon2: number
): number {
  const R = 6371; // Radio de la Tierra en km

  const toRadians = (degrees: number): number => {
    return degrees * (Math.PI / 180);
  };

  const dLat = toRadians(lat2 - lat1);
  const dLon = toRadians(lon2 - lon1);

  const a =
    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
    Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) *
    Math.sin(dLon / 2) * Math.sin(dLon / 2);

  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));

  return R * c; // Distancia en km
}

Estados de Unidad

El sistema mantiene el estado de cada unidad en tiempo real para determinar disponibilidad:

Estado	Codigo	Descripcion	Disponible
Disponible	AVAILABLE	Unidad lista para asignacion	Si
Asignada	ASSIGNED	Asignada a viaje, pendiente despacho	No
En Ruta	EN_ROUTE	Viajando hacia origen o destino	No
En Sitio	ON_SITE	En punto de carga/descarga	No
Retornando	RETURNING	Regresando a base	Parcial
Desconectada	OFFLINE	Sin comunicacion GPS	No
Mantenimiento	MAINTENANCE	En taller o inspeccion	No

Entidades del Centro de Despacho

Entidad	Descripcion	Estado
DispatchBoard	Tablero de despacho con viajes pendientes	NO IMPLEMENTADA
UnitStatus	Estado actual de unidad con ubicacion GPS	NO IMPLEMENTADA
DispatchLog	Registro de asignaciones y cambios	NO IMPLEMENTADA
DispatchRule	Reglas configurables de asignacion	NO IMPLEMENTADA

DispatchBoard

Tablero central que muestra viajes pendientes de asignacion:

interface DispatchBoard {
  id: string;
  tenantId: string;
  date: Date;
  pendingTrips: TripSummary[];
  availableUnits: UnitSummary[];
  assignments: Assignment[];
  createdAt: Date;
  updatedAt: Date;
}

UnitStatus

Estado en tiempo real de cada unidad:

interface UnitStatus {
  id: string;
  unitId: string;
  status: UnitStatusEnum;
  currentLocation: {
    latitude: number;
    longitude: number;
    timestamp: Date;
    accuracy: number;
  };
  currentTripId: string | null;
  operatorId: string;
  shiftStart: Date | null;
  shiftEnd: Date | null;
  lastUpdate: Date;
}

DispatchLog

Auditoria de todas las acciones de despacho:

interface DispatchLog {
  id: string;
  tripId: string;
  action: 'SUGGESTED' | 'ASSIGNED' | 'REASSIGNED' | 'CANCELLED';
  unitId: string;
  operatorId: string;
  performedBy: string;
  reason: string | null;
  previousUnitId: string | null;
  scoreAtAssignment: number | null;
  timestamp: Date;
}

DispatchRule

Reglas configurables por tenant:

interface DispatchRule {
  id: string;
  tenantId: string;
  name: string;
  priority: number;
  conditions: {
    tripTypes?: string[];
    customers?: string[];
    routes?: string[];
    timeRanges?: { start: string; end: string }[];
  };
  weights: {
    distance: number;    // default: 40
    capacity: number;    // default: 25
    availability: number;// default: 20
    skills: number;      // default: 15
  };
  isActive: boolean;
  createdAt: Date;
  updatedAt: Date;
}

---

Modulo MAI-005 - ERP Transportistas - Sistema SIMCO v4.0.0