---
id: EPIC-MCH-021
type: Epic
title: "MCH-021: Dashboard Web"
code: MCH-021
status: Completado
phase: 5
priority: P1
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 21
dependencies:
  blocks: []
  depends_on: []
---

# MCH-021: Dashboard Web

## Metadata
- **Codigo:** MCH-021
- **Fase:** 5 - Monetizacion
- **Prioridad:** P1
- **Estado:** Completado
- **Fecha completado:** 2026-01-10
- **Story Points:** 21

## Descripcion

Dashboard web completo para duenos de negocio: metricas de ventas, graficas, reportes exportables, configuracion del negocio, y administracion de usuarios.

## Objetivos

1. Metricas de ventas en tiempo real
2. Graficas interactivas
3. Reportes exportables (PDF/Excel)
4. Configuracion del negocio
5. Administracion de usuarios

## Alcance

### Incluido
- Dashboard principal con KPIs
- Graficas de ventas (dia/semana/mes)
- Top productos y categorias
- Reportes de corte de caja
- Configuracion de negocio
- Gestion de usuarios/roles

### Excluido
- BI avanzado (cubos OLAP)
- Predicciones ML en graficas
- Comparativos multi-sucursal

## Secciones del Dashboard

### Home / Resumen
```
┌─────────────────────────────────────────────────────────┐
│                    DASHBOARD                            │
├─────────────┬─────────────┬─────────────┬──────────────┤
│  Ventas Hoy │ Transacc.   │ Ticket Prom │ vs Ayer     │
│   $3,450    │    23       │    $150     │   +15%      │
├─────────────┴─────────────┴─────────────┴──────────────┤
│                                                         │
│  [Grafica de Ventas - Ultimos 7 dias]                  │
│                                                         │
├───────────────────────────┬─────────────────────────────┤
│  Top 5 Productos          │  Alertas                    │
│  1. Coca-Cola 600ml       │  ⚠️ Stock bajo (3)          │
│  2. Sabritas Original     │  💰 Fiados pendientes (5)   │
│  3. Pan Bimbo             │  📦 Pedidos nuevos (2)      │
└───────────────────────────┴─────────────────────────────┘
```

### Ventas
- Tabla de ventas del periodo
- Filtros por fecha, empleado, metodo de pago
- Detalle de cada venta
- Exportar a Excel

### Productos
- CRUD de productos
- Inventario actual
- Historial de precios
- Importar/exportar

### Clientes
- Lista de clientes
- Historial de compras
- Saldos de fiado
- Segmentacion

### Reportes
- Corte de caja diario
- Ventas por periodo
- Productos mas vendidos
- Inventario valorizado
- Fiados por cobrar

### Configuracion
- Datos del negocio
- Metodos de pago
- Usuarios y roles
- Integraciones
- Suscripcion

## KPIs Principales

| KPI | Descripcion | Calculo |
|-----|-------------|---------|
| Ventas del dia | Total vendido hoy | SUM(sales.total) |
| Transacciones | Numero de ventas | COUNT(sales) |
| Ticket promedio | Venta promedio | AVG(sales.total) |
| Margen bruto | Ganancia | (precio - costo) / precio |
| Productos sin stock | Productos en 0 | COUNT(stock = 0) |

## Graficas

### Ventas por Dia (7 dias)
- Tipo: Barras o linea
- Eje X: Dias
- Eje Y: Total ventas
- Comparativo vs semana anterior

### Ventas por Hora
- Tipo: Linea
- Eje X: Horas (7am - 10pm)
- Eje Y: Ventas
- Identificar horas pico

### Top Productos (Pie)
- Top 5 productos por ingresos
- Porcentaje del total

### Metodos de Pago (Donut)
- Efectivo vs Tarjeta vs Fiado
- Porcentaje de cada uno

## Historias de Usuario

### MCH-US-200: KPIs en Tiempo Real
**Story Points:** 5

**Como** dueno de negocio
**Quiero** visualizar metricas clave de ventas en tiempo real (ventas del dia, transacciones, ticket promedio)
**Para** monitorear el rendimiento de mi negocio de un vistazo

#### Criterios de Aceptacion
- [CA-200-1] El dashboard muestra ventas totales del dia actualizadas
- [CA-200-2] Se muestra el numero de transacciones realizadas
- [CA-200-3] El ticket promedio se calcula correctamente
- [CA-200-4] Se muestra comparativo porcentual vs dia anterior
- [CA-200-5] Los KPIs se refrescan automaticamente cada 5 minutos

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-200-01 | Implementar endpoint /analytics/dashboard | 4h |
| MCH-TT-200-02 | Crear componente KPICard reutilizable | 3h |
| MCH-TT-200-03 | Integrar KPIs en Dashboard page | 2h |
| MCH-TT-200-04 | Implementar auto-refresh con polling | 2h |
| MCH-TT-200-05 | Pruebas unitarias de calculos | 2h |

---

### MCH-US-201: Graficas Interactivas
**Story Points:** 5

**Como** dueno de negocio
**Quiero** ver graficas interactivas de ventas por dia/hora y productos mas vendidos
**Para** identificar tendencias y tomar decisiones informadas

#### Criterios de Aceptacion
- [CA-201-1] Grafica de ventas por dia muestra ultimos 7 dias
- [CA-201-2] Grafica de ventas por hora identifica horas pico
- [CA-201-3] Grafica de top productos muestra top 5 por ingresos
- [CA-201-4] Grafica de metodos de pago muestra distribucion
- [CA-201-5] Las graficas tienen tooltips interactivos al hover
- [CA-201-6] Se puede cambiar el periodo de visualizacion

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-201-01 | Implementar endpoint /analytics/sales-by-day | 3h |
| MCH-TT-201-02 | Implementar endpoint /analytics/sales-by-hour | 3h |
| MCH-TT-201-03 | Implementar endpoint /analytics/top-products | 2h |
| MCH-TT-201-04 | Crear componente SalesChart con Recharts | 4h |
| MCH-TT-201-05 | Crear componente TopProductsList | 2h |
| MCH-TT-201-06 | Integrar selector de periodo | 2h |

---

### MCH-US-202: Reportes Exportables
**Story Points:** 3

**Como** dueno de negocio
**Quiero** exportar reportes de ventas y corte de caja en PDF y Excel
**Para** mantener registros fisicos y compartir con mi contador

#### Criterios de Aceptacion
- [CA-202-1] Se puede exportar corte de caja diario a PDF
- [CA-202-2] Se puede exportar ventas del periodo a Excel
- [CA-202-3] El PDF incluye logo del negocio y fecha
- [CA-202-4] El Excel mantiene formato de tabla con totales
- [CA-202-5] Los reportes se descargan automaticamente

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-202-01 | Implementar servicio de generacion PDF (jsPDF) | 4h |
| MCH-TT-202-02 | Implementar servicio de generacion Excel (SheetJS) | 3h |
| MCH-TT-202-03 | Crear endpoint /reports/export | 2h |
| MCH-TT-202-04 | Crear botones de exportacion en UI | 1h |
| MCH-TT-202-05 | Disenar template de reporte PDF | 2h |

---

### MCH-US-203: Configuracion del Negocio
**Story Points:** 3

**Como** dueno de negocio
**Quiero** configurar los datos de mi negocio y metodos de pago aceptados
**Para** personalizar la plataforma a mis necesidades

#### Criterios de Aceptacion
- [CA-203-1] Se pueden editar nombre, direccion y telefono del negocio
- [CA-203-2] Se puede subir logo del negocio
- [CA-203-3] Se pueden activar/desactivar metodos de pago
- [CA-203-4] Se puede configurar horario de operacion
- [CA-203-5] Los cambios se guardan y aplican inmediatamente

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-203-01 | Crear pagina de configuracion del negocio | 3h |
| MCH-TT-203-02 | Implementar upload de logo | 2h |
| MCH-TT-203-03 | Crear formulario de metodos de pago | 2h |
| MCH-TT-203-04 | Implementar endpoints de configuracion | 3h |
| MCH-TT-203-05 | Validaciones y feedback de guardado | 1h |

---

### MCH-US-204: Gestion de Usuarios y Roles
**Story Points:** 3

**Como** dueno de negocio
**Quiero** administrar usuarios y asignar roles a mis empleados
**Para** controlar quien tiene acceso a que funcionalidades

#### Criterios de Aceptacion
- [CA-204-1] Se pueden crear nuevos usuarios empleados
- [CA-204-2] Se pueden asignar roles (admin, cajero, inventario)
- [CA-204-3] Se pueden desactivar usuarios sin eliminarlos
- [CA-204-4] Se muestra lista de usuarios con su rol y estado
- [CA-204-5] Solo el dueno puede gestionar usuarios

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-204-01 | Crear pagina de gestion de usuarios | 3h |
| MCH-TT-204-02 | Implementar CRUD de usuarios en backend | 4h |
| MCH-TT-204-03 | Crear sistema de roles y permisos | 3h |
| MCH-TT-204-04 | Implementar formulario de creacion/edicion | 2h |
| MCH-TT-204-05 | Agregar validaciones de permisos | 2h |

---

### MCH-US-205: Panel de Alertas
**Story Points:** 2

**Como** dueno de negocio
**Quiero** ver alertas de stock bajo, fiados pendientes y pedidos nuevos
**Para** actuar rapidamente ante situaciones que requieren atencion

#### Criterios de Aceptacion
- [CA-205-1] Se muestran alertas de productos con stock bajo
- [CA-205-2] Se muestran fiados pendientes por cobrar
- [CA-205-3] Se notifican pedidos nuevos de clientes
- [CA-205-4] Las alertas muestran cantidad de items
- [CA-205-5] Se puede hacer click para ver detalle

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-205-01 | Crear componente AlertsPanel | 2h |
| MCH-TT-205-02 | Implementar endpoint de alertas consolidadas | 3h |
| MCH-TT-205-03 | Integrar panel en dashboard | 1h |
| MCH-TT-205-04 | Agregar navegacion a detalle de alerta | 2h |
| MCH-TT-205-05 | Estilos y animaciones de alertas | 1h |

---

### Resumen de Historias de Usuario

| ID | Historia | Story Points | Estado |
|----|----------|--------------|--------|
| MCH-US-200 | KPIs en Tiempo Real | 5 | Completado |
| MCH-US-201 | Graficas Interactivas | 5 | Completado |
| MCH-US-202 | Reportes Exportables | 3 | Completado |
| MCH-US-203 | Configuracion del Negocio | 3 | Completado |
| MCH-US-204 | Gestion de Usuarios y Roles | 3 | Completado |
| MCH-US-205 | Panel de Alertas | 2 | Completado |
| **Total** | | **21** | |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| Dashboard.tsx | Completado | `pages/Dashboard.tsx` |
| analytics.module | En progreso | `modules/analytics/` |
| KPICard.tsx | Completado | `components/dashboard/` |
| SalesChart.tsx | En progreso | `components/dashboard/` |
| Reports export | Pendiente | `services/reports.service.ts` |

## Dependencias

### Depende de
- MCH-004 (Sales data)
- MCH-003 (Products data)
- MCH-014 (Customers data)

### Bloquea a
- Ninguno

## Endpoints API (Existentes)

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /analytics/dashboard | KPIs principales |
| GET | /analytics/sales-by-day | Ventas por dia |
| GET | /analytics/sales-by-hour | Ventas por hora |
| GET | /analytics/top-products | Top productos |
| GET | /analytics/payment-methods | Por metodo pago |
| GET | /reports/daily-close | Corte de caja |
| GET | /reports/export | Exportar reporte |

## Componentes React

### Dashboard Page
- `pages/Dashboard.tsx`
- Grid de KPI cards
- Graficas con Recharts
- Alertas sidebar

### KPICard
- Valor principal
- Comparativo (% vs anterior)
- Icono y color

### SalesChart
- Recharts BarChart/LineChart
- Selector de periodo
- Tooltip interactivo

### TopProductsList
- Lista ordenada
- Cantidad y total
- Tendencia

### AlertsPanel
- Stock bajo
- Fiados pendientes
- Pedidos nuevos

## Criterios de Aceptacion

- [x] Dashboard muestra KPIs correctos
- [x] Graficas cargan datos reales
- [x] Reportes se exportan a PDF/Excel
- [x] Configuracion de negocio funciona
- [x] Gestion de usuarios funciona

## Tecnologias

- **Framework:** React 18
- **Graficas:** Recharts
- **Tablas:** TanStack Table
- **Export PDF:** jsPDF
- **Export Excel:** SheetJS (xlsx)

---

**Ultima actualizacion:** 2026-01-17