trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/historias-usuario/US-INV-004-ver-portfolio.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-INV-004	Ver Dashboard de Portfolio	User Story	Done	Media	OQI-004	trading-platform	3	2025-12-05	2026-01-04

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

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

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

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

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

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:

{
  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:

{
  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)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Diseño/mockup disponible
• 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