# US-MAI003-005: Consultar status de OT

## Metadata

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

## Historia de Usuario

**Como** despachador o ejecutivo de cuenta de una empresa transportista,
**quiero** consultar el estado actual y el historial de una orden de transporte,
**para** informar al cliente sobre el progreso de su envio y tomar decisiones operativas oportunas.

## Descripcion Detallada

La consulta de status de OT es una operacion frecuente en el dia a dia operativo. Los despachadores y ejecutivos de cuenta necesitan verificar rapidamente en que fase se encuentra cada OT para responder consultas de clientes, coordinar con el equipo de planeacion y monitorear el avance general de las operaciones.

La consulta muestra el estado actual de la OT (BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA o CANCELADA), los datos principales del servicio (shipper, consignee, origen, destino, fechas programadas), la asignacion operativa (embarque y viaje asociados si existen) y los datos financieros (tarifa, total).

Adicionalmente, el sistema debe mostrar un timeline con las transiciones de estado de la OT, incluyendo fecha/hora y usuario responsable de cada cambio, utilizando los campos de auditoria (created_at, updated_at, created_by_id, updated_by_id).

## Criterios de Aceptacion

### Escenario 1: Consulta por codigo de OT

**Dado** que existe una OT con codigo OT-2026-00015 en el tenant actual,
**Cuando** el usuario busca por codigo "OT-2026-00015",
**Entonces** el sistema muestra la vista de detalle con el estado actual, datos del servicio, ubicaciones, carga, tarifa, embarque y viaje asociados.

### Escenario 2: Visualizacion del estado actual con indicador visual

**Dado** que una OT se encuentra en estado EN_PROCESO,
**Cuando** el usuario consulta el detalle de la OT,
**Entonces** el sistema muestra un indicador visual (badge de color) del estado actual y un timeline que refleja los estados por los que ha pasado la OT con fecha, hora y usuario de cada transicion.

### Escenario 3: Consulta de OT con embarque y viaje asociados

**Dado** que una OT esta en estado ASIGNADA con embarque_id y viaje_id poblados,
**Cuando** el usuario consulta el detalle,
**Entonces** el sistema muestra los datos del embarque (codigo, total de OTs, peso/volumen total) y del viaje (codigo, unidad, operador, fechas de salida/llegada programadas) con enlaces para navegar al detalle de cada uno.

### Escenario 4: Consulta de OT inexistente

**Dado** que el usuario busca una OT con un ID o codigo que no existe en su tenant,
**Cuando** realiza la consulta,
**Entonces** el sistema devuelve un error 404 con mensaje "Orden de transporte no encontrada".

## Tareas Tecnicas

- **Database:** Utilizar las tablas existentes `transport.ordenes_transporte`, `transport.embarques` y `transport.viajes` con JOINs para obtener datos relacionados. Los indices idx_ot_tenant y uq_ot_tenant_codigo soportan la busqueda por id y codigo.
- **Backend:** Agregar metodo `findById()` y `findByCodigo()` en `OrdenTransporteService` que retorne la OT con relaciones cargadas (embarque, viaje). Configurar endpoint GET `/api/v1/ordenes-transporte/:id` con query parameter opcional `?include=embarque,viaje` para cargar relaciones. Crear `OrdenTransporteDetailDto` con datos completos de la OT.
- **Frontend:** Crear pagina `OrdenTransporteDetailPage` con secciones: informacion general, origen/destino (con mapa), datos de carga, restricciones, tarifa/costos, embarque asignado, viaje asignado, timeline de estados. Implementar badge de colores por estado. Incluir acciones contextuales segun estado (confirmar, cancelar, editar).
- **Tests:** Tests unitarios de consulta por id y codigo. Tests de integracion del endpoint GET con relaciones. Tests de manejo de OT inexistente (404).

## Dependencias

- **Depende de:** US-MAI003-001 (la OT debe existir)
- **Bloquea:** Ninguno directamente (funcionalidad de solo lectura)

## Notas Tecnicas

- **Endpoint:** GET `/api/v1/ordenes-transporte/:id`
- **Query params:** `?include=embarque,viaje` para cargar relaciones lazy
- **RLS:** La consulta esta automaticamente filtrada por tenant_id via RLS policy
- **Timeline:** Dado que la tabla no almacena un historial explícito de transiciones, inicialmente el timeline se construye con created_at (creacion) y updated_at (ultima actualizacion). En una fase futura se recomienda implementar una tabla de historial de estados o usar la tabla de auditoria del modulo MAI-001
- **Performance:** La consulta por UUID (PK) es O(1). La consulta por codigo usa el indice uq_ot_tenant_codigo

---

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