Adrian Flores Cortes ec43d9c6cd docs: Add Phase 3 secondary modules specifications (P1/P2/P3)

Modules documented:
- MAI-003 (OT): README, REQUERIMIENTOS, RESUMEN-EPICA, 10 US
- MAI-006 (Tracking): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-008 (Incidencias): 3 US (18 SP)
- MAI-011 (Flota): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-012 (Combustible): 3 US (18 SP)
- MAI-013 (Mantenimiento): 3 US (18 SP)
- MAI-014 (Carriers): 3 US (18 SP)
- MAI-015 (Portal): 3 US (18 SP)
- MAE-016 (Carta Porte): 10 US
- MAE-017 (HOS): 3 US (16 SP)
- MAE-018 (Reportes): 3 US (18 SP)

Phase 2+3 complete: 13 modules, 50+ User Stories

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-27 02:24:35 -06:00

5.3 KiB

Raw Blame History

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

5.3 KiB Raw Blame History