# 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](./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/](./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. ```typescript 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; ``` ### 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: ```typescript /** * 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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*