rckrdmrd/trading-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bfda089f4e
trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/epicas/historias-usuario/US-ML-022-zonas-liquidez.md

8.1 KiB
Raw Blame History

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