trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/historias-usuario/US-ML-010-scan-multisimbolo.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-010	Scan Multi-Símbolo	User Story	Pending	Media	OQI-006	trading-platform	5	2026-01-25	2026-01-25

US-ML-010: Scan Multi-Símbolo

Metadata

Campo	Valor
ID	US-ML-010
Épica	OQI-006 - Señales ML y Predicciones
Módulo	ml-signals
Prioridad	P2 (Media)
Story Points	5
Sprint	Por asignar
Estado	Pendiente
Asignado a	Por asignar

---

Historia de Usuario

Como trader/inversor, quiero escanear múltiples símbolos simultáneamente en busca de señales de trading, para encontrar las mejores oportunidades disponibles en el mercado de forma eficiente.

Descripción Detallada

El usuario debe poder seleccionar una lista de símbolos (desde una lista predefinida, watchlist personal, o subir lista personalizada), ejecutar un escaneo que genere señales ML para todos ellos en paralelo, y visualizar los resultados filtrados y ordenados por confianza. El escaneo debe completarse en menos de 10 segundos para máximo 50 símbolos.

Mockups/Wireframes

┌──────────────────────────────────────────────────────────────────┐
│  MULTI-SYMBOL SCAN                                               │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Symbol Selection:                                                │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ ▼ Select from: [Popular ▼] [My Watchlist ▼] [Custom ▼]   │ │
│  │                                                             │ │
│  │ ☑ BTCUSDT    ☑ ETHUSDT    ☑ BNBUSDT                       │ │
│  │ ☑ ADAUSDT    ☑ XRPUSDT    ☑ DOGEUSDT                      │ │
│  │ ☑ MATICUSDT  ☑ SOLUSDT    ☑ LINKUSDT                      │ │
│  │                                                             │ │
│  │ [Clear All] [Select All] [Select: 9 symbols]             │ │
│  │                                                             │ │
│  │ Or upload CSV: [Choose File] upload-symbols.csv            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  Filter & Sort:                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Signal Type: [All ▼] Action: [BUY ▼] Horizon: [All ▼]   │ │
│  │ Min Confidence: [50% ▼]  Sort by: [Confidence ▼]         │ │
│  │                                                             │ │
│  │ [🔄 Scan Now] [⏸️ Cancel]      Scanning: 7/9              │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ══════════════════════════════════════════════════════════════  │
│                                                                   │
│  SCAN RESULTS - 9 Symbols, 12 Signals Found                      │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Symbol  Action Horizon    Conf.  Score   Entry      Status  │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │ BTCUSDT 🟢 BUY  Scalping   85%    9.2/10  $89,400  ✅ Ready│ │
│  │ ETHUSDT 🟢 BUY  Intraday   78%    8.8/10  $3,240   ✅ Ready│ │
│  │ BNBUSDT 🟢 BUY  Swing      72%    8.1/10  $620     ✅ Ready│ │
│  │ ADAUSDT 🔴 SELL Intraday   68%    7.6/10  $1.05    ✅ Ready│ │
│  │ LINKUSDT 🟢 BUY Swing      65%    7.3/10  $28.50   ✅ Ready│ │
│  │ SOLUSDT 🔵 HOLD Position   58%    6.9/10  $190.50  ⚠️ Weak │ │
│  │ XRPUSDT 🔴 SELL Scalping   55%    6.2/10  $2.45    ⚠️ Weak │ │
│  │ MATICUSDT - - -              -      -      -        ❌ NoSig│ │
│  │ DOGEUSDT - - -               -      -      -        ❌ NoSig│ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  [View Details] [Add to Watchlist] [Export Results]              │
│                                                                   │
│  SUMMARY                                                         │
│  ══════════════════════════════════════════════════════════════  │
│  Total Symbols Scanned: 9                                        │
│  Signals Found: 7 (77.8%)                                        │
│  Strong Signals (>70%): 4                                        │
│  Weak Signals (50-70%): 3                                        │
│  Avg Confidence: 68.3%                                           │
│                                                                   │
│  [Create Portfolio from BUY Signals]  [Refresh Scan]             │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  SCAN PROGRESS                                        [✕ Cancel]  │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Scanning 9 symbols in parallel...                               │
│                                                                   │
│  ✅ BTCUSDT   (2.1s)                                              │
│  ✅ ETHUSDT   (1.8s)                                              │
│  ✅ BNBUSDT   (1.5s)                                              │
│  ⏳ ADAUSDT   (Generating signal...)                              │
│  ⏳ XRPUSDT   (Generating signal...)                              │
│  ⏳ LINKUSDT  (Analyzing indicators...)                           │
│  ⏳ SOLUSDT   (Analyzing indicators...)                           │
│  ⏳ MATICUSDT (Analyzing indicators...)                           │
│  ⏳ DOGEUSDT  (Analyzing indicators...)                           │
│                                                                   │
│  Completed: 3/9  •  Elapsed: 5.2s  •  Est. time: ~7.8s           │
│  ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 33%                      │
│                                                                   │
│  [View Real-time Feed] [Pause] [Cancel]                          │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

---

Criterios de Aceptación

Escenario 1: Seleccionar símbolos desde lista predefinida

DADO que el usuario está en la pantalla Multi-Symbol Scan
CUANDO hace click en "Popular"
ENTONCES se muestran los 50 símbolos más populares/líquidos
Y puede seleccionar hasta 50 símbolos con checkboxes
Y se muestra el contador "Select: X symbols"

Escenario 2: Usar watchlist personal

DADO que el usuario tiene una watchlist guardada
CUANDO selecciona "My Watchlist"
ENTONCES se cargan automáticamente los símbolos de la watchlist
Y puede desseleccionar símbolos si lo desea
Y se mantiene la selección al cambiar de filtro

Escenario 3: Subir lista personalizada en CSV

DADO que el usuario está en Symbol Selection
CUANDO hace click en "Choose File" y selecciona un CSV
ENTONCES el sistema parsea el archivo (formato: 1 símbolo por línea)
Y agrega los símbolos a la selección
Y muestra cantidad de símbolos cargados (validando que sean correctos)
Y permite deseleccionar los que no desea

Escenario 4: Ejecutar escaneo multi-símbolo

DADO que el usuario ha seleccionado 9 símbolos
Y ha configurado filtros (tipo de señal, confianza mínima)
CUANDO hace click en "Scan Now"
ENTONCES inicia escaneo paralelo en todos los símbolos
Y muestra progreso en tiempo real (símbolos completados)
Y el escaneo completa en menos de 10 segundos para 50 símbolos
Y muestra "Scanning: 3/9" mientras se ejecuta

Escenario 5: Ver resultados en tabla

DADO que el escaneo se ha completado
CUANDO se muestran los resultados
ENTONCES se visualiza tabla con columnas:
  - Símbolo
  - Acción (BUY/SELL/HOLD)
  - Horizonte
  - Confianza %
  - Score (0-10)
  - Precio de entrada
  - Estado (✅ Ready / ⚠️ Weak / ❌ No Signal)
Y cada fila es clickeable para ver detalles completos

Escenario 6: Filtrar resultados por confianza

DADO que se muestran los resultados del escaneo
CUANDO selecciona "Min Confidence: 70%"
ENTONCES se muestran solo señales con confianza >= 70%
Y se actualiza el contador "7 of 12 signals"
Y el resumen se recalcula solo para señales filtradas

Escenario 7: Filtrar por tipo de señal

DADO que se muestran los resultados
CUANDO selecciona "Action: BUY"
ENTONCES muestra solo señales de compra
Y se pueden combinar filtros (ej: Action=BUY AND Horizon=Scalping)

Escenario 8: Ordenar por confianza

DADO que se muestran resultados
CUANDO hace click en "Sort by: Confidence" (descendente)
ENTONCES la tabla se ordena con señales más confiables primero
Y se puede invertir el orden (ascendente/descendente)
Y se pueden ordenar también por Score, Símbolo, etc.

Escenario 9: Exportar resultados

DADO que se muestran los resultados del escaneo
CUANDO hace click en "Export Results"
ENTONCES descarga archivo CSV con:
  - Symbol, Action, Horizon, Confidence, Score, Entry Price
  - Nombre: "scan-results-2026-01-25-09-30.csv"

Escenario 10: Crear portfolio desde resultados

DADO que se muestran resultados del escaneo
CUANDO hace click en "Create Portfolio from BUY Signals"
ENTONCES se abre modal para crear nuevo portfolio
Y se preseleccionan automáticamente todos los BUY signals
Y el usuario puede ajustar pesos y confirmar creación

Criterios Adicionales

• El escaneo debe soportar máximo 50 símbolos simultáneamente
• El tiempo máximo debe ser menor a 10 segundos
• Los resultados deben mostrarse ordenados por confianza descendente
• El CSV debe ser válido y con header
• Debe mostrar progreso en tiempo real durante el escaneo
• Debe manejar símbolos inválidos (ignorarlos o marcar con error)
• La tabla debe ser responsive en móvil
• Los filtros deben ser combinables

---

Tareas Técnicas

Backend:

• BE-ML-020: Crear endpoint POST /api/ml/scan
• BE-ML-021: Implementar worker para escaneo paralelo (queue-based)
• BE-ML-022: Validar símbolos de entrada
• BE-ML-023: Parsear CSV de símbolos
• BE-ML-024: Implementar filtros (action, horizon, confidence_min)
• BE-ML-025: Generar respuesta con resultados ordenados
• BE-ML-026: Implementar export a CSV

Frontend:

• FE-ML-040: Crear componente MultiSymbolScan.tsx
• FE-ML-041: Crear componente SymbolSelector.tsx
• FE-ML-042: Crear componente ScanFilters.tsx
• FE-ML-043: Crear componente ScanResults.tsx
• FE-ML-044: Crear componente ScanProgress.tsx
• FE-ML-045: Implementar upload de CSV
• FE-ML-046: Implementar tabla con sorting y filtros
• FE-ML-047: Implementar export a CSV
• FE-ML-048: Integración con TanStack Query (react-query)
• FE-ML-049: Real-time progress updates (WebSocket/SSE)

ML Engine:

• ML-020: Optimizar generación de señales para múltiples símbolos
• ML-021: Implementar ejecución paralela de análisis
• ML-022: Cachear indicadores técnicos por símbolo

Tests:

• TEST-ML-020: Test de validación de símbolos
• TEST-ML-021: Test de parseo CSV
• TEST-ML-022: Test de escaneo paralelo (timeout, errores)
• TEST-ML-023: Test de filtrado y ordenamiento
• TEST-ML-024: Test E2E completo del multi-scan

---

Dependencias

Depende de:

• US-ML-002: Ver señal - Estado: Pendiente
• RF-ML-001: Generación de señales ML
• Infrastructure: Worker queue (Bull/RabbitMQ)

Bloquea:

• US-ML-011: Alertas de señales (requiere resultados del scan)
• US-ML-012: Portfolio builder (requiere scan multi-símbolo)

---

Notas Técnicas

Endpoints involucrados:

Método	Endpoint	Descripción
POST	/api/ml/scan	Ejecutar escaneo multi-símbolo
GET	/api/ml/scan/:scanId/progress	Obtener progreso en tiempo real
GET	/api/ml/scan/:scanId/results	Obtener resultados del escaneo
GET	/api/ml/scan/:scanId/export.csv	Exportar resultados a CSV
GET	/api/symbols/popular	Lista de símbolos populares
GET	/api/watchlists/:id/symbols	Símbolos de watchlist

Request esperado:

interface MultiSymbolScanRequest {
  symbols: string[];           // Array de símbolos (ej: ['BTCUSDT', 'ETHUSDT'])
  filters: {
    signal_type?: 'BUY' | 'SELL' | 'HOLD' | 'ALL';
    horizon?: string;
    confidence_min?: number;   // 0-100
    action?: 'BUY' | 'SELL';
  };
  sort_by?: 'confidence' | 'score' | 'symbol';
  sort_order?: 'asc' | 'desc';
}

Response esperado:

interface MultiSymbolScanResponse {
  scan_id: string;
  status: 'completed' | 'in_progress' | 'failed';
  timestamp: string;
  symbols_scanned: number;
  signals_found: number;
  results: SignalResult[];
  summary: {
    total_symbols: number;
    signals_found: number;
    strong_signals: number;      // confidence >= 70%
    weak_signals: number;        // 50% <= confidence < 70%
    avg_confidence: number;
  };
  execution_time_ms: number;
}

interface SignalResult {
  symbol: string;
  action: 'BUY' | 'SELL' | 'HOLD' | null;
  horizon?: string;
  confidence?: number;
  score?: number;
  entry_price?: number;
  status: 'ready' | 'weak' | 'no_signal' | 'error';
  error_message?: string;
}

CSV Upload Parser:

// Soporta formatos:
// 1. Un símbolo por línea (simple)
BTCUSDT
ETHUSDT
BNBUSDT

// 2. CSV con header
Symbol,Exchange,Type
BTCUSDT,BINANCE,SPOT
ETHUSDT,BINANCE,SPOT

Componentes UI:

• MultiSymbolScan: Container principal
• SymbolSelector: Selector de símbolos con pestañas
• SymbolListPicker: Selector desde lista predefinida
• WatchlistPicker: Selector desde watchlist personal
• CSVUploader: Componente de upload de CSV
• ScanFilters: Filtros de escaneo
• ScanResults: Tabla de resultados
• ScanProgress: Modal de progreso en tiempo real
• ResultsActions: Acciones sobre resultados (export, create portfolio)

Estado (Zustand):

interface MultiSymbolScanStore {
  selectedSymbols: string[];
  scanResults: SignalResult[];
  scanProgress: {
    total: number;
    completed: number;
    currentSymbol: string;
  };
  filters: ScanFilters;
  isScanning: boolean;
  sortBy: 'confidence' | 'score' | 'symbol';
  sortOrder: 'asc' | 'desc';

  setSelectedSymbols: (symbols: string[]) => void;
  startScan: () => Promise<void>;
  updateProgress: (progress: ScanProgress) => void;
  updateFilters: (filters: Partial<ScanFilters>) => void;
  setSortBy: (field: string, order: 'asc' | 'desc') => void;
  exportToCSV: () => void;
}

Real-time Progress:

• Usar WebSocket o SSE para enviar actualizaciones de progreso
• Endpoint: /api/ml/scan/:scanId/progress con streaming
• O usar polling cada 500ms si WebSocket no disponible

Performance Targets:

• 50 símbolos scanned: < 10 segundos
• 20 símbolos scanned: < 5 segundos
• 10 símbolos scanned: < 3 segundos

---

Definition of Ready (DoR)

• Historia claramente escrita (quién, qué, por qué)
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Diseño/mockup disponible
• Targets de performance definidos
• Formatos de datos especificados

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
• Escaneo paralelo funciona correctamente
• Real-time progress updates funcionan
• CSV upload y export validan correctamente
• Filtros y ordenamiento funcionan
• Performance meets targets (< 10s para 50 símbolos)
• Manejo de errores robusto (símbolos inválidos, timeouts)
• Responsive en móvil
• Desplegado en producción

---

Historial de Cambios

Fecha	Cambio	Autor
2026-01-25	Creación	Requirements-Analyst

---

Creada por: Requirements-Analyst Fecha: 2026-01-25 Última actualización: 2026-01-25