# US-MAI003-009: Exportar listado de OTs

## Metadata

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

## Historia de Usuario

**Como** coordinador o ejecutivo de cuenta de una empresa transportista,
**quiero** exportar el listado de ordenes de transporte filtrado a formato CSV o Excel,
**para** compartir informacion con clientes, generar reportes internos y analizar datos operativos fuera del sistema.

## Descripcion Detallada

La exportacion de OTs permite a los usuarios descargar la informacion visible en el listado filtrado en formatos estandar para analisis externo. El usuario aplica los mismos filtros disponibles en la busqueda avanzada (US-MAI003-008) y solicita la descarga en formato CSV o Excel (XLSX).

El archivo exportado debe incluir las columnas principales de la OT: codigo, referencia del cliente, nombre del shipper, nombre del consignee, ciudades de origen y destino, fechas programadas de recoleccion y entrega, estado actual y total del servicio. El formato Excel incluye ademas encabezados estilizados, formato de fechas y moneda en las celdas.

Para volumenes mayores a 10,000 registros, la exportacion debe ejecutarse de forma asincrona, notificando al usuario cuando el archivo este listo para descarga. Para volumenes menores, la descarga es directa e inmediata.

## Criterios de Aceptacion

### Escenario 1: Exportar a CSV con filtros aplicados

**Dado** que el usuario tiene un listado filtrado de OTs (estado = CONFIRMADA, fecha enero 2026, 45 resultados),
**Cuando** presiona el boton "Exportar CSV",
**Entonces** el sistema genera y descarga un archivo CSV con 45 filas de datos mas encabezado, incluyendo las columnas: codigo, referencia_cliente, shipper_nombre, consignee_nombre, origen_ciudad, destino_ciudad, fecha_recoleccion_programada, fecha_entrega_programada, estado, total.

### Escenario 2: Exportar a Excel con formato

**Dado** que el usuario solicita exportacion en formato Excel,
**Cuando** selecciona "Exportar Excel",
**Entonces** el sistema genera un archivo XLSX con encabezados en negrita, columnas de fecha con formato dd/mm/yyyy, columna total con formato de moneda ($#,##0.00), y ancho de columnas ajustado al contenido.

### Escenario 3: Exportacion asincrona para grandes volumenes

**Dado** que el listado filtrado contiene mas de 10,000 registros,
**Cuando** el usuario solicita la exportacion,
**Entonces** el sistema muestra un mensaje "La exportacion se esta procesando. Recibira una notificacion cuando el archivo este listo." y ejecuta la generacion en segundo plano, notificando al usuario al completarse.

### Escenario 4: Exportacion sin resultados

**Dado** que los filtros aplicados no retornan resultados,
**Cuando** el usuario intenta exportar,
**Entonces** el sistema muestra un mensaje "No hay datos para exportar con los filtros seleccionados" y no genera ningun archivo.

## Tareas Tecnicas

- **Database:** Reutilizar la misma consulta de `findAll()` de US-MAI003-008 sin paginacion (o con paginacion extendida) para obtener todos los registros del filtro.
- **Backend:** Agregar metodo `exportCsv(filters)` y `exportExcel(filters)` en `OrdenTransporteService`. Configurar endpoint GET `/api/v1/ordenes-transporte/exportar?formato=csv` y `formato=xlsx` con los mismos query params de filtros que el listado. Para CSV, usar streaming con content-type text/csv. Para Excel, usar libreria exceljs para generar XLSX en memoria. Implementar logica de exportacion asincrona (Bull queue) cuando el conteo excede 10,000 registros.
- **Frontend:** Agregar botones "Exportar CSV" y "Exportar Excel" en la barra de acciones del listado. Los botones envian los filtros actuales al endpoint de exportacion. Para descargas directas, usar window.open o fetch + blob. Para exportaciones asincronas, mostrar snackbar de progreso y notificacion al completar.
- **Tests:** Tests unitarios de generacion de CSV (formato, columnas, datos). Tests unitarios de generacion de Excel (formato de celdas). Tests de integracion del endpoint de exportacion. Tests del umbral de exportacion asincrona (>10,000 registros).

## Dependencias

- **Depende de:** US-MAI003-008 (busqueda con filtros avanzados)
- **Bloquea:** Ninguno directamente

## Notas Tecnicas

- **Endpoint:** GET `/api/v1/ordenes-transporte/exportar?formato=csv&estado=CONFIRMADA&fecha_desde=...`
- **Content-Type CSV:** `text/csv; charset=utf-8` con header `Content-Disposition: attachment; filename="ordenes-transporte-2026-01-27.csv"`
- **Content-Type Excel:** `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` con header `Content-Disposition: attachment; filename="ordenes-transporte-2026-01-27.xlsx"`
- **Libreria Excel:** exceljs (compatible con NestJS, soporta streaming para grandes volumenes)
- **Limite duro:** Maximo 50,000 registros por exportacion. Si excede, informar al usuario que refine los filtros
- **Columnas exportadas:** codigo, referencia_cliente, shipper_nombre, consignee_nombre, origen_ciudad, origen_estado, destino_ciudad, destino_estado, tipo_carga, fecha_recoleccion_programada, fecha_entrega_programada, estado, peso_kg, volumen_m3, piezas, pallets, total, moneda
- **Encoding CSV:** UTF-8 con BOM para compatibilidad con Excel en espanol

---

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