# Workflow pracy w projekcie `trade` (dev → staging na VPS) + snapshot/rollback

Ten plik jest “source of truth” dla sposobu pracy nad zmianami w `trade`.  
Cel: **zero ręcznych zmian na VPS**, każdy deploy jest **snapshoot’em**, do którego można wrócić.

## Dla agenta / po restarcie sesji

1) Przeczytaj ten plik: `doc/workflow.md`.  
2) Kontekst funkcjonalny: `README.md`, `info.md`.  
3) Kontekst stacka: `doc/workflow-api-ingest.md` oraz `devops/*/README.md`.  
4) Stan VPS/k3s + GitOps: `doc/migration.md` i log zmian: `doc/steps.md`.

## Zasady (must-have)

- **Nie edytujemy “na żywo” VPS** (żadnych ręcznych poprawek w kontenerach/plikach na serwerze) → tylko Git + CI + Argo.
- **Sekrety nie trafiają do gita**: `tokens/*.json` są gitignored; w dokumentacji/logach redagujemy hasła/tokeny.
- **Brak `latest`**: obrazy w deployu są przypięte do `sha-<shortsha>` albo digesta.
- **Każda zmiana = snapshot**: “wersja” to commit w repo deploy + przypięte obrazy.

## Domyślne środowisko pracy (ważne)

- **Frontend**: domyślnie pracujemy lokalnie (Vite) i łączymy się z backendem na VPS (staging) przez proxy. Deploy frontendu na VPS robimy tylko jeśli jest to wyraźnie powiedziane (“wdrażam na VPS”).
- **Backend (trade-api + ingestor)**: zmiany backendu weryfikujemy/wdrażamy na VPS (staging), bo tam działa ingestor i tam są dane. Nie traktujemy lokalnego uruchomienia backendu jako domyślnego (tylko na wyraźną prośbę do debugowania).

## Standardowy flow zmian (polecany)

1) Zmiana w kodzie lokalnie.
   - Nie musisz odpalać lokalnego Dockera; na start rób szybkie walidacje (build/typecheck).
2) Commit + push (najlepiej przez PR).
3) CI:
   - build → push obrazów (tag `sha-*` lub digest),
   - aktualizacja `trade-deploy` (bump obrazu/rewizji).
4) Argo CD (auto-sync na staging) wdraża nowy snapshot w `trade-staging`.
5) Test na VPS:
   - API: `/healthz`, `/v1/ticks`, `/v1/chart`
   - UI: `trade.mpabi.pl`
   - Ingest: logi `trade-ingestor` + napływ ticków do tabeli.

## Snapshoty i rollback (playbook)

### Rollback szybki (preferowany)

- Cofnij snapshot w repo deploy:
  - `git revert` commita, który podbił obrazy, **albo**
  - w Argo cofnij do poprzedniej rewizji (ten sam efekt).

Efekt: Argo wraca do poprzedniego “dobrego” zestawu obrazów i konfiguracji.

### Rollback bezpieczny dla “dużych” zmian (schema/ingest)

Jeśli zmiana dotyka danych/ingestu, rób ją jako nową wersję vN:
- nowa tabela: `drift_ticks_vN`
- nowa funkcja: `get_drift_candles_vN`
- osobny deploy API/UI (inne porty/sufiksy), a ingest przełączany “cutover”.

W razie problemów: robisz “cut back” vN → v1 (stare dane zostają nietknięte).

## Lokalne uruchomienie (opcjonalne, do debugowania)

Dokładna instrukcja: `doc/workflow-api-ingest.md`.

Skrót:
```bash
npm install
docker compose -f devops/db/docker-compose.yml up -d
docker compose -f devops/tools/bootstrap/docker-compose.yml run --rm db-init
docker compose -f devops/tools/bootstrap/docker-compose.yml run --rm hasura-bootstrap
docker compose -f devops/app/docker-compose.yml up -d --build api
npm run token:api -- --scopes write --out tokens/alg.json
npm run token:api -- --scopes read --out tokens/read.json
docker compose -f devops/app/docker-compose.yml up -d --build frontend
docker compose -f devops/app/docker-compose.yml --profile ingest up -d --build
```

### Frontend dev (Vite) z backendem na VPS (staging)

Jeśli chcesz szybko iterować nad UI bez deploya, możesz odpalić lokalny Vite i podpiąć go do backendu na VPS przez istniejący proxy `/api` na `trade.mpabi.pl`.

- Vite trzyma `VITE_API_URL=/api` (default) i proxy’uje `/api/*` do VPS.
- Auth w staging jest w trybie `session` (`/auth/login`, cookie `trade_session`), więc w dev proxy’ujemy też `/whoami`, `/auth/*`, `/logout`.
- Dev proxy usuwa `Secure` z `Set-Cookie`, żeby cookie działało na `http://localhost:5173`.
- Na VPS `trade-frontend` proxy’uje dalej do `trade-api` i wstrzykuje read-token **server-side** (token nie trafia do przeglądarki).

Przykład:

```bash
cd apps/visualizer
API_PROXY_TARGET=https://trade.mpabi.pl \
npm run dev
```

Jeśli staging ma dodatkowy basic auth (np. Traefik `basicAuth`), dodaj:
`API_PROXY_BASIC_AUTH='USER:PASS'` albo `API_PROXY_BASIC_AUTH_FILE=tokens/frontend.json` (pola `username`/`password`).

## Definicja “done” dla zmiany

- Jest snapshot (commit w deploy) i można wrócić jednym ruchem.
- Staging działa (API/ingest/UI) i ma podstawowe smoke-checki.
- Sekrety nie zostały dodane do repo ani do logów/komentarzy.