# US-MAI003-003: Definir restricciones logisticas

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-MAI003-003 |
| **Epica** | EPIC-MAI-003 - Ordenes de Transporte |
| **Modulo** | ordenes-transporte |
| **Prioridad** | P1 |
| **Story Points** | 5 |
| **Sprint** | Por asignar |
| **Estado** | Backlog |

## Historia de Usuario

**Como** despachador de una empresa transportista,
**quiero** definir restricciones logisticas especificas para cada orden de transporte (temperatura, GPS, escolta, cita, instrucciones especiales),
**para** asegurar que la planeacion y ejecucion del servicio cumplan con los requisitos del cliente y la naturaleza de la carga.

## Descripcion Detallada

Las restricciones logisticas son requisitos adicionales que condicionan como debe ejecutarse el servicio de transporte. Estas restricciones van mas alla de los datos basicos de la OT y determinan el tipo de equipo, la seguridad y las condiciones especiales que se deben cumplir durante el viaje.

La tabla `ordenes_transporte` incluye campos booleanos y de parametros para estas restricciones: `requiere_temperatura` con rangos `temperatura_min` y `temperatura_max` (para carga refrigerada o de cadena de frio), `requiere_gps` (para seguimiento obligatorio), `requiere_escolta` (para carga de alto valor o zona de riesgo), `requiere_cita` (para destinos con sistema de appointment), e `instrucciones_especiales` (texto libre para indicaciones particulares del cliente).

Estas restricciones alimentan la planeacion (MAI-004) para seleccionar la unidad y operador adecuados, el despacho (MAI-005) para verificar el cumplimiento del checklist, y el tracking (MAI-006) para configurar alertas especificas.

## Criterios de Aceptacion

### Escenario 1: Definir requisito de temperatura

**Dado** que el despachador esta creando o editando una OT con tipo_carga REFRIGERADA,
**Cuando** activa requiere_temperatura e ingresa temperatura_min (-5.00) y temperatura_max (2.00),
**Entonces** el sistema almacena los rangos de temperatura y los validara contra las capacidades de la unidad asignada en la fase de planeacion.

### Escenario 2: Activar multiples restricciones de seguridad

**Dado** que el despachador esta registrando una OT para carga de alto valor,
**Cuando** activa requiere_gps y requiere_escolta simultaneamente,
**Entonces** el sistema registra ambas restricciones y estas seran visibles en el tablero de planeacion como requisitos obligatorios para la asignacion de recursos.

### Escenario 3: Registrar instrucciones especiales

**Dado** que el cliente tiene requerimientos operativos particulares,
**Cuando** el despachador ingresa instrucciones especiales (por ejemplo: "Entregar solo en horario matutino. Requiere montacargas en destino. Contactar al Sr. Lopez 30 minutos antes de arribo."),
**Entonces** el sistema almacena el texto completo y lo incluye en la informacion visible para el operador durante la ejecucion del viaje.

### Escenario 4: Validacion de rango de temperatura

**Dado** que el despachador activa requiere_temperatura,
**Cuando** ingresa temperatura_min mayor que temperatura_max,
**Entonces** el sistema muestra un error de validacion indicando que la temperatura minima no puede ser mayor que la maxima.

## Tareas Tecnicas

- **Database:** Los campos ya existen en `transport.ordenes_transporte`: requiere_temperatura (BOOLEAN DEFAULT FALSE), temperatura_min (DECIMAL(5,2)), temperatura_max (DECIMAL(5,2)), requiere_gps (BOOLEAN DEFAULT FALSE), requiere_escolta (BOOLEAN DEFAULT FALSE), requiere_cita (BOOLEAN DEFAULT FALSE), instrucciones_especiales (TEXT).
- **Backend:** Extender `CreateOrdenTransporteDto` y `UpdateOrdenTransporteDto` con campos de restricciones. Agregar validacion en el servicio: si requiere_temperatura es true, temperatura_min y temperatura_max son obligatorios y temperatura_min debe ser menor que temperatura_max. Agregar logica de compatibilidad que sera consumida por MAI-004 para validar capacidades de unidad.
- **Frontend:** Crear seccion "Restricciones Logisticas" en el formulario de OT con toggles para cada requisito. Mostrar campos de temperatura condicionalmente cuando requiere_temperatura esta activo. Incluir campo de texto enriquecido para instrucciones especiales.
- **Tests:** Tests unitarios de validacion de rangos de temperatura. Tests de validacion de datos obligatorios condicionales. Tests de integracion con persistencia de restricciones.

## Dependencias

- **Depende de:** US-MAI003-001 (la OT debe existir primero)
- **Bloquea:** MAI-004 (Planeacion - usa restricciones para compatibilidad de recursos), MAI-005 (Despacho - verifica cumplimiento en checklist), MAI-006 (Tracking - configura alertas por restriccion)

## Notas Tecnicas

- **Endpoint:** PATCH `/api/v1/ordenes-transporte/:id` (actualizacion parcial de campos de restricciones)
- **Entity:** Campos adicionales en `OrdenTransporte` entity
- **Validacion condicional:** Usar decoradores de class-validator como `@ValidateIf(o => o.requiere_temperatura === true)` para temperatura_min y temperatura_max
- **Compatibilidad futura:** Las restricciones seran leidas por el motor de planeacion de MAI-004 para filtrar unidades aptas (por ejemplo, solo unidades con refrigeracion si requiere_temperatura es true)
- **Tipos de carga y restricciones:** PELIGROSA implica automaticamente requiere_gps = true; REFRIGERADA implica requiere_temperatura = true (sugerencia al usuario, no forzado)

---

*US-MAI003-003 - ERP Transportistas v1.0.0*