erp-transportistas-v2/docs/02-definicion-modulos/MAI-003-ordenes-transporte/historias-usuario/US-MAI003-002.md

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