# US-MGN009-002: Gestionar Dashboards y Widgets

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN009-002 |
| **Modulo** | MGN-009 Reports |
| **Sprint** | Sprint 6 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 13 |
| **Estado** | Ready |
| **RF Relacionado** | RF-REPORT-002 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** crear y personalizar dashboards con widgets de KPIs y graficos
**Para** visualizar metricas clave de mi negocio en tiempo real

---

## Descripcion

Los usuarios crean dashboards personalizados con widgets configurables. Los widgets muestran KPIs, graficos, tablas y otros visuales. Soporta drag-and-drop, refresh automatico y compartir entre usuarios.

### Contexto

- Dashboards personalizables
- Widgets de diferentes tipos
- Refresh en tiempo real
- Compartir con equipo

---

## Criterios de Aceptacion

### Escenario 1: Ver dashboard por defecto

```gherkin
Given un usuario nuevo
When accede al dashboard
Then ve el dashboard por defecto del tenant
  And los widgets se cargan con datos actuales
```

### Escenario 2: Listar mis dashboards

```gherkin
Given un usuario con dashboards creados
When consulta GET /api/v1/dashboards
Then retorna sus dashboards + los compartidos
  And indica cual es el default
```

### Escenario 3: Crear nuevo dashboard

```gherkin
Given un usuario con permiso
When crea POST /api/v1/dashboards
  | name | "Mi Dashboard de Ventas" |
Then el dashboard se crea vacio
  And puede agregar widgets
```

### Escenario 4: Agregar widget KPI

```gherkin
Given un dashboard existente
When agrega widget tipo KPI
  | title | "Ventas Hoy" |
  | dataSource | query: "sales_today" |
  | format | "currency" |
Then el widget aparece en el dashboard
  And muestra el valor actual y tendencia
```

### Escenario 5: Agregar widget grafico

```gherkin
Given un dashboard existente
When agrega widget tipo line_chart
  | title | "Ventas Mensuales" |
  | dataSource | query: "sales_by_month" |
Then el widget muestra grafico de lineas
  And es interactivo (hover, zoom)
```

### Escenario 6: Reorganizar widgets (drag & drop)

```gherkin
Given un dashboard con multiples widgets
When el usuario arrastra un widget a nueva posicion
Then el layout se actualiza
  And se guarda automaticamente
```

### Escenario 7: Redimensionar widget

```gherkin
Given un widget en el dashboard
When el usuario cambia su tamano
Then el widget se redimensiona
  And el contenido se adapta
```

### Escenario 8: Refresh automatico

```gherkin
Given dashboard con refreshInterval = 60
When pasan 60 segundos
Then todos los widgets se actualizan
  And se muestra indicador de actualizacion
```

### Escenario 9: Compartir dashboard

```gherkin
Given un dashboard personal
When lo marca como compartido (isShared = true)
Then otros usuarios del tenant pueden verlo
  And aparece en su lista de dashboards
```

### Escenario 10: Configurar widget

```gherkin
Given un widget existente
When abre su configuracion
Then puede cambiar:
  | title, colores, formato, fuente de datos |
  And los cambios se reflejan inmediatamente
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  DASHBOARD: Executive Overview                    [+ Widget] [⚙] |
+------------------------------------------------------------------+
| [Mis Dashboards v]  [Periodo: Hoy v]        Ultima actualizacion: hace 30s |
+------------------------------------------------------------------+

+----------------+  +----------------+  +----------------+
| 💰 VENTAS HOY |  | 📦 PEDIDOS    |  | 👥 USUARIOS   |
|   $125,000    |  |     45        |  |     1,234     |
|   ↑ 15%       |  |   ↑ 8%        |  |   ↓ 2%        |
+----------------+  +----------------+  +----------------+

+-----------------------------------+  +-----------------------------------+
| VENTAS MENSUALES                  |  | DISTRIBUCION POR REGION          |
|                                   |  |                                   |
|     ^                             |  |        Norte                      |
|  $1M|     ___                     |  |       ████████ 45%               |
|     |    /   \                    |  |        Centro                     |
| $500|___/     \___                |  |       ██████ 35%                 |
|     |              \              |  |        Sur                        |
|   $0+---------------+             |  |       ████ 20%                   |
|      E F M A M J J                |  |                                   |
+-----------------------------------+  +-----------------------------------+

+------------------------------------------------------------------+
| ULTIMOS PEDIDOS                                                    |
+------------------------------------------------------------------+
| #1234 | Juan Perez      | $1,500  | Pendiente  | hace 5 min       |
| #1233 | Maria Garcia    | $2,300  | Enviado    | hace 15 min      |
| #1232 | Carlos Lopez    | $800    | Completado | hace 30 min      |
+------------------------------------------------------------------+

Modal: Agregar Widget
+------------------------------------------------------------------+
| AGREGAR WIDGET                                               [X]  |
+------------------------------------------------------------------+
| TIPO DE WIDGET                                                    |
| [KPI] [Grafico Lineas] [Grafico Barras] [Pastel] [Tabla] [Texto] |
+------------------------------------------------------------------+
|                                                                   |
| Titulo*                                                           |
| [Ventas por Categoria                                       ]    |
|                                                                   |
| Fuente de Datos                                                   |
| [Query: sales_by_category v]                                      |
|                                                                   |
| Configuracion                                                     |
| [✓] Mostrar leyenda                                              |
| [✓] Mostrar valores                                               |
| Colores: [Paleta 1 v]                                             |
|                                                                   |
| Tamano                                                            |
| Ancho: [6 columnas v]  Alto: [4 filas v]                         |
|                                                                   |
|                              [Cancelar]  [=== Agregar ===]       |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /dashboards | Listar dashboards |
| GET | /dashboards/:id | Dashboard con widgets |
| POST | /dashboards | Crear dashboard |
| PUT | /dashboards/:id | Actualizar |
| DELETE | /dashboards/:id | Eliminar |
| POST | /dashboards/:id/widgets | Agregar widget |
| PUT | /dashboards/:id/widgets/:wid | Actualizar widget |
| DELETE | /dashboards/:id/widgets/:wid | Eliminar widget |
| PUT | /dashboards/:id/layout | Actualizar layout |
| GET | /dashboards/:id/widgets/:wid/data | Datos de widget |

### Tipos de Widget

| Tipo | Libreria | Uso |
|------|----------|-----|
| KPI | Custom | Numero con tendencia |
| line_chart | Chart.js | Tendencias |
| bar_chart | Chart.js | Comparativas |
| pie_chart | Chart.js | Distribucion |
| table | Custom | Datos tabulares |
| gauge | Custom | Indicador circular |

### Layout Grid

```typescript
// Grid de 12 columnas
interface WidgetPosition {
  widgetId: UUID;
  x: number;      // 0-11 (columna)
  y: number;      // fila
  w: number;      // 1-12 (ancho)
  h: number;      // altura en filas
}
```

---

## Definicion de Done

- [ ] CRUD dashboards
- [ ] 10+ tipos de widgets
- [ ] Drag & drop de widgets
- [ ] Redimensionamiento
- [ ] Refresh automatico
- [ ] Compartir dashboards
- [ ] Datos en tiempo real
- [ ] Responsive design
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla dashboards | Storage |
| Tabla widgets | Widgets |
| Chart.js | Graficos |
| react-grid-layout | Layout |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Home page | Dashboard por defecto |

---

## Historial

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