# US-MGN009-001: Ejecutar Reportes Predefinidos

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN009-001 |
| **Modulo** | MGN-009 Reports |
| **Sprint** | Sprint 6 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 10 |
| **Estado** | Ready |
| **RF Relacionado** | RF-REPORT-001 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** ejecutar reportes predefinidos con parametros configurables
**Para** obtener informacion estructurada en diferentes formatos de salida

---

## Descripcion

El sistema proporciona reportes predefinidos por modulo con parametros configurables. Los usuarios pueden ver resultados en pantalla con paginacion o exportar a PDF, Excel, CSV. Los reportes grandes se procesan asincronamente.

### Contexto

- Reportes predefinidos por modulo
- Parametros configurables
- Exportacion multiformato
- Cache de resultados frecuentes

---

## Criterios de Aceptacion

### Escenario 1: Listar reportes disponibles

```gherkin
Given un usuario con permiso "reports.view"
When accede a GET /api/v1/reports
Then el sistema responde con status 200
  And retorna lista de reportes agrupados por modulo
  And solo muestra reportes para los que tiene permiso
```

### Escenario 2: Ver parametros de reporte

```gherkin
Given un reporte "balance_general"
When consulta sus detalles
Then muestra los parametros disponibles:
  | fecha_corte | date | required |
  | nivel_detalle | select | options: [1,2,3,4] |
  And muestra valores por defecto
```

### Escenario 3: Ejecutar reporte (vista)

```gherkin
Given un usuario ejecutando reporte
When envia POST /api/v1/reports/balance_general/execute
  | fecha_corte | "2025-12-05" |
  | nivel | 3 |
Then el sistema responde con status 200
  And retorna datos con columnas y filas
  And incluye totales si aplica
  And soporta paginacion
```

### Escenario 4: Exportar a Excel

```gherkin
Given un reporte ejecutado
When solicita POST /api/v1/reports/balance_general/export
  | format | "xlsx" |
  | parameters | {...} |
Then retorna jobId para tracking
  And el proceso se ejecuta asincronamente
```

### Escenario 5: Consultar estado de exportacion

```gherkin
Given una exportacion en proceso
When consulta GET /api/v1/reports/executions/{id}
Then retorna status y progreso
  And cuando completa incluye downloadUrl
  And indica expiresAt para el archivo
```

### Escenario 6: Exportar a PDF

```gherkin
Given un reporte con < 500 filas
When exporta a PDF
Then genera archivo PDF formateado
  And incluye header con logo y titulo
  And incluye fecha de generacion
```

### Escenario 7: Ordenar resultados

```gherkin
Given un reporte con multiples columnas
When especifica sort = { field: "total", order: "desc" }
Then los resultados se ordenan por total descendente
```

### Escenario 8: Filtrar por modulo

```gherkin
Given reportes de multiples modulos
When consulta GET /api/v1/reports?module=financial
Then retorna solo reportes del modulo financiero
```

### Escenario 9: Cache de resultados

```gherkin
Given un reporte ejecutado recientemente con mismos parametros
When otro usuario ejecuta el mismo reporte
Then los resultados se sirven desde cache
  And el tiempo de respuesta es < 100ms
```

### Escenario 10: Reporte con datos vacios

```gherkin
Given parametros que no retornan datos
When ejecuta el reporte
Then retorna array vacio con mensaje informativo
  And la exportacion no genera error
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  REPORTES                                                         |
+------------------------------------------------------------------+
| [Modulo: Todos v]  [Categoria: Todas v]  [Buscar...]              |
+------------------------------------------------------------------+

CONTABILIDAD
+------------------------------------------------------------------+
| Balance General                              [Ver] [Ejecutar]     |
|   Estado de situacion financiera a una fecha                      |
|                                                                   |
| Estado de Resultados                         [Ver] [Ejecutar]     |
|   Ingresos y gastos del periodo                                   |
|                                                                   |
| Libro Mayor                                  [Ver] [Ejecutar]     |
|   Movimientos por cuenta contable                                 |
+------------------------------------------------------------------+

VENTAS
+------------------------------------------------------------------+
| Ventas por Cliente                           [Ver] [Ejecutar]     |
|   Resumen de ventas agrupado por cliente                          |
+------------------------------------------------------------------+

Modal: Ejecutar Reporte
+------------------------------------------------------------------+
| EJECUTAR REPORTE: Balance General                            [X]  |
+------------------------------------------------------------------+
| Descripcion: Estado de situacion financiera a una fecha          |
|                                                                   |
| PARAMETROS                                                        |
+------------------------------------------------------------------+
| Fecha de Corte*         | [2025-12-05      ] [📅]                |
| Nivel de Detalle        | [3 - Subcuentas v ]                    |
| Incluir cuentas en cero | [ ]                                    |
+------------------------------------------------------------------+
|                                                                   |
|  [Cancelar]  [Excel v] [PDF]  [=== Ejecutar ===]                 |
+------------------------------------------------------------------+

Resultados:
+------------------------------------------------------------------+
| BALANCE GENERAL                           Al 05 de Diciembre 2025 |
+------------------------------------------------------------------+
| [Exportar: Excel v]  [PDF]  [CSV]                  Pagina 1 de 5 |
+------------------------------------------------------------------+

| CUENTA        | NOMBRE               | SALDO DEUDOR | SALDO ACREE |
+------------------------------------------------------------------+
| 1             | ACTIVO               |              |              |
|   1.1         |   Activo Circulante  |              |              |
|     1.1.1     |     Caja             |     50,000   |              |
|     1.1.2     |     Bancos           |    200,000   |              |
|   1.2         |   Activo Fijo        |              |              |
|     1.2.1     |     Mobiliario       |    150,000   |              |
+------------------------------------------------------------------+
| TOTAL ACTIVO                           |    400,000   |              |
+------------------------------------------------------------------+
| 2             | PASIVO               |              |              |
|   2.1         |   Pasivo Corto Plazo |              |              |
|     2.1.1     |     Proveedores      |              |    100,000   |
+------------------------------------------------------------------+
| TOTAL PASIVO                           |              |    100,000   |
+------------------------------------------------------------------+
| 3             | CAPITAL              |              |              |
|   3.1         |   Capital Social     |              |    250,000   |
|   3.2         |   Resultado Ejerc.   |              |     50,000   |
+------------------------------------------------------------------+
| TOTAL CAPITAL                          |              |    300,000   |
+------------------------------------------------------------------+
                                    [< Anterior] [1] [2] [Siguiente >]
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /reports | Listar disponibles |
| GET | /reports/:code | Detalle de reporte |
| POST | /reports/:code/execute | Ejecutar (vista) |
| POST | /reports/:code/export | Exportar |
| GET | /reports/executions/:id | Estado exportacion |

### Tipos de Parametros

| Tipo | UI Component | Ejemplo |
|------|--------------|---------|
| date | DatePicker | fecha_corte |
| date_range | RangePicker | periodo |
| select | Dropdown | nivel_detalle |
| multiselect | MultiSelect | cuentas |
| entity | EntitySearch | cliente_id |
| boolean | Checkbox | incluir_ceros |

### Cache

```typescript
// Cache key basado en reporte + params + tenant
const cacheKey = `report:${code}:${tenantId}:${hash(params)}`;
const TTL = 5 * 60; // 5 minutos
```

---

## Definicion de Done

- [ ] Catalogo de reportes predefinidos
- [ ] UI de parametros dinamica
- [ ] Ejecucion con paginacion
- [ ] Exportacion PDF, Excel, CSV
- [ ] Jobs asincronos para exportacion
- [ ] Cache de resultados
- [ ] Permisos por reporte
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla report_definitions | Definiciones |
| Tabla report_executions | Historial |
| Bull Queue | Para exportacion |
| ExcelJS | Para XLSX |
| Puppeteer | Para PDF |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN009-003 | Report Builder |
| US-MGN009-004 | Reportes Programados |

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial |
