# 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