rckrdmrd
5a49ad0185
## Documentation - Align MCH-029 to MCH-032 with template-saas modules (SAAS-008 to SAAS-015) - Create MCH-034 (Analytics) and MCH-035 (Reports) from SAAS-016/017 - Update PLAN-DESARROLLO.md with Phase 7 and 8 - Update _MAP.md indexes (35 total epics) ## Database (5 new schemas, 14 tables) - Add storage schema: buckets, files, signed_urls - Add webhooks schema: endpoints, deliveries - Add audit schema: logs, retention_policies - Add features schema: flags, tenant_flags (14 seeds) - Add analytics schema: metrics, events, reports, report_schedules - Add auth.oauth_connections for MCH-030 - Add timestamptz_to_date() IMMUTABLE function - Update EXPECTED_SCHEMAS in recreate-database.sh ## Analysis Reports - ANALISIS-INTEGRACION-TEMPLATE-SAAS-2026-01-13.md - VALIDACION-COHERENCIA-2026-01-13.md - GAP-ANALYSIS-BD-2026-01-13.md - REPORTE-EJECUCION-2026-01-13.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
447 lines
16 KiB
Markdown
447 lines
16 KiB
Markdown
---
|
|
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
|