trade-doc/frontent-local-run.md

# Frontend Local Run

Ten dokument opisuje, jak uruchamiać lokalnie `apps/visualizer` i podpiąć go pod backend ze `trade-staging` na `mevnode_bot`.

## Założenia

- pracujesz w repo `/home/user/dev/trade`
- masz dostęp SSH do `user@mevnode_bot`
- chcesz uruchamiać tylko lokalny frontend; backend zostaje na stagingu

## 1. Uruchom tunel SSH

Frontend lokalny używa trzech upstreamów:

- `13081 -> trade-frontend` na `mevnode_bot`
- `18787 -> trade-api` w klastrze `trade-staging`
- `18080 -> hasura` w klastrze `trade-staging`

Najpierw sprawdź aktualny `ClusterIP` dla `trade-api` i `hasura`:

```bash
ssh user@mevnode_bot "kubectl -n trade-staging get svc trade-api hasura -o custom-columns=NAME:.metadata.name,CLUSTER_IP:.spec.clusterIP"
```

Potem uruchom tunel. Wstaw zwrócone adresy zamiast `TRADE_API_CLUSTER_IP` i `HASURA_CLUSTER_IP`:

```bash
ssh -o ExitOnForwardFailure=yes -N \
  -L 13081:127.0.0.1:30081 \
  -L 18787:TRADE_API_CLUSTER_IP:8787 \
  -L 18080:HASURA_CLUSTER_IP:8080 \
  user@mevnode_bot
```

Uwagi:

- `13081` obsługuje `/whoami`, `/auth`, `/logout`
- `18787` obsługuje `/api`
- `18080` obsługuje `/graphql` i `/graphql-ws`
- jeśli tunel padnie, lokalny Vite zacznie zwracać `ECONNREFUSED`
- `18080 -> 127.0.0.1:8080` nie zakładaj w ciemno; Hasura nie musi być wystawiona lokalnie na `mevnode_bot`

## 2. Sprawdź lokalną konfigurację visualizera

`apps/visualizer/.env.local` powinno mieć co najmniej:

```env
VITE_DEV_PORT=5174

VITE_API_URL=/api
VITE_HASURA_URL=/graphql
VITE_HASURA_WS_URL=ws://127.0.0.1:18080/v1/graphql
VITE_GRAPHQL_POLL_MS=1000

VITE_SYMBOL=SOL-PERP
VITE_TF=1s
VITE_POLL_MS=1000
VITE_LIMIT=300

API_PROXY_TARGET=http://127.0.0.1:18787
API_PROXY_STRIP_PREFIX=/api
FRONTEND_PROXY_TARGET=http://127.0.0.1:13081
GRAPHQL_PROXY_TARGET=http://127.0.0.1:18080
GRAPHQL_PROXY_PATH=/v1/graphql
```

Ważne:

- `VITE_HASURA_URL` ma zostać ustawione na `/graphql`
- `VITE_HASURA_WS_URL` ma wskazywać bezpośrednio na tunel Hasury `ws://127.0.0.1:18080/v1/graphql`
- nie ustawiaj `VITE_GRAPHQL_POLL_ONLY=1`, jeśli chcesz live `ws` dla orderbooka i stats
- `npm run visualizer:dev` respektuje lokalne `.env.*` i nie powinno już nadpisywać tego adresem z `tokens/hasura.json`

## 3. Uruchom lokalny Vite

Z roota repo:

```bash
cd /home/user/dev/trade
npm install
npm run visualizer:dev
```

Visualiser wystartuje na:

```text
http://localhost:5174/
```

## 4. Zaloguj się

Po wejściu na `http://localhost:5174/` aplikacja powinna pokazać ekran logowania.

Użyj stagingowych danych sesyjnych. W local dev nie polegamy już na `DEV_PROXY_AUTH_USER`.

## 5. Smoke check

Po zalogowaniu sprawdź:

- górny pasek pokazuje użytkownika i przycisk `Wyloguj`
- orderbook ma rekordy dla `SOL-PERP`
- panel DLOB pokazuje `live`
- chart nie pokazuje `Failed to fetch`

## Szybki troubleshooting

### Sprawdź porty

```bash
ss -ltnp | rg ':(5174|13081|18080|18787)\b'
```

### Sprawdź sesję

```bash
curl -i http://localhost:5174/whoami
```

Po zalogowaniu powinno zwrócić `200` i `{"ok":true,"user":"...","mode":"session"}`.

### Sprawdź chart API

```bash
curl -i 'http://localhost:5174/api/v1/chart?symbol=SOL-PERP&tf=1s&limit=5'
```

Jeśli tu jest `ECONNREFUSED`, problem siedzi w tunelu `18787`.

### Sprawdź GraphQL proxy

```bash
curl -i \
  -H 'content-type: application/json' \
  --data '{"query":"query { dlob_hot_snapshot_latest(limit: 1, where: {market_name: {_eq: \"SOL-PERP\"}}) { market_name } }"}' \
  http://localhost:5174/graphql
```

Jeśli przeglądarka próbuje iść do `localhost:8080` zamiast do `localhost:5174/graphql`, to Vite nie wczytał poprawnego `.env.local`. Zrestartuj `npm run visualizer:dev`.

### Objaw: logowanie działa, ale DLOB / L2 pokazuje `Hasura HTTP 500`

Typowy objaw:

- logowanie przez `/auth/login` przechodzi
- `/whoami` zwraca `200`
- w UI pola `DLOB` i `L2` pokazują `Hasura HTTP 500`
- w logu Vite widać `http proxy error: /v1/graphql` oraz `ECONNRESET` albo `ECONNREFUSED`

Najczęstsza przyczyna:

- tunel `18080` jest skierowany na zły remote target
- nie zakładaj, że `mevnode_bot` ma lokalny nasłuch Hasury na `127.0.0.1:8080`

Sprawdź aktualny adres Hasury:

```bash
ssh user@mevnode_bot "kubectl -n trade-staging get svc hasura -o wide"
```

Jeśli `ClusterIP` Hasury to np. `10.43.174.102`, to tunel powinien wyglądać tak:

```bash
ssh -o ExitOnForwardFailure=yes -N \
  -L 13081:127.0.0.1:30081 \
  -L 18787:TRADE_API_CLUSTER_IP:8787 \
  -L 18080:10.43.174.102:8080 \
  user@mevnode_bot
```

Szybki test po poprawce:

```bash
curl -i \
  -H 'content-type: application/json' \
  --data '{"query":"query { __typename }"}' \
  http://127.0.0.1:18080/v1/graphql
```

To powinno zwrócić `200 OK` i `{"data":{"__typename":"query_root"}}`.

### Objaw: DLOB działa, ale `Last` / `Oracle` albo chart są puste

To nie musi oznaczać problemu z frontendem.

Najpierw sprawdź live DLOB:

```bash
curl -sS \
  -H 'content-type: application/json' \
  --data '{"query":"query($market:String!){ dlob_hot_derived_latest(where:{market_name:{_eq:$market},is_indicative:{_eq:false}},limit:1){ market_name mark_price oracle_price best_bid_price best_ask_price updated_at }}","variables":{"market":"SOL-PERP"}}' \
  http://localhost:5174/graphql
```

Potem sprawdź chart API:

```bash
curl -i 'http://localhost:5174/api/v1/chart?symbol=SOL-PERP&tf=1s&limit=5'
curl -i 'http://localhost:5174/api/v1/ticks?symbol=SOL-PERP&limit=5'
```

Interpretacja:

- jeśli GraphQL zwraca świeże `updated_at`, ale `/api/v1/chart` zwraca `candles: []`, to problem siedzi w stagingowym API albo danych wejściowych do funkcji świec
- jeśli `/api/v1/ticks` zwraca tylko stare rekordy, staging nie ma świeżych ticków dla chart API
- summary w UI może wtedy żyć z fallbacku DLOB, ale sam wykres dalej będzie pusty, dopóki staging nie zacznie zwracać świec