---
id: EPIC-MCH-034
type: Epic
title: "MCH-034: Analytics y Metricas del Negocio"
code: MCH-034
status: Planificado
phase: 8
priority: P1
created_at: 2026-01-13
updated_at: 2026-01-13
simco_version: "4.0.1"
dependencies:
  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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
[
  {
    "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
```typescript
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)