# 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*