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

**RF Asociado:** [RF-MGN-007-006](../../02-modelado/requerimientos-funcionales/mgn-007/RF-MGN-007-006-reportes-de-ventas.md)
**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

- [RF-MGN-007-006](../../02-modelado/requerimientos-funcionales/mgn-007/RF-MGN-007-006-reportes-de-ventas.md)
- [ET Backend](../../02-modelado/especificaciones-tecnicas/backend/mgn-007/ET-BACKEND-MGN-007-006-reportes.md)
- [ET Frontend](../../02-modelado/especificaciones-tecnicas/frontend/mgn-007/ET-FRONTEND-MGN-007-006-reportes.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-007.yaml)