# _MAP: MGN-009 - Reports

**Modulo:** MGN-009
**Nombre:** Reportes y Dashboards
**Fase:** 02 - Core Business
**Story Points:** 35 SP
**Estado:** COMPLETADO (Sprint 8-11)
**Ultima actualizacion:** 2026-01-07

---

## Resumen

Sistema de reportes y dashboards con generador de reportes, exportacion multi-formato, widgets configurables y programacion automatica.

---

## Metricas

| Metrica | Valor |
|---------|-------|
| Story Points | 35 SP |
| Requerimientos (RF) | 4 |
| Especificaciones (ET) | 0 (pendiente) |
| User Stories (US) | 0 (pendiente) |
| Tablas DB | 12 |
| Endpoints API | ~30 |

---

## Requerimientos Funcionales

| ID | Titulo | Prioridad | SP | Estado |
|----|--------|-----------|---:|--------|
| [RF-REPORT-001](./requerimientos/RF-REPORT-001.md) | Reportes Predefinidos | P0 | 10 | Implementado |
| [RF-REPORT-002](./requerimientos/RF-REPORT-002.md) | Dashboards | P0 | 10 | Implementado |
| [RF-REPORT-003](./requerimientos/RF-REPORT-003.md) | Report Builder | P1 | 10 | Implementado |
| [RF-REPORT-004](./requerimientos/RF-REPORT-004.md) | Reportes Programados | P1 | 5 | Implementado |

**Indice completo:** [INDICE-RF-REPORT.md](./requerimientos/INDICE-RF-REPORT.md)

---

## Especificaciones Tecnicas

*Pendiente de documentacion*

---

## Historias de Usuario

*Pendiente de documentacion*

---

## Implementacion

### Database (Schema: reports)

| Objeto | Tipo | Estado | DDL |
|--------|------|--------|-----|
| report_definitions | Tabla | Creado | 14-reports.sql |
| report_executions | Tabla | Creado | 14-reports.sql |
| report_schedules | Tabla | Creado | 14-reports.sql |
| report_recipients | Tabla | Creado | 14-reports.sql |
| schedule_executions | Tabla | Creado | 14-reports.sql |
| dashboards | Tabla | Creado | 14-reports.sql |
| dashboard_widgets | Tabla | Creado | 14-reports.sql |
| widget_queries | Tabla | Creado | 14-reports.sql |
| data_model_entities | Tabla | Creado | 14-reports.sql |
| data_model_fields | Tabla | Creado | 14-reports.sql |
| data_model_relationships | Tabla | Creado | 14-reports.sql |
| custom_reports | Tabla | Creado | 14-reports.sql |

### Backend Services

| Objeto | Tipo | Path | Estado |
|--------|------|------|--------|
| ReportsService | Service | src/modules/reports/reports.service.ts | Implementado |
| DashboardsService | Service | src/modules/reports/dashboards.service.ts | Implementado |
| ExportService | Service | src/modules/reports/export.service.ts | Implementado |
| ReportBuilderService | Service | src/modules/reports/report-builder.service.ts | Implementado |
| SchedulerService | Service | src/modules/reports/scheduler.service.ts | Implementado |

### Backend Controllers

| Objeto | Tipo | Path | Estado |
|--------|------|------|--------|
| ReportsController | Controller | src/modules/reports/reports.controller.ts | Implementado |
| DashboardsController | Controller | src/modules/reports/dashboards.controller.ts | Implementado |

### Backend Routes

| Ruta Base | Path | Estado |
|-----------|------|--------|
| /api/v1/reports | src/modules/reports/reports.routes.ts | Implementado |
| /api/v1/dashboards | src/modules/reports/dashboards.routes.ts | Implementado |

### API Endpoints - Reports

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /reports/definitions | Listar definiciones de reportes |
| GET | /reports/definitions/:id | Obtener definicion por ID |
| POST | /reports/definitions | Crear definicion de reporte |
| POST | /reports/execute | Ejecutar un reporte |
| GET | /reports/executions | Listar ejecuciones recientes |
| GET | /reports/executions/:id | Obtener resultado de ejecucion |
| GET | /reports/schedules | Listar programaciones |
| POST | /reports/schedules | Crear programacion |
| PATCH | /reports/schedules/:id/toggle | Activar/desactivar |
| DELETE | /reports/schedules/:id | Eliminar programacion |
| GET | /reports/quick/trial-balance | Balanza de comprobacion |
| GET | /reports/quick/general-ledger | Libro mayor |

### API Endpoints - Dashboards

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /dashboards | Listar dashboards |
| GET | /dashboards/default | Obtener dashboard por defecto |
| GET | /dashboards/:id | Obtener dashboard con widgets |
| POST | /dashboards | Crear dashboard |
| PATCH | /dashboards/:id | Actualizar dashboard |
| DELETE | /dashboards/:id | Eliminar dashboard |
| POST | /dashboards/:id/clone | Clonar dashboard |
| PUT | /dashboards/:id/layout | Actualizar layout |
| GET | /dashboards/:id/data | Obtener datos de todos los widgets |
| POST | /dashboards/:id/widgets | Agregar widget |
| PATCH | /dashboards/:id/widgets/:widgetId | Actualizar widget |
| DELETE | /dashboards/:id/widgets/:widgetId | Eliminar widget |
| GET | /dashboards/:id/widgets/:widgetId/data | Obtener datos de widget |

---

## Tipos de Widgets Soportados

| Tipo | Descripcion | Uso |
|------|-------------|-----|
| kpi | Numero grande con tendencia | Metricas principales |
| gauge | Medidor circular | Porcentajes, metas |
| progress | Barra de progreso | Avance de objetivos |
| line_chart | Grafico de lineas | Tendencias temporales |
| bar_chart | Grafico de barras | Comparaciones |
| pie_chart | Grafico de pastel | Distribucion |
| donut_chart | Grafico de dona | Distribucion con total |
| area_chart | Grafico de areas | Tendencias acumuladas |
| funnel | Embudo | Pipeline de ventas |
| table | Tabla de datos | Listados detallados |
| list | Lista simple | Items resumidos |
| timeline | Linea de tiempo | Actividad reciente |
| map | Mapa geografico | Distribucion regional |
| calendar | Calendario | Eventos y citas |
| text | Texto/HTML | Contenido estatico |

---

## Formatos de Exportacion

| Formato | Extension | MIME Type | Estado |
|---------|-----------|-----------|--------|
| CSV | .csv | text/csv | Implementado |
| JSON | .json | application/json | Implementado |
| XLSX | .xlsx | application/vnd.openxmlformats... | Basico |
| HTML | .html | text/html | Implementado |
| PDF | .pdf | application/pdf | Pendiente (requiere puppeteer) |

---

## Dependencias

**Depende de:**
- MGN-001 (Auth) - Autenticacion y permisos
- MGN-004 (Tenants) - Aislamiento multi-tenant
- MGN-008 (Notifications) - Notificaciones de reportes programados

**Requerido por:**
- Verticales (ERP-Retail, ERP-Construccion, etc.)

---

## Frontend Features

### Feature: dashboards (Sprint 9)

| Componente | Descripcion | Estado |
|------------|-------------|--------|
| DashboardViewer | Visualizador con react-grid-layout | Implementado |
| DashboardEditor | Editor con drag & drop | Implementado |
| DashboardList | Lista con CRUD | Implementado |
| WidgetConfigModal | Configuracion de widgets | Implementado |
| 15 Widget Types | Charts, KPIs, Tables, etc. | Implementado |

### Feature: report-builder (Sprint 10)

| Componente | Descripcion | Estado |
|------------|-------------|--------|
| EntityExplorer | Arbol de entidades | Implementado |
| FieldSelector | Selector con agregaciones | Implementado |
| FilterBuilder | Constructor visual de filtros | Implementado |
| ReportPreview | Preview datos y SQL | Implementado |
| ReportBuilder | Componente principal | Implementado |

### Feature: scheduled-reports (Sprint 11)

| Componente | Descripcion | Estado |
|------------|-------------|--------|
| CronBuilder | Constructor de cron | Implementado |
| RecipientManager | Gestion de destinatarios | Implementado |
| ExecutionHistory | Historial de ejecuciones | Implementado |
| ScheduleList | Lista con acciones | Implementado |
| ScheduleForm | Formulario CRUD | Implementado |

---

## Sprints Completados

| Sprint | Layer | Descripcion | Archivos |
|--------|-------|-------------|----------|
| Sprint 8 | Backend | API Dashboards & Reports | 14 |
| Sprint 9 | Frontend | Dashboard UI | 24 |
| Sprint 10 | Frontend | Report Builder UI | 13 |
| Sprint 11 | Frontend | Scheduled Reports UI | 11 |
| **TOTAL** | | | **62** |

---

## Pendientes Futuros

| Item | Descripcion | Prioridad |
|------|-------------|-----------|
| PDF Export | Integracion con puppeteer para PDF | P2 |
| Tests | Tests unitarios para componentes | P2 |
| Pages | Crear paginas/rutas para features | P1 |

---

## Trazabilidad

Ver: [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)

---

**Actualizado por:** Frontend-Agent (Claude Opus 4.5)
**Fecha:** 2026-01-07
**Sprint:** 11 - COMPLETADO
