trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/historias-usuario/US-ML-002-ver-senal.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-002	Ver Señal de Trading	User Story	Done	Media	OQI-006	trading-platform	3	2025-12-05	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

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

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

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

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

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:

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

interface SignalStore {
  activeSignal: TradingSignal | null;
  recentSignals: TradingSignal[];
  isLoading: boolean;
  error: string | null;

  fetchSignal: (symbol: string) => Promise<void>;
  copyLevels: (signal: TradingSignal) => void;
  setAlert: (signalId: string) => Promise<void>;
}

---

Definition of Ready (DoR)

• Historia claramente escrita (quién, qué, por qué)
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Sin bloqueadores
• Diseño/mockup disponible
• 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