trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/historias-usuario/US-ML-009-ver-ict-analysis.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-009	Ver Análisis ICT	User Story	Pending	Alta	OQI-006	trading-platform	5	2026-01-25	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

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

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

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

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

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

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

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

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

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:

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

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)

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