---
id: "US-ML-009"
title: "Ver Análisis ICT"
type: "User Story"
status: "Pending"
priority: "Alta"
epic: "OQI-006"
project: "trading-platform"
story_points: 5
created_date: "2026-01-25"
updated_date: "2026-01-25"
---

# US-ML-009: Ver Análisis ICT

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-ML-009 |
| **Épica** | OQI-006 - Señales ML y Predicciones |
| **Módulo** | ml-signals |
| **Prioridad** | P0 (Alta) |
| **Story Points** | 5 |
| **Sprint** | Sprint 8 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** trader/inversor,
**quiero** ver el análisis ICT (Inner Circle Trader) que incluye zonas de liquidez, fair value gaps, y order blocks,
**para** identificar puntos de entrada/salida de alto potencial basados en la metodología ICT.

## Descripción Detallada

El usuario debe poder visualizar en el chart de precios un análisis completo de la metodología ICT que incluya:

1. **Zonas de Liquidez (Liquidity Zones)**: Áreas donde se acumulan órdenes de compra/venta
2. **Fair Value Gaps (FVGs)**: Brechas de precio donde no hay transacciones (gaps de aire)
3. **Order Blocks (OB)**: Bloques de órdenes que actúan como soporte/resistencia
4. **Puntos de Interés (POI)**: Zonas clave de reversión y manipulación de precios

Cada elemento debe ser interactivo mostrando detalles como tamaño de la zona, potencia, fechas de formación, y probabilidad de inversión de precio.

## Mockups/Wireframes

```
┌──────────────────────────────────────────────────────────────────┐
│  ICT ANALYSIS - BTCUSDT                                    4h   │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Controls:                                                        │
│  [Liquidity Zones ☑] [FVGs ☑] [Order Blocks ☑] [POI ☑]         │
│  [Bias: Bullish ▼] [Threshold: Medium ▼]       [Legend]        │
│                                                                   │
│  ══════════════════════════════════════════════════════════════  │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                                                              │ │
│  │              BTCUSDT / 4H Chart                             │ │
│  │                                                              │ │
│  │                          ╱╲                                 │ │
│  │                        ╱┌──┐╲         🔵 Order Block        │ │
│  │         ╱╲            ╱│ 🔵 │╲        (Bullish, 8.2/10)     │ │
│  │       ╱┌──┐╲        ╱  │    │  ╲      Entry: $89,200       │ │
│  │     ╱  │ 🟢│  ╲    ╱   │    │   ╲    Strength: 95%         │ │
│  │   ╱┌───┼────┼───╲╱     │    │    ╲                          │ │
│  │  ╱ │ 🟡 │ 🔴 │  ║      │    │     ╲  ☑ Liquidity Zone     │ │
│  │╱───┼────┼────┼──║──────┼────┼──────╲  Above: $90,100       │ │
│  │─────┼────┼────┼──║──────┼────┼───────  Strength: High      │ │
│  │     │    │    │  ║      │    │         Probability: 75%     │ │
│  │     │    │    │  ║      │ 🔘 │                              │ │
│  │     │    │    │  ║      │ 🟣 │         🟡 Fair Value Gap  │
│  │     └────┴────┴──║──────┴────┴──       $89,850 - $89,650   │
│  │                  ║                    Gap Size: 0.2%        │
│  │                  ║                    Type: Bullish Breaker │
│  │                                                              │
│  │  [Zoom] [Reset] [Compare] [Backtest This] [Alerts]         │
│  │                                                              │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ICT ELEMENTS FOUND (16)                                         │
│  ═════════════════════════════════════════════════════════════  │
│                                                                   │
│  ┌─ LIQUIDITY ZONES (4) ─────────────────────────────────────┐ │
│  │ ☑ Above Current Price:                                     │ │
│  │   • $90,100 - $90,500 (Strength: 94%) - Last 3H ago      │ │
│  │   • $91,200 - $91,800 (Strength: 87%) - Last 8H ago      │ │
│  │ ☑ Below Current Price:                                     │ │
│  │   • $88,500 - $88,200 (Strength: 91%) - Last 2H ago      │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ FAIR VALUE GAPS (3) ──────────────────────────────────────┐ │
│  │ • $89,850 - $89,650 (Bullish Breaker, Gap Size: 0.2%)    │ │
│  │   ├─ Formed: 45 min ago                                    │ │
│  │   ├─ Status: Unmitigated (Not touched by price)           │ │
│  │   └─ Probability: High that will be filled in 4-8H        │ │
│  │ • $87,900 - $87,500 (Bearish Breaker, Gap Size: 0.4%)    │ │
│  │   ├─ Formed: 6H ago                                        │ │
│  │   ├─ Status: Partially Mitigated                          │ │
│  │   └─ Probability: Medium that will be retested            │ │
│  │ • $90,200 - $89,950 (Bullish Breaker, Gap Size: 0.25%)   │ │
│  │   ├─ Formed: 2H ago                                        │ │
│  │   ├─ Status: Unmitigated                                  │ │
│  │   └─ Probability: Very High (needs mitigation)            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ ORDER BLOCKS (5) ────────────────────────────────────────┐ │
│  │ ☑ Bullish Order Block:                                     │ │
│  │   • Entry: $89,200 - $89,350 (Strength: 95%, Score: 8.2)  │ │
│  │   • Formed during strong uptrend 3H ago                    │ │
│  │   • Touch points: 2 (May retry)                            │ │
│  │   • Next resistance: $90,100 (Liquidity Zone)              │ │
│  │ ☑ Bearish Order Block:                                     │ │
│  │   • Entry: $90,500 - $90,650 (Strength: 88%, Score: 7.9)  │ │
│  │   • Formed during downtrend 6H ago                         │ │
│  │   • Touch points: 1 (Fresh block)                          │ │
│  │   • Next support: $89,500 (FVG area)                       │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ POINTS OF INTEREST (4) ──────────────────────────────────┐ │
│  │ • $90,100 (Swing High + Liquidity Zone)                   │ │
│  │   ├─ Type: Supply/Resistance                               │ │
│  │   ├─ Confluence: 3 levels                                  │ │
│  │   └─ Probability of reversal: 82%                          │ │
│  │ • $88,500 (Swing Low + Liquidity Zone)                    │ │
│  │   ├─ Type: Demand/Support                                  │ │
│  │   ├─ Confluence: 2 levels                                  │ │
│  │   └─ Probability of bounce: 76%                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Mostrar análisis ICT completo**
```gherkin
DADO que el usuario está en la pantalla de chart
CUANDO abre la sección "ICT Analysis"
ENTONCES se visualizan en el chart:
  - Zonas de liquidez (coloreadas y etiquetadas)
  - Fair Value Gaps (dibujados como rectángulos vacíos)
  - Order Blocks (rectángulos rellenos con poder)
  - Puntos de Interés (círculos/estrelas destacadas)
Y cada elemento tiene color diferenciado (bullish/bearish)
Y se muestra un panel lateral con listado de todos los elementos
```

**Escenario 2: Filtrar elementos ICT**
```gherkin
DADO que el usuario está viendo el análisis ICT
CUANDO desactiva un tipo de elemento (ej: FVGs)
ENTONCES desaparecen del chart
Y se actualiza el contador en el panel lateral
Y el resto de elementos se mantienen visibles
```

**Escenario 3: Ver detalles de zona de liquidez**
```gherkin
DADO que el usuario está en ICT Analysis
CUANDO hace hover/click en una zona de liquidez
ENTONCES aparece un tooltip/modal con:
  - Rango de precios (high-low)
  - Fortaleza/poder de la zona (%)
  - Fecha de formación
  - Número de toques/veces que fue tocada
  - Probabilidad de que el precio vuelva a esa zona
  - Botón para crear orden en esa zona
```

**Escenario 4: Ver detalles de Fair Value Gap**
```gherkin
DADO que el usuario está en ICT Analysis
CUANDO hace click en un FVG
ENTONCES aparece un modal con:
  - Rango del gap (precio alto - precio bajo)
  - Tipo de gap (Bullish Breaker / Bearish Breaker / Continuation)
  - Tamaño del gap (en pips/%)
  - Estado (Unmitigated / Partially mitigated / Fully mitigated)
  - Fecha de formación
  - Probabilidad de que se cierre el gap (%)
  - Momento estimado de cierre
  - [Ver en chart] [Crear alerta] [Crear orden]
```

**Escenario 5: Ver detalles de Order Block**
```gherkin
DADO que el usuario está en ICT Analysis
CUANDO hace click en un Order Block
ENTONCES aparece un modal con:
  - Rango de entrada del bloque
  - Tipo (Bullish / Bearish)
  - Score de fortaleza (1-10)
  - Potencia del bloque (%)
  - Número de veces que fue tocado
  - Formación: qué vela/candle lo creó
  - Próxima resistencia/soporte
  - [Crear orden en este bloque] [Crear alerta]
```

**Escenario 6: Cambiar timeframe**
```gherkin
DADO que el usuario está en ICT Analysis
CUANDO cambia el timeframe (ej: 1H → 4H → 1D)
ENTONCES se recalcula y redibuja todo el análisis ICT
Y los elementos cambian según el timeframe elegido
Y el API actualiza con los datos del nuevo timeframe
```

**Escenario 7: Crear alerta en zona ICT**
```gherkin
DADO que el usuario está viendo un elemento ICT
CUANDO hace click en "Crear alerta" desde el modal
ENTONCES se abre un formulario para crear una alerta:
  - Precio de trigger (pre-rellenado)
  - Tipo de alerta (email/push/SMS)
  - Mensaje personalizado
  CUANDO confirma
  ENTONCES se crea la alerta
  Y se muestra confirmación "Alerta creada para $90,100"
```

**Escenario 8: Comparar análisis entre timeframes**
```gherkin
DADO que el usuario está en ICT Analysis
CUANDO hace click en "Compare"
ENTONCES se abre una vista con dos charts lado a lado:
  - Izquierda: timeframe actual (ej: 4H)
  - Derecha: timeframe diferente (ej: 1D)
  Y ambos muestran su análisis ICT correspondiente
  Y se resaltan confluyencias entre timeframes
```

**Escenario 9: Backtesting de zona ICT**
```gherkin
DADO que el usuario está viendo un Order Block o FVG
CUANDO hace click en "Backtest This"
ENTONCES se abre un análisis histórico mostrando:
  - Cuántas veces el precio tocó esta zona en el pasado
  - Cuántas veces resultó en reversión
  - Ganancia promedio si se hubiera operado en esta zona
  - Tasa de éxito (%)
  - Gráfico histórico de touch points
```

## Criterios Adicionales

- [ ] El análisis debe cargar en menos de 1.5 segundos
- [ ] Debe soportar todos los timeframes (1m, 5m, 15m, 1h, 4h, 1d, 1w)
- [ ] Debe recalcularse automáticamente cada nueva vela
- [ ] Los colores deben ser customizables por tema (light/dark)
- [ ] Bullish elements en verde/azul, Bearish en rojo/naranja
- [ ] Responsive en tablets y mobile (scrollable chart)
- [ ] Performance: máximo 50 elementos ICT dibujados simultáneamente
- [ ] Debe funcionar sin valores reales de market data si es necesario (mock data)

---

## Tareas Técnicas

**Backend (FastAPI - ml-engine):**
- [ ] BE-ML-016: Crear endpoint GET /api/ml/ict/:symbol
- [ ] BE-ML-017: Implementar análisis de Liquidity Zones
- [ ] BE-ML-018: Implementar detección de Fair Value Gaps
- [ ] BE-ML-019: Implementar detección de Order Blocks
- [ ] BE-ML-020: Implementar cálculo de Points of Interest
- [ ] BE-ML-021: Implementar score/strength para cada elemento
- [ ] BE-ML-022: Endpoint GET /api/ml/ict/:symbol/compare (compare timeframes)
- [ ] BE-ML-023: Implementar caching de análisis ICT

**Python ML Service:**
- [ ] ML-ICT-001: Desarrollar módulo ICT detector
- [ ] ML-ICT-002: Algoritmo de identificación de Liquidity Zones
- [ ] ML-ICT-003: Algoritmo de detección de FVGs
- [ ] ML-ICT-004: Algoritmo de detección de Order Blocks
- [ ] ML-ICT-005: Algoritmo de cálculo de POI (Points of Interest)
- [ ] ML-ICT-006: Validación y backtesting de elementos ICT
- [ ] ML-ICT-007: Tests unitarios de detección

**Frontend (React):**
- [ ] FE-ML-035: Crear componente `ICTAnalysis.tsx`
- [ ] FE-ML-036: Crear componente `ICTChart.tsx` (integración lightweight-charts)
- [ ] FE-ML-037: Crear componente `ICTControls.tsx` (filtros y toggles)
- [ ] FE-ML-038: Crear componente `ICTSidebar.tsx` (listado de elementos)
- [ ] FE-ML-039: Crear componente `LiquidityZoneModal.tsx`
- [ ] FE-ML-040: Crear componente `FVGModal.tsx`
- [ ] FE-ML-041: Crear componente `OrderBlockModal.tsx`
- [ ] FE-ML-042: Crear componente `POIModal.tsx`
- [ ] FE-ML-043: Crear componente `ComparisonChart.tsx`
- [ ] FE-ML-044: Crear componente `BacktestModal.tsx`
- [ ] FE-ML-045: Implementar dibujado en lightweight-charts
- [ ] FE-ML-046: Implementar state management (Zustand) para ICT data
- [ ] FE-ML-047: Implementar tooltips interactivos
- [ ] FE-ML-048: Implementar colores customizables por tema

**Tests:**
- [ ] TEST-ML-016: Test detección de Liquidity Zones
- [ ] TEST-ML-017: Test detección de FVGs
- [ ] TEST-ML-018: Test detección de Order Blocks
- [ ] TEST-ML-019: Test E2E de análisis completo
- [ ] TEST-ML-020: Test de performance (<1.5s load)

**Documentación:**
- [ ] DOC-ICT-001: Guía de análisis ICT en la plataforma
- [ ] DOC-ICT-002: Explicación de cada elemento ICT
- [ ] DOC-ICT-003: Cómo interpretar las métricas

---

## Dependencias

**Depende de:**
- [ ] RF-ML-001: Integración de datos de mercado (OHLCV)
- [ ] US-ML-001: Ver chart de trading
- [ ] US-ML-002: Ver señal en chart
- [ ] OQI-003: Trading Charts (infraestructura base)

**Bloquea:**
- [ ] US-ML-010: Alertas ICT
- [ ] US-ML-011: Backtesting de estrategia ICT

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /api/ml/ict/:symbol | Obtener análisis ICT para símbolo |
| GET | /api/ml/ict/:symbol/timeframe/:tf | Análisis ICT por timeframe |
| GET | /api/ml/ict/:symbol/compare | Comparar análisis entre TFs |
| POST | /api/ml/ict/:symbol/backtest | Backtesting de zona ICT |
| GET | /api/alerts/:symbol/ict | Obtener alertas ICT activas |

**Query Parameters - ICT Analysis:**
```
GET /api/ml/ict/BTCUSDT?
  timeframe=4h&
  include=liquidity_zones,fvgs,order_blocks,poi&
  threshold=medium&
  bias=bullish
```

**Response esperado:**
```typescript
interface ICTAnalysisResponse {
  symbol: string;
  timeframe: string;
  timestamp: string;
  analysis: {
    liquidity_zones: LiquidityZone[];
    fair_value_gaps: FairValueGap[];
    order_blocks: OrderBlock[];
    points_of_interest: PointOfInterest[];
  };
  summary: {
    total_elements: number;
    bullish_elements: number;
    bearish_elements: number;
    strongest_level: number;
    nearest_liquidity_up: number;
    nearest_liquidity_down: number;
  };
}

interface LiquidityZone {
  id: string;
  type: 'BUY' | 'SELL';
  price_high: number;
  price_low: number;
  strength: number; // 0-100
  formed_at: string;
  touch_count: number;
  probability_return: number; // 0-100
}

interface FairValueGap {
  id: string;
  type: 'BULLISH_BREAKER' | 'BEARISH_BREAKER' | 'CONTINUATION';
  gap_high: number;
  gap_low: number;
  gap_size_pips: number;
  gap_size_percent: number;
  status: 'UNMITIGATED' | 'PARTIALLY_MITIGATED' | 'FULLY_MITIGATED';
  formed_at: string;
  probability_fill: number; // 0-100
  estimated_fill_time: string; // ISO duration
}

interface OrderBlock {
  id: string;
  type: 'BULLISH' | 'BEARISH';
  entry_high: number;
  entry_low: number;
  strength_score: number; // 1-10
  power_percent: number; // 0-100
  touch_count: number;
  formed_at: string;
  candle_formation: string;
  next_target: number;
}

interface PointOfInterest {
  id: string;
  price: number;
  type: 'SWING_HIGH' | 'SWING_LOW' | 'CONFLUENCE';
  confluence_count: number;
  reversal_probability: number; // 0-100
  bounce_probability: number; // 0-100
  elements: string[]; // IDs de elementos que confluyen
}
```

**Componentes UI principales:**
- `ICTAnalysis`: Container del análisis
- `ICTChart`: Canvas del chart con dibujado de elementos
- `ICTControls`: Controles de filtrado y display
- `ICTSidebar`: Listado de elementos detectados
- `ICTModals`: Familia de modales (Liquidity, FVG, OB, POI)
- `ComparisonChart`: Vista comparativa de timeframes
- `BacktestView`: Análisis histórico de una zona

**State Management (Zustand):**
```typescript
interface ICTStore {
  ictData: ICTAnalysisResponse | null;
  selectedElement: ICTElement | null;
  timeframe: string;
  visibleElements: {
    liquidity_zones: boolean;
    fvgs: boolean;
    order_blocks: boolean;
    poi: boolean;
  };
  bias: 'BULLISH' | 'BEARISH' | 'NEUTRAL';
  threshold: 'LOW' | 'MEDIUM' | 'HIGH';

  fetchICTAnalysis: (symbol: string, tf: string) => Promise<void>;
  selectElement: (element: ICTElement) => void;
  toggleElementType: (type: keyof visibleElements) => void;
  setBias: (bias: string) => void;
  setThreshold: (threshold: string) => void;
}
```

**Integración con Chart:**
- Usar series personalizada de lightweight-charts
- Plugins para dibujado de zonas y elementos
- Overlay layers para diferentes tipos de elementos

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita (quién, qué, por qué)
- [x] Criterios de aceptación detallados (9 escenarios)
- [x] Story points estimados (5)
- [x] Dependencias identificadas
- [x] Sin bloqueadores
- [x] Diseño/mockup disponible
- [x] APIs especificadas

## Definition of Done (DoD)

- [ ] Código Python implementado (ICT detectors)
- [ ] Código TypeScript implementado (endpoints + frontend)
- [ ] Tests unitarios escritos y pasando (Python y TS)
- [ ] Tests E2E pasando
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] Backtesting validado (accuracy > 80%)
- [ ] Rendimiento verificado (<1.5s load)
- [ ] Responsive en mobile/tablet
- [ ] QA aprobado en staging
- [ ] Desplegado en producción

---

## Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2026-01-25 | Creación | Claude Code |

---

**Creada por:** Claude Code
**Fecha:** 2026-01-25
**Última actualización:** 2026-01-25
