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

US-MAI003-004: Agrupar OTs en embarque

Metadata

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

Historia de Usuario

Como coordinador de trafico de una empresa transportista, quiero agrupar multiples ordenes de transporte en un embarque de consolidacion, para optimizar la capacidad de las unidades, reducir costos operativos y asignar el grupo completo a un viaje.

Descripcion Detallada

Un embarque (shipment) es una agrupacion logica de OTs que se transportaran juntas. La consolidacion es una practica fundamental en el transporte de carga, especialmente en modalidad LTL (Less Than Truckload), donde se combinan cargas parciales de distintos clientes o destinos para aprovechar al maximo la capacidad de la unidad.

La tabla transport.embarques almacena el codigo unico del embarque, una descripcion, el cliente principal, los totales consolidados (total_ots, peso_total_kg, volumen_total_m3), el estado del embarque y la referencia al viaje asignado. Al agregar OTs a un embarque, el sistema actualiza el campo embarque_id en cada OT y recalcula los totales consolidados del embarque.

El coordinador debe poder crear un embarque, buscar OTs confirmadas compatibles (por zona, ventana de tiempo, tipo de carga) y agregarlas al embarque. Al completar la agrupacion, el embarque puede asignarse a un viaje para su ejecucion.

Criterios de Aceptacion

Escenario 1: Crear embarque nuevo

Dado que el coordinador tiene permisos de creacion de embarques, Cuando ingresa codigo, descripcion y selecciona el cliente principal, Entonces el sistema crea el embarque en estado ABIERTO con total_ots = 0 y genera un registro en transport.embarques con constraint uq_embarque_tenant_codigo.

Escenario 2: Agregar OTs al embarque

Dado que existe un embarque en estado ABIERTO y hay OTs en estado CONFIRMADA del mismo tenant, Cuando el coordinador selecciona 3 OTs y las agrega al embarque, Entonces el sistema actualiza embarque_id en cada OT, recalcula total_ots (3), peso_total_kg (suma de peso_kg de las 3 OTs) y volumen_total_m3 (suma de volumen_m3 de las 3 OTs).

Escenario 3: Remover OT de un embarque

Dado que un embarque tiene 3 OTs agrupadas y ninguna esta en estado EN_PROCESO o posterior, Cuando el coordinador remueve una OT del embarque, Entonces el sistema limpia el campo embarque_id de la OT removida, recalcula los totales del embarque (total_ots = 2, peso y volumen actualizados).

Escenario 4: Asignar embarque a viaje

Dado que un embarque tiene al menos una OT agrupada, Cuando el coordinador asigna el embarque a un viaje existente, Entonces el sistema actualiza viaje_id en el embarque, actualiza viaje_id y embarque_id en cada OT del embarque, y cambia el estado de las OTs de CONFIRMADA a ASIGNADA.

Tareas Tecnicas

• Database: Verificar tabla transport.embarques con campos: codigo (VARCHAR(50)), descripcion (VARCHAR(500)), cliente_id (UUID), total_ots (INT DEFAULT 0), peso_total_kg (DECIMAL(12,2)), volumen_total_m3 (DECIMAL(12,4)), estado (VARCHAR(20) DEFAULT 'ABIERTO'), viaje_id (UUID). Verificar indices idx_embarque_tenant e idx_embarque_cliente. Verificar constraint uq_embarque_tenant_codigo.
• Backend: Crear entity Embarque mapeada a transport.embarques. Crear EmbarqueService con metodos: create(), addOts(), removeOt(), assignToViaje(), recalcularTotales(). Crear EmbarqueController con endpoints: POST /api/v1/embarques, GET /api/v1/embarques, GET /api/v1/embarques/:id, POST /api/v1/embarques/:id/ots (agregar OTs), DELETE /api/v1/embarques/:id/ots/:otId (remover OT), PATCH /api/v1/embarques/:id/asignar-viaje. Crear DTOs correspondientes.
• Frontend: Crear pagina EmbarquesListPage con listado de embarques y conteo de OTs. Crear pagina EmbarqueDetailPage con detalle del embarque y lista de OTs agrupadas. Implementar selector de OTs disponibles (CONFIRMADA, sin embarque) con filtros. Incluir resumen visual de capacidad (peso/volumen utilizados).
• Tests: Tests unitarios de recalculo de totales. Tests de integracion del flujo completo (crear embarque, agregar OTs, asignar a viaje). Tests de validacion de estados permitidos.

Dependencias

• Depende de: US-MAI003-001 (las OTs deben existir y estar CONFIRMADAS), MAI-002 (datos de clientes para cliente_id del embarque)
• Bloquea: MAI-004 (Planeacion - el embarque es la unidad de asignacion a viajes), MAI-005 (Despacho - el despacho opera sobre viajes con embarques)

Notas Tecnicas

• Endpoints: POST /api/v1/embarques, POST /api/v1/embarques/:id/ots, PATCH /api/v1/embarques/:id/asignar-viaje
• Entity: Embarque -> transport.embarques
• RLS: Politica tenant_isolation_embarques filtra por tenant_id
• Recalculo atomico: El metodo recalcularTotales() debe ejecutarse en una transaccion que actualice las OTs y los totales del embarque de forma atomica
• Generacion de codigo: Formato sugerido: EMB-{YYYY}-{SECUENCIAL:5}
• Validaciones de negocio: Solo OTs en estado CONFIRMADA pueden agregarse a un embarque. Una OT solo puede pertenecer a un embarque a la vez (embarque_id es nullable pero unico por OT activa). Al asignar a viaje, todas las OTs del embarque pasan a estado ASIGNADA

---

US-MAI003-004 - ERP Transportistas v1.0.0