trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/epicas/historias-usuario/US-ML-022-zonas-liquidez.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-022	HISTORIA DE USUARIO	User Story	Done	Media	OQI-006	trading-platform	3	2025-12-05	2026-01-04

HISTORIA DE USUARIO

Version: 1.0.0 Fecha: 2025-12-05 Uso: Definicion de historia de usuario

---

US-ML-022: Ver Zonas de Liquidez (BSL/SSL) en Chart

Metadata

Campo	Valor
ID	US-ML-022
Epica	OQI-006A - Estrategia AMD y Modelos ML Avanzados
Modulo	ml-signals
Prioridad	P0
Story Points	8
Sprint	Sprint 9
Estado	Ready
Asignado a	ML-Engineer / Frontend-Developer

---

Historia de Usuario

Como trader que utiliza conceptos de Smart Money, quiero ver las zonas de liquidez (Buy Side Liquidity y Sell Side Liquidity) superpuestas en el chart, para anticipar movimientos institucionales de "stop hunting" y planificar entradas/salidas optimas.

Descripcion Detallada

Las zonas de liquidez representan areas donde se acumulan ordenes stop-loss de traders retail:

• BSL (Buy Side Liquidity): Zonas sobre maximos recientes donde hay stops de posiciones cortas. Color azul claro.
• SSL (Sell Side Liquidity): Zonas bajo minimos recientes donde hay stops de posiciones largas. Color rojo claro.

El modelo LiquidityHunter predice:

1. Ubicacion de zonas de liquidez
2. Densidad de liquidez (baja/media/alta)
3. Probabilidad de que el precio visite la zona
4. Si la zona ya fue "sweepada" (barrida)

Los traders institucionales frecuentemente "cazan" estas zonas antes de mover el precio en la direccion opuesta.

Mockups/Wireframes

+----------------------------------------------------------+
|                    TRADING CHART                          |
+----------------------------------------------------------+
|                                                          |
|  BSL Zone =========== [High Density] ============= $2450 |
|            P(sweep): 72%                                 |
|                                                          |
|        /\                                                |
|       /  \    /\                                         |
|      /    \  /  \                                        |
|     /      \/    \    Current: $2380                     |
|    /              \  /                                   |
|   /                \/                                    |
|                                                          |
|  SSL Zone =========== [Medium Density] =========== $2320 |
|            P(sweep): 45%                                 |
|                                                          |
+----------------------------------------------------------+
|  Legend: [BSL] Buy Side Liquidity  [SSL] Sell Side Liq   |
+----------------------------------------------------------+

---

Criterios de Aceptacion

Escenario 1: Visualizacion de zonas BSL

DADO que estoy viendo el chart de trading
CUANDO el modelo LiquidityHunter detecta zonas BSL
ENTONCES veo rectangulos azul claro sobre los maximos recientes
Y cada zona muestra su densidad (baja/media/alta)
Y puedo ver la probabilidad de sweep al hacer hover

Escenario 2: Visualizacion de zonas SSL

DADO que estoy viendo el chart de trading
CUANDO el modelo LiquidityHunter detecta zonas SSL
ENTONCES veo rectangulos rojo claro bajo los minimos recientes
Y cada zona muestra su densidad (baja/media/alta)
Y puedo ver la probabilidad de sweep al hacer hover

Escenario 3: Zona sweepada (barrida)

DADO que existe una zona de liquidez en el chart
CUANDO el precio atraviesa la zona (sweep)
ENTONCES la zona cambia a color gris con lineas diagonales
Y el label muestra "SWEPT" con timestamp
Y se dispara una alerta visual (si esta configurada)

Escenario 4: Actualizacion dinamica

DADO que estoy viendo zonas de liquidez
CUANDO se forman nuevos maximos/minimos
ENTONCES las zonas se actualizan en menos de 5 segundos
Y las zonas antiguas se marcan como menos relevantes (opacidad menor)

Escenario 5: Toggle de visualizacion

DADO que estoy viendo el chart con zonas de liquidez
CUANDO desactivo el indicador de liquidez
ENTONCES las zonas desaparecen del chart
Y el boton de toggle muestra estado "OFF"

Criterios Adicionales

• Zonas no bloquean visualizacion del precio
• Opacidad configurable por usuario
• Filtro por densidad minima (mostrar solo alta/media)
• Historial de sweeps en sidebar
• Compatible con TradingView Lightweight Charts

---

Tareas Tecnicas

Backend (FastAPI):

• BE-ML-030: Endpoint GET /api/ml/liquidity/zones
• BE-ML-031: Endpoint GET /api/ml/liquidity/sweeps
• BE-ML-032: WebSocket para actualizaciones de zonas

ML Model:

• ML-030: Implementar LiquidityHunter.detect_zones()
• ML-031: Implementar LiquidityHunter.predict_sweep()
• ML-032: Feature engineering para liquidez (10 features)
• ML-033: Entrenamiento con datos historicos de sweeps

Frontend:

• FE-ML-030: Componente LiquidityZonesOverlay
• FE-ML-031: Componente LiquidityZoneBadge
• FE-ML-032: Componente SweepHistoryPanel
• FE-ML-033: Store liquidityStore (Zustand)
• FE-ML-034: Integracion con TradingView chart

Tests:

• TEST-ML-030: Unit tests LiquidityHunter
• TEST-ML-031: Unit tests zona detection
• TEST-ML-032: E2E tests visualizacion

---

Dependencias

Depende de:

• OQI-003: Trading Charts basico - Estado: In Progress
• LiquidityHunter modelo entrenado - Estado: Pending

Bloquea:

• US-ML-024: Score de confluencia (incluye liquidez)

---

Notas Tecnicas

Endpoints involucrados:

Metodo	Endpoint	Descripcion
GET	/api/ml/liquidity/zones	Zonas activas
GET	/api/ml/liquidity/sweeps	Historial de sweeps
WS	/ws/ml/liquidity	Stream de actualizaciones

Entidades/Tablas:

• ml.liquidity_zones: Zonas detectadas
• ml.liquidity_sweeps: Registro de sweeps

Componentes UI:

• LiquidityZonesOverlay: Overlay para chart
• LiquidityZoneBadge: Badge individual de zona
• SweepHistoryPanel: Panel lateral con historial

Response Schema:

interface LiquidityZone {
  id: string;
  type: 'bsl' | 'ssl';
  price_low: number;
  price_high: number;
  density: 'low' | 'medium' | 'high';
  sweep_probability: number;  // 0-1
  is_swept: boolean;
  swept_at: string | null;    // ISO 8601
  created_at: string;         // ISO 8601
  source_candles: number[];   // Indices de velas que formaron la zona
}

interface SweepEvent {
  zone_id: string;
  swept_at: string;
  sweep_price: number;
  reversal_occurred: boolean;
  reversal_pct: number | null;
}

LiquidityHunter Features:

features = [
    'swing_high_count_10',    # Numero de swing highs en 10 periodos
    'swing_low_count_10',     # Numero de swing lows en 10 periodos
    'distance_to_bsl',        # Distancia normalizada a BSL mas cercano
    'distance_to_ssl',        # Distancia normalizada a SSL mas cercano
    'bsl_density',            # Densidad de liquidez en BSL
    'ssl_density',            # Densidad de liquidez en SSL
    'volume_at_level',        # Volumen historico en el nivel
    'touches_count',          # Numero de veces que precio toco el nivel
    'time_since_formation',   # Tiempo desde formacion de la zona
    'amd_phase'               # Fase AMD actual (input de AMDDetector)
]

---

Definition of Ready (DoR)

• Historia claramente escrita (quien, que, por que)
• Criterios de aceptacion definidos
• Story points estimados
• Dependencias identificadas
• LiquidityHunter modelo entrenado
• Diseno/mockup disponible
• API spec disponible

Definition of Done (DoD)

• Codigo implementado segun criterios
• Tests unitarios escritos y pasando
• Tests de integracion pasando
• Code review aprobado
• Documentacion actualizada
• Inventarios actualizados
• Traza registrada
• QA aprobado
• Desplegado en ambiente de pruebas

---

Historial de Cambios

Fecha	Cambio	Autor
2025-12-05	Creacion	Requirements-Analyst

---

Notas de Implementacion

Pendiente de desarrollo

Notas de QA

Pendiente de pruebas

---

Creada por: Requirements-Analyst Fecha: 2025-12-05 Ultima actualizacion: 2025-12-05