rckrdmrd
c1b5081208
ML Engine Updates: - Updated BTCUSD with Polygon API data (2024-2025): 215,699 new records - Re-trained all ML models: Attention (R²: 0.223), Base, Metamodel (87.3% confidence) - Backtest results: +176.71R profit with aggressive_filter strategy Documentation Consolidation: - Created docs/99-analisis/_MAP.md index with 13 new analysis documents - Consolidated inventories: removed duplicates from orchestration/inventarios/ - Updated ML_INVENTORY.yml with BTCUSD metrics and training results - Added execution reports: FASE11-BTCUSD, correction issues, alignment validation Architecture & Integration: - Updated all module documentation with NEXUS v3.4 frontmatter - Fixed _MAP.md indexes across all folders - Updated orchestration plans and traces Files: 229 changed, 5064 insertions(+), 1872 deletions(-) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
327 lines
11 KiB
Markdown
327 lines
11 KiB
Markdown
---
|
|
id: "US-ML-006"
|
|
title: "Integrar Señales en Chart"
|
|
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"
|
|
---
|
|
|
|
# US-ML-006: Integrar Señales en Chart
|
|
|
|
## Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **ID** | US-ML-006 |
|
|
| **Épica** | OQI-006 - Señales ML y Predicciones |
|
|
| **Módulo** | ml-signals + trading-charts |
|
|
| **Prioridad** | P0 |
|
|
| **Story Points** | 5 |
|
|
| **Sprint** | Sprint 7 |
|
|
| **Estado** | Pendiente |
|
|
| **Asignado a** | Por asignar |
|
|
|
|
---
|
|
|
|
## Historia de Usuario
|
|
|
|
**Como** trader/inversor,
|
|
**quiero** ver las señales de trading, niveles de TP/SL y predicciones directamente sobre el gráfico de velas,
|
|
**para** visualizar de forma integrada el contexto del mercado y las recomendaciones del ML.
|
|
|
|
## Descripción Detallada
|
|
|
|
El usuario debe poder visualizar directamente en el chart de TradingView/Lightweight Charts:
|
|
- Marcadores de señales BUY/SELL en el punto de entrada
|
|
- Líneas horizontales para TP1, TP2, TP3 y Stop Loss
|
|
- Rangos de predicción (High/Low esperados) como bandas
|
|
- Labels con información contextual
|
|
- Todo integrado de forma limpia y no invasiva
|
|
|
|
## Mockups/Wireframes
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ BTCUSDT $89,400.00 +2.34% ▲ [1h] [ML Signals ON 🔘] │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ Chart + ML Overlay │
|
|
│ │
|
|
│ $92,000 ┼─────────────────────────────────────────────────────────│
|
|
│ │ │
|
|
│ $91,000 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ TP3: $89,900 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ (Green) │
|
|
│ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ TP2: $89,775 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ │
|
|
│ $90,000 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ TP1: $89,650 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ │
|
|
│ │ ▲ │
|
|
│ │ ████ │ ████ ████ │
|
|
│ │ ████ │ ████ ████ ████ [Predicted High] │
|
|
│ $89,400 ┼──────────●──────────────────────────────────────────── │
|
|
│ │ ENTRY 🟢 BUY (75% conf) │
|
|
│ │ ████ ████ ████ │
|
|
│ │ ████ ████ ████ ████ [Predicted Low] │
|
|
│ $89,000 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ SL: $89,150 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ (Red) │
|
|
│ │ │
|
|
│ $88,000 ┼─────────────────────────────────────────────────────────│
|
|
│ │
|
|
│ Legend: │
|
|
│ 🟢 BUY Signal 🔴 SELL Signal ─── Take Profit ─── Stop Loss │
|
|
│ ░░░ Predicted Range (30 min Scalping) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Criterios de Aceptación
|
|
|
|
**Escenario 1: Ver señal BUY en chart**
|
|
```gherkin
|
|
DADO que existe una señal BUY activa para BTCUSDT
|
|
Y el usuario está viendo el chart de BTCUSDT
|
|
Y "ML Signals" está activado (toggle ON)
|
|
CUANDO el chart renderiza
|
|
ENTONCES se muestra:
|
|
- Marcador 🟢 en el precio de entrada (vela actual)
|
|
- Label "BUY 75%" junto al marcador
|
|
- Línea horizontal verde punteada para TP1
|
|
- Línea horizontal verde punteada para TP2
|
|
- Línea horizontal verde punteada para TP3
|
|
- Línea horizontal roja punteada para Stop Loss
|
|
- Labels en cada línea ("TP1: $89,650", "SL: $89,150")
|
|
```
|
|
|
|
**Escenario 2: Ver rango de predicción**
|
|
```gherkin
|
|
DADO que el usuario activó "Show Prediction Range"
|
|
Y existe una predicción para Scalping (30 min)
|
|
CUANDO el chart renderiza
|
|
ENTONCES se muestra:
|
|
- Banda superior en predicted_high (color verde transparente)
|
|
- Banda inferior en predicted_low (color rojo transparente)
|
|
- Fill entre bandas con color neutro (gris transparente)
|
|
- Label "30 min range (69% conf)" en la banda
|
|
```
|
|
|
|
**Escenario 3: Toggle ON/OFF de señales**
|
|
```gherkin
|
|
DADO que el usuario está viendo el chart
|
|
CUANDO hace click en el toggle "ML Signals"
|
|
ENTONCES:
|
|
- Si OFF → ON: Se muestran todas las overlays (señales, TP/SL, rangos)
|
|
- Si ON → OFF: Se ocultan todas las overlays
|
|
- El estado persiste en localStorage
|
|
```
|
|
|
|
**Escenario 4: Señal SELL en chart**
|
|
```gherkin
|
|
DADO que existe una señal SELL activa
|
|
CUANDO el chart renderiza con ML Signals ON
|
|
ENTONCES se muestra:
|
|
- Marcador 🔴 en el precio de entrada
|
|
- Label "SELL 68%"
|
|
- TP1, TP2, TP3 en precios MENORES (líneas verdes hacia abajo)
|
|
- Stop Loss en precio MAYOR (línea roja hacia arriba)
|
|
```
|
|
|
|
**Escenario 5: Actualización en tiempo real**
|
|
```gherkin
|
|
DADO que el usuario está viendo el chart con ML Signals ON
|
|
CUANDO se cierra una nueva vela de 5 minutos
|
|
Y se genera una nueva señal o actualiza la predicción
|
|
ENTONCES las overlays se actualizan automáticamente
|
|
Y se muestra una animación suave de transición
|
|
Y no se recarga todo el chart (solo las overlays)
|
|
```
|
|
|
|
**Escenario 6: Hover sobre línea de TP/SL**
|
|
```gherkin
|
|
DADO que el usuario está viendo el chart con señales
|
|
CUANDO pasa el cursor sobre una línea de TP1
|
|
ENTONCES se muestra tooltip con:
|
|
- "Take Profit 1"
|
|
- Precio: $89,650.00
|
|
- % desde entrada: +0.28%
|
|
- "Conservative target"
|
|
```
|
|
|
|
## Criterios Adicionales
|
|
|
|
- [ ] Las overlays no deben interferir con las velas del chart
|
|
- [ ] Los colores deben ser consistentes con el tema de la app
|
|
- [ ] Debe funcionar en modo claro y oscuro
|
|
- [ ] Las líneas deben ser no editables (solo visualización)
|
|
- [ ] El toggle debe estar en el header del chart, bien visible
|
|
|
|
---
|
|
|
|
## Tareas Técnicas
|
|
|
|
**Backend:**
|
|
- No requiere cambios (usa endpoints existentes)
|
|
|
|
**Frontend:**
|
|
- [ ] FE-ML-020: Crear `ChartMLOverlay.tsx` (container de overlays)
|
|
- [ ] FE-ML-021: Implementar `addSignalMarker()` en Lightweight Charts
|
|
- [ ] FE-ML-022: Implementar `addPriceLine()` para TP/SL
|
|
- [ ] FE-ML-023: Implementar `addPredictionBand()` para rangos
|
|
- [ ] FE-ML-024: Crear toggle "ML Signals" en ChartHeader
|
|
- [ ] FE-ML-025: Integrar WebSocket updates con chart overlays
|
|
- [ ] FE-ML-026: Implementar tooltips para líneas
|
|
- [ ] FE-ML-027: Persistir estado del toggle en localStorage
|
|
|
|
**Tests:**
|
|
- [ ] TEST-ML-010: Test unitario de posicionamiento de marcadores
|
|
- [ ] TEST-ML-011: Test de renderizado de overlays
|
|
- [ ] TEST-ML-012: Test E2E de toggle ML Signals ON/OFF
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
**Depende de:**
|
|
- [ ] US-TRD-001: Ver chart - Estado: ✅ Completado
|
|
- [ ] US-ML-001: Ver predicción - Estado: Pendiente
|
|
- [ ] US-ML-002: Ver señal - Estado: Pendiente
|
|
|
|
**Bloquea:**
|
|
- Ninguna (historia final de la cadena)
|
|
|
|
---
|
|
|
|
## Notas Técnicas
|
|
|
|
**Lightweight Charts API - Price Lines:**
|
|
```typescript
|
|
// Agregar línea de Take Profit
|
|
const tp1Line = series.createPriceLine({
|
|
price: 89650.00,
|
|
color: '#22c55e',
|
|
lineWidth: 2,
|
|
lineStyle: LineStyle.Dashed,
|
|
axisLabelVisible: true,
|
|
title: 'TP1: $89,650',
|
|
});
|
|
|
|
// Agregar línea de Stop Loss
|
|
const slLine = series.createPriceLine({
|
|
price: 89150.00,
|
|
color: '#ef4444',
|
|
lineWidth: 2,
|
|
lineStyle: LineStyle.Dashed,
|
|
axisLabelVisible: true,
|
|
title: 'SL: $89,150',
|
|
});
|
|
```
|
|
|
|
**Lightweight Charts API - Markers:**
|
|
```typescript
|
|
// Agregar marcador de señal BUY
|
|
series.setMarkers([
|
|
{
|
|
time: currentTime,
|
|
position: 'belowBar',
|
|
color: '#22c55e',
|
|
shape: 'arrowUp',
|
|
text: 'BUY 75%',
|
|
}
|
|
]);
|
|
|
|
// Marcador de señal SELL
|
|
series.setMarkers([
|
|
{
|
|
time: currentTime,
|
|
position: 'aboveBar',
|
|
color: '#ef4444',
|
|
shape: 'arrowDown',
|
|
text: 'SELL 68%',
|
|
}
|
|
]);
|
|
```
|
|
|
|
**Lightweight Charts API - Series de Bandas:**
|
|
```typescript
|
|
// Agregar banda de predicción
|
|
const predictionSeries = chart.addAreaSeries({
|
|
topColor: 'rgba(34, 197, 94, 0.2)',
|
|
bottomColor: 'rgba(239, 68, 68, 0.2)',
|
|
lineColor: 'rgba(156, 163, 175, 0.5)',
|
|
lineWidth: 1,
|
|
});
|
|
|
|
predictionSeries.setData([
|
|
{ time: currentTime + 300, value: predictedHigh },
|
|
{ time: currentTime + 1800, value: predictedHigh },
|
|
]);
|
|
```
|
|
|
|
**Componentes UI:**
|
|
- `ChartMLOverlay`: Gestor de todas las overlays ML
|
|
- `MLToggle`: Switch para activar/desactivar overlays
|
|
- `SignalMarker`: Lógica de marcadores de señales
|
|
- `PriceLevels`: Lógica de líneas TP/SL
|
|
- `PredictionBands`: Lógica de bandas de predicción
|
|
|
|
**Estado (Zustand) - Integración con Chart Store:**
|
|
```typescript
|
|
interface ChartStore {
|
|
// ... existing chart state
|
|
mlOverlaysEnabled: boolean;
|
|
activeSignal: TradingSignal | null;
|
|
prediction: Prediction | null;
|
|
|
|
toggleMLOverlays: () => void;
|
|
updateMLOverlays: () => void;
|
|
}
|
|
```
|
|
|
|
**LocalStorage:**
|
|
```typescript
|
|
// Persistir estado del toggle
|
|
const ML_OVERLAYS_KEY = 'trading:ml-overlays-enabled';
|
|
|
|
localStorage.setItem(ML_OVERLAYS_KEY, String(enabled));
|
|
```
|
|
|
|
---
|
|
|
|
## Definition of Ready (DoR)
|
|
|
|
- [x] Historia claramente escrita (quién, qué, por qué)
|
|
- [x] Criterios de aceptación definidos
|
|
- [x] Story points estimados
|
|
- [x] Dependencias identificadas
|
|
- [ ] Sin bloqueadores (depende de US-ML-001 y US-ML-002)
|
|
- [x] Diseño/mockup disponible
|
|
- [x] Documentación de Lightweight Charts API revisada
|
|
|
|
## Definition of Done (DoD)
|
|
|
|
- [ ] Código implementado según criterios
|
|
- [ ] Tests unitarios escritos y pasando
|
|
- [ ] Tests E2E pasando
|
|
- [ ] Code review aprobado
|
|
- [ ] Documentación actualizada
|
|
- [ ] QA aprobado en staging
|
|
- [ ] Funciona en light/dark mode
|
|
- [ ] Toggle persiste estado correctamente
|
|
- [ ] Overlays no interfieren con interactividad del chart
|
|
- [ ] Desplegado en producción
|
|
|
|
---
|
|
|
|
## Historial de Cambios
|
|
|
|
| Fecha | Cambio | Autor |
|
|
|-------|--------|-------|
|
|
| 2025-12-05 | Creación | Requirements-Analyst |
|
|
|
|
---
|
|
|
|
**Creada por:** Requirements-Analyst
|
|
**Fecha:** 2025-12-05
|
|
**Última actualización:** 2025-12-05
|