# US-MAI003-002: Agregar multiples paradas a OT

## Metadata

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

## Historia de Usuario

**Como** coordinador de trafico de una empresa transportista,
**quiero** definir multiples paradas (recoleccion, entrega, escala) asociadas a un viaje que agrupe varias OTs,
**para** optimizar rutas multi-drop y atender a varios clientes o destinos en un mismo recorrido.

## Descripcion Detallada

El transporte de carga frecuentemente requiere rutas con multiples puntos de recoleccion y entrega (multi-drop). La tabla `paradas_viaje` permite definir una secuencia ordenada de paradas asociadas a un viaje, donde cada parada tiene un tipo (RECOLECCION, ENTREGA o ESCALA), ubicacion georreferenciada, horarios programados y reales, contacto en sitio, y las OTs asociadas a esa parada especifica.

Las paradas se vinculan al viaje (viaje_id) y cada parada referencia las OTs que se recolectan o entregan en ese punto mediante el campo ots_ids (array de UUIDs). La secuencia numerica determina el orden de visita. Al crear las paradas, el sistema debe validar que la secuencia sea consecutiva y que las OTs referenciadas existan y pertenezcan al mismo tenant.

Esta funcionalidad es critica para operaciones LTL (Less Than Truckload) donde se consolida carga de distintos clientes u origenes en un mismo viaje, asi como para entregas multi-destino donde un shipper necesita distribuir mercancia a varios consignees.

## Criterios de Aceptacion

### Escenario 1: Agregar paradas secuenciales a un viaje

**Dado** que existe un viaje creado en estado BORRADOR con al menos una OT asignada,
**Cuando** el coordinador agrega paradas indicando tipo, direccion, secuencia y OTs asociadas,
**Entonces** el sistema registra cada parada en `transport.paradas_viaje` con la secuencia correcta, respetando la constraint uq_parada_viaje_secuencia que garantiza unicidad de secuencia por viaje.

### Escenario 2: Validacion de secuencia unica

**Dado** que un viaje ya tiene paradas con secuencias 1, 2 y 3,
**Cuando** el coordinador intenta agregar una nueva parada con secuencia 2,
**Entonces** el sistema rechaza la operacion indicando que la secuencia 2 ya esta asignada en ese viaje.

### Escenario 3: Parada con datos de contacto y horarios

**Dado** que el coordinador esta agregando una parada de tipo ENTREGA,
**Cuando** completa los datos de ubicacion (direccion, ciudad, estado, coordenadas), contacto (nombre, telefono) y horarios programados (hora_programada_llegada, hora_programada_salida),
**Entonces** el sistema almacena todos los datos y los disponibiliza para el operador durante la ejecucion del viaje.

### Escenario 4: Asociar OTs a paradas especificas

**Dado** que un viaje tiene 3 OTs asignadas y el coordinador esta definiendo paradas,
**Cuando** asocia la OT-001 a la parada 1 (RECOLECCION) y las OTs OT-002 y OT-003 a la parada 2 (ENTREGA),
**Entonces** el campo ots_ids de cada parada contiene los UUIDs correctos de las OTs asociadas.

## Tareas Tecnicas

- **Database:** Verificar que la tabla `transport.paradas_viaje` existe con todos los campos: secuencia, tipo (RECOLECCION/ENTREGA/ESCALA), datos de ubicacion, contacto, horarios programados/reales, ots_ids (UUID[]), estado y observaciones. Verificar indice idx_parada_viaje y constraint uq_parada_viaje_secuencia.
- **Backend:** Crear entity `ParadaViaje` mapeada a `transport.paradas_viaje`. Crear `ParadaViajeService` con metodos `createParada()`, `reorderParadas()` y `assignOtsToParada()`. Crear `ParadaViajeController` con endpoints anidados bajo viaje: POST `/api/v1/viajes/:viajeId/paradas`, PATCH `/api/v1/viajes/:viajeId/paradas/:id`. Crear DTOs: `CreateParadaViajeDto`, `UpdateParadaViajeDto`.
- **Frontend:** Crear componente `ParadasViajeList` con vista tipo timeline/sortable para las paradas. Incluir formulario de parada con mapa para seleccionar ubicacion. Permitir drag-and-drop para reordenar secuencia.
- **Tests:** Tests unitarios de validacion de secuencia y asociacion de OTs. Tests de integracion del CRUD de paradas. Test de constraint de secuencia unica.

## Dependencias

- **Depende de:** US-MAI003-001 (las OTs deben existir), MAI-004 (el viaje debe existir para asociar paradas)
- **Bloquea:** MAI-005 (Despacho - las paradas son parte de la orden de viaje), MAI-006 (Tracking - los eventos se registran por parada), MAI-007 (POD - la evidencia se captura por parada)

## Notas Tecnicas

- **Endpoint:** POST `/api/v1/viajes/:viajeId/paradas`
- **Entity:** `ParadaViaje` -> `transport.paradas_viaje`
- **RLS:** Politica `tenant_isolation_paradas` filtra por `tenant_id`
- **Campo ots_ids:** Es un array nativo de PostgreSQL (UUID[]), no una relacion FK tradicional. En TypeORM se mapea como `@Column({ type: 'uuid', array: true, nullable: true })`
- **Tipos de parada:** 'RECOLECCION' (pickup), 'ENTREGA' (drop-off), 'ESCALA' (waypoint/stop intermedio)
- **Constraint:** uq_parada_viaje_secuencia(viaje_id, secuencia) impide secuencias duplicadas en un mismo viaje

---

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