mercadodevida/docs/reporting/REPORTING_TASKS.md

Reporting — Roadmap de tareas

Este documento divide la implementación en tickets pequeños y verificables. F-142 solo entrega discovery/arquitectura; no implementa dashboards. Las referencias RPT-* son identificadores de trabajo del plan y se han abierto en backlog como:

Plan	Ticket backlog	Título
RPT-001	F-143	Contracts, filters and RBAC
RPT-002	F-144	Historical store and financial snapshots
RPT-003	F-145	Payment lines and POS cash-safe capture
RPT-004	F-146	ReportingService, summary and sales API
RPT-005	F-147	Admin reporting shell and global filters
RPT-006	F-148	Sales dashboard and channel views
RPT-007	F-149	Product, category and brand reports
RPT-008	F-150	CSV export

RPT-009 en adelante se abrirá como backlog cuando sus dependencias P0 estén aprobadas.

Dependencias y orden recomendado

RPT-001 contratos/filtros/RBAC
   ├── RPT-002 datos históricos mínimos (store, tax/cost snapshots)
   ├── RPT-003 líneas de pago POS/ecommerce
   └── RPT-004 ReportingService + summary/sales
              ├── RPT-005 Admin shell + filtros URL
              ├── RPT-006 Sales dashboard / channel / store / terminal
              ├── RPT-007 Product/category/brand reports
              └── RPT-008 CSV export

RPT-003 ──> RPT-011 Payments report
RPT-002 ──> RPT-012 Tax report / RPT-013 margin
POS cash implementation ──> RPT-014 cash report
Refund model ──> RPT-015 refunds report

Regla: ningún ticket debe inventar datos ausentes; si una métrica no tiene fuente, se incorpora como unavailable o se crea primero el ticket de modelo correspondiente.

---

P0 — Base útil y primera entrega

RPT-001 — Reporting contracts, filters and permissions

Objetivo: crear ReportingFilters, parser común, rangos relativos, comparación y permisos backend/frontend.

Incluye:

• intervalos [from,to) en UTC + zona Europe/Madrid para agrupaciones;
• presets hoy/ayer/7/30 días/mes/año/período anterior;
• channel, tiendas, terminales, cajeros, producto, categoría, marca, cliente, estado;
• paginación, orden y límite máximo;
• respuesta común con range, comparison, dataAvailability, updatedAt;
• permisos REPORTING_*, incluyendo REPORTING_FINANCIAL y REPORTING_EXPORT;
• tests de fechas invertidas, zona, cero y filtros combinados.

No incluye: SQL de reportes ni UI final.

RPT-002 — Reporting data snapshots and store scope

Objetivo: hacer reportables de forma fiable las dimensiones históricas obligatorias.

Evaluar/implementar en migraciones:

• orders_orders.store_id NOT NULL, FK, backfill y escritura desde ecommerce/POS/admin;
• snapshot vat_rate y cost_at_sale_cents nullable en orders_items;
• snapshot de marca/categoría solo si el negocio necesita histórico estable, no copiar el catálogo sin justificación;
• separación de shipping_cents de los totales;
• índices medidos para fecha/tienda/canal.

Aceptación: migración reversible/documentada, ventas antiguas conservan valores, margen/IVA siguen unavailable si faltan snapshots.

RPT-003 — Payment lines and cash-safe payment capture

Objetivo: poder informar efectivo/tarjeta/otros y pagos mixtos sin guardar datos de tarjeta.

Incluye:

• tabla inmutable order_payment_lines o equivalente, con order, método, tienda, terminal, sesión, importe, currency, provider ref, estado y timestamps;
• integración de venta ecommerce y POS con la línea real;
• idempotencia por evento/provider;
• no PAN/CVV;
• relación con reembolsos preparada.

Aceptación: una venta con uno o varios métodos se puede sumar exactamente una vez; pruebas de duplicado y cross-store.

RPT-004 — ReportingService, summary and sales API

Objetivo: primera API real de reporting a partir de pedidos/líneas.

Endpoints: GET /reporting/summary y GET /reporting/sales.

Métricas P0: ventas totales registradas, pedidos/tickets, unidades, ticket medio, descuentos e impuestos registrados; tendencia y comparación cuando haya período anterior.

Agrupaciones: día, semana, mes, canal, tienda y terminal cuando existan.

Aceptación: SQL parametrizado, sin N+1, estados documentados, respuesta de disponibilidad, tests unitarios de fórmulas e integración con ecommerce/POS.

RPT-005 — Admin Reporting shell and global filters

Objetivo: añadir Reporting al menú Admin y una pantalla /reporting reutilizando Auth/API/layout existentes.

Componentes: ReportingLayout, ReportingFilters, DateRangePicker, ComparisonSelector, KpiCard, ComparisonKpi, loading/error/empty/no-data states.

Aceptación: filtros se reflejan en URL, sobreviven navegación válida, tablet usable, no se cargan listas masivas en frontend, backend autoriza cada petición.

RPT-006 — Sales dashboard and channel/store views

Objetivo: presentar summary/sales real sin recalcular en React.

Incluye: KPIs, tendencia, ecommerce vs TPV, tiendas, terminales y tabla paginada con drill-down a pedidos.

Aceptación: filtros globales, comparación equivalente, importes EUR en céntimos convertidos solo para presentación, unavailable cuando no hay store/terminal histórico.

RPT-007 — Product, category and brand reports

Objetivo: ranking de productos y desglose de categorías/marcas usando catálogo real.

Incluye: top 10/25/50, unidades, ventas de mercancía, precio medio, descuento, devoluciones si existen; filtros y orden server-side.

Nota: marcar que categoría/marca es clasificación actual mientras no exista snapshot histórico.

RPT-008 — CSV export

Objetivo: exportar summary/sales/products respetando exactamente filtros, rango, orden y columnas.

Aceptación: stream/paginación server-side, BOM/encoding adecuado para Excel, cabecera con fecha/zona/filtros, permission REPORTING_EXPORT, límites y auditoría.

RPT-009 — Reporting frontend API client and table primitives

Objetivo: adaptar api-client.ts con tipos de respuesta y tabla reutilizable sin duplicar fetch/serialización.

Incluye: abort/cancel de consultas, estados de error, columnas configurables y enlaces drill-down.

RPT-010 — P0 integration and regression suite

Objetivo: fixtures transaccionales y pruebas end-to-end.

Casos: venta ecommerce, venta POS COMPLETED, pedido cancelado, descuento, stock confirmado, comparación de período, filtro tienda no autorizada y export con filtros.

---

P1 — Informes operativos y comerciales

RPT-011 — Payments report

Depende de RPT-003. Importe, operaciones, porcentaje, medio y devoluciones por método; admite pago mixto y filtra método/tienda/terminal.

RPT-012 — Fiscal/IVA report

Depende del snapshot fiscal de RPT-002. Base imponible, tipo de IVA, cuota y total usando datos de la venta, nunca configuración actual.

RPT-013 — Customers report

Clientes únicos, nuevos, recurrentes, pedidos, ventas, ticket y última compra. Ocultar PII según permiso y separar walk-ins.

RPT-014 — Inventory report

Stock actual por tienda, vendido, stock bajo/sin stock, rotación aproximada y días de stock solo con denominador suficiente. Usa inventory_stock, movimientos y pedidos sin duplicar ventas.

RPT-015 — Products without movement

Configurable 30/60/90 días: stock positivo + última venta anterior al umbral. Indicar “sin historial” distinto de “sin movimiento”.

RPT-016 — Categories and brands detail

Tablas con ventas/unidades/pedidos/% y navegación a producto; clasificación histórica documentada.

RPT-017 — Discounts report

Depende de snapshot de promoción. Total, porcentaje, media, código/tipo, producto/categoría/tienda/terminal/cajero y descuentos manuales identificables.

RPT-018 — Refund model and report

Crear primero order_refunds/líneas y luego importe, cantidad, motivo, producto, canal, tienda, terminal, usuario y porcentaje sobre ventas. No inferir importe desde estado.

RPT-019 — Cash sessions report

Depende de movimientos de caja/pagos POS. Apertura, ventas efectivo, esperado, contado, diferencia, cajero, terminal, tienda y filtro “solo diferencias”. Proteger con REPORTING_CASH/REPORTING_FINANCIAL.

RPT-020 — Drill-down navigation

Ventas → canal → tienda → terminal → producto → pedido/ticket, conservando filtros compatibles y evitando IDs sensibles en URLs no autorizadas.

RPT-021 — Period comparison UX

Presets y período equivalente; mostrar valor actual, anterior y porcentaje/null. Tests para períodos con cero y distinta duración.

RPT-022 — Server-side reporting tables

Paginación, búsqueda, sorting, selección de columnas y límites. Nunca cargar decenas de miles de filas en React.

---

P2 — Análisis avanzado condicionado a datos

RPT-023 — Historical cost and gross margin

Solo tras cost_at_sale_cents: revenue, COGS, gross profit y margen por producto/categoría/marca/tienda/canal. No usar el coste actual.

RPT-024 — Sales by hour and weekday

Agrupación en zona local, line/bar chart y tabla de horas punta/valle. Validar volumen mínimo para evitar conclusiones engañosas.

RPT-025 — Sales heatmap

Heatmap día de semana/hora por ventas o tickets, con selector de métrica y accesibilidad alternativa en tabla.

RPT-026 — Advanced stock analytics

Rotación, velocidad de venta, días de stock y productos sin movimiento con ventanas configurables y advertencia de aproximación.

RPT-027 — XLSX export

Exportación server-side con columnas/formato/filtros y límites; conservar auditoría y evitar bloqueo del request.

RPT-028 — PDF export

Solo para informes donde el formato aporte valor (resumen/caja/fiscal); no convertir tablas grandes a PDF sin paginación.

---

P3 — Evolución futura, no implementar ahora

• RPT-029 — Forecast de ventas.
• RPT-030 — Forecast y alertas de stock.
• RPT-031 — Alertas de negocio.
• RPT-032 — Informes programados/email.
• RPT-033 — ABC de productos, cohortes y RFM.
• RPT-034 — Integración con BI/API externa.
• RPT-035 — Materialized views/agregaciones cuando volumen y EXPLAIN lo justifiquen.

Definition of Done común

• Contrato/API/documentación actualizados.
• Backend calcula métricas; frontend no duplica reglas financieras.
• Query parametrizada y plan revisado para consultas críticas.
• Permiso backend + prueba negativa cross-store.
• Estados loading/empty/error/no-data/unavailable.
• Unit tests de cálculos y integration tests de datos reales.
• CSV/XLSX respeta filtros si aplica.
• npm run build, npm test, ./scripts/verify.sh y gates reviewer/security/qa verdes.