# 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*