# US-MGN009-004: Programar Ejecucion Automatica de Reportes

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN009-004 |
| **Modulo** | MGN-009 Reports |
| **Sprint** | Sprint 6 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 5 |
| **Estado** | Ready |
| **RF Relacionado** | RF-REPORT-004 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador
**Quiero** programar ejecucion automatica de reportes
**Para** recibir informacion periodica sin tener que ejecutar manualmente

---

## Descripcion

Los reportes se pueden programar para ejecutarse automaticamente (diario, semanal, mensual) y enviarse por email a destinatarios configurados. Soporta parametros dinamicos con fechas relativas.

### Contexto

- Programacion con expresiones cron
- Envio automatico por email
- Parametros con fechas relativas
- Historial de ejecuciones

---

## Criterios de Aceptacion

### Escenario 1: Listar programaciones

```gherkin
Given un usuario con reportes programados
When accede a GET /api/v1/reports/schedules
Then retorna lista de programaciones
  And muestra proxima ejecucion
  And muestra ultima ejecucion
```

### Escenario 2: Crear programacion diaria

```gherkin
Given un reporte existente
When crea programacion:
  | schedule.type | "cron" |
  | schedule.cron | "0 8 * * *" |
  | timezone | "America/Mexico_City" |
Then se calcula nextRunAt = manana 8:00 AM
  And la programacion queda activa
```

### Escenario 3: Programacion semanal

```gherkin
Given necesidad de reporte semanal
When configura:
  | schedule.cron | "0 8 * * 1" |
Then el reporte se ejecuta cada lunes a las 8:00
```

### Escenario 4: Parametros con fechas relativas

```gherkin
Given reporte con parametro fecha_desde
When configura:
  | fecha_desde | { type: "relative_date", value: "start_of_week" } |
Then al ejecutar, fecha_desde = inicio de la semana actual
```

### Escenario 5: Configurar destinatarios

```gherkin
Given programacion creada
When agrega destinatarios:
  | type: "user", value: "uuid-user" |
  | type: "email", value: "externo@mail.com" |
  | type: "role", value: "sales_manager" |
Then al ejecutar se envia a todos los destinatarios
```

### Escenario 6: Ejecucion automatica

```gherkin
Given programacion activa con nextRunAt = ahora
When el cron job se ejecuta
Then el reporte se genera
  And se envia por email con adjunto
  And se actualiza lastRunAt y nextRunAt
```

### Escenario 7: Skip si sin datos

```gherkin
Given programacion con skipIfEmpty = true
  And el reporte no tiene datos para el periodo
When se ejecuta
Then NO se envia email
  And se registra como "skipped"
```

### Escenario 8: Ejecutar manualmente

```gherkin
Given programacion existente
When envia POST /api/v1/reports/schedules/{id}/run
Then el reporte se ejecuta inmediatamente
  And no afecta la proxima ejecucion programada
```

### Escenario 9: Pausar programacion

```gherkin
Given programacion activa
When cambia isActive = false
Then la programacion se pausa
  And no se ejecuta hasta reactivar
```

### Escenario 10: Ver historial de ejecuciones

```gherkin
Given programacion con ejecuciones previas
When consulta GET /api/v1/reports/schedules/{id}/history
Then retorna lista de ejecuciones:
  | startedAt, status, duration, rowCount, recipientsSent |
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  REPORTES PROGRAMADOS                         [+ Nueva Programacion]|
+------------------------------------------------------------------+
| [Estado: Todos v]  [Buscar...]                                    |
+------------------------------------------------------------------+

| NOMBRE              | REPORTE         | FRECUENCIA | PROXIMA | ESTADO |
+------------------------------------------------------------------+
| Ventas Semanales    | Ventas x Cliente| Lunes 8:00 | 09/12   | ✓ Activo |
| Balance Mensual     | Balance General | Dia 1 8:00 | 01/01   | ✓ Activo |
| Inventario Diario   | Stock Bajo      | Diario 7:00| 06/12   | ⏸ Pausado|
+------------------------------------------------------------------+

Detalle de Programacion:
+------------------------------------------------------------------+
| VENTAS SEMANALES                                            [⚙] [▶]|
+------------------------------------------------------------------+
| Reporte: Ventas por Cliente                                       |
| Formato: Excel                                                    |
| Programacion: Cada lunes a las 8:00 AM (America/Mexico_City)     |
| Proxima ejecucion: Lunes 9 de Diciembre 2025, 8:00 AM            |
|                                                                   |
| PARAMETROS                                                        |
| - fecha_desde: Inicio de la semana                               |
| - fecha_hasta: Fin de la semana                                   |
|                                                                   |
| DESTINATARIOS                                                     |
| - Juan Perez (juan@empresa.com)                                   |
| - Maria Garcia (maria@empresa.com)                                |
| - Rol: Gerentes de Ventas (3 usuarios)                           |
|                                                                   |
| OPCIONES                                                          |
| [✓] No enviar si no hay datos                                    |
| [✓] Adjuntar archivo                                              |
| [✓] Incluir link al reporte                                       |
+------------------------------------------------------------------+

+------------------------------------------------------------------+
| HISTORIAL DE EJECUCIONES                                          |
+------------------------------------------------------------------+
| FECHA              | ESTADO    | DURACION | FILAS | ENVIADOS      |
+------------------------------------------------------------------+
| 2025-12-02 08:00   | ✓ Exito   | 15s      | 150   | 5             |
| 2025-11-25 08:00   | ✓ Exito   | 12s      | 142   | 5             |
| 2025-11-18 08:00   | ⏭ Skip   | -        | 0     | 0             |
| 2025-11-11 08:00   | ✓ Exito   | 18s      | 165   | 5             |
+------------------------------------------------------------------+

Modal: Nueva Programacion
+------------------------------------------------------------------+
| PROGRAMAR REPORTE                                            [X]  |
+------------------------------------------------------------------+
| Nombre*                                                           |
| [Ventas Semanales para Gerencia                             ]    |
|                                                                   |
| Reporte*                                                          |
| [Ventas por Cliente v]                                           |
|                                                                   |
| PROGRAMACION                                                      |
+------------------------------------------------------------------+
| Frecuencia: ( ) Una vez  ( ) Diario  (•) Semanal  ( ) Mensual    |
| Dia: [Lunes v]  Hora: [08:00 v]                                  |
| Zona Horaria: [America/Mexico_City v]                            |
+------------------------------------------------------------------+
|                                                                   |
| PARAMETROS                                                        |
+------------------------------------------------------------------+
| fecha_desde: [Inicio de semana v]                                |
| fecha_hasta: [Fin de semana v]                                   |
+------------------------------------------------------------------+
|                                                                   |
| DESTINATARIOS                                                     |
+------------------------------------------------------------------+
| [+ Usuario] [+ Email] [+ Rol]                                    |
| 👤 Juan Perez                                                [x] |
| 📧 gerencia@empresa.com                                      [x] |
+------------------------------------------------------------------+
|                                                                   |
| FORMATO Y OPCIONES                                                |
+------------------------------------------------------------------+
| Formato: (•) Excel  ( ) PDF  ( ) CSV                             |
| [✓] No enviar si sin datos                                       |
| [✓] Adjuntar archivo (max 10MB)                                  |
|                                                                   |
|                              [Cancelar]  [=== Programar ===]     |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /reports/schedules | Listar programaciones |
| POST | /reports/schedules | Crear programacion |
| GET | /reports/schedules/:id | Detalle |
| PUT | /reports/schedules/:id | Actualizar |
| DELETE | /reports/schedules/:id | Eliminar |
| POST | /reports/schedules/:id/run | Ejecutar ahora |
| PUT | /reports/schedules/:id/status | Pausar/Activar |
| GET | /reports/schedules/:id/history | Historial |

### Expresiones Cron

| Expresion | Descripcion |
|-----------|-------------|
| 0 8 * * * | Diario 8:00 |
| 0 8 * * 1 | Lunes 8:00 |
| 0 8 1 * * | Dia 1 del mes 8:00 |
| 0 8 * * 1-5 | Lun-Vie 8:00 |

### Fechas Relativas

| Valor | Significado |
|-------|-------------|
| today | Hoy |
| yesterday | Ayer |
| start_of_week | Inicio de semana |
| end_of_week | Fin de semana |
| start_of_month | Inicio de mes |
| -7d | Hace 7 dias |
| -1m | Hace 1 mes |

---

## Definicion de Done

- [ ] CRUD programaciones
- [ ] Parser de expresiones cron
- [ ] Parametros relativos
- [ ] Job scheduler
- [ ] Envio por email
- [ ] Historial de ejecuciones
- [ ] Pausar/Reanudar
- [ ] Ejecucion manual
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| US-MGN009-001 | Reportes predefinidos |
| US-MGN008-002 | Envio de emails |
| Bull Queue | Scheduler |
| node-cron | Parser cron |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Automatizacion | Reportes automaticos |

---

## Historial

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