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

US-MAI003-001: Crear orden de transporte

Metadata

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

Historia de Usuario

Como despachador de una empresa transportista, quiero crear una orden de transporte con todos los datos del servicio solicitado por el cliente, para registrar formalmente la demanda de transporte y que pueda ser procesada por el equipo de planeacion y operaciones.

Descripcion Detallada

La creacion de una OT es el punto de entrada del flujo operativo de transporte. El despachador recibe la solicitud del cliente (por telefono, email o portal) y registra toda la informacion necesaria para ejecutar el servicio: datos del shipper y consignee, ubicaciones de origen y destino con coordenadas geograficas, fechas y ventanas de tiempo para recoleccion y entrega, caracteristicas de la carga (tipo, peso, volumen, piezas, pallets, valor declarado) y la tarifa aplicable.

El sistema debe generar automaticamente un codigo unico de OT por tenant (por ejemplo, OT-2026-00001) y registrar al usuario creador. La OT se crea en estado BORRADOR, permitiendo al despachador completar o modificar los datos antes de confirmarla.

Los campos de origen y destino incluyen datos de geolocalizacion (latitud/longitud) que seran utilizados posteriormente por los modulos de planeacion (MAI-004) y tracking (MAI-006). La tarifa se calcula automaticamente al asociar un tarifario, aplicando recargos y descuentos para obtener el total del servicio.

Criterios de Aceptacion

Escenario 1: Creacion exitosa con datos obligatorios

Dado que el despachador tiene permisos de creacion de OT y existe al menos un cliente registrado, Cuando completa el formulario con los datos obligatorios (shipper, consignee, origen, destino) y presiona guardar, Entonces el sistema crea la OT en estado BORRADOR con un codigo unico generado automaticamente, registra created_at y created_by_id, y muestra el detalle de la OT creada.

Escenario 2: Validacion de datos obligatorios

Dado que el despachador esta creando una nueva OT, Cuando intenta guardar sin completar los campos obligatorios (shipper_id, shipper_nombre, consignee_id, consignee_nombre, origen_direccion, destino_direccion, created_by_id), Entonces el sistema muestra mensajes de validacion indicando los campos faltantes y no crea la OT.

Escenario 3: Codigo unico por tenant

Dado que el tenant ya tiene OTs registradas, Cuando se crea una nueva OT, Entonces el sistema genera un codigo que no exista previamente para ese tenant, respetando la constraint uq_ot_tenant_codigo.

Escenario 4: Registro completo de carga y tarifas

Dado que el despachador esta creando una OT con datos de carga completos, Cuando selecciona tipo_carga, ingresa peso_kg, volumen_m3, piezas, pallets, valor_declarado y asocia una tarifa_id, Entonces el sistema calcula tarifa_base, recargos, descuentos, subtotal, IVA y total automaticamente y los almacena en la OT.

Tareas Tecnicas

• Database: Verificar que la tabla transport.ordenes_transporte existe con todos los campos del DDL, incluyendo indices idx_ot_tenant, idx_ot_estado, idx_ot_shipper, idx_ot_fechas y constraint uq_ot_tenant_codigo.
• Backend: Crear entity OrdenTransporte mapeada a transport.ordenes_transporte. Crear OrdenTransporteService con metodo create() que valide datos obligatorios, genere codigo unico y calcule tarifas. Crear OrdenTransporteController con endpoint POST /api/v1/ordenes-transporte. Crear DTOs: CreateOrdenTransporteDto con validaciones class-validator.
• Frontend: Crear pagina OrdenesTransporteCreatePage con formulario multi-seccion (datos generales, origen/destino, carga, tarifas). Incluir seleccion de shipper y consignee con autocompletado. Incluir mapa para seleccion de coordenadas.
• Tests: Tests unitarios del servicio (validacion, generacion de codigo, calculo de tarifas). Tests de integracion del endpoint POST. Tests e2e del flujo completo de creacion.

Dependencias

• Depende de: MAI-001 (Auth - autenticacion y permisos), MAI-002 (Clientes - catalogo de shippers/consignees y tarifas)
• Bloquea: US-MAI003-002 (paradas), US-MAI003-003 (restricciones), US-MAI003-004 (embarques), US-MAI003-005 (consulta status), US-MAI003-006 (modificar), US-MAI003-007 (cancelar)

Notas Tecnicas

• Endpoint: POST /api/v1/ordenes-transporte
• Entity: OrdenTransporte -> transport.ordenes_transporte
• RLS: La politica tenant_isolation_ot filtra por tenant_id = current_setting('app.tenant_id')::uuid
• Generacion de codigo: Implementar secuencia por tenant, formato sugerido: OT-{YYYY}-{SECUENCIAL:5}
• Calculo de tarifa: Consultar tarifa vigente del modulo MAI-002, aplicar recargos del catalogo de billing, calcular IVA al 16%
• Coordenadas: Campos origen_latitud, origen_longitud, destino_latitud, destino_longitud como DECIMAL(10,7) para precision de ~1cm

---

US-MAI003-001 - ERP Transportistas v1.0.0