# US-MAE018-003: Reportes personalizados

**ID:** US-MAE018-003
**Modulo:** MAE-018 (Reportes y KPIs)
**Prioridad:** Media
**Story Points:** 5

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** generar reportes personalizados con los datos que necesito
**Para** analizar informacion especifica y compartirla

---

## Criterios de Aceptacion

### CA-001: Catalogo de reportes
**Dado** que hay reportes predefinidos
**Cuando** accedo al modulo de reportes
**Entonces** veo catalogo por categoria (operaciones, finanzas, flota)

### CA-002: Parametros de reporte
**Dado** que ejecuto un reporte
**Cuando** lo configuro
**Entonces** puedo filtrar por fechas, clientes, rutas

### CA-003: Vista previa
**Dado** que configure los parametros
**Cuando** ejecuto el reporte
**Entonces** veo vista previa antes de exportar

### CA-004: Multiples formatos
**Dado** que necesito compartir el reporte
**Cuando** exporto
**Entonces** puedo elegir Excel, PDF o CSV

### CA-005: Programar envio
**Dado** que necesito reportes periodicos
**Cuando** configuro programacion
**Entonces** se envia automaticamente por email

---

## Mockup / UI

### Catalogo de Reportes

```
+----------------------------------------------------------+
| REPORTES                                                 |
+----------------------------------------------------------+
|                                                          |
|  Buscar: [________________________] [Q]                 |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  OPERACIONES                                            |
|                                                          |
|  [icon] Viajes por periodo                             |
|         Listado de viajes con filtros                   |
|                                                          |
|  [icon] Performance OTIF                               |
|         Detalle de entregas a tiempo                    |
|                                                          |
|  [icon] Incidencias detallado                          |
|         Listado con costos y resoluciones              |
|                                                          |
|  [icon] Detention por cliente                          |
|         Tiempos de espera en carga/descarga            |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  FINANCIEROS                                            |
|                                                          |
|  [icon] Rentabilidad por cliente                       |
|         Ingresos, costos y margen por cliente          |
|                                                          |
|  [icon] Rentabilidad por ruta                          |
|         Analisis de lanes rentables                    |
|                                                          |
|  [icon] Costos por viaje                               |
|         Desglose de combustible, peajes, etc.          |
|                                                          |
|  [icon] Facturacion pendiente                          |
|         Viajes cerrados sin facturar                   |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  FLOTA                                                  |
|                                                          |
|  [icon] Rendimiento de combustible                     |
|         km/litro por unidad y operador                 |
|                                                          |
|  [icon] Historial de mantenimiento                     |
|         OTs por unidad con costos                      |
|                                                          |
|  [icon] Disponibilidad historica                       |
|         % disponibilidad por periodo                   |
|                                                          |
+----------------------------------------------------------+
```

### Ejecutar Reporte

```
+----------------------------------------------------------+
| REPORTE: Rentabilidad por Cliente                     X  |
+----------------------------------------------------------+
|                                                          |
|  PARAMETROS                                             |
|                                                          |
|  Periodo: [01-ene-2026] a [31-ene-2026]                |
|                                                          |
|  Clientes:                                              |
|  (o) Todos                                              |
|  ( ) Seleccionar: [________________________]           |
|                                                          |
|  Incluir:                                               |
|  [x] Desglose de costos                                |
|  [x] Comparativo mes anterior                          |
|  [ ] Solo clientes con margen < 15%                    |
|                                                          |
|  Ordenar por: [Margen descendente           v]         |
|                                                          |
|  [Ejecutar]                                            |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  VISTA PREVIA                                           |
|                                                          |
|  | Cliente      | Viajes | Ingreso   | Costo    |Margen||
|  |--------------|--------|-----------|----------|------||
|  | Liverpool    |   45   | $820,000  | $664,200 |19.2% ||
|  | Bimbo        |   32   | $580,000  | $476,600 |17.8% ||
|  | Soriana      |   25   | $450,000  | $366,750 |18.5% ||
|  | Walmart      |   28   | $510,000  | $435,900 |14.5% ||
|  | CEMEX        |   38   | $690,000  | $585,810 |15.1% ||
|  |--------------|--------|-----------|----------|------||
|  | TOTAL        |  168   |$3,050,000 |$2,529,260|17.1% ||
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  EXPORTAR                                               |
|                                                          |
|  Formato: (o) Excel  ( ) PDF  ( ) CSV                  |
|                                                          |
|  [Descargar]                                           |
|                                                          |
|  ------------------------------------------------------ |
|                                                          |
|  PROGRAMAR ENVIO                                        |
|                                                          |
|  [ ] Enviar automaticamente                            |
|      Frecuencia: [Semanal       v]                     |
|      Dia: [Lunes          v]                           |
|      Destinatarios: [controller@empresa.com         ]  |
|                                                          |
|  [Guardar programacion]                                |
|                                                          |
+----------------------------------------------------------+
```

---

## Reportes Predefinidos

| Categoria | Reporte | Parametros |
|-----------|---------|------------|
| Operaciones | Viajes por periodo | Fechas, cliente, estado |
| Operaciones | Performance OTIF | Fechas, cliente, dimension |
| Operaciones | Incidencias | Fechas, tipo, estado |
| Financiero | Rentabilidad cliente | Fechas, cliente |
| Financiero | Rentabilidad ruta | Fechas, origen, destino |
| Financiero | Costos por viaje | Fechas, viaje |
| Flota | Rendimiento combustible | Fechas, unidad, operador |
| Flota | Historial mantenimiento | Fechas, unidad |
| Carriers | Scorecard carriers | Periodo, carrier |

---

## Notas Tecnicas

- Generador de reportes con templates
- Exportacion: xlsx (exceljs), PDF (puppeteer)
- Jobs programados para envio automatico
- Cola de reportes para reportes pesados

---

## Definicion de Done

- [ ] Catalogo de reportes por categoria
- [ ] Formulario de parametros
- [ ] Vista previa de resultados
- [ ] Exportacion Excel, PDF, CSV
- [ ] Programacion de envio automatico
- [ ] Cola para reportes pesados
- [ ] Tests de generacion de reportes