# RF-REPORT-002: Dashboards

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-REPORT-002 |
| **Modulo** | MGN-009 Reports |
| **Titulo** | Dashboards |
| **Prioridad** | P0 - Critica |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe permitir crear y visualizar dashboards con widgets configurables que muestren KPIs, graficos, tablas y metricas en tiempo real, personalizables por usuario y tenant.

---

## Requisitos Funcionales

### RF-REPORT-002.1: Estructura de Dashboard

```typescript
interface Dashboard {
  id: UUID;
  tenantId: UUID;
  userId?: UUID;          // null = dashboard de tenant
  name: string;
  description?: string;
  layout: LayoutConfig;   // Configuracion del grid
  isDefault: boolean;     // Dashboard por defecto
  isShared: boolean;      // Compartido con otros
  refreshInterval?: number; // Segundos
  createdAt: TIMESTAMPTZ;
  updatedAt: TIMESTAMPTZ;
}

interface LayoutConfig {
  columns: number;        // 12 columnas tipico
  rowHeight: number;      // Altura base
  widgets: WidgetPosition[];
}

interface WidgetPosition {
  widgetId: UUID;
  x: number;              // Columna inicio
  y: number;              // Fila inicio
  w: number;              // Ancho en columnas
  h: number;              // Alto en filas
}
```

### RF-REPORT-002.2: Tipos de Widgets

```typescript
enum WidgetType {
  // Metricas
  KPI = 'kpi',                    // Numero grande con tendencia
  GAUGE = 'gauge',                // Medidor circular
  PROGRESS = 'progress',          // Barra de progreso

  // Graficos
  LINE_CHART = 'line_chart',      // Lineas
  BAR_CHART = 'bar_chart',        // Barras
  PIE_CHART = 'pie_chart',        // Pastel
  DONUT_CHART = 'donut_chart',    // Dona
  AREA_CHART = 'area_chart',      // Areas
  FUNNEL = 'funnel',              // Embudo

  // Datos
  TABLE = 'table',                // Tabla de datos
  LIST = 'list',                  // Lista simple
  TIMELINE = 'timeline',          // Linea de tiempo

  // Otros
  MAP = 'map',                    // Mapa geografico
  CALENDAR = 'calendar',          // Calendario
  TEXT = 'text'                   // Texto/HTML
}
```

### RF-REPORT-002.3: Configuracion de Widget

```typescript
interface Widget {
  id: UUID;
  dashboardId: UUID;
  type: WidgetType;
  title: string;
  config: WidgetConfig;
  dataSource: DataSourceConfig;
  refreshInterval?: number;
  createdAt: TIMESTAMPTZ;
  updatedAt: TIMESTAMPTZ;
}

interface WidgetConfig {
  // Comun
  showTitle: boolean;
  showBorder: boolean;
  backgroundColor?: string;

  // Para KPI
  format?: string;            // currency, percentage, number
  trend?: boolean;            // Mostrar tendencia
  target?: number;            // Meta

  // Para graficos
  colors?: string[];
  legend?: boolean;
  xAxis?: AxisConfig;
  yAxis?: AxisConfig;

  // Para tablas
  columns?: TableColumn[];
  pagination?: boolean;
  pageSize?: number;
}

interface DataSourceConfig {
  type: 'query' | 'report' | 'api';
  source: string;            // Query ID, Report code, API endpoint
  parameters?: Record<string, any>;
  transform?: TransformConfig;
}
```

### RF-REPORT-002.4: Widgets Predefinidos

| Widget | Tipo | Descripcion |
|--------|------|-------------|
| Ventas del dia | KPI | Total ventas hoy vs ayer |
| Ventas mensuales | Line Chart | Tendencia de ventas |
| Top productos | Bar Chart | Productos mas vendidos |
| Inventario bajo | Table | Productos con stock bajo |
| Cuentas por cobrar | Donut | Por vencimiento |
| Actividad reciente | Timeline | Ultimas acciones |
| Mapa de clientes | Map | Distribucion geografica |

### RF-REPORT-002.5: Dashboards de Sistema

Dashboards predefinidos no editables:

| Dashboard | Modulo | Widgets |
|-----------|--------|---------|
| Executive Overview | - | KPIs principales, tendencias |
| Sales Dashboard | Sales | Ventas, metas, pipeline |
| Inventory Dashboard | Inventory | Stock, movimientos |
| Financial Dashboard | Financial | Balance, flujo caja |
| User Activity | Admin | Logins, actividad |

### RF-REPORT-002.6: Refresh en Tiempo Real

```typescript
interface RealTimeConfig {
  enabled: boolean;
  interval: number;        // Segundos (min 10)
  strategy: 'polling' | 'websocket';
  onlyWhenVisible: boolean;  // Pausar si no visible
}
```

---

## Operaciones

### Listar Dashboards

```typescript
GET /api/v1/dashboards

Response:
{
  "data": [
    {
      "id": "uuid",
      "name": "Mi Dashboard",
      "isDefault": true,
      "widgetCount": 6,
      "lastModified": "2025-12-05T10:00:00Z"
    }
  ]
}
```

### Obtener Dashboard con Widgets

```typescript
GET /api/v1/dashboards/:id

Response:
{
  "id": "uuid",
  "name": "Executive Overview",
  "layout": {
    "columns": 12,
    "rowHeight": 100,
    "widgets": [
      { "widgetId": "uuid1", "x": 0, "y": 0, "w": 3, "h": 2 },
      { "widgetId": "uuid2", "x": 3, "y": 0, "w": 3, "h": 2 }
    ]
  },
  "widgets": [
    {
      "id": "uuid1",
      "type": "kpi",
      "title": "Ventas Hoy",
      "config": { "format": "currency", "trend": true }
    }
  ]
}
```

### Obtener Datos de Widget

```typescript
GET /api/v1/dashboards/:dashboardId/widgets/:widgetId/data

Response:
{
  "value": 125000,
  "previousValue": 110000,
  "trend": 13.6,
  "updatedAt": "2025-12-05T10:00:00Z"
}
```

### Crear Dashboard

```typescript
POST /api/v1/dashboards
{
  "name": "Mi Dashboard",
  "layout": { "columns": 12, "rowHeight": 100 }
}
```

### Agregar Widget

```typescript
POST /api/v1/dashboards/:id/widgets
{
  "type": "line_chart",
  "title": "Ventas Mensuales",
  "position": { "x": 0, "y": 0, "w": 6, "h": 4 },
  "config": { "legend": true },
  "dataSource": {
    "type": "query",
    "source": "sales_by_month"
  }
}
```

### Actualizar Layout

```typescript
PUT /api/v1/dashboards/:id/layout
{
  "widgets": [
    { "widgetId": "uuid1", "x": 0, "y": 0, "w": 6, "h": 4 },
    { "widgetId": "uuid2", "x": 6, "y": 0, "w": 6, "h": 4 }
  ]
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Max 20 widgets por dashboard | Performance |
| BR-002 | Refresh minimo cada 10 segundos | Performance |
| BR-003 | Dashboards de sistema no editables | Security |
| BR-004 | Widgets comparten datos si mismo query | Performance |
| BR-005 | Dashboard por defecto es obligatorio | UX |

---

## Criterios de Aceptacion

- [ ] CRUD de dashboards
- [ ] 10+ tipos de widgets
- [ ] Drag and drop de widgets
- [ ] Refresh automatico configurable
- [ ] Dashboards compartidos
- [ ] Widgets con datos en tiempo real
- [ ] Responsive en diferentes pantallas

---

## Historial

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