# Módulo Trading

**Epic:** OQI-003 - Trading Charts
**Progreso:** 40%
**Responsable:** Trading + ML Teams

## Descripción

El módulo de trading es el núcleo de la plataforma, proporcionando un dashboard completo de análisis técnico y ejecución de operaciones. Incluye charts avanzados con predicciones ML, paper trading para práctica, integración real con MetaTrader 4, gestión de watchlists, alertas de precio, y visualización de señales generadas por inteligencia artificial.

Este módulo integra 3 servicios principales: API REST principal (puerto 3080), ML Engine FastAPI (puerto 3083) para predicciones, y LLM Agent (puerto 3085) para integración MT4.

## Componentes

### Páginas

- `Trading.tsx` - Dashboard principal multi-panel con watchlist, chart, órdenes, señales ML, alertas, y paper trading

### Chart Components (11)

- `CandlestickChart.tsx` - Chart básico de velas japonesas
- `CandlestickChartWithML.tsx` - Chart avanzado con overlays ML (Order Blocks, FVGs, Range Predictions)
- `TradingChart.tsx` - Wrapper principal del sistema de charts
- `ChartToolbar.tsx` - Selector de símbolos, timeframes e indicadores
- `IndicatorConfigPanel.tsx` - Configuración de indicadores técnicos (SMA, EMA, RSI, MACD, Bollinger)
- `ChartDrawingToolsPanel.tsx` - Herramientas de dibujo en charts
- `SymbolInfoPanel.tsx` - Información detallada del símbolo activo
- `SymbolComparisonChart.tsx` - Comparación de múltiples símbolos
- `TradeJournalPanel.tsx` - Diario de operaciones
- `OrderBookDepthVisualization.tsx` - Visualización de profundidad de mercado
- `MarketDepthPanel.tsx` - Panel de depth of market con agrupación

### Market Data Components (7)

- `WatchlistSidebar.tsx` - Sidebar con lista de símbolos seguidos y precios en tiempo real
- `WatchlistItem.tsx` - Item individual de watchlist con precio y cambio porcentual
- `AddSymbolModal.tsx` - Modal para agregar símbolos a watchlist
- `OrderBookPanel.tsx` - Order book Level 2
- `TradingScreener.tsx` - Scanner de símbolos con filtros personalizados

### Trading & Account Components (5)

- `PaperTradingPanel.tsx` - Interface completa de paper trading (órdenes, posiciones, historial, settings)
- `OrderForm.tsx` - Formulario de órdenes market/limit
- `PositionsList.tsx` - Lista de posiciones abiertas con P&L
- `TradesHistory.tsx` - Historial de operaciones cerradas
- `AccountSummary.tsx` - Resumen de cuenta (balance, equity, margin)

### ML & Signals Components (10)

- `MLSignalsPanel.tsx` - Panel de señales ML con scores de confianza
- `MT4ConnectionStatus.tsx` - Indicador de conexión MetaTrader 4
- `LivePositionCard.tsx` - Tarjeta de posición en vivo con P&L no realizado
- `MT4PositionsManager.tsx` - Gestor de posiciones MT4
- `MT4LiveTradesPanel.tsx` - Panel de trades activos en MT4
- `RiskMonitor.tsx` - Monitor de riesgo en tiempo real
- `AdvancedOrderEntry.tsx` - Dialog de orden avanzada con SL/TP pre-llenados
- `RiskBasedPositionSizer.tsx` - Calculadora de tamaño de posición basada en % de riesgo
- `PositionModifierDialog.tsx` - Modificador de SL/TP en posiciones vivas

### Alerts & Analytics Components (5)

- `AlertsPanel.tsx` - Gestión de alertas de precio
- `TradingStatsPanel.tsx` - Estadísticas de trading y rendimiento
- `TradeAlertsNotificationCenter.tsx` - Centro de notificaciones de eventos de trading
- `TradeExecutionHistory.tsx` - Log de ejecuciones de trades
- `TradingMetricsCard.tsx` - Tarjeta de métricas de rendimiento
- `AccountHealthDashboard.tsx` - Dashboard de salud de cuenta e indicadores de riesgo

### Utility Components (1)

- `ExportButton.tsx` - Exportar datos de trading a CSV/JSON

## Hooks

### useMT4WebSocket

**Ubicación:** `modules/trading/hooks/useMT4WebSocket.ts`

Hook especializado para integración WebSocket con MetaTrader 4 en tiempo real.

```typescript
const {
  connected,        // Estado de conexión
  connecting,       // Estado de conexión en progreso
  account,          // MT4AccountInfo (login, balance, equity, margin, leverage)
  positions,        // Array de MT4Position
  orders,           // Array de MT4Order
  connect,          // Función para conectar
  disconnect,       // Función para desconectar
  subscribe,        // Suscribirse a canales
  unsubscribe      // Desuscribirse de canales
} = useMT4WebSocket(mt4Login);
```

**Características:**
- Auto-reconnect con backoff exponencial
- Heartbeat mechanism cada 30 segundos
- Event-driven updates (account, position, order, trade events)
- Channel subscription management

## Estructura de Carpetas

```
modules/trading/
├── components/
│   ├── (38 componentes organizados por categoría)
│   ├── CandlestickChartWithML.tsx
│   ├── WatchlistSidebar.tsx
│   ├── PaperTradingPanel.tsx
│   ├── MLSignalsPanel.tsx
│   ├── AlertsPanel.tsx
│   └── ...
├── hooks/
│   └── useMT4WebSocket.ts
├── pages/
│   └── Trading.tsx
└── README.md
```

**Servicios y estado compartidos:**
- **Services:** `services/trading.service.ts`, `services/mlService.ts`
- **Store:** `stores/tradingStore.ts` (Zustand)
- **Types:** `types/trading.types.ts`

## APIs Consumidas

### Market Data APIs (Base URL: `/api/v1`)

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/trading/market/klines/{symbol}` | GET | Datos OHLCV (candlesticks) para símbolo |
| `/trading/market/price/{symbol}` | GET | Precio actual |
| `/trading/market/ticker/{symbol}` | GET | Ticker 24h (high, low, volume) |
| `/trading/market/tickers` | GET | Todos los tickers |
| `/trading/market/orderbook/{symbol}` | GET | Order book Level 2 |
| `/trading/market/search` | GET | Búsqueda de símbolos |
| `/trading/market/popular` | GET | Símbolos populares |
| `/trading/market/watchlist` | GET | Watchlist con precios |

### Technical Indicators APIs

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/trading/indicators/{symbol}/sma` | GET | Simple Moving Average |
| `/trading/indicators/{symbol}/ema` | GET | Exponential Moving Average |
| `/trading/indicators/{symbol}/rsi` | GET | Relative Strength Index |
| `/trading/indicators/{symbol}/macd` | GET | MACD Indicator |
| `/trading/indicators/{symbol}/bollinger` | GET | Bollinger Bands |

### Watchlist APIs

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/trading/watchlists` | GET | Obtener watchlists del usuario |
| `/trading/watchlists/default` | GET | Watchlist por defecto |
| `/trading/watchlists/{id}` | GET/PATCH | Obtener o actualizar watchlist |
| `/trading/watchlists` | POST | Crear nueva watchlist |
| `/trading/watchlists/{id}` | DELETE | Eliminar watchlist |
| `/trading/watchlists/{id}/symbols` | POST | Agregar símbolo |
| `/trading/watchlists/{id}/symbols/{symbol}` | DELETE | Remover símbolo |

### Paper Trading APIs

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/trading/paper/initialize` | POST | Inicializar cuenta paper trading |
| `/trading/paper/balances` | GET | Balance y equity de cuenta |
| `/trading/paper/orders` | GET/POST | Obtener o crear órdenes |
| `/trading/paper/orders/{id}` | DELETE | Cancelar orden |
| `/trading/paper/positions` | GET | Posiciones abiertas |
| `/trading/paper/positions/{id}/close` | POST | Cerrar posición |
| `/trading/paper/trades` | GET | Historial de trades |
| `/trading/paper/portfolio` | GET | Resumen de cuenta |
| `/trading/paper/reset` | POST | Resetear cuenta a estado inicial |
| `/trading/paper/stats` | GET | Estadísticas de cuenta |

### Price Alerts APIs

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/trading/alerts` | GET/POST | Obtener o crear alertas |
| `/trading/alerts/{id}` | GET/PATCH/DELETE | Gestionar alerta |
| `/trading/alerts/{id}/enable` | POST | Habilitar alerta |
| `/trading/alerts/{id}/disable` | POST | Deshabilitar alerta |
| `/trading/alerts/stats` | GET | Estadísticas de alertas |

### ML Engine APIs (Base URL: `http://localhost:3083`)

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/v1/signals/latest/{symbol}` | GET | Última señal ML para símbolo |
| `/api/v1/signals/active` | GET | Todas las señales activas |
| `/api/v1/analysis/amd/{symbol}` | GET | Análisis AMD Phase (Accumulation/Manipulation/Distribution) |
| `/api/v1/predictions/range/{symbol}` | GET | Predicción de rango de precios |
| `/api/v1/signals/generate` | POST | Generar nueva señal |
| `/api/v1/backtest` | POST | Ejecutar backtest de estrategia |
| `/api/ict/{symbol}` | POST | Análisis ICT/SMC (Order Blocks, Fair Value Gaps) |
| `/api/ensemble/{symbol}` | POST | Señal ensemble (multi-modelo) |
| `/api/scan` | POST | Escanear múltiples símbolos |

### LLM Agent APIs (Base URL: `http://localhost:3085`)

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/trade/execute` | POST | Ejecutar trade basado en señal ML |
| `/api/mt4/account` | GET | Información de cuenta MT4 |
| `/api/mt4/positions` | GET | Posiciones MT4 |
| `/api/mt4/positions/{ticket}/close` | POST | Cerrar posición MT4 |
| `/api/mt4/positions/{ticket}/modify` | POST | Modificar SL/TP |
| `/api/mt4/calculate-size` | POST | Calcular tamaño de posición |
| `/health` | GET | Health check del LLM Agent |

## Uso Rápido

```tsx
import { Trading } from '@/modules/trading';
import { useTradingStore } from '@/stores/tradingStore';
import { useMT4WebSocket } from '@/modules/trading/hooks/useMT4WebSocket';

// Uso en router
<Route path="/trading" element={<Trading />} />

// Uso de store
function MyTradingComponent() {
  const {
    selectedSymbol,
    timeframe,
    klines,
    setSymbol,
    fetchKlines,
    createOrder
  } = useTradingStore();

  useEffect(() => {
    fetchKlines();
  }, [selectedSymbol, timeframe]);

  const handleOrder = async () => {
    await createOrder({
      symbol: 'BTCUSDT',
      side: 'buy',
      type: 'market',
      quantity: 0.01
    });
  };

  return (
    <div>
      <p>Symbol: {selectedSymbol}</p>
      <button onClick={handleOrder}>Place Order</button>
    </div>
  );
}

// Uso de MT4 WebSocket
function MT4Component() {
  const { connected, account, positions, connect } = useMT4WebSocket('12345678');

  useEffect(() => {
    connect();
  }, []);

  return (
    <div>
      {connected ? (
        <>
          <p>Balance: ${account?.balance}</p>
          <p>Positions: {positions.length}</p>
        </>
      ) : (
        <p>Connecting to MT4...</p>
      )}
    </div>
  );
}
```

## Características Principales

### Charts Avanzados
- Candlestick charts con lightweight-charts 4.1.1
- Múltiples timeframes (1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w)
- Indicadores técnicos: SMA, EMA, RSI, MACD, Bollinger Bands
- Drawing tools para anotaciones
- ML overlays: Order Blocks, Fair Value Gaps, Range Predictions

### ML-Powered Trading
- AMD Phase detection (Accumulation/Manipulation/Distribution)
- ICT/SMC analysis (Smart Money Concepts)
- Ensemble signals con voting de múltiples modelos
- Confidence scores y risk/reward ratios
- Backtesting de estrategias

### Paper Trading
- Demo trading sin capital real
- Órdenes market y limit
- Gestión de posiciones con SL/TP
- Historial completo de trades
- Estadísticas de rendimiento

### MT4 Integration
- WebSocket real-time para actualizaciones
- Streaming de account info, positions, orders
- Ejecución de trades en MT4 real
- Risk monitoring
- Position modification (SL/TP)

### Watchlists & Alerts
- Múltiples watchlists personalizables
- Búsqueda de símbolos
- Alertas de precio (above/below/crosses)
- Notificaciones email y push

## Tests

```bash
# Tests unitarios del módulo
npm run test modules/trading

# Tests de integración con ML Engine
npm run test:integration trading/ml

# Tests E2E de flujos de trading
npm run test:e2e trading
```

## Roadmap

### Pendientes - Alta Prioridad (P0-P1)
- [ ] **Drawing Tools Persistence** (3h) - Persistir dibujos en charts en backend
- [ ] **WebSocket Real-time Market Data** (60h) - Migrar de polling a WebSocket para precios
- [ ] **Advanced Indicators** (40h) - Fibonacci, Ichimoku, Elliott Wave
- [ ] **Order Flow Visualization** (50h) - Heatmap de volumen y delta

### Mediano Plazo (P2)
- [ ] **Multi-timeframe Analysis** (35h) - Sincronización de múltiples timeframes
- [ ] **Trade Copier** (45h) - Copiar trades entre cuentas
- [ ] **Custom Indicators** (60h) - Permitir indicadores personalizados en Pine Script
- [ ] **TradingView Integration** (80h) - Embed de charts de TradingView

### Largo Plazo (P3)
- [ ] **Automated Trading Bots** (120h) - Bot builder visual
- [ ] **Social Trading** (90h) - Copiar traders exitosos
- [ ] **Advanced Analytics** (50h) - Deep analytics de rendimiento

## Dependencias

- `lightweight-charts@4.1.1` - Charting library
- `zustand` - State management
- `axios` - HTTP client
- `socket.io-client` - WebSocket client
- `@heroicons/react` - Icons

## Documentación Relacionada

- **ET Specs:**
  - ET-TRD-009: Risk-Based Position Sizer
  - ET-TRD-010: Drawing Tools Persistence
  - ET-TRD-011: Market Bias Indicator
- **User Stories:** US-TRD-001 a US-TRD-020
- **Backend API Docs:** `/docs/api/trading.md`
- **ML Engine Docs:** `/docs/ml/signals.md`

---

**Última actualización:** 2026-01-25
**Autor:** Claude Opus 4.5
