# US-MAI003-008: Buscar OTs con filtros avanzados

## Metadata

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

## Historia de Usuario

**Como** despachador, coordinador o ejecutivo de cuenta de una empresa transportista,
**quiero** buscar ordenes de transporte utilizando multiples filtros combinados (estado, cliente, fechas, tipo de carga, codigo),
**para** localizar rapidamente las OTs que necesito gestionar y tener visibilidad del estado de las operaciones.

## Descripcion Detallada

El listado de OTs con filtros avanzados es la pantalla principal del modulo de ordenes de transporte. Los usuarios necesitan filtrar y navegar grandes volumenes de OTs de forma eficiente. La tabla `ordenes_transporte` cuenta con indices especificos para las columnas de filtrado mas frecuentes: idx_ot_estado (tenant_id, estado), idx_ot_shipper (tenant_id, shipper_id) e idx_ot_fechas (tenant_id, fecha_recoleccion_programada).

El sistema debe soportar filtros combinados por: estado de la OT (uno o varios), shipper (cliente), rango de fechas de recoleccion y entrega, tipo de carga, codigo de OT (busqueda parcial), referencia del cliente, y existencia de embarque o viaje asignado. Los resultados deben ser paginados, ordenables por cualquier columna, y la respuesta debe incluir metadatos de paginacion.

La busqueda por codigo y referencia_cliente debe soportar coincidencia parcial (LIKE/ILIKE) para facilitar la localizacion rapida cuando el usuario no recuerda el codigo completo.

## Criterios de Aceptacion

### Escenario 1: Filtrar OTs por estado

**Dado** que el tenant tiene OTs en distintos estados,
**Cuando** el usuario selecciona el filtro estado = "CONFIRMADA",
**Entonces** el sistema retorna solo las OTs en estado CONFIRMADA del tenant actual, paginadas con 20 registros por pagina, usando el indice idx_ot_estado.

### Escenario 2: Filtrar por shipper y rango de fechas

**Dado** que el usuario necesita ver las OTs de un cliente especifico en enero 2026,
**Cuando** selecciona shipper_id = "uuid-cliente-x" y rango fecha_recoleccion_programada entre 2026-01-01 y 2026-01-31,
**Entonces** el sistema retorna las OTs que coinciden con ambos criterios, ordenadas por fecha_recoleccion_programada descendente.

### Escenario 3: Busqueda parcial por codigo

**Dado** que el usuario recuerda parcialmente el codigo de una OT,
**Cuando** ingresa "2026-001" en el campo de busqueda por codigo,
**Entonces** el sistema retorna todas las OTs cuyo codigo contiene "2026-001" (busqueda case-insensitive con ILIKE).

### Escenario 4: Multiples filtros combinados con paginacion

**Dado** que el usuario aplica filtros de estado (CONFIRMADA, ASIGNADA), tipo_carga (REFRIGERADA) y rango de fechas,
**Cuando** la busqueda retorna 85 resultados,
**Entonces** el sistema muestra los primeros 20 resultados con metadatos de paginacion: { total: 85, page: 1, pageSize: 20, totalPages: 5 } y permite navegar entre paginas.

## Tareas Tecnicas

- **Database:** Verificar indices existentes: idx_ot_tenant (tenant_id), idx_ot_estado (tenant_id, estado), idx_ot_shipper (tenant_id, shipper_id), idx_ot_fechas (tenant_id, fecha_recoleccion_programada). Evaluar si se requieren indices adicionales para combinaciones frecuentes.
- **Backend:** Agregar metodo `findAll(filters, pagination, sort)` en `OrdenTransporteService` con QueryBuilder de TypeORM para construir consultas dinamicas con filtros opcionales. Configurar endpoint GET `/api/v1/ordenes-transporte` con query params: `?estado=CONFIRMADA&shipper_id=uuid&fecha_desde=2026-01-01&fecha_hasta=2026-01-31&tipo_carga=REFRIGERADA&codigo=OT-2026&referencia=PO-123&page=1&pageSize=20&sort=fecha_recoleccion_programada&order=DESC`. Crear `FilterOrdenTransporteDto` con decoradores de validacion y transformacion. Implementar paginacion con respuesta estandar (data, total, page, pageSize, totalPages).
- **Frontend:** Crear pagina `OrdenesTransporteListPage` con tabla paginada, columnas ordenables y panel de filtros colapsable. Implementar filtros: dropdown multi-select para estado, autocompletado para shipper, date pickers para rangos de fechas, dropdown para tipo_carga, campo de texto para codigo y referencia. Persistir filtros en URL query params para compartir enlaces. Incluir indicador de resultados totales y paginacion con navegacion por paginas.
- **Tests:** Tests unitarios de construccion de query con diferentes combinaciones de filtros. Tests de integracion del endpoint con parametros de busqueda. Tests de paginacion (primera pagina, ultima pagina, fuera de rango). Tests de busqueda parcial por codigo (ILIKE).

## Dependencias

- **Depende de:** US-MAI003-001 (las OTs deben existir)
- **Bloquea:** US-MAI003-009 (la exportacion opera sobre el mismo listado filtrado)

## Notas Tecnicas

- **Endpoint:** GET `/api/v1/ordenes-transporte`
- **Query params:** `estado` (string o array), `shipper_id` (UUID), `fecha_desde` (ISO date), `fecha_hasta` (ISO date), `tipo_carga` (enum), `codigo` (string, busqueda parcial), `referencia` (string, busqueda parcial), `tiene_embarque` (boolean), `tiene_viaje` (boolean), `page` (int, default 1), `pageSize` (int, default 20, max 100), `sort` (string), `order` (ASC/DESC)
- **RLS:** Todas las consultas se filtran automaticamente por tenant_id via la politica tenant_isolation_ot
- **Performance:** Filtro por deleted_at IS NULL (soft delete) debe ser la primera condicion. Los indices idx_ot_estado e idx_ot_shipper son parciales por tenant_id, lo que optimiza queries multi-tenant
- **Busqueda parcial:** Usar `ILIKE '%valor%'` para codigo y referencia_cliente. Para volumenes muy altos, evaluar pg_trgm para busqueda por trigramas

---

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