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

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