567 lines
12 KiB
Markdown
567 lines
12 KiB
Markdown
# 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)
|