# US-ML-007: Ver Historial de Señales ## Metadata | Campo | Valor | |-------|-------| | **ID** | US-ML-007 | | **Épica** | OQI-006 - Señales ML y Predicciones | | **Módulo** | ml-signals | | **Prioridad** | P1 | | **Story Points** | 3 | | **Sprint** | Sprint 7 | | **Estado** | Pendiente | | **Asignado a** | Por asignar | --- ## Historia de Usuario **Como** trader/inversor, **quiero** ver un historial completo de señales pasadas con su outcome real (TP alcanzado, SL activado, expirada), **para** evaluar el desempeño histórico del ML y aprender de señales anteriores. ## Descripción Detallada El usuario debe poder acceder a una tabla/lista de todas las señales generadas históricamente, filtradas por símbolo, horizonte, y rango de fechas. Cada señal debe mostrar si alcanzó TP1/TP2/TP3, si activó SL, o si expiró, junto con la ganancia/pérdida real. ## Mockups/Wireframes ``` ┌──────────────────────────────────────────────────────────────────┐ │ SIGNAL HISTORY BTCUSDT │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ Filters: │ │ [Symbol: BTCUSDT ▼] [Horizon: All ▼] [Date: Last 30 days ▼] │ │ [Action: All ▼] [Outcome: All ▼] [Export CSV] │ │ │ │ ══════════════════════════════════════════════════════════════ │ │ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ Date/Time Action Horizon Conf Outcome P&L │ │ │ ├────────────────────────────────────────────────────────────┤ │ │ │ Dec 5, 18:30 🟢 BUY Scalping 75% ✅ TP2 +0.42% │ │ │ │ Entry: $89,400 → Exit: $89,775 (TP2) in 22 min │ │ │ │ [View Details] │ │ │ ├────────────────────────────────────────────────────────────┤ │ │ │ Dec 5, 17:45 🔴 SELL Intraday 68% ✅ TP1 +0.31% │ │ │ │ Entry: $90,100 → Exit: $89,820 (TP1) in 45 min │ │ │ │ [View Details] │ │ │ ├────────────────────────────────────────────────────────────┤ │ │ │ Dec 5, 16:20 🟢 BUY Scalping 62% ❌ SL -0.25% │ │ │ │ Entry: $89,800 → Exit: $89,575 (SL) in 18 min │ │ │ │ [View Details] │ │ │ ├────────────────────────────────────────────────────────────┤ │ │ │ Dec 5, 15:10 🟢 BUY Swing 58% ⏱️ Expired 0% │ │ │ │ Entry: $89,500 → Expired after 3 hours (no TP/SL hit) │ │ │ │ [View Details] │ │ │ ├────────────────────────────────────────────────────────────┤ │ │ │ Dec 5, 14:00 🔵 HOLD Intraday 45% ⏱️ Expired 0% │ │ │ │ No action recommended │ │ │ ├────────────────────────────────────────────────────────────┤ │ │ │ Dec 5, 12:35 🟢 BUY Position 71% ✅ TP3 +1.12% │ │ │ │ Entry: $88,900 → Exit: $89,896 (TP3) in 5h 23min │ │ │ │ [View Details] │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ │ Showing 6 of 247 signals [Load More] │ │ │ │ SUMMARY (Last 30 days): │ │ Win Rate: 69% | Avg Gain: +0.42% | Avg Loss: -0.28% │ │ │ └──────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────┐ │ SIGNAL DETAILS - Dec 5, 18:30 [✕ Close]│ ├──────────────────────────────────────────────────────────────────┤ │ │ │ 🟢 BUY Signal - BTCUSDT (Scalping) │ │ │ │ Signal ID: 550e8400-e29b-41d4-a716-446655440000 │ │ Generated: Dec 5, 2025 18:30:00 UTC │ │ Expired: Dec 5, 2025 19:00:00 UTC │ │ │ │ SIGNAL DETAILS │ │ ══════════════════════════════════════════════════════════════ │ │ Entry Price: $89,400.00 │ │ Exit Price: $89,775.00 (TP2) │ │ Confidence: 75% │ │ Score: 8.5/10 │ │ Priority: HIGH │ │ │ │ LEVELS │ │ ══════════════════════════════════════════════════════════════ │ │ TP1: $89,650 (+0.28%) ✅ Hit at 18:42 (+12 min) │ │ TP2: $89,775 (+0.42%) ✅ Hit at 18:52 (+22 min) ← Exit │ │ TP3: $89,900 (+0.56%) ⬜ Not reached │ │ SL: $89,150 (-0.28%) ⬜ Not triggered │ │ │ │ PERFORMANCE │ │ ══════════════════════════════════════════════════════════════ │ │ Outcome: TP2 Hit (Success) │ │ Duration: 22 minutes │ │ Realized P&L: +0.42% (+$375.00) │ │ Risk/Reward: 1:2.0 │ │ │ │ TECHNICAL CONTEXT (at signal generation) │ │ ══════════════════════════════════════════════════════════════ │ │ RSI: 55.3 (Neutral) │ │ MACD: Bullish crossover │ │ Volume Ratio: 1.2x (Above average) │ │ │ │ REASONS │ │ ══════════════════════════════════════════════════════════════ │ │ ✓ Strong upward prediction (0.75 confidence) │ │ ✓ Healthy RSI (55.3, not overbought) │ │ ✓ Above average volume (1.2x) │ │ ✓ Favorable risk/reward (1:2) │ │ │ │ [View on Chart] [Similar Signals] │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## Criterios de Aceptación **Escenario 1: Ver historial de señales** ```gherkin DADO que el usuario está autenticado CUANDO navega a "Signal History" ENTONCES se muestra una tabla con las últimas 20 señales Y cada fila muestra: - Fecha y hora de generación - Acción (BUY/SELL/HOLD) - Horizonte - Confianza - Outcome (TP1/TP2/TP3/SL/Expired) - P&L real (% y USD si aplica) Y se muestra resumen al final (win rate, avg gain, avg loss) ``` **Escenario 2: Filtrar por símbolo** ```gherkin DADO que el usuario está en Signal History CUANDO selecciona "ETHUSDT" en el filtro de símbolo ENTONCES se muestran solo señales de ETHUSDT Y el contador actualiza a "Showing X of Y signals" Y el resumen se recalcula solo para ETHUSDT ``` **Escenario 3: Filtrar por outcome** ```gherkin DADO que el usuario está en Signal History CUANDO selecciona "TP Hit" en el filtro de Outcome ENTONCES se muestran solo señales que alcanzaron TP1, TP2 o TP3 Y el win rate refleja solo estas señales ``` **Escenario 4: Ver detalles de señal** ```gherkin DADO que el usuario está viendo el historial CUANDO hace click en "View Details" de una señal ENTONCES se abre un modal con: - Todos los detalles de la señal original - Outcome detallado (qué niveles se alcanzaron y cuándo) - P&L real calculado - Duración de la señal - Contexto técnico al momento de generación - Botón para ver la señal en el chart ``` **Escenario 5: Exportar historial a CSV** ```gherkin DADO que el usuario está viendo el historial filtrado CUANDO hace click en "Export CSV" ENTONCES se descarga un archivo CSV con: - Todas las señales del filtro actual - Columnas: Date, Symbol, Action, Horizon, Confidence, Outcome, P&L - Nombre de archivo: "signal-history-BTCUSDT-2025-12-05.csv" ``` **Escenario 6: Paginación** ```gherkin DADO que existen más de 20 señales CUANDO el usuario hace scroll hasta el final ENTONCES se muestra botón "Load More" Y al hacer click, carga las siguientes 20 señales Y el contador actualiza "Showing 40 of 247 signals" ``` ## Criterios Adicionales - [ ] El historial debe cargar en menos de 2 segundos - [ ] Debe soportar hasta 1000 señales por símbolo - [ ] Los filtros deben ser combinables - [ ] El modal de detalles debe ser responsive - [ ] El CSV debe incluir header con metadatos (fecha de export, filtros) --- ## Tareas Técnicas **Backend:** - [ ] BE-ML-011: Crear endpoint GET /api/signals/:symbol/history - [ ] BE-ML-012: Implementar filtros (date_range, horizon, action, outcome) - [ ] BE-ML-013: Implementar paginación (offset/limit) - [ ] BE-ML-014: Endpoint GET /api/signals/:id/details - [ ] BE-ML-015: Implementar generación de CSV **Frontend:** - [ ] FE-ML-028: Crear componente `SignalHistory.tsx` - [ ] FE-ML-029: Crear componente `SignalTable.tsx` - [ ] FE-ML-030: Crear componente `SignalFilters.tsx` - [ ] FE-ML-031: Crear componente `SignalDetailsModal.tsx` - [ ] FE-ML-032: Implementar infinite scroll / paginación - [ ] FE-ML-033: Implementar export a CSV - [ ] FE-ML-034: Agregar indicadores visuales de outcome (✅❌⏱️) **Tests:** - [ ] TEST-ML-013: Test de filtrado de señales - [ ] TEST-ML-014: Test de cálculo de P&L - [ ] TEST-ML-015: Test E2E de historial y detalles --- ## Dependencias **Depende de:** - [ ] RF-ML-002: Generación de señales (tracking de outcomes) - [ ] US-ML-002: Ver señal - Estado: Pendiente **Bloquea:** - Ninguna (historia final) --- ## Notas Técnicas **Endpoints involucrados:** | Método | Endpoint | Descripción | |--------|----------|-------------| | GET | /api/signals/:symbol/history | Obtener historial con filtros | | GET | /api/signals/:id/details | Detalles de señal específica | | GET | /api/signals/:symbol/export.csv | Exportar a CSV | **Query Parameters - History:** ``` GET /api/signals/BTCUSDT/history? date_from=2025-11-05& date_to=2025-12-05& horizon=scalping& action=BUY& outcome=tp_hit& limit=20& offset=0 ``` **Response esperado:** ```typescript interface SignalHistoryResponse { signals: SignalHistoryItem[]; total_count: number; page_info: { limit: number; offset: number; has_more: boolean; }; summary: { total_signals: number; win_rate: number; avg_gain: number; avg_loss: number; overall_pnl: number; }; } interface SignalHistoryItem { signal_id: string; symbol: string; timestamp: string; action: 'BUY' | 'SELL' | 'HOLD'; horizon: string; confidence: number; score: number; priority: string; entry_price: number; exit_price?: number; outcome: 'tp1' | 'tp2' | 'tp3' | 'sl' | 'expired'; outcome_timestamp?: string; duration_minutes?: number; realized_pnl_pct?: number; realized_pnl_usd?: number; } ``` **Componentes UI:** - `SignalHistory`: Container principal - `SignalTable`: Tabla de señales - `SignalRow`: Fila individual - `SignalFilters`: Barra de filtros - `SignalDetailsModal`: Modal de detalles - `OutcomeBadge`: Badge de outcome (✅/❌/⏱️) - `SummaryStats`: Resumen de estadísticas **Estado (Zustand):** ```typescript interface SignalHistoryStore { signals: SignalHistoryItem[]; filters: SignalFilters; summary: SummaryStats; isLoading: boolean; hasMore: boolean; fetchHistory: (symbol: string, filters: SignalFilters) => Promise; loadMore: () => Promise; updateFilters: (filters: Partial) => void; exportCSV: () => void; } ``` --- ## Definition of Ready (DoR) - [x] Historia claramente escrita (quién, qué, por qué) - [x] Criterios de aceptación definidos - [x] Story points estimados - [x] Dependencias identificadas - [x] Sin bloqueadores - [x] Diseño/mockup disponible ## Definition of Done (DoD) - [ ] Código implementado según criterios - [ ] Tests unitarios escritos y pasando - [ ] Tests E2E pasando - [ ] Code review aprobado - [ ] Documentación actualizada - [ ] QA aprobado en staging - [ ] Filtros funcionan correctamente (combinados) - [ ] Paginación funciona sin memory leaks - [ ] Export CSV genera archivo válido - [ ] Modal de detalles responsive - [ ] Desplegado en producción --- ## 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