# MAI-004: Planeación TMS

**Version:** 1.0.0
**Fecha:** 2026-01-27
**Estado:** Diseño
**Prioridad:** P0 (Crítico - Workflow principal)

---

## Descripción General

El módulo de Planeación TMS (Transportation Management System) es responsable de convertir las Órdenes de Transporte en embarques y viajes factibles, optimizando la asignación de recursos (unidades, operadores, remolques) según capacidad, ventanas de tiempo y restricciones.

**Problema que resuelve:**
- Asignación manual ineficiente de recursos
- Subutilización de capacidad de unidades
- Incumplimiento de ventanas de entrega
- Falta de visibilidad de disponibilidad de flota

---

## Objetivos del Módulo

1. **Consolidación:** Agrupar OTs compatibles en embarques para optimizar capacidad
2. **Asignación:** Seleccionar la mejor combinación unidad-operador-remolque
3. **Validación:** Verificar que los recursos cumplen requisitos del servicio
4. **Visibilidad:** Tablero de planeación con vista de recursos y OTs pendientes

---

## Alcance Funcional

### Incluido

- Tablero de planeación (vista Gantt/Kanban)
- Consolidación de OTs en embarques
- Cálculo de capacidad por unidad
- Pre-asignación de recursos
- Validación de compatibilidad operador-unidad-cliente
- Estimación de ETA inicial
- Generación de viajes planificados

### Excluido

- Optimización automática de rutas (MAA-019)
- Despacho y liberación de viaje (MAI-005)
- Tracking en tiempo real (MAI-006)

---

## Actores

| Actor | Rol en el módulo |
|-------|------------------|
| Planner/Tráfico | Usuario principal, planifica y asigna |
| Jefe de Flota | Consulta disponibilidad, bloquea recursos |
| Ventas | Consulta capacidad para compromisos |
| Sistema | Sugiere consolidaciones automáticas |

---

## Flujo Principal

```
OTs CONFIRMADAS
      │
      ▼
┌─────────────────────────────────────────┐
│ 1. TABLERO DE PLANEACIÓN                │
│    - Vista por fecha/región/cliente     │
│    - OTs pendientes de asignar          │
│    - Recursos disponibles               │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 2. CONSOLIDACIÓN                        │
│    - Sistema sugiere agrupaciones       │
│    - Por zona, ventana, tipo equipo     │
│    - Planner acepta/modifica            │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 3. VALIDACIÓN DE CAPACIDAD              │
│    - Peso vs capacidad unidad           │
│    - Volumen vs metros cúbicos          │
│    - Pallets vs posiciones              │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 4. ASIGNACIÓN DE RECURSOS               │
│    - Seleccionar unidad disponible      │
│    - Seleccionar operador calificado    │
│    - Seleccionar remolque compatible    │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 5. VALIDACIONES                         │
│    ✓ Operador con licencia vigente      │
│    ✓ Unidad con documentos OK           │
│    ✓ Cumple requisitos del cliente      │
│    ✓ No hay conflicto de horarios       │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 6. VIAJE PLANIFICADO                    │
│    - Estado: PLANIFICADO                │
│    - Listo para despacho (MAI-005)      │
└─────────────────────────────────────────┘
```

---

## Datos del Módulo

### Entidades Principales

| Entidad | Descripción | Estado |
|---------|-------------|--------|
| Embarque | Agrupación de OTs | NO IMPLEMENTADA |
| Viaje | Ejecución planificada | NO IMPLEMENTADA |
| AsignacionRecurso | Reserva de unidad/operador | NO IMPLEMENTADA |
| CapacidadUnidad | Configuración de capacidad | NO IMPLEMENTADA |
| ReglaAsignacion | Criterios de compatibilidad | NO IMPLEMENTADA |

### Campos Clave Viaje

| Campo | Tipo | Obligatorio | Descripción |
|-------|------|-------------|-------------|
| embarque_id | UUID | Sí | Embarque asociado |
| unidad_id | UUID | Sí | Unidad asignada |
| operador_id | UUID | Sí | Operador asignado |
| remolque_id | UUID | No | Remolque si aplica |
| fecha_salida_planificada | TIMESTAMP | Sí | Salida estimada |
| fecha_llegada_planificada | TIMESTAMP | Sí | Llegada estimada |
| status | ENUM | Sí | PLANIFICADO, DESPACHADO, etc. |

---

## Requerimientos Funcionales

Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)

---

## Métricas del Módulo

| KPI | Fórmula | Meta |
|-----|---------|------|
| Utilización flota | % unidades en viaje | >75% |
| Fill rate | Capacidad usada vs disponible | >85% |
| Planificación exitosa | % OTs asignadas vs recibidas | >95% |
| Tiempo de planeación | Promedio minutos por viaje | <15 min |

---

## Dependencias

### Este módulo depende de:
- MAI-003 (OT): Recibe órdenes confirmadas
- MAI-011 (Flota): Consulta disponibilidad de recursos
- MAI-002 (Tarifas): Restricciones del cliente

### Otros módulos dependen de este:
- MAI-005 (Despacho): Recibe viajes planificados
- MAI-006 (Tracking): Inicia seguimiento del viaje

---

## Consideraciones Técnicas

### Performance
- Consulta de disponibilidad debe responder en <2 segundos
- Tablero debe manejar 500+ OTs sin degradación
- Cálculo de consolidación en background

### Integraciones
- Consulta de distancias/tiempos vía API de mapas
- Sincronización con calendario de operadores
- Webhook a notificaciones cuando se asigna recurso

---

## Historias de Usuario

Ver carpeta: [historias-usuario/](./historias-usuario/)

| US | Título | Prioridad |
|----|--------|-----------|
| US-MAI004-001 | Ver tablero de planeación | Alta |
| US-MAI004-002 | Consolidar OTs en embarque | Alta |
| US-MAI004-003 | Asignar unidad a viaje | Alta |
| US-MAI004-004 | Validar compatibilidad de recursos | Alta |
| US-MAI004-005 | Calcular ETA inicial | Media |

---

## Referencias

- REQ-GIRO-TRANSPORTISTA.md - Sección 4.3
- MATRIZ-COHERENCIA-DDL-BACKEND.yml
- MAPEO-RF-GIRO-A-MODULOS.yml

---

*Módulo MAI-004 - ERP Transportistas - Sistema SIMCO v4.0.0*