--- id: "US-ML-002" title: "Ver Señal de Trading" type: "User Story" status: "Done" priority: "Media" epic: "OQI-006" project: "trading-platform" story_points: 3 created_date: "2025-12-05" updated_date: "2026-01-04" --- # US-ML-002: Ver Señal de Trading ## Metadata | Campo | Valor | |-------|-------| | **ID** | US-ML-002 | | **Épica** | OQI-006 - Señales ML y Predicciones | | **Módulo** | ml-signals | | **Prioridad** | P0 | | **Story Points** | 5 | | **Sprint** | Sprint 6 | | **Estado** | Pendiente | | **Asignado a** | Por asignar | --- ## Historia de Usuario **Como** trader/inversor, **quiero** ver señales de trading (BUY/SELL/HOLD) generadas por el modelo ML con niveles de TP/SL recomendados, **para** saber exactamente cuándo y dónde entrar, dónde colocar mis objetivos de ganancia y mi stop de pérdida. ## Descripción Detallada El usuario debe poder visualizar señales de trading claras y accionables generadas por el sistema ML. Cada señal debe incluir la acción recomendada (BUY/SELL/HOLD), precio de entrada, múltiples niveles de Take Profit (TP1, TP2, TP3), Stop Loss, y métricas de riesgo/recompensa. ## Mockups/Wireframes ``` ┌─────────────────────────────────────────────────────────────────┐ │ BTCUSDT $89,400.00 +2.34% ▲ [ML Trading Signals]│ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ACTIVE SIGNAL Updated: Just now │ │ ═══════════════════════════════════════════════════════════════│ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 🟢 BUY SIGNAL Priority: HIGH │ │ │ │ ─────────────────────────────────────────────────────────│ │ │ │ Scalping (30 min) · Confidence: 75% · Score: 8.5/10 │ │ │ │ │ │ │ │ Entry Price: $89,400.00 ← Current │ │ │ │ │ │ │ │ 📈 Take Profit Levels: │ │ │ │ TP1: $89,650.00 (+0.28%) [Conservative] ✓ │ │ │ │ TP2: $89,775.00 (+0.42%) [Moderate] │ │ │ │ TP3: $89,900.00 (+0.56%) [Aggressive] │ │ │ │ │ │ │ │ 🛑 Stop Loss: $89,150.00 (-0.28%) │ │ │ │ │ │ │ │ ⚖️ Risk/Reward: 1:2.0 (Good) │ │ │ │ 💰 Position Size: 0.05 BTC (1% risk) │ │ │ │ │ │ │ │ ─────────────────────────────────────────────────────── │ │ │ │ 📊 Technical Context: │ │ │ │ • RSI: 55.3 (Neutral, not overbought) │ │ │ │ • Volume: 1.2x average (Strong) │ │ │ │ • MACD: Bullish crossover │ │ │ │ │ │ │ │ 💡 Reasons: │ │ │ │ ✓ Strong upward prediction (0.75 confidence) │ │ │ │ ✓ Healthy RSI (not overbought) │ │ │ │ ✓ Above average volume (1.2x) │ │ │ │ ✓ Favorable risk/reward (1:2) │ │ │ │ │ │ │ │ ⏱️ Signal expires in: 25 minutes │ │ │ │ │ │ │ │ [Copy Levels] [Set Alert] [View Details] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ RECENT SIGNALS │ │ ═══════════════════════════════════════════════════════════════│ │ 🔵 HOLD ETHUSDT Intraday 55% conf 5 min ago │ │ 🟢 BUY BNBUSDT Scalping 68% conf 15 min ago │ │ 🔴 SELL SOLUSDT Swing 62% conf 1 hour ago │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Criterios de Aceptación **Escenario 1: Ver señal BUY activa** ```gherkin DADO que el modelo generó una señal BUY para BTCUSDT Y la señal es de prioridad HIGH CUANDO el usuario visualiza la sección de señales ENTONCES se muestra una tarjeta destacada con: - Badge verde "🟢 BUY SIGNAL" - Horizonte temporal (ej: Scalping - 30 min) - Confianza (ej: 75%) - Score (ej: 8.5/10) - Entry Price igual al precio actual - 3 niveles de Take Profit con porcentajes - 1 Stop Loss con porcentaje - Risk/Reward ratio con indicador visual - Position Size recomendado - Indicadores técnicos (RSI, Volume, MACD) - Lista de razones por las que se generó la señal - Tiempo restante hasta expiración ``` **Escenario 2: Señal HOLD por baja confianza** ```gherkin DADO que el modelo generó una señal HOLD para ETHUSDT Y la confianza es 45% CUANDO el usuario visualiza la señal ENTONCES se muestra tarjeta neutral con: - Badge azul "🔵 HOLD" - Mensaje "Market conditions unclear" - Razón principal: "Low confidence (45%)" - Recomendación: "Wait for better opportunity" - Sin niveles de TP/SL ``` **Escenario 3: Señal SELL** ```gherkin DADO que el modelo generó una señal SELL para BTCUSDT CUANDO el usuario visualiza la señal ENTONCES se muestra tarjeta roja con: - Badge rojo "🔴 SELL SIGNAL" - Entry price = precio actual - TP1, TP2, TP3 con precios MENORES (bajada esperada) - Stop Loss con precio MAYOR (protección al alza) - Razones (ej: "Bearish prediction", "RSI overbought") ``` **Escenario 4: Copiar niveles al portapapeles** ```gherkin DADO que el usuario está viendo una señal BUY CUANDO hace click en "Copy Levels" ENTONCES se copian al portapapeles: """ BTCUSDT BUY Signal Entry: $89,400.00 TP1: $89,650.00 | TP2: $89,775.00 | TP3: $89,900.00 SL: $89,150.00 R/R: 1:2.0 """ Y se muestra notificación "Levels copied!" ``` **Escenario 5: Señal expirada** ```gherkin DADO que una señal fue generada hace 35 minutos Y el horizonte era Scalping (30 min) CUANDO el usuario visualiza la señal ENTONCES se muestra con opacidad reducida Y un badge "EXPIRED" Y se mueve a la sección "Recent Signals" ``` ## Criterios Adicionales - [ ] La señal debe actualizarse en tiempo real cada 5 minutos - [ ] Debe soportar múltiples señales simultáneas (diferentes símbolos) - [ ] Debe mostrar solo 1 señal activa por símbolo (la más reciente) - [ ] Los colores deben ser claros: Verde (BUY), Rojo (SELL), Azul (HOLD) - [ ] Debe incluir botón para configurar alertas automáticas --- ## Tareas Técnicas **Backend:** - [ ] BE-ML-004: Crear endpoint GET /api/signals/:symbol - [ ] BE-ML-005: Implementar lógica de expiración de señales - [ ] BE-ML-006: Endpoint POST /api/signals/:id/alert para configurar alertas **Frontend:** - [ ] FE-ML-007: Crear componente `TradingSignal.tsx` - [ ] FE-ML-008: Crear componente `SignalCard.tsx` - [ ] FE-ML-009: Crear componente `TPSLLevels.tsx` (visualización de niveles) - [ ] FE-ML-010: Crear hook `useSignal(symbol)` para fetch - [ ] FE-ML-011: Implementar lógica de "Copy to Clipboard" - [ ] FE-ML-012: Integrar con WebSocket para updates en tiempo real - [ ] FE-ML-013: Crear `SignalReasons.tsx` (lista de razones) **Tests:** - [ ] TEST-ML-004: Test unitario de cálculo de R/R ratio - [ ] TEST-ML-005: Test de formateo de señales BUY/SELL/HOLD - [ ] TEST-ML-006: Test E2E de visualización de señal activa --- ## Dependencias **Depende de:** - [ ] RF-ML-002: Generación de señales - Estado: ✅ Implementado - [ ] US-ML-001: Ver predicción - Estado: Pendiente **Bloquea:** - [ ] US-ML-006: Integrar señales en chart - [ ] US-ML-007: Ver historial de señales --- ## Notas Técnicas **Endpoints involucrados:** | Método | Endpoint | Descripción | |--------|----------|-------------| | GET | /api/signals/:symbol | Obtener señal activa | | GET | /api/signals/:symbol/history | Historial de señales | | POST | /api/signals/:id/alert | Configurar alerta | | WS | /ws/:symbol | Stream de señales en tiempo real | **Response esperado:** ```typescript interface TradingSignal { signal_id: string; symbol: string; timestamp: string; horizon: 'scalping' | 'intraday' | 'swing' | 'position'; action: 'BUY' | 'SELL' | 'HOLD'; priority: 'HIGH' | 'MEDIUM' | 'LOW'; score: number; // 0-10 current_price: number; entry_price: number; take_profit: { tp1: number; tp2: number; tp3: number; }; stop_loss: number; risk_reward_ratio: number; expected_gain_pct: number; max_risk_pct: number; confidence: number; recommended_position_size?: number; rsi: number; volume_ratio: number; reasons: string[]; expires_at: string; is_expired: boolean; } ``` **Componentes UI:** - `TradingSignal`: Container principal - `SignalCard`: Tarjeta de señal individual - `ActionBadge`: Badge de BUY/SELL/HOLD - `TPSLLevels`: Visualización de niveles TP/SL - `RiskRewardBadge`: Indicador de R/R ratio - `SignalReasons`: Lista de razones - `SignalTimer`: Countdown de expiración **Estado (Zustand):** ```typescript interface SignalStore { activeSignal: TradingSignal | null; recentSignals: TradingSignal[]; isLoading: boolean; error: string | null; fetchSignal: (symbol: string) => Promise; copyLevels: (signal: TradingSignal) => void; setAlert: (signalId: string) => Promise; } ``` --- ## 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 - [x] API spec 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 - [ ] Responsive en mobile/tablet/desktop - [ ] Funcionalidad de "Copy Levels" verificada - [ ] 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