From f3c4a999c3b4365b8a360df448072708fb289970 Mon Sep 17 00:00:00 2001
From: u1 <u1@rv32i.pl>
Date: Wed, 7 Jan 2026 19:49:59 +0000
Subject: [PATCH] docs: add workflow playbook

---
 doc/workflow.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 doc/workflow.md

diff --git a/doc/workflow.md b/doc/workflow.md
new file mode 100644
index 0000000..7ddae8a
--- /dev/null
+++ b/doc/workflow.md
@@ -0,0 +1,93 @@
+# 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.
+
+## 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.rv32i.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.rv32i.pl`.
+
+- Vite trzyma `VITE_API_URL=/api` (default) i proxy’uje `/api/*` do VPS.
+- 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.rv32i.pl/api \
+API_PROXY_BASIC_AUTH='USER:PASS' \
+npm run dev
+```
+
+Alternatywnie dla basic auth możesz użyć pliku JSON:
+`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.