erp-transportistas-v2/docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md

REQUERIMIENTOS.md - MAI-004: Planeación TMS

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

---

Requerimientos Funcionales

RF-4.3.1: Tablero de Planeación

Descripción: El sistema debe proveer un tablero visual (Gantt/Kanban) para ver OTs por fecha, ventana, estado, prioridad y región.

Criterios de Aceptación:

1. Vista Gantt muestra línea de tiempo con OTs y viajes
2. Vista Kanban muestra OTs por estado (Pendiente, Asignada, Planificada)
3. Filtros por: fecha, cliente, región, tipo de servicio, prioridad
4. Drag & drop para mover OTs entre fechas/recursos
5. Indicadores visuales de urgencia (SLA próximo a vencer)
6. Panel lateral con detalle de OT seleccionada
7. Vista de recursos disponibles por fecha

Mapeo a DDL:

• Tabla: ordenes_transporte, viajes, embarques
• Vista: v_tablero_planeacion

Endpoints Requeridos:

• GET /api/v1/planeacion/tablero - Datos del tablero
• GET /api/v1/planeacion/recursos-disponibles - Recursos por fecha
• PUT /api/v1/ot/:id/fecha-planificada - Mover OT de fecha

Prioridad: Alta

---

RF-4.3.2: Consolidación Automática Sugerida

Descripción: El sistema debe sugerir agrupaciones de OTs compatibles por zona, ventana de tiempo, capacidad y tipo de equipo.

Criterios de Aceptación:

1. Al seleccionar múltiples OTs, el sistema sugiere si son consolidables
2. Criterios de consolidación configurables:
   • Misma zona de origen
   • Zona de destino cercana (radio configurable)
   • Ventanas de tiempo compatibles (overlap)
   • Mismo tipo de equipo requerido
3. El sistema calcula capacidad total vs disponible
4. El planner puede aceptar, modificar o rechazar sugerencia
5. Se crea embarque al aceptar consolidación

Mapeo a DDL:

• Tabla: embarques
• Campos: ot_ids[], capacidad_total, tipo_equipo

Endpoints Requeridos:

• POST /api/v1/planeacion/sugerir-consolidacion - Analizar OTs
• POST /api/v1/embarques - Crear embarque
• PUT /api/v1/embarques/:id/agregar-ot - Añadir OT a embarque

Prioridad: Alta

---

RF-4.3.3: Cálculo de Capacidad

Descripción: El sistema debe validar que la carga no exceda capacidad de la unidad por peso, volumen, pallets y altura.

Criterios de Aceptación:

1. Cada unidad tiene configurada su capacidad:
   • Peso máximo (toneladas)
   • Volumen máximo (m³)
   • Posiciones de pallet
   • Altura máxima de carga
2. Al asignar OT/embarque, el sistema valida:
   • Suma de pesos ≤ capacidad peso
   • Suma de volúmenes ≤ capacidad volumen
   • Suma de pallets ≤ posiciones
3. Alerta si se excede 90% de capacidad
4. Bloquea si se excede 100%
5. Considera restricciones especiales (temperatura, peligrosidad)

Mapeo a DDL:

• Tabla: unidades campos capacidad_*
• Tabla: ordenes_transporte campos peso, volumen, pallets

Endpoints Requeridos:

• GET /api/v1/unidades/:id/capacidad - Consultar capacidad
• POST /api/v1/planeacion/validar-capacidad - Validar asignación

Prioridad: Alta

---

RF-4.3.4: Reservas de Recursos

Descripción: El sistema debe permitir pre-asignar unidad, operador y remolque con bloqueo de disponibilidad.

Criterios de Aceptación:

1. Al asignar recurso, se crea reserva con:
   • Fecha/hora inicio y fin estimados
   • Estado: RESERVADO
2. El recurso no aparece disponible para otras asignaciones
3. La reserva puede cancelarse liberando el recurso
4. Conflictos de horario se detectan y alertan
5. Vista de calendario por recurso muestra reservas

Mapeo a DDL:

• Tabla: asignaciones
• Campos: recurso_tipo, recurso_id, viaje_id, fecha_inicio, fecha_fin, status

Endpoints Requeridos:

• POST /api/v1/asignaciones - Crear reserva
• DELETE /api/v1/asignaciones/:id - Cancelar reserva
• GET /api/v1/recursos/:tipo/:id/calendario - Ver calendario

Prioridad: Alta

---

RF-4.3.5: Reglas de Compatibilidad

Descripción: El sistema debe validar que el recurso asignado cumple requisitos del servicio y del cliente.

Criterios de Aceptación:

1. Validaciones de operador:
   • Licencia tipo requerido vigente
   • Certificaciones especiales (hazmat, doble articulado)
   • No está en lista negra del cliente
   • Horas de servicio disponibles
2. Validaciones de unidad:
   • Tipo de equipo correcto (caja seca, refrigerada, plataforma)
   • Documentos vigentes (verificación, seguro, permiso SCT)
   • Cumple requisitos de cliente (GPS, antigüedad máxima)
3. El sistema bloquea asignación si no cumple
4. Opción de override con justificación (supervisor)

Mapeo a DDL:

• Tabla: reglas_asignacion
• Tabla: requisitos_cliente

Endpoints Requeridos:

• POST /api/v1/planeacion/validar-compatibilidad - Validar reglas
• GET /api/v1/clientes/:id/requisitos - Requisitos del cliente

Prioridad: Alta

---

RF-4.3.6: Simulación de Ruta y ETA

Descripción: El sistema debe calcular estimación de tiempos y ETAs basado en distancias y velocidades promedio.

Criterios de Aceptación:

1. Cálculo de distancia entre origen y destinos
2. Estimación de tiempo de tránsito:
   • Velocidad promedio por tipo de vía
   • Paradas programadas (descansos, combustible)
   • Ventanas de carga/descarga
3. ETA por cada parada del itinerario
4. Comparación ETA vs ventana comprometida (SLA)
5. Alerta si ETA > ventana permitida

Mapeo a DDL:

• Tabla: eta_calculado
• Campos: viaje_id, parada_id, eta_llegada, eta_salida

Endpoints Requeridos:

• POST /api/v1/planeacion/calcular-eta - Calcular ETAs
• GET /api/v1/viajes/:id/itinerario - Ver itinerario con ETAs

Prioridad: Media

---

Requerimientos No Funcionales

RNF-001: Performance Tablero

El tablero debe cargar en menos de 3 segundos con 500 OTs visibles.

RNF-002: Concurrencia

Múltiples planners pueden trabajar simultáneamente sin conflictos de asignación.

RNF-003: Tiempo Real

Los cambios de disponibilidad deben reflejarse en menos de 5 segundos.

RNF-004: Usabilidad

El flujo de asignación completo debe completarse en menos de 5 clics.

---

Validaciones de Negocio

Validación	Descripción	Acción si falla
PLN_001	Capacidad no excedida	Bloquear asignación
PLN_002	Operador con licencia vigente	Bloquear asignación
PLN_003	Unidad con documentos OK	Bloquear asignación
PLN_004	Sin conflicto de horarios	Alertar, permitir override
PLN_005	ETA dentro de SLA	Alertar, permitir continuar

---

Matriz de Trazabilidad

RF	Tabla DDL	Entity	Endpoint	US
RF-4.3.1	v_tablero_planeacion	-	GET /planeacion/tablero	US-MAI004-001
RF-4.3.2	embarques	Embarque	POST /embarques	US-MAI004-002
RF-4.3.3	unidades	Unidad	POST /validar-capacidad	US-MAI004-003
RF-4.3.4	asignaciones	AsignacionRecurso	POST /asignaciones	US-MAI004-003
RF-4.3.5	reglas_asignacion	ReglaAsignacion	POST /validar-compatibilidad	US-MAI004-004
RF-4.3.6	eta_calculado	ETACalculado	POST /calcular-eta	US-MAI004-005

---

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