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

REQUERIMIENTOS.md - MAI-005: Despacho

Version: 1.0.0 Fecha: 2026-01-27 Fuente: REQ-GIRO-TRANSPORTISTA.md - Sección 4.4

---

Requerimientos Funcionales

RF-4.4.1: Orden de Viaje (OV)

Descripción: El sistema debe generar la Orden de Viaje desde el embarque con toda la información operativa necesaria.

Criterios de Aceptación:

1. La OV incluye: unidad, remolques, operador, ruta completa, paradas con secuencia
2. La OV incluye instrucciones especiales del cliente
3. La OV es visible en app móvil del operador
4. La OV puede imprimirse en formato compacto
5. La OV tiene código QR para identificación rápida

Mapeo a DDL:

• Tabla: viajes
• Vista: v_orden_viaje

Endpoints Requeridos:

• GET /api/v1/viajes/:id/orden-viaje - Obtener OV
• GET /api/v1/viajes/:id/orden-viaje/pdf - Descargar PDF

Prioridad: Alta

---

RF-4.4.2: Checklists Pre-Viaje

Descripción: El sistema debe permitir ejecutar una inspección de la unidad con checklist parametrizable por tipo de vehículo, cumpliendo NOM-068.

Criterios de Aceptación:

1. Checklist configurable por tipo de unidad (tractora, remolque, caja)
2. Puntos de inspección incluyen:
   • Llantas (presión, estado, profundidad)
   • Frenos (servicio, estacionamiento)
   • Luces (delanteras, traseras, direccionales)
   • Espejos y cristales
   • Niveles (aceite, anticongelante, combustible)
   • Sistema de acoplamiento (quinta rueda, conexiones)
   • Documentación abordo
3. Cada punto tiene opciones: OK, Observación, Falla
4. Fallas críticas bloquean el despacho
5. Operador firma digitalmente al completar
6. Se pueden adjuntar fotos por punto

Mapeo a DDL:

• Tabla: inspecciones_pre_viaje
• Tabla: checklist_items (catálogo)

Endpoints Requeridos:

• GET /api/v1/checklists/plantilla/:tipo-unidad - Obtener plantilla
• POST /api/v1/viajes/:id/checklist - Registrar checklist
• POST /api/v1/viajes/:id/checklist/items/:item/foto - Adjuntar foto

Prioridad: Alta

---

RF-4.4.3: Control de Sellos

Descripción: El sistema debe registrar la asignación y evidencia de sellos de seguridad.

Criterios de Aceptación:

1. Asignar uno o más sellos al viaje
2. Registrar número de sello (manual o escáner)
3. Registrar ubicación del sello (puerta trasera, lateral)
4. Capturar foto del sello colocado
5. Registrar ruptura de sello con motivo
6. Reemplazo de sello con nuevo número y evidencia

Mapeo a DDL:

• Tabla: sellos_viaje
• Campos: numero, ubicacion, foto_url, fecha_colocacion, status

Endpoints Requeridos:

• POST /api/v1/viajes/:id/sellos - Registrar sello
• PUT /api/v1/sellos/:id/ruptura - Registrar ruptura
• POST /api/v1/sellos/:id/reemplazo - Registrar reemplazo

Prioridad: Alta

---

RF-4.4.4: Evidencias de Carga

Descripción: El sistema debe capturar evidencias fotográficas del estado de la carga antes de cerrar.

Criterios de Aceptación:

1. Capturar fotos de la carga estibada
2. Registrar peso en báscula (opcional, manual o integrado)
3. Capturar firma del responsable de almacén
4. Asociar evidencias al viaje
5. Las fotos funcionan en modo offline

Mapeo a DDL:

• Tabla: evidencias_carga
• Campos: viaje_id, tipo, url, peso_bascula, firma_almacen

Endpoints Requeridos:

• POST /api/v1/viajes/:id/evidencias-carga - Subir evidencia
• POST /api/v1/viajes/:id/evidencias-carga/firma - Registrar firma

Prioridad: Alta

---

RF-4.4.5: Kit Documental

Descripción: El sistema debe compilar todos los documentos necesarios para el viaje en formato digital.

Criterios de Aceptación:

1. Compilar automáticamente:
   • Orden de Viaje
   • Carta Porte (si ya generada)
   • Remisión/factura del cliente
   • Permisos especiales (hazmat, sobredimensión)
   • Instrucciones de entrega por parada
2. Disponible en app móvil para consulta offline
3. Opción de imprimir paquete completo
4. Alertar si falta documento obligatorio

Mapeo a DDL:

• Tabla: documentos_viaje
• Campos: viaje_id, tipo_documento, url, obligatorio

Endpoints Requeridos:

• GET /api/v1/viajes/:id/kit-documental - Obtener lista
• GET /api/v1/viajes/:id/kit-documental/zip - Descargar todos
• POST /api/v1/viajes/:id/documentos - Agregar documento

Prioridad: Media

---

RF-4.4.6: Gate Out / Salida Oficial

Descripción: El sistema debe registrar el evento de salida con timestamp, usuario responsable y geolocalización.

Criterios de Aceptación:

1. Validar que todas las condiciones de despacho estén cumplidas
2. Registrar timestamp exacto de salida
3. Registrar coordenadas GPS de la salida
4. Registrar usuario que autoriza (despachador o vigilancia)
5. Cambiar estado del viaje a DESPACHADO
6. Notificar al cliente que el viaje inició
7. Activar tracking (MAI-006)

Mapeo a DDL:

• Tabla: despachos
• Campos: viaje_id, fecha_salida, coordenadas, usuario_id, notas

Endpoints Requeridos:

• POST /api/v1/viajes/:id/gate-out - Registrar salida
• GET /api/v1/viajes/:id/validar-despacho - Verificar condiciones

Prioridad: Alta

---

Requerimientos No Funcionales

RNF-001: Modo Offline

El checklist y captura de evidencias deben funcionar sin conexión.

RNF-002: Performance

El checklist debe cargar en menos de 2 segundos.

RNF-003: Compliance

Todos los registros deben ser inmutables para auditoría NOM-068.

RNF-004: Disponibilidad

El módulo debe estar disponible 24/7 para operaciones nocturnas.

---

Validaciones de Negocio

Validación	Descripción	Acción si falla
DSP_001	Checklist completado	Bloquear gate out
DSP_002	Sin fallas críticas en checklist	Bloquear gate out
DSP_003	Sellos registrados (si aplica)	Bloquear gate out
DSP_004	Documentos obligatorios presentes	Alertar, permitir override
DSP_005	Operador con HOS suficiente	Bloquear gate out

---

Matriz de Trazabilidad

RF	Tabla DDL	Entity	Endpoint	US
RF-4.4.1	viajes	Viaje	GET /orden-viaje	US-MAI005-004
RF-4.4.2	inspecciones_pre_viaje	ChecklistPreViaje	POST /checklist	US-MAI005-001
RF-4.4.3	sellos_viaje	SelloViaje	POST /sellos	US-MAI005-002
RF-4.4.4	evidencias_carga	EvidenciaCarga	POST /evidencias-carga	US-MAI005-003
RF-4.4.5	documentos_viaje	DocumentoViaje	GET /kit-documental	US-MAI005-004
RF-4.4.6	despachos	DespachoViaje	POST /gate-out	US-MAI005-005

---

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