# 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<void>;
  copyLevels: (signal: TradingSignal) => void;
  setAlert: (signalId: string) => Promise<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
- [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
