242 lines
11 KiB
Markdown
242 lines
11 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|