michangarrito/docs/01-epicas/MCH-034-analytics.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-034	Epic	MCH-034: Analytics y Metricas del Negocio	MCH-034	Planificado	8	P1	2026-01-13	2026-01-13	4.0.1	blocks depends_on MCH-031 MCH-021

MCH-034: Analytics y Metricas del Negocio

Metadata

• Codigo: MCH-034
• Fase: 8 - Reportes y Metricas
• Prioridad: P1 (Alta)
• Estado: Planificado
• Story Points: 21
• Sprint Objetivo: Sprint 8-9

Descripcion

Modulo de analytics que proporciona metricas y KPIs clave para el changarrito. Incluye metricas de ventas, clientes, fiados e inventario con tendencias historicas. Todas las metricas se calculan en tiempo real basandose en datos de ventas, clientes, fiados, productos y logs de auditoria. Este modulo permite al tendero tomar decisiones informadas sobre su negocio.

Objetivos

1. Proporcionar metricas de ventas (totales, ticket promedio, tendencias, productos top)
2. Calcular metricas de clientes (nuevos, recurrentes, retencion)
3. Analizar estado de fiados (pendientes, cobrados, morosidad)
4. Monitorear inventario (stock bajo, rotacion de productos)
5. Generar resumen de KPIs para dashboard del tendero

Alcance

Incluido

• Metricas de ventas por periodo (dia, semana, mes)
• Metricas de clientes nuevos y recurrentes
• Estado de fiados y cobranza
• Alertas de inventario bajo
• Resumen de KPIs principales para dashboard
• Tendencias historicas para graficos
• Soporte para periodos: 7d, 30d, 90d, 1y

Excluido

• Exportacion de reportes a PDF/Excel
• Metricas en tiempo real (streaming)
• Comparativas entre sucursales/tenants
• Alertas automaticas basadas en metricas
• Predicciones con machine learning

Metricas Disponibles

Metricas de Ventas

Metrica	Descripcion
totalSales	Total de ventas en pesos en el periodo
salesCount	Cantidad de transacciones realizadas
averageTicket	Ticket promedio por venta
salesByDay	Ventas agrupadas por dia
salesByHour	Distribucion de ventas por hora del dia
topProducts	Top 10 productos mas vendidos
salesGrowth	Crecimiento de ventas (%) vs periodo anterior
cashSales	Ventas en efectivo
cardSales	Ventas con tarjeta
fiadoSales	Ventas a credito (fiados)

Metricas de Clientes

Metrica	Descripcion
totalCustomers	Total de clientes registrados
newCustomers	Nuevos clientes en el periodo
activeCustomers	Clientes que compraron en el periodo
customerRetention	Tasa de retencion (%) clientes recurrentes
averagePurchaseFrequency	Frecuencia promedio de compra por cliente
topCustomers	Top 10 clientes por monto de compra
customerGrowth	Crecimiento de clientes (%) vs periodo anterior

Metricas de Fiados

Metrica	Descripcion
totalFiados	Cantidad total de fiados activos
pendingBalance	Saldo total pendiente por cobrar
paidThisPeriod	Monto cobrado en el periodo
paidOnTime	Porcentaje de pagos a tiempo
overdueCount	Cantidad de fiados vencidos
overdueAmount	Monto total vencido
averageFiadoAmount	Monto promedio por fiado
fiadosByCustomer	Distribucion de fiados por cliente
collectionRate	Tasa de cobranza del periodo

Metricas de Inventario

Metrica	Descripcion
totalProducts	Total de productos en catalogo
activeProducts	Productos con stock disponible
lowStockCount	Productos con stock bajo el minimo
outOfStockCount	Productos agotados
turnoverRate	Tasa de rotacion de inventario
inventoryValue	Valor total del inventario
topSellingCategories	Categorias con mayor venta
slowMovingProducts	Productos con baja rotacion

Summary KPIs (Dashboard)

Metrica	Descripcion
totalSalesToday	Ventas del dia actual
totalSalesWeek	Ventas de la semana
totalSalesMonth	Ventas del mes
pendingFiados	Monto pendiente de fiados
lowStockAlerts	Alertas de stock bajo
activeCustomers	Clientes activos del mes
salesGrowth	Crecimiento vs mes anterior
topProductToday	Producto mas vendido hoy

Trend Data (Graficos)

Serie	Descripcion
daily_sales	Ventas diarias
weekly_sales	Ventas semanales
new_customers	Nuevos clientes por periodo
fiados_collected	Fiados cobrados por periodo
inventory_value	Valor de inventario por periodo

Endpoints API

Metodo	Endpoint	Descripcion
GET	/analytics/sales	Metricas de ventas
GET	/analytics/customers	Metricas de clientes
GET	/analytics/fiados	Metricas de fiados
GET	/analytics/inventory	Metricas de inventario
GET	/analytics/summary	Resumen de KPIs para dashboard
GET	/analytics/trends	Datos de tendencias historicas

GET /analytics/sales

Retorna metricas de ventas para el changarrito autenticado.

Query Parameters:

Parametro	Tipo	Default	Descripcion
period	string	30d	Periodo: 7d, 30d, 90d, 1y

Response:

{
  "totalSales": 45000.00,
  "salesCount": 320,
  "averageTicket": 140.63,
  "salesGrowth": 12.5,
  "cashSales": 35000.00,
  "cardSales": 5000.00,
  "fiadoSales": 5000.00,
  "topProducts": [
    { "productId": "uuid", "name": "Coca-Cola 600ml", "quantity": 150, "revenue": 3750.00 },
    { "productId": "uuid", "name": "Pan Bimbo Grande", "quantity": 80, "revenue": 3200.00 }
  ],
  "salesByDay": [
    { "date": "2026-01-01", "total": 1500.00, "count": 12 },
    { "date": "2026-01-02", "total": 1800.00, "count": 15 }
  ],
  "peakHour": 18
}

GET /analytics/customers

Retorna metricas de clientes para el changarrito autenticado.

Query Parameters:

Parametro	Tipo	Default	Descripcion
period	string	30d	Periodo: 7d, 30d, 90d, 1y

Response:

{
  "totalCustomers": 85,
  "newCustomers": 12,
  "activeCustomers": 45,
  "customerRetention": 72.5,
  "averagePurchaseFrequency": 3.2,
  "customerGrowth": 8.5,
  "topCustomers": [
    { "customerId": "uuid", "name": "Juan Perez", "totalPurchases": 2500.00, "visits": 15 },
    { "customerId": "uuid", "name": "Maria Garcia", "totalPurchases": 1800.00, "visits": 12 }
  ]
}

GET /analytics/fiados

Retorna metricas de fiados para el changarrito autenticado.

Query Parameters:

Parametro	Tipo	Default	Descripcion
period	string	30d	Periodo: 7d, 30d, 90d, 1y

Response:

{
  "totalFiados": 25,
  "pendingBalance": 8500.00,
  "paidThisPeriod": 12000.00,
  "paidOnTime": 68.5,
  "overdueCount": 8,
  "overdueAmount": 3200.00,
  "averageFiadoAmount": 340.00,
  "collectionRate": 58.5,
  "fiadosByCustomer": [
    { "customerId": "uuid", "name": "Pedro Lopez", "balance": 1500.00, "fiados": 3 },
    { "customerId": "uuid", "name": "Ana Martinez", "balance": 800.00, "fiados": 2 }
  ]
}

GET /analytics/inventory

Retorna metricas de inventario para el changarrito autenticado.

Query Parameters:

Parametro	Tipo	Default	Descripcion
period	string	30d	Periodo: 7d, 30d, 90d, 1y

Response:

{
  "totalProducts": 150,
  "activeProducts": 142,
  "lowStockCount": 12,
  "outOfStockCount": 8,
  "turnoverRate": 2.5,
  "inventoryValue": 85000.00,
  "topSellingCategories": [
    { "category": "Bebidas", "sales": 15000.00, "percentage": 33.3 },
    { "category": "Abarrotes", "sales": 12000.00, "percentage": 26.7 }
  ],
  "lowStockProducts": [
    { "productId": "uuid", "name": "Leche Lala 1L", "currentStock": 3, "minStock": 10 },
    { "productId": "uuid", "name": "Huevo 12pz", "currentStock": 2, "minStock": 5 }
  ]
}

GET /analytics/summary

Retorna resumen de KPIs principales para dashboard del tendero.

Response:

{
  "totalSalesToday": 2500.00,
  "totalSalesWeek": 15000.00,
  "totalSalesMonth": 45000.00,
  "salesGrowth": 12.5,
  "pendingFiados": 8500.00,
  "lowStockAlerts": 12,
  "activeCustomers": 45,
  "topProductToday": {
    "name": "Coca-Cola 600ml",
    "quantity": 25,
    "revenue": 625.00
  },
  "salesByPaymentMethod": {
    "cash": 35000.00,
    "card": 5000.00,
    "fiado": 5000.00
  }
}

GET /analytics/trends

Retorna datos de tendencias historicas para graficos.

Query Parameters:

Parametro	Tipo	Default	Descripcion
period	string	30d	Periodo: 7d, 30d, 90d, 1y

Response:

[
  {
    "metric": "daily_sales",
    "data": [
      { "date": "2026-01-01", "value": 1500.00 },
      { "date": "2026-01-02", "value": 1800.00 },
      { "date": "2026-01-03", "value": 2200.00 }
    ]
  },
  {
    "metric": "new_customers",
    "data": [
      { "date": "2026-01-01", "value": 2 },
      { "date": "2026-01-02", "value": 1 },
      { "date": "2026-01-03", "value": 3 }
    ]
  },
  {
    "metric": "fiados_collected",
    "data": [
      { "date": "2026-01-01", "value": 500.00 },
      { "date": "2026-01-02", "value": 350.00 },
      { "date": "2026-01-03", "value": 800.00 }
    ]
  },
  {
    "metric": "inventory_value",
    "data": [
      { "date": "2026-01-01", "value": 82000.00 },
      { "date": "2026-01-02", "value": 83500.00 },
      { "date": "2026-01-03", "value": 85000.00 }
    ]
  }
]

Permisos Requeridos

Endpoint	Permiso	Rol Minimo
GET /analytics/sales	analytics:read	Owner
GET /analytics/customers	analytics:read	Owner
GET /analytics/fiados	analytics:read	Owner
GET /analytics/inventory	analytics:read	Owner
GET /analytics/summary	analytics:read	Owner, Empleado
GET /analytics/trends	analytics:read	Owner

Nota: El endpoint /analytics/summary esta disponible para empleados con vista reducida (solo ventas del dia y alertas de stock).

---

Historias de Usuario

MCH-US-150: Dashboard de Metricas del Tendero

Como dueno del changarrito Quiero ver un resumen de metricas clave en mi dashboard Para entender rapidamente el estado de mi negocio

Story Points: 8

Criterios de Aceptacion:

• [CA-150-1] Dashboard muestra ventas del dia, semana y mes
• [CA-150-2] Muestra crecimiento porcentual vs periodo anterior
• [CA-150-3] Indica cantidad de fiados pendientes y monto
• [CA-150-4] Alerta visualmente sobre productos con stock bajo
• [CA-150-5] Muestra producto mas vendido del dia
• [CA-150-6] Grafico de ventas de los ultimos 7 dias
• [CA-150-7] Se actualiza en tiempo real al registrar ventas

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-150-01	Crear AnalyticsModule en backend	Backend	0.5
MCH-TT-150-02	Implementar AnalyticsService base	Backend	1
MCH-TT-150-03	Endpoint GET /analytics/summary	Backend	1
MCH-TT-150-04	Componente DashboardMetrics en frontend	Frontend	2
MCH-TT-150-05	Integracion con graficos (Chart.js/Recharts)	Frontend	1.5
MCH-TT-150-06	Widget de alertas de stock bajo	Frontend	1
MCH-TT-150-07	Tests unitarios	Test	0.5
MCH-TT-150-08	Documentacion de endpoints	Docs	0.5

---

MCH-US-151: Reportes de Ventas

Como dueno del changarrito Quiero ver reportes detallados de mis ventas Para identificar tendencias y productos estrella

Story Points: 8

Criterios de Aceptacion:

• [CA-151-1] Filtrar ventas por periodo (7d, 30d, 90d, 1y)
• [CA-151-2] Ver desglose por metodo de pago (efectivo, tarjeta, fiado)
• [CA-151-3] Lista de top 10 productos mas vendidos
• [CA-151-4] Grafico de ventas por dia
• [CA-151-5] Identificar hora pico de ventas
• [CA-151-6] Calcular ticket promedio del periodo

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-151-01	Endpoint GET /analytics/sales	Backend	1.5
MCH-TT-151-02	Queries SQL optimizadas para agregaciones	Backend	1
MCH-TT-151-03	Endpoint GET /analytics/trends	Backend	1
MCH-TT-151-04	Pagina ReportesVentas en frontend	Frontend	2
MCH-TT-151-05	Componente filtro de periodos	Frontend	0.5
MCH-TT-151-06	Graficos de tendencias	Frontend	1
MCH-TT-151-07	Tests de integracion	Test	0.5
MCH-TT-151-08	Documentacion	Docs	0.5

---

MCH-US-152: Metricas de Fiados y Clientes

Como dueno del changarrito Quiero ver el estado de mis fiados y comportamiento de clientes Para gestionar mejor la cobranza y fidelizar clientes

Story Points: 5

Criterios de Aceptacion:

• [CA-152-1] Ver saldo total pendiente de fiados
• [CA-152-2] Lista de clientes con fiados vencidos
• [CA-152-3] Tasa de cobranza del periodo
• [CA-152-4] Top clientes por monto de compra
• [CA-152-5] Nuevos clientes vs clientes recurrentes
• [CA-152-6] Alertas de fiados por vencer

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-152-01	Endpoint GET /analytics/fiados	Backend	1
MCH-TT-152-02	Endpoint GET /analytics/customers	Backend	1
MCH-TT-152-03	Pagina MetricasFiados en frontend	Frontend	1.5
MCH-TT-152-04	Componente lista fiados vencidos	Frontend	0.5
MCH-TT-152-05	Tests unitarios	Test	0.5
MCH-TT-152-06	Documentacion	Docs	0.5

---

Resumen de Story Points

Historia	SP	Sprint
MCH-US-150: Dashboard de Metricas	8	8
MCH-US-151: Reportes de Ventas	8	8
MCH-US-152: Metricas de Fiados y Clientes	5	9
TOTAL	21	8-9

---

Criterios de Aceptacion de Epica

• Dashboard muestra KPIs correctos en tiempo real
• Metricas de ventas calculan correctamente por periodo
• Metricas de fiados reflejan estado actual de cobranza
• Metricas de inventario identifican productos con stock bajo
• Graficos de tendencias muestran datos historicos correctos
• Filtro de periodos funciona (7d, 30d, 90d, 1y)
• Datos se filtran por tenant_id del usuario autenticado
• Cobertura de tests >80%
• Rendimiento: endpoints responden en <500ms

Entregables

Entregable	Estado	Sprint	Ubicacion
analytics.module.ts	Planificado	8	apps/backend/src/modules/analytics/
analytics.controller.ts	Planificado	8	apps/backend/src/modules/analytics/
analytics.service.ts	Planificado	8	apps/backend/src/modules/analytics/
DTOs	Planificado	8	apps/backend/src/modules/analytics/dto/
Pagina Dashboard	Planificado	8	apps/frontend/src/pages/dashboard/
Pagina Reportes	Planificado	8	apps/frontend/src/pages/reportes/

Dependencias

Depende de

• MCH-031 (Audit Logs) - Para metricas de uso y actividad
• MCH-021 (Ventas y POS) - Datos de ventas y transacciones

Bloquea a

• Ninguno (modulo de solo lectura)

Entidades Utilizadas

import { Sale } from '../sales/entities/sale.entity';
import { Customer } from '../customers/entities/customer.entity';
import { Fiado } from '../fiados/entities/fiado.entity';
import { FiadoPayment } from '../fiados/entities/fiado-payment.entity';
import { Product } from '../products/entities/product.entity';
import { AuditLog } from '../audit/entities/audit-log.entity';

Notas de Implementacion

Calculo de Periodos

• El periodo se calcula desde la fecha actual hacia atras
• Para comparar crecimiento, se usa el periodo anterior de igual duracion
• Truncamiento de fechas:
  • 7d, 30d: Por dia
  • 90d: Por semana
  • 1y: Por mes

Performance

• Las consultas utilizan agregaciones SQL para eficiencia
• Se usa COUNT(DISTINCT customer_id) para clientes activos unicos
• Las tendencias usan DATE_TRUNC para agrupar por periodo
• Considerar cache en Redis para metricas frecuentes (summary)

Estimaciones

• customerRetention: Se calcula como (clientesRecurrentes / clientesActivos) * 100
• turnoverRate: Se calcula como (costoVentas / inventarioPromedio)

---

Referencia Template-SaaS

Esta epica esta basada en el modulo SAAS-016 de template-saas, adaptado al contexto de punto de venta para changarritos:

Modulo SAAS	Version	Adaptacion MCH
SAAS-016 Analytics	1.0.0	Metricas de ventas, clientes, fiados, inventario

Mapeo de Metricas SAAS-016 a MCH-034

SAAS-016 Original	MCH-034 Adaptado
User Metrics	Customer Metrics
Billing Metrics	Sales Metrics
Usage Metrics	Inventory Metrics
-	Fiados Metrics (nuevo)

Ver documentacion fuente en projects/template-saas/docs/01-modulos/SAAS-016-analytics.md

---

Ultima actualizacion: 2026-01-13 Autor: Architecture Team Alineacion: template-saas v1.0.0 (SAAS-016)