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

```json
{
  "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`:

```bash
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
```