# US-INV-004: Ver Dashboard de Portfolio

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-INV-004 |
| **Épica** | OQI-004 - Cuentas de Inversión |
| **Módulo** | investment |
| **Prioridad** | P0 |
| **Story Points** | 5 |
| **Sprint** | Sprint 6 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** inversor activo,
**quiero** ver un dashboard con el estado de mi portfolio,
**para** monitorear mi inversión, rendimiento y actividad del agente en tiempo real.

## Descripción Detallada

El usuario debe poder acceder a un dashboard que muestre información clave de su cuenta: balance actual, rendimiento acumulado, gráfico de evolución, últimas transacciones, operaciones activas del agente, y KPIs principales. El dashboard debe actualizarse en tiempo real y ser intuitivo.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│                    MI PORTFOLIO - ATLAS                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────────┐  ┌──────────────────────┐            │
│  │  Balance Total       │  │  Rendimiento         │            │
│  │  $1,245.50          │  │  +$245.50 (+24.5%)   │            │
│  │  ↑ +$45.20 (hoy)    │  │  🟢 Objetivo: 3-5%    │            │
│  └──────────────────────┘  └──────────────────────┘            │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  📈 Evolución del Balance (últimos 30 días)             │  │
│  │  [Gráfico de línea con balance diario]                  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐ │
│  │ Trades hoy: 3   │  │ Win rate: 78%   │  │ Max DD: 2.3%   │ │
│  └─────────────────┘  └─────────────────┘  └────────────────┘ │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  🤖 Actividad del Agente Atlas                          │  │
│  │                                                           │  │
│  │  Estado: 🟢 Operando activamente                         │  │
│  │  Última operación: Hace 15 min                           │  │
│  │                                                           │  │
│  │  Posiciones abiertas (2):                                │  │
│  │  • BTC/USDT - Long - +2.3% ($125.50)                    │  │
│  │  • ETH/USDT - Long - +1.1% ($55.20)                     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  📊 Últimas Transacciones                               │  │
│  │                                                           │  │
│  │  2025-12-05  Depósito              +$1,000.00            │  │
│  │  2025-12-04  Ganancia (BTC trade)  +$45.20              │  │
│  │  2025-12-03  Ganancia (ETH trade)  +$32.10              │  │
│  │                                                           │  │
│  │  [Ver historial completo →]                             │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  [Depositar]  [Retirar]  [Exportar PDF]                 │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver dashboard con cuenta activa**
```gherkin
DADO que el usuario tiene cuenta de inversión activa
Y tiene balance de $1,245.50
CUANDO navega a /investment/dashboard/:accountId
ENTONCES se muestra balance actual
Y se muestra rendimiento acumulado (+$245.50, +24.5%)
Y se muestra gráfico de evolución (30 días)
Y se muestran KPIs (trades, win rate, max drawdown)
Y se muestran posiciones abiertas del agente
Y se muestran últimas 5 transacciones
```

**Escenario 2: Dashboard sin actividad**
```gherkin
DADO que el usuario abrió cuenta recientemente
Y tiene balance $0
Y no hay transacciones
CUANDO accede al dashboard
ENTONCES se muestra balance $0
Y se muestra CTA prominente "Realizar primer depósito"
Y se muestra mensaje de bienvenida
Y NO se muestra gráfico de evolución
```

**Escenario 3: Actualización en tiempo real**
```gherkin
DADO que el usuario está viendo el dashboard
CUANDO el agente cierra una operación con ganancia
ENTONCES se actualiza balance en tiempo real (WebSocket)
Y se muestra notificación "Nueva ganancia: +$45.20"
Y se actualiza gráfico de evolución
Y se incrementa contador de trades
```

**Escenario 4: Ver posiciones activas del agente**
```gherkin
DADO que el agente tiene 2 posiciones abiertas
CUANDO el usuario ve el dashboard
ENTONCES se muestra lista de posiciones
Y cada posición muestra: par, dirección, P&L, tamaño
Y se actualiza P&L en tiempo real
```

**Escenario 5: Navegación desde dashboard**
```gherkin
DADO que el usuario está en el dashboard
CUANDO hace click en "Ver historial completo"
ENTONCES se navega a /investment/transactions
Y se muestran todas las transacciones paginadas
```

## Criterios Adicionales

- [ ] Dashboard responsive para móvil
- [ ] Gráfico interactivo con tooltips
- [ ] Opción de cambiar período del gráfico (7d, 30d, 6m, 1y)
- [ ] Mostrar comparación con rendimiento del mercado
- [ ] Export data como CSV

---

## Tareas Técnicas

**Database:**
- [ ] DB-INV-001: Query optimizada para dashboard data
- [ ] DB-INV-002: Vista materializada para performance
- [ ] DB-INV-003: Índices en transacciones por fecha

**Backend:**
- [ ] BE-INV-001: Crear endpoint GET /investment/accounts/:id/dashboard
- [ ] BE-INV-002: Implementar DashboardService.getOverview()
- [ ] BE-INV-003: Endpoint GET /investment/accounts/:id/chart-data
- [ ] BE-INV-004: WebSocket para actualizaciones en tiempo real
- [ ] BE-INV-005: Calcular métricas (win rate, drawdown, etc.)
- [ ] BE-INV-006: Obtener posiciones activas del agente ML

**Frontend:**
- [ ] FE-INV-001: Crear página DashboardPage.tsx
- [ ] FE-INV-002: Crear componente BalanceCard.tsx
- [ ] FE-INV-003: Crear componente PerformanceCard.tsx
- [ ] FE-INV-004: Crear componente BalanceChart.tsx (Chart.js/Recharts)
- [ ] FE-INV-005: Crear componente ActivePositions.tsx
- [ ] FE-INV-006: Crear componente RecentTransactions.tsx
- [ ] FE-INV-007: Implementar WebSocket client
- [ ] FE-INV-008: Implementar dashboardStore (Zustand)

**Tests:**
- [ ] TEST-INV-001: Test unitario DashboardService
- [ ] TEST-INV-002: Test cálculo de métricas
- [ ] TEST-INV-003: Test WebSocket updates
- [ ] TEST-INV-004: Test E2E dashboard completo

---

## Dependencias

**Depende de:**
- [ ] US-INV-002: Abrir cuenta - Estado: Pendiente
- [ ] US-INV-003: Realizar depósito - Estado: Pendiente
- [ ] OQI-006: ML Signals (posiciones del agente) - Estado: Pendiente

**Bloquea:**
- [ ] US-INV-005: Ver rendimiento histórico
- [ ] US-INV-011: Exportar reporte PDF

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /investment/accounts/:id/dashboard | Data completa del dashboard |
| GET | /investment/accounts/:id/chart | Data para gráfico |
| GET | /investment/accounts/:id/positions | Posiciones activas |
| WS | /ws/investment/:accountId | Updates en tiempo real |

**Entidades/Tablas:**
- `investment.accounts`: Balance actual
- `investment.transactions`: Historial
- `investment.account_metrics`: KPIs calculados
- `ml.agent_positions`: Posiciones del agente

**Response GET /dashboard:**
```typescript
{
  account: {
    id: "uuid",
    productId: "uuid-atlas",
    balance: 1245.50,
    totalDeposited: 1000,
    totalWithdrawn: 0,
    totalReturn: 245.50,
    returnPercentage: 24.5
  },
  metrics: {
    todayPnL: 45.20,
    tradesCount: 3,
    winRate: 78,
    maxDrawdown: 2.3,
    sharpeRatio: 1.8
  },
  activePositions: [
    {
      symbol: "BTC/USDT",
      side: "long",
      entryPrice: 45000,
      currentPrice: 46035,
      unrealizedPnL: 125.50,
      pnlPercentage: 2.3,
      size: 0.05
    }
  ],
  recentTransactions: [
    {
      id: "uuid",
      type: "deposit",
      amount: 1000,
      createdAt: "2025-12-05T..."
    }
  ]
}
```

**Response GET /chart:**
```typescript
{
  period: "30d",
  dataPoints: [
    { date: "2025-11-05", balance: 1000, pnl: 0 },
    { date: "2025-11-06", balance: 1032, pnl: 32 },
    // ...
  ]
}
```

**WebSocket Events:**
- `balance:updated` - Balance cambió
- `position:opened` - Nueva posición
- `position:closed` - Posición cerrada
- `transaction:new` - Nueva transacción

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [ ] Diseño/mockup disponible
- [x] API spec disponible
- [ ] WebSocket protocol definido

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] WebSocket funcionando
- [ ] Dashboard responsive
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] Performance < 2s carga inicial
- [ ] QA aprobado
- [ ] Desplegado en ambiente de pruebas

---

## Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creación | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Última actualización:** 2025-12-05
