# ML Module - Trading Platform Frontend

Dashboard dedicado para visualizaciones de predicciones ML generadas por el ML Engine.

## Estructura del Módulo

```
ml/
├── components/
│   ├── AMDPhaseIndicator.tsx              # Indicador de fase AMD (Accumulation/Manipulation/Distribution)
│   ├── PredictionCard.tsx                 # Tarjeta de señal ML individual
│   ├── SignalsTimeline.tsx                # Timeline de señales históricas
│   ├── AccuracyMetrics.tsx                # Métricas de accuracy del modelo
│   ├── ICTAnalysisCard.tsx                # ICT/SMC analysis (Order Blocks, FVGs)
│   ├── EnsembleSignalCard.tsx             # Multi-model ensemble signal
│   ├── TradeExecutionModal.tsx            # Trade execution modal
│   ├── ConfidenceMeter.tsx                # [OQI-006] Advanced confidence visualization
│   ├── SignalPerformanceTracker.tsx       # [OQI-006] Signal P&L tracking
│   ├── ModelAccuracyDashboard.tsx         # [OQI-006] Multi-model comparison
│   ├── BacktestResultsVisualization.tsx   # [OQI-006] Backtest analytics
│   └── index.ts                           # Barrel exports
├── pages/
│   └── MLDashboard.tsx                    # Página principal del dashboard ML
├── hooks/
│   ├── useMLAnalysis.ts                   # ML data fetching con caché
│   └── useQuickSignals.ts                 # Fast polling hook
└── README.md
```

## Componentes

### AMDPhaseIndicator
Muestra la fase AMD actual del mercado con:
- Indicador visual de la fase (Accumulation/Manipulation/Distribution)
- Nivel de confianza
- Duración de la fase
- Probabilidades de próxima fase
- Niveles clave de soporte/resistencia

**Props:**
```typescript
{
  phase: 'accumulation' | 'manipulation' | 'distribution' | 'unknown';
  confidence: number;
  phaseDuration?: number;
  nextPhaseProbability?: {
    accumulation: number;
    manipulation: number;
    distribution: number;
  };
  keyLevels?: {
    support: number;
    resistance: number;
  };
  className?: string;
  compact?: boolean;  // Versión compacta para cards
}
```

### PredictionCard
Tarjeta que muestra detalles de una señal ML:
- Dirección (LONG/SHORT)
- Niveles de precio (Entry/SL/TP)
- Métricas (Confidence, R:R, P(TP))
- Estado de validez
- Botón para ejecutar trade

**Props:**
```typescript
{
  signal: MLSignal;
  onExecuteTrade?: (signal: MLSignal) => void;
  showExecuteButton?: boolean;
  className?: string;
}
```

### SignalsTimeline
Timeline de señales recientes con su estado:
- Vista cronológica de señales
- Estados: pending, success, failed, expired
- Métricas de cada señal
- Resultado P&L si está disponible

**Props:**
```typescript
{
  signals: SignalHistoryItem[];
  maxItems?: number;  // Default: 10
  className?: string;
}
```

### AccuracyMetrics
Muestra métricas de performance del modelo ML:
- Overall accuracy
- Win rate
- Total signals / Successful / Failed
- Average Risk:Reward
- Sharpe ratio y Profit factor
- Best performing phase

**Props:**
```typescript
{
  metrics: ModelMetrics;
  period?: string;  // e.g., "Last 30 days"
  className?: string;
}
```

### ConfidenceMeter (NEW - OQI-006)
Advanced confidence gauge con visualización de model agreement:
- Circular confidence meter con gradient
- Model voting visualization (cuántos modelos están de acuerdo)
- Breakdown de confidence por modelo individual
- Color coding: green (high), yellow (medium), red (low)
- Show details toggle para ver reasoning de cada modelo

**Props:**
```typescript
{
  confidence: number;               // 0.0 - 1.0
  direction: 'BUY' | 'SELL';
  showDetails?: boolean;            // Default: false
  modelBreakdown?: Array<{
    model: string;
    confidence: number;
    vote: 'BUY' | 'SELL' | 'NEUTRAL';
  }>;
  className?: string;
}
```

### SignalPerformanceTracker (NEW - OQI-006)
Historical signal analysis con tracking de win/loss:
- Lista de señales históricas con outcome real
- Win rate calculation y stats aggregation
- P&L tracking por señal
- Filter por símbolo, timeframe, fecha
- Export functionality (CSV/JSON)
- Click en señal para ver detalles

**Props:**
```typescript
{
  signals: Array<SignalWithOutcome>;
  onSignalSelect?: (signal: SignalWithOutcome) => void;
  onExport?: (format: 'csv' | 'json') => void;
  filters?: {
    symbol?: string;
    timeframe?: string;
    dateRange?: { start: Date; end: Date };
  };
  className?: string;
}
```

### ModelAccuracyDashboard (NEW - OQI-006)
Multi-model comparison y monitoring:
- Side-by-side comparison de múltiples modelos ML
- Accuracy, precision, recall, F1 score por modelo
- Performance trends chart
- Real-time health status por modelo
- Model selection para deep dive
- Refresh button para update manual

**Props:**
```typescript
{
  models: Array<{
    id: string;
    name: string;
    type: 'LSTM' | 'RandomForest' | 'SVM' | 'XGBoost' | 'Ensemble';
    accuracy: number;
    precision: number;
    recall: number;
    f1Score: number;
    lastTrainedAt: string;
    status: 'active' | 'training' | 'error';
  }>;
  onModelSelect?: (modelId: string) => void;
  onRefresh?: () => void;
  className?: string;
}
```

### BacktestResultsVisualization (NEW - OQI-006)
Comprehensive backtest results viewer:
- Summary metrics (total return %, win rate, max drawdown)
- Equity curve chart con drawdown visualization
- Trade-by-trade list con P&L
- Performance by symbol/timeframe breakdown
- Risk metrics (Sharpe ratio, Sortino ratio, Calmar ratio)
- Export backtest report (PDF/JSON)
- Compare múltiples backtests

**Props:**
```typescript
{
  result: {
    summary: {
      totalReturn: number;
      winRate: number;
      maxDrawdown: number;
      sharpeRatio: number;
      sortinoRatio: number;
    };
    equityCurve: Array<{ date: string; equity: number; drawdown: number }>;
    trades: Array<TradeRecord>;
  };
  onExport?: (format: 'pdf' | 'json') => void;
  onTradeSelect?: (trade: TradeRecord) => void;
  className?: string;
}
```

## Páginas

### MLDashboard
Dashboard principal que integra todos los componentes:

**Características:**
- Vista general de todas las predicciones activas
- Filtros por símbolo y estado (active only)
- Indicador de fase AMD prominente
- Grid de señales activas
- Timeline de señales históricas
- Métricas de accuracy del modelo
- Auto-refresh cada 60 segundos

## Custom Hooks

### useMLAnalysis
Hook principal para fetching de datos ML con caché inteligente:

**Características:**
- Cache de 1 minuto para ICT Analysis, Ensemble Signals, Scan Results
- Health check del ML Engine
- Auto-refresh configurable
- Symbol y timeframe management
- Parallel data fetching

**Uso:**
```typescript
const {
  ictAnalysis,         // ICT Analysis | null
  ensembleSignal,      // EnsembleSignal | null
  scanResults,         // ScanResult[]
  loading,             // boolean
  error,               // string | null
  isHealthy,           // boolean - ML Engine status
  refreshICT,          // () => Promise<void>
  refreshEnsemble,     // () => Promise<void>
  refreshScan,         // () => Promise<void>
  refreshAll,          // () => Promise<void>
  setSymbol,           // (symbol: string) => void
  setTimeframe         // (timeframe: string) => void
} = useMLAnalysis({
  symbol?: string,           // Default: 'BTCUSDT'
  timeframe?: string,        // Default: '1h'
  autoRefresh?: boolean,     // Default: false
  refreshInterval?: number   // Default: 60000 (1 min)
});
```

### useQuickSignals
Fast polling hook para múltiples símbolos:

**Uso:**
```typescript
const {
  signals,     // Map<symbol, QuickSignal>
  loading,     // boolean
  refresh      // () => Promise<void>
} = useQuickSignals(
  symbols: string[],        // ['BTCUSDT', 'ETHUSD']
  pollInterval?: number     // Default: 30000 (30s)
);
```

## Integración con API

El módulo consume los siguientes endpoints del ML Engine (Base URL: `http://localhost:3083`):

### Signal Management
```typescript
GET  /api/v1/signals/active           // Señales activas
GET  /api/v1/signals/latest/:symbol   // Última señal por símbolo
POST /api/v1/signals/generate         // Generar nueva señal
```

### AMD Phase Analysis
```typescript
GET  /api/v1/amd/detect/:symbol       // Detectar fase AMD actual
```

### Price Range Prediction
```typescript
GET  /api/v1/predict/range/:symbol?timeframe=1h  // Predicción de rango
```

### Backtesting
```typescript
POST /api/v1/backtest/run             // Ejecutar backtest con params
```

### ICT/SMC Analysis
```typescript
POST /api/ict/:symbol?timeframe=1h    // Análisis ICT (Order Blocks, FVGs)
```

### Ensemble Signals
```typescript
POST /api/ensemble/:symbol?timeframe=1h  // Señal ensemble (multi-modelo)
GET  /api/ensemble/quick/:symbol         // Quick signal (cached)
```

### Symbol Scanning
```typescript
POST /api/scan                        // Escanear múltiples símbolos con threshold
```

### Health Check
```typescript
GET  /health                          // ML Engine availability
```

## Estilos y Diseño

### Paleta de Colores (Tailwind)

**Fases AMD:**
- Accumulation: `bg-blue-500` / `text-blue-400`
- Manipulation: `bg-amber-500` / `text-amber-400`
- Distribution: `bg-red-500` / `text-red-400`

**Señales:**
- BUY/LONG: `bg-green-500` / `text-green-400`
- SELL/SHORT: `bg-red-500` / `text-red-400`

**Confianza:**
- Alta (≥70%): `text-green-400`
- Media (50-70%): `text-yellow-400`
- Baja (<50%): `text-red-400`

### Layout
- Grid responsive (1 col mobile, 3 cols desktop)
- Cards con `shadow-lg` y `rounded-lg`
- Dark mode por defecto
- Transiciones suaves con `transition-colors`

## Rutas

```
/ml-dashboard  → MLDashboard page
```

Accesible desde:
- Navegación principal
- Link en MLSignalsPanel (panel lateral de Trading)

## Uso

```typescript
// En App.tsx (ya integrado)
import MLDashboard from './modules/ml/pages/MLDashboard';

<Route path="/ml-dashboard" element={<MLDashboard />} />
```

```typescript
// Usar componentes individuales
import {
  AMDPhaseIndicator,
  PredictionCard,
  SignalsTimeline,
  AccuracyMetrics,
  ConfidenceMeter,
  SignalPerformanceTracker,
  ModelAccuracyDashboard,
  BacktestResultsVisualization
} from './modules/ml/components';

<AMDPhaseIndicator
  phase="accumulation"
  confidence={0.85}
  compact={true}
/>

<ConfidenceMeter
  confidence={0.75}
  direction="BUY"
  showDetails={true}
  modelBreakdown={[
    { model: 'LSTM', confidence: 0.82, vote: 'BUY' },
    { model: 'RandomForest', confidence: 0.68, vote: 'BUY' },
    { model: 'SVM', confidence: 0.55, vote: 'NEUTRAL' }
  ]}
/>
```

```typescript
// Usar hooks
import { useMLAnalysis, useQuickSignals } from './modules/ml/hooks';

function MyComponent() {
  const {
    ictAnalysis,
    ensembleSignal,
    loading,
    refreshAll
  } = useMLAnalysis({
    symbol: 'EURUSD',
    timeframe: '1h',
    autoRefresh: true
  });

  const { signals } = useQuickSignals(['BTCUSDT', 'ETHUSD'], 60000);

  return (
    <div>
      {loading ? <Spinner /> : (
        <>
          <ICTAnalysisCard analysis={ictAnalysis} />
          <EnsembleSignalCard signal={ensembleSignal} />
        </>
      )}
    </div>
  );
}
```

## Mejoras Futuras

### Completadas (OQI-006)
- [x] ~~Comparación de modelos ML~~ ✅ ModelAccuracyDashboard
- [x] ~~Backtesting visual integrado~~ ✅ BacktestResultsVisualization
- [x] ~~Gráficos de performance histórica~~ ✅ SignalPerformanceTracker
- [x] ~~Exportar señales a CSV/PDF~~ ✅ Export en componentes

### Pendientes
- [ ] Filtros avanzados (por timeframe, volatility regime) - P2 (15h)
- [ ] Alertas push para nuevas señales - P1 (30h)
- [ ] Real-time WebSocket updates - P1 (40h)
- [ ] Model retraining interface - P2 (60h)
- [ ] Custom model upload - P3 (80h)
- [ ] A/B testing de modelos - P2 (50h)

## Notas de Desarrollo

- Todos los componentes son TypeScript strict
- Usa React Hooks (useState, useEffect, useCallback)
- Error handling con try/catch
- Loading states para UX fluida
- Responsive design mobile-first
- Optimizado para performance (memoización donde sea necesario)
