# 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)