docs(snapshot): sync workspace documentation

workflow.md

@@ -0,0 +1,99 @@
+# 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.
+- UI ma też GraphQL (Hasura) pod `/graphql` (HTTP + WS subscriptions) – w dev proxy’ujemy `/graphql` i `/graphql-ws` do VPS, żeby subscriptions działały na `http://localhost:5173`.
+- 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
+bash __start
+```
+
+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.