--- 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; 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