rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
23786ad49f
erp-core/docs/05-user-stories/mgn-007/US-MGN-007-006-001-dashboard-ventas.md

8.2 KiB
Raw Blame History

US-MGN-007-006-001: Dashboard de Ventas

RF Asociado: RF-MGN-007-006 Módulo: MGN-007 - Ventas Básico Epic: Reportes de Ventas Prioridad: P1 Story Points: 3 Sprint: Sprint 17 Estado: Ready for Development Fecha: 2025-11-24

User Story

Como gerente de ventas, Quiero ver un dashboard con KPIs y métricas de ventas, Para monitorear el rendimiento del equipo y tomar decisiones informadas.

Descripción Detallada

Dashboard de ventas muestra:

  • KPIs principales:

    • Total ventas del mes (revenue)

    • órdenes confirmadas

    • cotizaciones pendientes

    • Ticket promedio
    • Tasa de conversión cotización → orden

  • Gráficos:

    • Ventas por mes (últimos 12 meses)
    • Top 10 productos más vendidos
    • Top 10 clientes por revenue
    • Pipeline de cotizaciones por estado

  • Filtros:

    • Rango de fechas
    • Vendedor
    • Cliente
    • Producto

Criterios de Aceptación

Escenario 1: Ver dashboard con datos del mes actual (Camino Feliz)

Dado que hay 50 SO confirmadas en el mes actual con total=$100,000, Cuando accedo al dashboard, Entonces veo KPI "Ventas del mes: $100,000", "Órdenes: 50", "Ticket promedio: $2,000".

Escenario 2: Filtrar por rango de fechas

Dado que selecciono rango "01/01/2024 - 31/01/2024", Cuando aplico filtro, Entonces dashboard muestra solo datos del rango seleccionado.

Escenario 3: Filtrar por vendedor

Dado que soy sales_manager, Cuando selecciono vendedor "Juan Pérez", Entonces dashboard muestra solo ventas de Juan.

Escenario 4: Gráfico de ventas mensuales

Dado que hay ventas en los últimos 12 meses, Cuando veo el dashboard, Entonces gráfico de barras muestra ventas agrupadas por mes.

Escenario 5: Top productos más vendidos

Dado que Producto A vendió 100 unidades, Producto B vendió 80, Cuando veo el dashboard, Entonces tabla "Top Productos" muestra A en primer lugar, B en segundo.

Escenario 6: Tasa de conversión

Dado que hay 20 cotizaciones creadas, 15 convertidas a SO, Cuando veo el dashboard, Entonces KPI muestra "Conversión: 75%".

Reglas de Negocio

  • RN-1: Dashboard filtra por empresa del usuario (RLS).
  • RN-2: sales_user solo ve sus propias ventas, sales_manager ve todas.
  • RN-3: Datos se calculan en tiempo real (no cache por defecto).
  • RN-4: Montos en moneda de la empresa (company.currency_id).
  • RN-5: Filtros son opcionales, default: mes actual.

Tareas Técnicas

Backend

  • Endpoint: GET /api/v1/sales/dashboard/kpis?date_from&date_to&user_id&customer_id
  • Endpoint: GET /api/v1/sales/dashboard/monthly-sales
  • Endpoint: GET /api/v1/sales/dashboard/top-products
  • Endpoint: GET /api/v1/sales/dashboard/top-customers
  • Service: SalesDashboardService.getKPIs(filters)
  • Query: Calcular total_revenue, order_count, avg_ticket
  • Query: Calcular conversion_rate (quotations → orders)
  • Query: Top productos por qty_sold y revenue
  • Query: Top clientes por revenue
  • Query: Ventas mensuales agrupadas
  • Aplicar RLS y permisos
  • Unit tests (>80%)
  • Integration tests
  • Swagger docs

Frontend

  • Página: SalesDashboardPage.tsx (/sales/dashboard)
  • Componente: SalesKPICards.tsx (4 cards con KPIs)
  • Componente: MonthlySalesChart.tsx (bar chart)
  • Componente: TopProductsTable.tsx
  • Componente: TopCustomersTable.tsx
  • Componente: ConversionFunnelChart.tsx
  • Filtros: DateRangePicker, UserSelector, CustomerSelector
  • API client: dashboardApi.getSalesKPIs(filters)
  • State management: useSalesDashboardStore
  • Charts: Usar recharts o chart.js
  • Component tests
  • E2E test: "should display sales dashboard with KPIs"

Database

  • View (opcional): sales_dashboard_kpis para optimizar queries
  • Índices: Optimizar queries de dashboard (orders.date, orders.state)

Mockups / Wireframes

Dashboard de Ventas:

┌─────────────────────────────────────────────────────┐
│ Dashboard de Ventas                                 │
├─────────────────────────────────────────────────────┤
│ Filtros: [Rango: Este mes ▼] [Vendedor: Todos ▼]  │
├─────────────────────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐        │
│ │Revenue │ │Órdenes │ │Ticket  │ │Conver. │        │
│ │$100K   │ │  50    │ │$2,000  │ │  75%   │        │
│ └────────┘ └────────┘ └────────┘ └────────┘        │
├─────────────────────────────────────────────────────┤
│ Ventas Mensuales (últimos 12 meses)                │
│ ┌─────────────────────────────────────────────┐    │
│ │ [Gráfico de barras]                         │    │
│ └─────────────────────────────────────────────┘    │
├──────────────────────────┬──────────────────────────┤
│ Top 10 Productos         │ Top 10 Clientes          │
│ 1. Laptop HP - 100 unid. │ 1. ABC Corp - $50K       │
│ 2. Mouse - 80 unid.      │ 2. XYZ Ltd - $30K        │
│ ...                      │ ...                      │
└──────────────────────────┴──────────────────────────┘

Casos de Prueba

Funcionales

  1. TC-001: Dashboard muestra KPIs correctamente
  2. TC-002: Filtro por fecha funciona
  3. TC-003: Filtro por vendedor funciona
  4. TC-004: Gráfico mensual muestra datos correctos
  5. TC-005: Top productos ordenados por qty
  6. TC-006: Top clientes ordenados por revenue
  7. TC-007: Tasa de conversión calculada correctamente
  8. TC-008: RLS filtra por empresa
  9. TC-009: sales_user solo ve sus datos
  10. TC-010: sales_manager ve todos los datos

No Funcionales

  1. Performance: < 2s para cargar dashboard completo
  2. Seguridad: JWT + permiso sales_user

Dependencias

  • US bloqueantes:
    • US-MGN-007-002-001 (Crear SO)
    • US-MGN-007-001-001 (Crear Cotización)
  • Módulos requeridos: MGN-003 (Partners), MGN-005 (Productos)

Notas de Implementación

  • Queries optimizadas con índices en date y state
  • Considerar cache de 5 minutos para KPIs si hay muchos datos
  • Frontend: Skeleton loaders mientras cargan datos
  • Exportar dashboard a PDF como feature futura

Estimación Detallada

Tarea Horas
Backend 2
Frontend 2.5
Testing 1
Code Review 0.5
TOTAL 6 horas = 3 SP

Definition of Done

  • Código implementado según ET
  • Tests pasando (>80%)
  • Code review aprobado
  • KPIs se calculan correctamente
  • Gráficos muestran datos correctos
  • Filtros funcionan
  • RLS y permisos aplicados
  • Swagger docs actualizado
  • QA validado
  • PO aprobado

Referencias