michangarrito/docs/01-epicas/MCH-035-sistema-reportes.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-035	Epic	MCH-035: Sistema de Reportes	MCH-035	Planificado	8	P2	2026-01-13	2026-01-13	4.0.1	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

{
  '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

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

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

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