michangarrito/docs/01-epicas/MCH-021-dashboard-web.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-021	Epic	MCH-021: Dashboard Web	MCH-021	Completado	5	P1	2026-01-10	2026-01-17	4.0.1	21	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

• Dashboard muestra KPIs correctos
• Graficas cargan datos reales
• Reportes se exportan a PDF/Excel
• Configuracion de negocio funciona
• 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