# Modulo 12: Dashboard y Reportes (Operacion)

## 1. Objetivo
El Dashboard centraliza indicadores comerciales y operativos para toma de decisiones rapida.
Incluye KPI de ventas, actividades, comunicaciones, calidad de datos, comparativos, pronostico y exportaciones.

## 2. Alcance funcional
- KPI comerciales: monto ganado, pipeline abierto, oportunidades creadas/ganadas.
- KPI operativos: actividades vencidas, alertas criticas, errores, tickets.
- Embudo y tendencia: tabla + graficas.
- Centro de acciones: prioridades del dia (actividades y alertas).
- Insights automaticos: hallazgos con severidad y recomendacion.
- Metas KPI: avance vs objetivo con semaforo.
- Pronostico: escenarios conservador/base/agresivo.
- Comparativos: periodo actual vs periodo anterior.
- Calidad de datos: reconciliacion + salud global.
- Exportaciones: CSV, XLS, PDF.

## 3. Arquitectura tecnica
### Backend
- Servicio principal: `app/Services/PlatformExpansionService.php`
  - Metodo base: `executiveDashboard(...)`
  - Cache: `cachedExecutiveDashboard(...)`
  - Telemetria: `createDashboardTelemetryEvent(...)`
  - Export jobs: `createDashboardExportJob(...)`

### Frontend
- Vista: `public/views/app.php` (bloque `module === 'dashboard'`).
- Graficas: `public/assets/js/app.js` (`initDashboardCharts`).
- Rutas:
  - `GET /dashboard?module=dashboard`
  - `GET /dashboard/export?format=csv|excel|pdf`
  - `POST /dashboard/quality/run`

### Datos (DB)
- `dashboard_report_snapshots`
- `dashboard_export_jobs`
- `dashboard_kpi_definitions`
- `dashboard_widget_preferences`
- `dashboard_telemetry_events`
- `dashboard_data_quality_checks`
- `dashboard_refresh_locks`

## 4. Seguridad y aislamiento
- Multi-tenant obligatorio por `tenant_id` en consultas.
- Permiso requerido: modulo `dashboard` accion `view`.
- Contexto de tenant validado en sesion (`requireUser` + `TenantContext`).
- Scope por usuario/rol aplicado por politica de datos (`user_data_scopes`).

## 5. Filtros y comportamiento
- Filtros activos:
  - `from`, `to` (rango de fechas)
  - `owner_id` (responsable)
  - `stage_id` (etapa de embudo)
- El dashboard usa cache por llave de rango + filtros para reducir recalculo.
- `refresh=1` fuerza recalculo.

## 6. Exportaciones
- CSV: descarga inmediata.
- XLS: descarga inmediata en formato tabular compatible con Excel.
- PDF: descarga inmediata con resumen ejecutivo.
- Todos los intentos registran job en `dashboard_export_jobs` y telemetria.

## 7. Secciones visuales y uso recomendado
1. KPI vs metas
   - Ver avance porcentual y estado (en objetivo, seguimiento, riesgo).
2. Insights automaticos
   - Revisar primero severidad `critical` y `high`.
3. Pronostico de cierre
   - Usar escenario `base` para planeacion semanal.
4. Comparativos
   - Detectar caidas de tendencia frente al periodo anterior.
5. Centro de acciones del dia
   - Ejecutar primero items de mayor prioridad.
6. Embudo y tendencia
   - Usar drill-down (click en grafica) para ir a pipeline.
7. Calidad de datos
   - Monitorear score global y reconciliacion.
8. Personalizacion por rol
   - Activar widgets recomendados por rol.

## 8. Operacion diaria (runbook corto)
1. Abrir Dashboard con rango de trabajo (7/30 dias).
2. Validar alertas criticas e insights.
3. Ejecutar centro de acciones.
4. Revisar forecast y comparativos.
5. Correr reconciliacion de calidad.
6. Exportar reporte para direccion (XLS/PDF).

## 9. Monitoreo y observabilidad
- Medir eventos:
  - `dashboard_load`
  - `dashboard_refresh`
  - `dashboard_export`
  - `dashboard_drilldown`
- Auditar:
  - tiempos de respuesta
  - ratio cache hit/miss
  - fallos de exportacion
  - score de calidad de datos

## 10. Troubleshooting
### Caso: no descarga exportacion
- Verificar ruta `/dashboard/export`.
- Confirmar permisos `dashboard:view`.
- Revisar registros en `dashboard_export_jobs`.

### Caso: metricas en cero
- Confirmar datos del tenant.
- Validar rango de fechas y filtros (`owner_id`, `stage_id`).
- Ejecutar `refresh=1`.

### Caso: dashboard lento
- Revisar indices de tablas hot-path (opportunities, sales_activities, notifications).
- Verificar uso de cache y telemetria de duracion.

## 11. Checklist de salida a produccion
- [ ] Migraciones 029, 030, 031, 032, 033 aplicadas.
- [ ] Permisos y scopes validados por rol.
- [ ] Exportaciones CSV/XLS/PDF probadas.
- [ ] Telemetria registrando eventos correctamente.
- [ ] Calidad de datos con reconciliacion operativa.
- [ ] Pruebas de aislamiento tenant sin fugas.

## 12. Mejoras recomendadas (fase siguiente)
- Programacion de reportes automaticos por correo.
- Metas configurables por equipo/usuario desde UI.
- Drill-down avanzado con filtros persistentes.
- Motor de insights con reglas configurables.

## 13. Estado actual de fase siguiente (implementado)
- Programacion de reportes:
  - Tabla: `dashboard_report_schedules`.
  - UI: formulario en dashboard para crear/actualizar programaciones.
  - Ejecucion: accion manual `Ejecutar programaciones vencidas` y ejecucion automatica cuando hay schedules vencidos en la carga del dashboard.
  - Registro operativo: `dashboard_export_jobs` + `technical_log_entries`.
- Metas configurables:
  - Tabla: `dashboard_kpi_targets`.
  - Alcances: `tenant`, `team`, `user`.
  - Prioridad de aplicacion: `user > team > tenant > default`.
- Drill-down avanzado:
  - Click en graficas conserva filtros (`from`, `to`, `owner_id`, `stage_id`) en la navegacion.
- Insights configurables:
  - Tabla: `dashboard_insight_rules`.
  - Comparadores soportados: `gt`, `gte`, `lt`, `lte`, `eq`.
  - Placeholders de mensaje: `{rule_key}`, `{metric_key}`, `{value}`, `{threshold}`.