---
id: "US-ML-022"
title: "HISTORIA DE USUARIO"
type: "User Story"
status: "Done"
priority: "Media"
epic: "OQI-006"
project: "trading-platform"
story_points: 3
created_date: "2025-12-05"
updated_date: "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**
```gherkin
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**
```gherkin
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)**
```gherkin
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**
```gherkin
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**
```gherkin
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:**
```typescript
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:**
```python
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)

- [x] Historia claramente escrita (quien, que, por que)
- [x] Criterios de aceptacion definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [ ] LiquidityHunter modelo entrenado
- [x] Diseno/mockup disponible
- [x] 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