---
id: EPIC-MCH-035
type: Epic
title: "MCH-035: Sistema de Reportes"
code: MCH-035
status: Planificado
phase: 8
priority: P2
created_at: 2026-01-13
updated_at: 2026-01-13
simco_version: "4.0.1"
dependencies:
  blocks: []
  depends_on: ["MCH-034", "MCH-021"]
---

# MCH-035: Sistema de Reportes

## Metadata
- **Codigo:** MCH-035
- **Fase:** 8 - Reportes y Analitica
- **Prioridad:** P2 (Media)
- **Estado:** Planificado
- **Story Points:** 21
- **Sprint Objetivo:** Sprint 8-9

## Descripcion

Sistema de generacion y exportacion de reportes en multiples formatos (PDF, Excel, CSV) para MiChangarrito. Proporciona capacidades de exportacion de datos de ventas, fiados pendientes, inventario y clientes con filtros de fecha y paginacion. Los reportes permiten al dueno del changarrito tener visibilidad completa de su negocio para toma de decisiones.

## Objetivos

1. Generar reportes de ventas con desglose diario, semanal y mensual
2. Exportar estado de fiados pendientes y pagos parciales
3. Proporcionar reportes de inventario (stock bajo, rotacion de productos)
4. Generar reportes de clientes (mejores clientes, deudores)
5. Soportar multiples formatos de exportacion (PDF, Excel, CSV)

## Alcance

### Incluido
- Generacion de reportes PDF con formato profesional para changarritos
- Exportacion a Excel (XLSX) con estilos para analisis
- Exportacion a CSV para integracion con otras herramientas
- Reporte de ventas (diario, semanal, mensual)
- Reporte de fiados pendientes y abonos
- Reporte de inventario (stock bajo, productos mas vendidos)
- Reporte de clientes (mejores clientes, deudores)
- Filtros por fecha (dateFrom, dateTo)
- Paginacion (page, limit)
- Headers de descarga configurados
- Streaming de archivos

### Excluido
- Reportes personalizados dinamicos (builder visual)
- Programacion de reportes automaticos
- Envio de reportes por email/WhatsApp
- Dashboard de reportes visuales interactivos
- Reportes de analytics avanzados
- Reportes comparativos multi-periodo

## Formatos de Exportacion

| Formato | Extension | Content-Type | Libreria |
|---------|-----------|--------------|----------|
| PDF | .pdf | application/pdf | PDFKit (opcional) |
| Excel | .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | ExcelJS (opcional) |
| CSV | .csv | text/csv | Nativo |

### Fallback Implementations
El modulo incluye implementaciones de fallback cuando las librerias PDFKit o ExcelJS no estan disponibles:
- **PDF Fallback:** Genera un archivo de texto con formato PDF basico
- **Excel Fallback:** Genera SpreadsheetML (formato XML compatible con Excel)

## Endpoints API

### Reporte de Ventas

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /reports/sales/:format | Exportar reporte de ventas |

**Parametros de Ruta:**
- `format`: Formato de exportacion (`pdf`, `excel`, `csv`)

**Query Parameters:**
- `dateFrom` (opcional): Fecha inicio filtro (ISO 8601)
- `dateTo` (opcional): Fecha fin filtro (ISO 8601)
- `period` (opcional): Periodo de agrupacion (`daily`, `weekly`, `monthly`)
- `page` (opcional): Numero de pagina (default: 1)
- `limit` (opcional): Items por pagina (default: 100, max: 10000)

**Response:**
- `200`: Archivo de reporte (StreamableFile)
- `400`: Formato invalido
- `401`: No autenticado

### Reporte de Fiados

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /reports/fiados/:format | Exportar reporte de fiados pendientes |

**Parametros de Ruta:**
- `format`: Formato de exportacion (`pdf`, `excel`, `csv`)

**Query Parameters:**
- `dateFrom` (opcional): Fecha inicio filtro (ISO 8601)
- `dateTo` (opcional): Fecha fin filtro (ISO 8601)
- `status` (opcional): Estado de fiado (`pending`, `partial`, `paid`, `overdue`)
- `page` (opcional): Numero de pagina (default: 1)
- `limit` (opcional): Items por pagina (default: 100, max: 10000)

**Response:**
- `200`: Archivo de reporte (StreamableFile)
- `400`: Formato invalido
- `401`: No autenticado

### Reporte de Inventario

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /reports/inventory/:format | Exportar reporte de inventario |

**Parametros de Ruta:**
- `format`: Formato de exportacion (`pdf`, `excel`, `csv`)

**Query Parameters:**
- `dateFrom` (opcional): Fecha inicio filtro (ISO 8601)
- `dateTo` (opcional): Fecha fin filtro (ISO 8601)
- `filter` (opcional): Filtro especial (`low_stock`, `best_sellers`, `slow_moving`)
- `page` (opcional): Numero de pagina (default: 1)
- `limit` (opcional): Items por pagina (default: 100, max: 10000)

**Response:**
- `200`: Archivo de reporte (StreamableFile)
- `400`: Formato invalido
- `401`: No autenticado

## Tipos de Reportes

### Reporte de Ventas

Permite visualizar el resumen de ventas del changarrito con diferentes niveles de agrupacion.

| Columna PDF | Columna Excel/CSV | Descripcion |
|-------------|-------------------|-------------|
| Fecha | date | Fecha de la venta |
| Folio | sale_number | Numero de venta |
| Cliente | customer_name | Nombre del cliente (si aplica) |
| Productos | items_count | Cantidad de productos |
| Subtotal | subtotal | Subtotal sin descuentos |
| Descuento | discount | Descuento aplicado |
| Total | total | Total de la venta |
| Metodo Pago | payment_method | Efectivo, tarjeta, fiado |

**Periodos disponibles:**
- **Diario:** Desglose hora por hora del dia seleccionado
- **Semanal:** Desglose dia por dia de la semana
- **Mensual:** Desglose semana por semana del mes

### Reporte de Fiados Pendientes

Muestra el estado actual de todos los fiados del changarrito.

| Columna PDF | Columna Excel/CSV | Descripcion |
|-------------|-------------------|-------------|
| Cliente | customer_name | Nombre del cliente deudor |
| Telefono | customer_phone | Telefono de contacto |
| Fecha Fiado | created_at | Fecha en que se genero el fiado |
| Monto Original | original_amount | Monto total del fiado |
| Abonos | total_payments | Suma de abonos realizados |
| Saldo Pendiente | pending_balance | Monto pendiente por cobrar |
| Dias Vencido | days_overdue | Dias desde la fecha de vencimiento |
| Estado | status | Pendiente, parcial, vencido |

### Reporte de Inventario

Proporciona visibilidad del estado actual del inventario.

| Columna PDF | Columna Excel/CSV | Descripcion |
|-------------|-------------------|-------------|
| SKU | sku | Codigo del producto |
| Producto | product_name | Nombre del producto |
| Categoria | category_name | Categoria del producto |
| Stock Actual | current_stock | Cantidad en existencia |
| Stock Minimo | min_stock | Nivel de reorden |
| Precio Compra | purchase_price | Costo unitario |
| Precio Venta | sale_price | Precio al publico |
| Valor Inventario | inventory_value | Stock * precio compra |

**Filtros especiales:**
- **Stock Bajo:** Productos donde stock_actual <= stock_minimo
- **Mas Vendidos:** Top productos por cantidad vendida en periodo
- **Baja Rotacion:** Productos sin movimiento en 30+ dias

### Reporte de Clientes

Analisis del comportamiento de clientes del changarrito.

| Columna PDF | Columna Excel/CSV | Descripcion |
|-------------|-------------------|-------------|
| Cliente | customer_name | Nombre del cliente |
| Telefono | phone | Telefono de contacto |
| Total Compras | total_purchases | Suma de compras en periodo |
| Cantidad Visitas | visit_count | Numero de transacciones |
| Ticket Promedio | avg_ticket | Promedio por visita |
| Fiados Activos | active_fiados | Numero de fiados pendientes |
| Saldo Deudor | debt_balance | Total adeudado |
| Ultima Visita | last_visit | Fecha ultima compra |

**Filtros especiales:**
- **Mejores Clientes:** Top clientes por volumen de compra
- **Deudores:** Clientes con fiados pendientes o vencidos

---

## Historias de Usuario

### MCH-US-120: Reportes de Ventas

**Como** dueno de changarrito
**Quiero** generar reportes de mis ventas en diferentes periodos
**Para** conocer el desempeno de mi negocio y tomar decisiones

**Story Points:** 8

**Criterios de Aceptacion:**
- [CA-120-1] Generar reporte de ventas diario con desglose por hora
- [CA-120-2] Generar reporte de ventas semanal con desglose por dia
- [CA-120-3] Generar reporte de ventas mensual con desglose por semana
- [CA-120-4] Exportar a PDF con formato profesional y logo del changarrito
- [CA-120-5] Exportar a Excel con formulas de totales
- [CA-120-6] Exportar a CSV para importar a otras herramientas
- [CA-120-7] Filtrar por rango de fechas personalizado
- [CA-120-8] Incluir totales y promedios en el reporte

**Tareas:**
| ID | Tarea | Tipo | SP |
|----|-------|------|-----|
| MCH-TT-120-01 | Crear ReportsModule y estructura base | Backend | 0.5 |
| MCH-TT-120-02 | Implementar ReportsService con metodos de ventas | Backend | 1.5 |
| MCH-TT-120-03 | Implementar PdfService para ventas | Backend | 1.5 |
| MCH-TT-120-04 | Implementar ExcelService para ventas | Backend | 1.5 |
| MCH-TT-120-05 | Implementar CsvService para ventas | Backend | 0.5 |
| MCH-TT-120-06 | Crear ReportsController con endpoint ventas | Backend | 0.5 |
| MCH-TT-120-07 | DTOs de query y validaciones | Backend | 0.5 |
| MCH-TT-120-08 | Tests unitarios reportes ventas | Test | 1 |
| MCH-TT-120-09 | Documentacion API reportes ventas | Docs | 0.5 |

---

### MCH-US-121: Reportes de Fiados e Inventario

**Como** dueno de changarrito
**Quiero** generar reportes de fiados pendientes e inventario
**Para** controlar mis cuentas por cobrar y existencias

**Story Points:** 13

**Criterios de Aceptacion:**
- [CA-121-1] Generar reporte de fiados pendientes con saldo por cliente
- [CA-121-2] Filtrar fiados por estado (pendiente, parcial, vencido)
- [CA-121-3] Generar reporte de inventario con stock actual
- [CA-121-4] Filtrar productos con stock bajo (alerta de reorden)
- [CA-121-5] Generar reporte de productos mas vendidos
- [CA-121-6] Generar reporte de mejores clientes por volumen
- [CA-121-7] Generar reporte de clientes deudores
- [CA-121-8] Exportar todos los reportes en PDF, Excel y CSV
- [CA-121-9] Incluir graficos basicos en PDF (opcional)

**Tareas:**
| ID | Tarea | Tipo | SP |
|----|-------|------|-----|
| MCH-TT-121-01 | Extender ReportsService con metodos de fiados | Backend | 2 |
| MCH-TT-121-02 | Extender PdfService para fiados | Backend | 1 |
| MCH-TT-121-03 | Extender ExcelService para fiados | Backend | 1 |
| MCH-TT-121-04 | Extender ReportsService con metodos de inventario | Backend | 2 |
| MCH-TT-121-05 | Extender PdfService para inventario | Backend | 1 |
| MCH-TT-121-06 | Extender ExcelService para inventario | Backend | 1 |
| MCH-TT-121-07 | Extender ReportsService con metodos de clientes | Backend | 1.5 |
| MCH-TT-121-08 | Crear endpoints fiados, inventario, clientes | Backend | 1 |
| MCH-TT-121-09 | Tests unitarios todos los reportes | Test | 1.5 |
| MCH-TT-121-10 | Documentacion API completa | Docs | 1 |

---

## Resumen de Story Points

| Historia | SP | Sprint |
|----------|-----|--------|
| MCH-US-120: Reportes de Ventas | 8 | 8 |
| MCH-US-121: Reportes de Fiados e Inventario | 13 | 8-9 |
| **TOTAL** | **21** | 8-9 |

---

## Criterios de Aceptacion de Epica

- [ ] Reporte de ventas genera correctamente en los 3 formatos
- [ ] Reporte de fiados muestra saldos pendientes precisos
- [ ] Reporte de inventario identifica productos con stock bajo
- [ ] Reporte de clientes ordena por volumen de compra
- [ ] Filtros de fecha funcionan correctamente
- [ ] Paginacion funciona para grandes volumenes
- [ ] PDFs tienen formato profesional legible
- [ ] Excel incluye formulas de totales
- [ ] CSV es compatible con Excel/Google Sheets
- [ ] Cobertura de tests >80%
- [ ] Documentacion de API completa

## Estructura de Archivos

```
apps/backend/src/modules/reports/
├── reports.module.ts
├── reports.controller.ts
├── index.ts
├── dto/
│   ├── report-query.dto.ts
│   ├── sales-report-query.dto.ts
│   ├── fiados-report-query.dto.ts
│   ├── inventory-report-query.dto.ts
│   └── index.ts
├── enums/
│   ├── report-format.enum.ts
│   ├── report-period.enum.ts
│   └── index.ts
├── interfaces/
│   ├── report-result.interface.ts
│   └── index.ts
└── services/
    ├── reports.service.ts
    ├── pdf.service.ts
    ├── excel.service.ts
    ├── csv.service.ts
    └── index.ts
```

## Entregables

| Entregable | Estado | Sprint | Ubicacion |
|------------|--------|--------|-----------|
| reports.module.ts | Planificado | 8 | `apps/backend/src/modules/reports/` |
| reports.controller.ts | Planificado | 8 | `apps/backend/src/modules/reports/` |
| reports.service.ts | Planificado | 8 | `apps/backend/src/modules/reports/services/` |
| pdf.service.ts | Planificado | 8 | `apps/backend/src/modules/reports/services/` |
| excel.service.ts | Planificado | 8 | `apps/backend/src/modules/reports/services/` |
| csv.service.ts | Planificado | 8 | `apps/backend/src/modules/reports/services/` |
| report-query.dto.ts | Planificado | 8 | `apps/backend/src/modules/reports/dto/` |

## Dependencias

### Depende de
- MCH-034 (Notificaciones Push) - Para alertas de reportes programados (futuro)
- MCH-021 (Inventario) - Datos de productos y stock
- MCH-014 (Ventas) - Datos de transacciones
- MCH-015 (Fiados) - Datos de cuentas por cobrar
- MCH-012 (Clientes) - Datos de clientes

### Bloquea a
- Dashboards de analytics (futuro)
- Reportes programados automaticos (futuro)
- Exportacion masiva (futuro)

## Seguridad

- Requiere autenticacion JWT (JwtAuthGuard)
- Datos filtrados por tenant_id del usuario autenticado
- No permite acceso cross-tenant
- Cache deshabilitado para evitar fugas de datos
- Limites de exportacion por plan

## Limites por Plan

| Plan | Reportes/dia | Registros max |
|------|--------------|---------------|
| Changarrito | 5 | 1,000 |
| Tiendita | 20 | 5,000 |
| Tienda Pro | Ilimitado | 50,000 |

## Headers de Respuesta

```typescript
{
  'Content-Type': '<content-type-segun-formato>',
  'Content-Disposition': 'attachment; filename="<tipo>-report-<fecha>.ext"',
  'Content-Length': '<tamano-buffer>',
  'Cache-Control': 'no-cache, no-store, must-revalidate',
  'Pragma': 'no-cache',
  'Expires': '0'
}
```

## Ejemplos de Uso

### Exportar ventas del mes a PDF
```bash
curl -X GET \
  'http://localhost:3000/reports/sales/pdf?dateFrom=2026-01-01&dateTo=2026-01-31&period=monthly' \
  -H 'Authorization: Bearer <token>' \
  -o ventas-enero-2026.pdf
```

### Exportar fiados pendientes a Excel
```bash
curl -X GET \
  'http://localhost:3000/reports/fiados/excel?status=pending' \
  -H 'Authorization: Bearer <token>' \
  -o fiados-pendientes.xlsx
```

### Exportar inventario con stock bajo a CSV
```bash
curl -X GET \
  'http://localhost:3000/reports/inventory/csv?filter=low_stock' \
  -H 'Authorization: Bearer <token>' \
  -o stock-bajo.csv
```

---

## Referencia Template-SaaS

Esta epica esta basada en el siguiente modulo de template-saas:

| Modulo SAAS | Version | Elementos Integrados |
|-------------|---------|---------------------|
| SAAS-017 Reports | 1.0.0 | Estructura base, formatos PDF/Excel/CSV, filtros, paginacion |

Ver documentacion fuente en `projects/template-saas/docs/01-modulos/SAAS-017-reports.md`

### Adaptaciones para MiChangarrito

| Aspecto | SAAS-017 (Original) | MCH-035 (Adaptado) |
|---------|---------------------|-------------------|
| Reportes principales | Users, Billing, Audit | Ventas, Fiados, Inventario, Clientes |
| Contexto | SaaS empresarial | Punto de venta changarritos |
| Filtros adicionales | Solo fechas | Fechas + periodo + status + filtros especiales |
| Columnas | Genericas multi-tenant | Especificas para comercio minorista |

---

**Ultima actualizacion:** 2026-01-13
**Autor:** Architecture Team
**Alineacion:** template-saas v1.0.0, SAAS-017