rckrdmrd/trading-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2b34fc3693
trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/historias-usuario/US-INV-005-ver-rendimiento.md
rckrdmrd a7cca885f0 feat: Major platform documentation and architecture updates 
Changes include:
- Updated architecture documentation
- Enhanced module definitions (OQI-001 to OQI-008)
- ML integration documentation updates
- Trading strategies documentation
- Orchestration and inventory updates
- Docker configuration updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 05:33:35 -06:00

320 lines
12 KiB
Markdown
Raw Blame History

---
id: "US-INV-005"
title: "Ver Rendimiento Histórico"
type: "User Story"
status: "Done"
priority: "Media"
epic: "OQI-004"
project: "trading-platform"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
# US-INV-005: Ver Rendimiento Histórico
## Metadata
| Campo | Valor |
|-------|-------|
| **ID** | US-INV-005 |
| **Épica** | OQI-004 - Cuentas de Inversión |
| **Módulo** | investment |
| **Prioridad** | P1 |
| **Story Points** | 3 |
| **Sprint** | Sprint 6 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |
---
## Historia de Usuario
**Como** inversor,
**quiero** ver el rendimiento histórico detallado de mi cuenta,
**para** analizar el desempeño del agente IA y tomar decisiones informadas.
## Descripción Detallada
El usuario debe poder acceder a una vista detallada del rendimiento histórico de su cuenta con gráficos, métricas avanzadas, comparación con benchmarks, y desglose por período. Debe poder filtrar por diferentes rangos de tiempo y exportar los datos.
## Mockups/Wireframes
```
┌─────────────────────────────────────────────────────────────────┐
│ RENDIMIENTO HISTÓRICO │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Período: [ 7D ] [ 30D ] [ 3M ] [ 6M ] [ 1Y ] [ Todo ] │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 📈 Retorno Acumulado │ │
│ │ │ │
│ │ [Gráfico de área con retorno % acumulado en el tiempo] │ │
│ │ Línea benchmark: BTC Hold │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │
│ │ Retorno total │ │ Retorno mensual │ │ Sharpe Ratio │ │
│ │ +24.5% │ │ +4.1% │ │ 1.8 │ │
│ └─────────────────┘ └─────────────────┘ └────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │
│ │ Max Drawdown │ │ Win Rate │ │ Total Trades │ │
│ │ -3.2% │ │ 78% │ │ 156 │ │
│ └─────────────────┘ └─────────────────┘ └────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 📊 Rendimiento por Mes │ │
│ │ │ │
│ │ Nov 2025: +4.8% 🟢 │ │
│ │ Oct 2025: +3.2% 🟢 │ │
│ │ Sep 2025: +5.1% 🟢 │ │
│ │ Ago 2025: +2.9% 🟢 │ │
│ │ Jul 2025: -1.2% 🔴 │ │
│ │ Jun 2025: +6.3% 🟢 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 🔍 Comparación con Benchmarks │ │
│ │ │ │
│ │ Tu cuenta (Atlas): +24.5% █████████████████ │ │
│ │ BTC Hold: +18.2% ████████████ │ │
│ │ ETH Hold: +22.1% ███████████████ │ │
│ │ S&P 500: +12.3% ████████ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ [Exportar CSV] [Exportar PDF] │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Criterios de Aceptación
**Escenario 1: Ver rendimiento con datos históricos**
```gherkin
DADO que el usuario tiene cuenta con 6 meses de historial
CUANDO navega a /investment/performance/:accountId
ENTONCES se muestra gráfico de retorno acumulado
Y se muestran métricas clave (retorno total, mensual, Sharpe)
Y se muestra desglose mensual
Y se muestra comparación con BTC/ETH hold
Y por defecto se selecciona período "6M"
```
**Escenario 2: Cambiar período de visualización**
```gherkin
DADO que el usuario está viendo rendimiento (período 6M)
CUANDO selecciona período "30D"
ENTONCES se actualiza el gráfico para últimos 30 días
Y se recalculan todas las métricas para ese período
Y se actualiza comparación con benchmarks
```
**Escenario 3: Cuenta nueva sin historial**
```gherkin
DADO que el usuario abrió cuenta hace menos de 24 horas
CUANDO accede a rendimiento histórico
ENTONCES se muestra mensaje "Aún no hay datos suficientes"
Y se muestra "Los datos estarán disponibles después de 24h"
Y se muestra CTA "Ver productos" o "Realizar depósito"
```
**Escenario 4: Comparar con benchmark específico**
```gherkin
DADO que el usuario está viendo rendimiento
CUANDO hace click en "Comparar con BTC Hold"
ENTONCES se superpone línea de BTC hold en gráfico
Y se muestra diferencia porcentual (+6.3% mejor que BTC)
```
**Escenario 5: Exportar datos**
```gherkin
DADO que el usuario está viendo rendimiento
CUANDO hace click en "Exportar CSV"
ENTONCES se descarga archivo con datos diarios
Y incluye: fecha, balance, retorno diario, retorno acumulado
```
## Criterios Adicionales
- [ ] Gráfico con zoom interactivo
- [ ] Tooltips con datos exactos al pasar mouse
- [ ] Mostrar eventos importantes (depósitos, retiros) en gráfico
- [ ] Calcular métricas avanzadas (Sortino ratio, Calmar ratio)
- [ ] Cache de datos para optimizar carga
---
## Tareas Técnicas
**Database:**
- [ ] DB-INV-001: Tabla investment.daily_snapshots para datos históricos
- [ ] DB-INV-002: Vista para cálculo de métricas
- [ ] DB-INV-003: Índices en snapshots por fecha
**Backend:**
- [ ] BE-INV-001: Endpoint GET /investment/accounts/:id/performance
- [ ] BE-INV-002: Implementar PerformanceService.getHistoricalData()
- [ ] BE-INV-003: Implementar PerformanceService.calculateMetrics()
- [ ] BE-INV-004: Endpoint GET /investment/benchmarks (BTC, ETH, S&P500)
- [ ] BE-INV-005: Cron job para snapshots diarios
- [ ] BE-INV-006: Cache Redis para datos históricos
**Frontend:**
- [ ] FE-INV-001: Crear página PerformancePage.tsx
- [ ] FE-INV-002: Crear componente PerformanceChart.tsx
- [ ] FE-INV-003: Crear componente MetricsGrid.tsx
- [ ] FE-INV-004: Crear componente MonthlyBreakdown.tsx
- [ ] FE-INV-005: Crear componente BenchmarkComparison.tsx
- [ ] FE-INV-006: Implementar exportación a CSV/PDF
- [ ] FE-INV-007: Implementar performanceStore
**Tests:**
- [ ] TEST-INV-001: Test cálculo de métricas
- [ ] TEST-INV-002: Test generación snapshots
- [ ] TEST-INV-003: Test exportación datos
- [ ] TEST-INV-004: Test E2E performance page
---
## Dependencias
**Depende de:**
- [ ] US-INV-004: Ver dashboard portfolio - Estado: Pendiente
- [ ] Daily snapshots job implementado
**Bloquea:**
- [ ] US-INV-011: Exportar reporte PDF
- [ ] US-INV-014: Ver performance del agente
---
## Notas Técnicas
**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /investment/accounts/:id/performance | Datos históricos |
| GET | /investment/benchmarks | Datos de benchmarks |
| GET | /investment/accounts/:id/metrics | Métricas calculadas |
**Entidades/Tablas:**
- `investment.daily_snapshots`: Snapshot diario de balance
- `investment.account_metrics`: Métricas calculadas
- `market_data.benchmarks`: Datos de BTC, ETH, S&P500
**Response GET /performance:**
```typescript
{
period: "6M",
accountId: "uuid",
snapshots: [
{
date: "2025-06-05",
balance: 1000,
totalDeposited: 1000,
totalWithdrawn: 0,
pnl: 0,
returnPercentage: 0
},
{
date: "2025-06-06",
balance: 1032,
totalDeposited: 1000,
totalWithdrawn: 0,
pnl: 32,
returnPercentage: 3.2
}
// ...
],
metrics: {
totalReturn: 24.5,
avgMonthlyReturn: 4.1,
sharpeRatio: 1.8,
maxDrawdown: -3.2,
winRate: 78,
totalTrades: 156,
bestMonth: 6.3,
worstMonth: -1.2
},
monthlyBreakdown: [
{ month: "2025-11", return: 4.8, trades: 28 },
{ month: "2025-10", return: 3.2, trades: 24 }
// ...
]
}
```
**Response GET /benchmarks:**
```typescript
{
period: "6M",
benchmarks: [
{
name: "BTC Hold",
symbol: "BTC",
return: 18.2,
data: [
{ date: "2025-06-05", value: 45000 },
{ date: "2025-06-06", value: 45500 }
// ...
]
},
{
name: "ETH Hold",
symbol: "ETH",
return: 22.1,
data: [...]
}
]
}
```
**Cálculo de Métricas:**
- **Sharpe Ratio:** (Retorno promedio - Tasa libre riesgo) / Desviación estándar
- **Max Drawdown:** Máxima caída desde un pico
- **Win Rate:** Operaciones ganadoras / Total operaciones
- **Sortino Ratio:** Similar a Sharpe pero solo penaliza volatilidad negativa
---
## 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
- [x] Fórmulas de métricas definidas
## Definition of Done (DoD)
- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] Cron job de snapshots funcionando
- [ ] Gráficos interactivos
- [ ] Exportación funcionando
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] 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
Reference in New Issue View Git Blame Copy Permalink