feat(calibration): complete step 1 data inspection with data quality v1

DesignUI.md

@@ -0,0 +1,566 @@
+# UI Plan — Trading Mode + Calibrate Mode (FastAPI + SQLite + Chart.js + Tabler)
+
+## Objetivo
+Construir una UI web para el bot con dos modos:
+
+1) **Trading Mode** (read-only):
+- Visualizar estado del bot en tiempo real.
+- Inspeccionar posiciones abiertas/cerradas, trades, performance, eventos/logs.
+- Navegación por pestañas (tabs) y filtros por rango temporal.
+
+2) **Paper Mode** (read-only)
+- Supervisión de simulación en tiempo real.
+- Similar, por no decir igual, que Trading Mode.
+
+2) **Calibrate Mode** (workflow guiado):
+- Ejecutar un pipeline de calibración por pasos (tipo wizard por tabs).
+- En cada paso:
+  - Ejecutar scripts/experimentos (controlados).
+  - Mostrar outputs (tablas/estadísticas).
+  - Mostrar gráficas (Chart.js o imágenes generadas).
+  - Guardar artefactos (parámetros, resultados, reportes) para construir un “portfolio de estrategias” por símbolo.
+
+---
+
+## UX / Navegación global
+
+### Selector de modo (Dropdown)
+En la barra superior (navbar):
+- Dropdown: **Mode**
+  - Trading
+  - Paper
+  - Calibrate
+
+Regla:
+- El modo activo define completamente la UI.
+- Cada modo tiene su propio set de tabs.
+- Persistir el modo seleccionado en `localStorage`.
+- URLs separadas:
+  - `/ui/trading/...`
+  - `/ui/paper/...`
+  - `/ui/calibrate/...`
+
+---
+
+## Trading Mode (Live)
+
+### Propósito
+Supervisar **trading real** con foco en:
+- estabilidad
+- riesgo
+- latencia
+- seguridad
+
+Este modo debe ser **sobrio y conservador**.
+
+---
+
+### Tabs - Trading Mode
+
+#### Tab 1 — Overview
+
+**Propósito**
+> “¿Qué está haciendo el bot ahora y cómo va?”
+
+> ¿El bot está operando correctamente ahora mismo?
+
+**Componentes**
+- KPIs:
+  - Equity actual
+  - Realized PnL
+  - Max DD (según rango)
+  - Estado del bot (RUNNING/PAUSED/ERROR)
+  - Latencia
+    - exchange latency
+    - data latency
+    - execution latency (si existe)
+  - Last heartbeat / last update timestamp
+- Gráfica:
+  - Equity + Cash
+  - DD shading toggle
+  - Rango: 1h / 6h / 24h / ALL
+  - Zoom/pan + reset
+  - Markers BUY/SELL con tooltips ricos
+- Alerts:
+  - Redis down
+  - Latency > threshold
+  - Exchange unreachable
+  - No new data the last X minutes
+  - Errors
+
+**Endpoints recomendados**
+- `GET /api/v1/bot/status`
+- `GET /api/v1/equity/state`
+- `GET /api/v1/equity/curve?range=1h|6h|24h|all`
+- `GET /api/v1/trades?limit=...`
+- `GET /api/v1/events?limit=...`
+
+---
+
+#### Tab 2 — Positions
+
+**Propósito**:
+> “¿Qué tengo abierto y qué se cerró?”
+
+**Sub-tabs internos**
+- Open Positions
+- Closed Positions
+
+**Open Positions (tabla)**
+- Symbol
+- Side
+- Entry price
+- Qty / Notional
+- Unrealized PnL (si aplica)
+- Strategy (desde meta)
+- Stop/TP (si existen)
+- Duration
+
+**Closed Positions (tabla)**
+- Symbol
+- Side
+- Entry / Exit
+- Realized PnL
+- Fees
+- Strategy
+- Duration
+- Exit reason (si existe)
+
+**Datos**
+- Ideal: consumir `broker_snapshot` (fuente de verdad).
+- Alternativa: derivar positions desde trades (más costoso/menos fiable).
+
+**Endpoints recomendados**
+- `GET /api/v1/broker/snapshot/latest`
+- `GET /api/v1/broker/snapshot?range=...` (opcional)
+- Si no existe: crear `GET /api/v1/positions/open` y `GET /api/v1/positions/closed`
+
+---
+
+#### Tab 3 — Trades
+**Propósito**
+> Inspección granular de ejecución.
+
+**Tabla con:**
+- timestamp
+- symbol
+- side
+- price
+- qty
+- fee
+- notional
+- realized_pnl
+- strategy (meta.strategy)
+**Filtros**
+- range
+- symbol
+- strategy
+
+**Endpoints recomendados**
+- `GET /api/v1/trades?range=...&symbol=...&strategy=...&limit=...` (recomendado)
+(ahora existe `limit`, se puede extender).
+
+---
+
+#### Tab 4 — Performance / Risk
+**Propósito**
+> visión de métricas agregadas (sin ensuciar la gráfica principal).
+
+**Bloques**
+- KPIs:
+  - Max DD (histórico / por rango)
+  - Return %
+  - Win rate
+  - Avg trade
+  - Expectancy
+  - Exposure actual (si aplica)
+- Gráficas opcionales:
+  - Drawdown % curve
+  - Rolling returns
+  - Distribución retornos (normalizada)
+
+**Endpoints recomendados**
+- `GET /api/v1/performance/summary?range=...`
+- o calculado frontend si el dataset no es enorme.
+
+---
+
+#### Tab 5 — Events / Logs
+**Propósito**
+> debug operativo.
+
+- Stream/poll de eventos con niveles (INFO/WARN/ERROR).
+- Búsqueda (texto).
+- “Copy” rápido.
+
+**Endpoints recomendados**
+- `GET /api/v1/events?limit=...`
+- `GET /api/v1/events?range=...&level=...&q=...` (recomendado)
+
+---
+
+## Paper Mode (SIMULATION)
+
+### Propósito
+
+Completar este apartado por la IA
+
+---
+
+### Tabs - Paper Mode
+
+#### Tab 1 — Overview
+
+**Propósito**
+> “¿Qué está haciendo el bot ahora y cómo va?”
+
+> ¿El bot está operando correctamente ahora mismo?
+
+**Componentes**
+- KPIs:
+  - Equity actual
+  - Realized PnL
+  - Max DD (según rango)
+  - Estado del bot (RUNNING/PAUSED/ERROR)
+  - Latencia
+    - exchange latency
+    - data latency
+    - execution latency (si existe)
+- Gráfica:
+  - Equity + Cash
+  - DD shading toggle
+  - Rango: 1h / 6h / 24h / ALL
+  - Zoom/pan + reset
+  - Markers BUY/SELL con tooltips ricos
+- Alerts:
+  - Redis down
+  - Latency > threshold
+  - Exchange unreachable
+  - No new data the last X minutes
+  - Errors
+
+**Endpoints recomendados**
+- `GET /api/v1/bot/status`
+- `GET /api/v1/equity/state`
+- `GET /api/v1/equity/curve?range=1h|6h|24h|all`
+- `GET /api/v1/trades?limit=...`
+- `GET /api/v1/events?limit=...`
+
+#### Tab 2 — Positions
+
+**Propósito**:
+> “¿Qué tengo abierto y qué se cerró?”
+
+**Sub-tabs internos**
+- Open Positions
+- Closed Positions
+
+**Open Positions (tabla)**
+- Symbol
+- Side
+- Entry price
+- Qty / Notional
+- Unrealized PnL (si aplica)
+- Strategy (desde meta)
+- Stop/TP (si existen)
+- Duration
+
+**Closed Positions (tabla)**
+- Symbol
+- Side
+- Entry / Exit
+- Realized PnL
+- Fees
+- Strategy
+- Duration
+- Exit reason (si existe)
+
+**Datos**
+- Ideal: consumir `broker_snapshot` (fuente de verdad).
+- Alternativa: derivar positions desde trades (más costoso/menos fiable).
+
+**Endpoints recomendados**
+- `GET /api/v1/broker/snapshot/latest`
+- `GET /api/v1/broker/snapshot?range=...` (opcional)
+- Si no existe: crear `GET /api/v1/positions/open` y `GET /api/v1/positions/closed`
+
+#### Tab 3 — Trades
+
+**Propósito**
+> Inspección granular de ejecución.
+
+**Tabla con:**
+- timestamp
+- symbol
+- side
+- price
+- qty
+- fee
+- notional
+- realized_pnl
+- strategy (meta.strategy)
+**Filtros**
+- range
+- symbol
+- strategy
+
+**Endpoints recomendados**
+- `GET /api/v1/trades?range=...&symbol=...&strategy=...&limit=...` (recomendado)
+(ahora existe `limit`, se puede extender).
+
+---
+
+#### Tab 4 — Performance / Risk
+
+**Propósito**
+> visión de métricas agregadas (sin ensuciar la gráfica principal).
+
+**Bloques**
+- KPIs:
+  - Max DD (histórico / por rango)
+  - Return %
+  - Win rate
+  - Avg trade
+  - Expectancy
+  - Exposure actual (si aplica)
+- Gráficas opcionales:
+  - Drawdown % curve
+  - Rolling returns
+  - Distribución retornos (normalizada)
+
+**Endpoints recomendados**
+- `GET /api/v1/performance/summary?range=...`
+- o calculado frontend si el dataset no es enorme.
+
+---
+
+#### Tab 5 — Events / Logs
+
+**Propósito**
+> debug operativo.
+
+- Stream/poll de eventos con niveles (INFO/WARN/ERROR).
+- Búsqueda (texto).
+- “Copy” rápido.
+
+**Endpoints recomendados**
+- `GET /api/v1/events?limit=...`
+- `GET /api/v1/events?range=...&level=...&q=...` (recomendado)
+
+---
+
+## Calibrate Mode (Workflow Tabs)
+
+### Filosofía
+Calibrar es un pipeline con pasos que producen:
+- Artefactos (parámetros, configs, datasets)
+- Resultados (tablas, métricas)
+- Gráficas / reportes
+
+Requisitos:
+- Cada paso debe ser **repetible**.
+- Guardar “run id” de calibración para reproducibilidad.
+- No mezclar runs.
+
+### Estructura de tabs (propuesta)
+1) **Select Asset**
+2) **Download / Prepare Data**
+3) **Market Regimes / Filters** (opcional)
+4) **Stops / Risk Model**
+5) **Strategy Selection**
+6) **Parameter Search / Optimization**
+7) **Walk-Forward Validation**
+8) **Portfolio Builder**
+9) **Export / Deploy**
+
+---
+
+### Step 1 — Select Asset
+Inputs:
+- symbol (BTC/USDT)
+- timeframe (1m/5m/1h)
+- date range (start/end)
+Output:
+- “Calibration session created” + session_id
+
+Endpoint:
+- `POST /api/v1/calibrate/session`
+- `GET /api/v1/calibrate/session/{id}`
+
+Persistencia recomendada:
+- tabla `calibration_sessions` en SQLite
+
+---
+
+### Step 2 — Download / Prepare Data
+Acciones:
+- descargar OHLCV
+- normalizar huecos
+- guardar dataset versionado
+
+Outputs:
+- tabla: coverage, missing bars, rango real
+- gráfico: velas + volumen (opcional)
+- log de ejecución
+
+Endpoints:
+- `POST /api/v1/calibrate/{id}/data/download`
+- `GET /api/v1/calibrate/{id}/data/status`
+- `GET /api/v1/calibrate/{id}/artifacts`
+
+---
+
+### Step 3 — Market Regimes / Filters (opcional)
+Acciones:
+- definir filtros (trend filter, volatility filter, etc.)
+Outputs:
+- gráficos de régimen
+- % tiempo en cada régimen
+
+---
+
+### Step 4 — Stops / Risk Model
+Acciones:
+- seleccionar modelo de stop (ATR, trailing, fixed %)
+- seleccionar sizing (percent risk, fixed notional)
+Outputs:
+- gráficos: ejemplo de stop sobre precio
+- tabla: distribución de distancias de stop, riesgo medio
+
+---
+
+### Step 5 — Strategy Selection
+Acciones:
+- elegir set de estrategias candidatas
+- activar/desactivar
+Outputs:
+- tabla: lista estrategias + descripción + inputs
+
+---
+
+### Step 6 — Parameter Search / Optimization
+Acciones:
+- grid search / random / bayesian (si existe)
+- constraints (drawdown max, trades min)
+Outputs:
+- tabla top N configs
+- gráfico: Pareto (return vs dd) (opcional)
+- export: “best params per strategy”
+
+---
+
+### Step 7 — Walk-Forward Validation
+Acciones:
+- definir train/test windows
+- ejecutar WF por estrategia/config
+Outputs:
+- gráficos:
+  - equity acumulada WF
+  - equity por ventana
+  - distribución de retornos por ventana (normalizada)
+- tabla resumen WF
+
+---
+
+### Step 8 — Portfolio Builder
+Acciones:
+- seleccionar estrategias finalistas
+- asignar pesos/capital
+- reglas de conflicto (solo una posición por símbolo, etc.)
+Outputs:
+- equity combinada
+- correlaciones (opcional)
+- métricas agregadas
+
+---
+
+### Step 9 — Export / Deploy
+Acciones:
+- exportar configuración lista para paper/live
+- snapshot de parámetros, versiones y artefactos
+Outputs:
+- `portfolio_config.json`
+- `strategies_config.yaml`
+- reporte final (md/pdf opcional)
+
+---
+
+## Diseño técnico (Backend)
+
+### Principio clave: “Calibrate Mode ejecuta jobs”
+No ejecutar procesos largos dentro del request normal.
+
+Recomendación:
+- jobs async (thread/process) o cola simple.
+- endpoints:
+  - `POST /calibrate/{id}/run/{step}`
+  - `GET /calibrate/{id}/run/{run_id}/status`
+  - `GET /calibrate/{id}/run/{run_id}/logs`
+  - `GET /calibrate/{id}/run/{run_id}/results`
+
+Persistencia mínima:
+- `calibration_sessions`
+- `calibration_runs`
+- `calibration_artifacts`
+
+Artifact storage:
+- carpeta `data/calibration/{session_id}/{run_id}/...`
+- SQLite guarda metadata + paths
+
+Seguridad:
+- whitelist de scripts/steps ejecutables
+- validar inputs (symbol/timeframe/fechas)
+- límites de recursos (duración/memoria si aplica)
+
+---
+
+## Diseño técnico (Frontend)
+
+### Layout base
+- Navbar: Mode dropdown
+- Sidebar/Tabs: tabs del modo activo
+- Área principal: cards + tablas + charts
+
+### Patrón de datos
+- Trading Mode: polling (ya lo tienes)
+- Calibrate Mode: jobs + polling de status/logs
+
+### Componentes UI reutilizables
+- `KpiCard`
+- `DataTable` con filtros
+- `ChartPanel` (line/candles si introduces)
+- `LogViewer` (scroll + autoscroll + copy)
+- `ArtifactList` (descargas + previews)
+
+---
+
+## Plan de implementación (iterativo)
+
+### Fase 1 — Trading UI “completa”
+1. Tabs Trading (Overview / Positions / Trades / Performance / Events)
+2. Endpoints mínimos para Positions
+3. Filtros y rangos coherentes en todos
+
+### Fase 2 — Calibrate UI “skeleton”
+1. Session + wizard tabs
+2. Step 1 y 2 funcionando (Select asset + Download data)
+3. Artefactos + logs visibles
+
+### Fase 3 — Calibrate “core”
+1. Stops + Strategies + Params
+2. Walk-forward
+3. Portfolio builder
+
+### Fase 4 — Export + versioning
+1. Export configs
+2. Reportes
+3. Reproducibilidad total
+
+---
+
+## Decisiones pendientes (para cerrar antes de programar)
+- Fuente de verdad de posiciones: broker_snapshot vs derivación desde trades
+- Qué motor de jobs usar (simple threads vs celery/redis)
+- Formato de artefactos (json/csv/parquet)
+- Modelo de “portfolio” (capital fijo, pesos, conflictos)
+- Cómo versionar datasets y parámetros (hash + metadata)