trade-doc/observer-visualizer-v1.md

Observer Visualizer V1

Ten dokument opisuje pierwszy panel UI dla bot-observer w visualizerze.

Cel

Pokazać operatorowi stan observera bez liczenia logiki bota po stronie frontendu.

UI ma:

• czytać gotowy stan z control plane
• pokazywać bieżącą decyzję, gates i feature snapshot
• pokazywać heartbeat, błędy i feed eventów

Źródła danych

Panel czyta przez istniejący trade-api:

• GET /api/v1/bots?limit=100
• GET /api/v1/bots/:id/state
• GET /api/v1/bots/:id/events?limit=100

Frontend nie odpytuje Hasury bezpośrednio dla panelu observera.

Zasada wyboru aktywnego bota

Panel rozwiązuje bota w kolejności:

1. VITE_BOT_ID jeśli ustawione
2. VITE_BOT_NAME jeśli ustawione
3. pierwszy bot, którego market_name === aktualny symbol na wykresie

Jeśli żaden bot nie pasuje, panel pokazuje stan No bot configured.

Schema danych w UI

bot_config

UI używa:

• id
• name
• market_name
• market_type
• mode
• kill_switch
• updated_at

bot_state

UI używa:

• last_heartbeat_at
• last_action_at
• last_error
• updated_at
• state

bot_state.state

Observer zapisuje już gotowy summary payload. UI czyta tylko:

{
  "service": "bot-observer",
  "version": "observer-sol-v1",
  "observe_only": true,
  "market_name": "SOL-PERP",
  "market_type": "perp",
  "mode": "observe",
  "kill_switch": false,
  "status": "observe",
  "strategy_type": "predictive_observer_v1",
  "loop_ms": 1000,
  "last_snapshot": {
    "query_latency_ms": 82,
    "data_age_ms": 214,
    "candles_count": 64,
    "stats_age_ms": 180,
    "depth_age_ms": 210,
    "buy_slippage_age_ms": 205,
    "sell_slippage_age_ms": 208
  },
  "last_features": {
    "mark_price": 182.12,
    "oracle_price": 182.08,
    "mid_price": 182.11,
    "spread_bps": 2.1,
    "stats_imbalance": 0.08,
    "depth_bid_usd": 12400,
    "depth_ask_usd": 9700,
    "depth_imbalance": 0.12,
    "buy_slippage_bps": 4.2,
    "sell_slippage_bps": 4.0,
    "mark_vs_oracle_bps": 0.22,
    "mom_3s": 3.8,
    "mom_10s": 6.1,
    "mom_30s": -12.5,
    "vol_30s": 5.9
  },
  "last_gates": {
    "fresh": true,
    "spread_ok": true,
    "slippage_ok": true,
    "depth_ok": true,
    "has_candles": true,
    "all": true
  },
  "last_decision": {
    "side": "long",
    "confidence": 0.72,
    "long_score": 1.91,
    "short_score": -2.34,
    "target_notional_usd": 500,
    "horizon_s": 60,
    "skip_reason": null
  },
  "counters": {
    "loops": 1012,
    "decisions": 620,
    "skips": 382,
    "errors": 1
  }
}

Sekcje panelu

1. Status

• mode
• kill_switch
• status
• observe_only
• heartbeat age
• last_error

2. Current Decision

• side
• confidence
• target_notional_usd
• horizon_s
• long_score
• short_score
• skip_reason

3. Gates

• fresh
• spread_ok
• slippage_ok
• depth_ok
• has_candles

4. Feature Snapshot

• spread_bps
• mark_vs_oracle_bps
• mom_3s
• mom_10s
• mom_30s
• vol_30s
• depth_bid_usd
• depth_ask_usd
• depth_imbalance
• buy_slippage_bps
• sell_slippage_bps
• data_age_ms
• query_latency_ms

5. Event Feed

Pokazujemy ostatnie eventy:

• decision
• skip
• status
• error

UI nie renderuje pełnego JSON, tylko krótkie summary + timestamp.

Zakres V1

V1 to tylko wizualizacja aktualnego stanu observera.

Poza zakresem:

• edycja bot_config
• ręczne sterowanie mode
• wykres historyczny decyzji na świecach
• live subscriptions

V2 może dodać:

• markery decyzji na wykresie
• odtwarzanie decision history
• mutacje control-plane z UI