# EPICA: EPIC-MGN-009 - Reportes

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-009 |
| **Nombre** | Reportes y Analytics |
| **Modulo** | reports |
| **Fase** | Fase 2 - Core Business |
| **Prioridad** | P1 |
| **Estado** | En Progreso |
| **Story Points** | 26 |
| **Sprint(s)** | Sprint 8 |

---

## Descripcion

Sistema de reportes genericos que permite definir reportes personalizados con drag & drop, exportar a PDF/Excel, programar reportes automaticos por email, y crear dashboards con KPIs y graficas interactivas.

---

## Objetivo de Negocio

Proveer reportes que:
- Faciliten toma de decisiones basadas en datos
- Soporten multiples formatos de exportacion
- Permitan automatizacion con programacion
- Sean personalizables sin desarrollo
- Ofrezcan visualizacion interactiva

---

## Stakeholders

| Rol | Nombre/Equipo | Responsabilidad |
|-----|---------------|-----------------|
| Product Owner | Equipo Producto | Definicion de reportes base |
| Tech Lead | Equipo Backend | Arquitectura de query builder |
| Business Analysts | Operaciones | Definicion de KPIs |
| Gerentes | Usuarios finales | Consumo de dashboards |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN009-001 | Como usuario, quiero generar reportes predefinidos para analizar datos operativos | P0 | 5 | Backlog |
| US-MGN009-002 | Como usuario, quiero exportar reportes a PDF para compartir formalmente | P0 | 5 | Backlog |
| US-MGN009-003 | Como usuario, quiero exportar reportes a Excel para analisis detallado | P0 | 3 | Backlog |
| US-MGN009-004 | Como admin, quiero crear reportes personalizados para necesidades especificas | P1 | 8 | Backlog |
| US-MGN009-005 | Como usuario, quiero programar reportes automaticos para recibir informacion periodica | P1 | 5 | Backlog |
| US-MGN009-006 | Como gerente, quiero ver dashboards con KPIs para monitorear el negocio | P1 | 5 | Backlog |

**Total Story Points:** 31 SP (ajustado a 26)

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Reportes predefinidos por modulo (ventas, compras, inventario, etc.)
- [ ] Exportacion PDF con formato profesional y logo de empresa
- [ ] Exportacion Excel con datos estructurados y formulas
- [ ] Constructor de reportes visual (campos, filtros, agrupaciones)
- [ ] Scheduler de reportes (diario, semanal, mensual) con envio por email
- [ ] Dashboards con graficas interactivas (Bar, Line, Pie, Gauge)
- [ ] Filtros dinamicos por fecha, entidad, etc.

**No Funcionales:**
- [ ] Performance: Reportes de hasta 10k registros en < 5s
- [ ] PDF: Generacion en background para reportes grandes
- [ ] Escalabilidad: Cache de reportes frecuentes

**Tecnicos:**
- [ ] Cobertura de tests > 80%
- [ ] Query builder seguro contra SQL injection
- [ ] Documentacion de reportes disponibles

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MGN-004 Tenants | Ready | Si |
| EPIC-MGN-008 Notifications | Backlog | Parcial (para envio programado) |
| Modulos de datos (Financial, Sales, etc.) | Variable | No (datos disponibles) |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| Ninguno | Modulo complementario |

---

## Desglose Tecnico

**Database:** ✅ COMPLETADO
- [x] Schema: `reports` (14-reports.sql)
- [x] Tablas: 12 (report_definitions, report_executions, report_schedules, report_recipients, schedule_executions, custom_reports, dashboards, dashboard_widgets, widget_queries, data_model_entities, data_model_fields, data_model_relationships)
- [x] ENUMs: 7 (report_type, execution_status, export_format, delivery_method, widget_type, param_type, filter_operator)
- [x] RLS Policies: 7 (tenant isolation en todas las tablas)

**Backend:** 🔄 EN PROGRESO (Sprint 8)
- [x] Modulo: `reports`
- [x] Services: DashboardsService (~500 LOC), ExportService (~350 LOC)
- [x] Controller: DashboardsController (~400 LOC)
- [x] Routes: 13 endpoints para dashboards
- [ ] Services pendientes: ReportBuilderService (BE-024), SchedulerService (BE-025)
- [ ] Tests: DashboardsService tests (TEST-003)

**Frontend:** ⏳ PENDIENTE
- [ ] Paginas: 5 (ReportsList, ReportViewer, ReportBuilder, ScheduleManager, Dashboards)
- [ ] Componentes: Charts (Bar, Line, Pie, Gauge), KPICard, FilterPanel, DragDropFields
- [ ] Stores: 1 (reportsStore)
- [ ] Libs: Chart.js o Recharts para graficas

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Queries lentas | Alta | Alto | Indices optimizados, cache, timeout |
| PDF grande tarda mucho | Media | Medio | Generacion async, notificacion al terminar |
| SQL injection en query builder | Baja | Critico | Parametros escapados, whitelist de campos |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Reportes base definidos (lista)
- [ ] KPIs por modulo definidos
- [x] Sin bloqueadores activos

## Definition of Done (DoD)

- [ ] Codigo implementado y revisado
- [ ] Tests pasando (unit, integration)
- [ ] Reportes predefinidos funcionando
- [ ] Exportacion PDF y Excel funcional
- [ ] Scheduler enviando emails
- [ ] Dashboard con al menos 3 graficas
- [ ] Documentacion actualizada
- [ ] Inventarios actualizados
- [ ] Demo realizada
- [ ] Product Owner aprobo

---

## Documentacion Relacionada

- Requerimientos: `docs/03-requerimientos/RF-reports/`
- User Stories: `docs/05-user-stories/mgn-009/`
- DDL Spec: `docs/04-modelado/database-design/DDL-SPEC-core_reports.md`

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creacion de epica | Requirements-Analyst |
| 2025-12-05 | Completado con Stakeholders, Riesgos, DoR/DoD | Requirements-Analyst |
| 2026-01-07 | Implementado DDL 14-reports.sql (12 tablas, 7 ENUMs) | Database-Agent |
| 2026-01-07 | Implementado DashboardsService, ExportService, 13 endpoints | Backend-Agent |
| 2026-01-07 | Movido a Sprint 8 - Estado: En Progreso | Orquestador |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Ultima actualizacion:** 2026-01-07