trade-doc/observer-right-rail-v1.md

Observer Right Rail V1

Ten dokument opisuje kompaktowy widget Bot State Machine w prawej kolumnie visualizera.

Cel

Prawy panel ma pokazywać operatorowi stale widoczny summary stanu bota bez przełączania na dolny tab Bot.

Widget nie zastępuje pełnego panelu debugowego na dole.

Podział odpowiedzialności:

• prawa kolumna: aktualny stan operacyjny bota
• dolny tab Bot: szczegóły, event feed, feature snapshot, debug

Źródło danych

Widget używa dokładnie tego samego payloadu co dolny panel:

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

Nie wprowadza nowych endpointów.

Schema summary

Widget czyta tylko podzbiór istniejącego kontraktu bot_state.state.

bot_config

• id
• name
• market_name
• mode
• kill_switch

bot_state

• last_heartbeat_at
• last_error
• state

bot_state.state

Pola używane w prawym panelu:

{
  "status": "observe",
  "mode": "observe",
  "observe_only": true,
  "last_snapshot": {
    "query_latency_ms": 82,
    "data_age_ms": 214
  },
  "last_gates": {
    "fresh": true,
    "spread_ok": true,
    "slippage_ok": true,
    "depth_ok": true,
    "all": true
  },
  "last_decision": {
    "side": "long",
    "confidence": 0.72,
    "target_notional_usd": 500,
    "skip_reason": null
  },
  "counters": {
    "loops": 1012,
    "errors": 1
  }
}

Sekcje widgetu

1. State Machine

Stała linia etapów:

• off
• observe
• paper
• trade
• panic

Aktywny etap wybieramy z:

1. state.status
2. state.mode
3. bot.mode

Jeśli kill_switch === true, etap panic ma priorytet wizualny.

2. Runtime Summary

• desired mode
• runtime status
• heartbeat age
• data age
• query latency

3. Decision Summary

• side
• confidence
• target_notional_usd
• skip_reason jeśli istnieje

4. Gates

Kompaktowe chipy:

• fresh
• spread
• slippage
• depth

Zakres V1

V1 dodaje tylko read-only summary do prawej kolumny.

Poza zakresem:

• mutacje mode
• kill-switch z UI
• event feed po prawej
• pełna historia decyzji po prawej