trade-doc/bot-control-plane-staging-v1.md

Bot Control Plane Staging V1

Ten dokument opisuje minimalny deploy path potrzebny, żeby SOL-PERP observer był widoczny w stagingowym UI i w trade-api.

Cel

Zapewnić, że środowisko trade-staging ma:

• fizyczne tabele bot_config, bot_state, bot_events w Postgresie
• tracking tych tabel w Hasurze
• możliwość odczytu przez trade-api

Bez tego frontend może tylko pokazać fallback:

• Bot control plane is not deployed here

Zakres V1

V1 nie wdraża jeszcze seedów ani samego procesu observera.

V1 obejmuje tylko:

• schema SQL
• metadata Hasury
• gotowość trade-api do odczytu control-plane

Obiekty bazy

Wymagane są trzy tabele:

bot_config

Desired state bota:

• name
• market_name
• market_type
• mode
• kill_switch
• params

bot_state

Heartbeat i ostatni stan runtime:

• last_heartbeat_at
• last_action_at
• last_error
• state
• updated_at

bot_events

Append-only audit log:

• ts
• type
• payload

Hasura

Hasura musi trackować:

• public.bot_config
• public.bot_state
• public.bot_events

W V1 nie wymagamy publicznych permissionów do bezpośredniego odczytu z frontendu, bo panel bota czyta przez trade-api.

Integracja z trade-api

trade-api czyta te tabele przez admin secret Hasury i wystawia:

• GET /v1/bots
• GET /v1/bots/:id
• GET /v1/bots/:id/state
• GET /v1/bots/:id/events

Kryterium done

Po wdrożeniu staging powinien spełniać:

1. Hasura zna bot_config, bot_state, bot_events.
2. trade-api /v1/bots zwraca 200 bez fallbacku bot_control_plane_schema_missing.
3. Frontend nie pokazuje już komunikatu o braku control-plane z powodu schema gap.

Następny krok po V1

Po tej zmianie można dopiero sensownie zrobić:

1. seed bot_config dla SOL-PERP observer
2. uruchomienie bot-observer
3. podgląd realnego stanu w UI

Seed SOL-PERP observer

Minimalny seed dla pierwszego observera:

{
  "name": "sol-observer",
  "market_name": "SOL-PERP",
  "market_type": "perp",
  "mode": "observe",
  "kill_switch": false,
  "params": {
    "strategy": {
      "type": "predictive_observer_v1"
    },
    "loop": {
      "decision_interval_ms": 1000,
      "candle_bucket_seconds": 1,
      "candles_limit": 64
    },
    "features": {
      "mom_fast_s": 3,
      "mom_mid_s": 10,
      "mom_slow_s": 30,
      "vol_window_s": 30,
      "depth_band_bps": 10,
      "slippage_size_usd": 500
    },
    "gates": {
      "freshness_max_ms": 800,
      "spread_max_bps": 8,
      "slippage_max_bps": 12,
      "depth_band_min_usd": 3000
    },
    "sizing": {
      "target_notional_usd": 500
    },
    "decision": {
      "threshold": 1.2,
      "horizon_s": 60
    },
    "scoring": {
      "weights": {
        "mom_fast": 0.9,
        "mom_mid": 0.35,
        "mom_slow_reversal": 0.55,
        "imbalance": 5.0,
        "mark_vs_oracle": 0.08,
        "spread": 0.15,
        "slippage": 0.12
      }
    }
  }
}

Po wdrożeniu schema + metadata seed można wstawić przez trade-api:

curl -sS \
  -H 'content-type: application/json' \
  -H 'x-admin-secret: YOUR_API_ADMIN_SECRET' \
  --data @seed-sol-observer.json \
  http://localhost:8787/v1/bots