docs(snapshot): sync workspace documentation

2026-03-29 13:14:30 +02:00
parent 93a6e4aa2f
commit 0d3d110026
37 changed files with 8500 additions and 123 deletions
--- a/momentum-service-v1.md
+++ b/momentum-service-v1.md
@@ -0,0 +1,156 @@
+# Momentum Service V1
+
+Ten dokument definiuje pierwszy osobny mikroserwis dla bloku `Momentum` z
+[bot1.tex](/home/user/dev/trade/doc/bot/bot1.tex).
+
+## Cel
+
+`momentum-service` liczy tylko skladniki momentum i zmiennosci z candles.
+
+Zakres v1:
+- `mom_3s`
+- `mom_10s`
+- `mom_30s`
+- `vol_30s`
+
+Poza zakresem v1:
+- spread
+- depth
+- slippage
+- gating
+- scoring
+- zapis decyzji tradingowej
+
+## Zasady
+
+- `Hasura` jest jedynym source of truth dla danych wejsciowych.
+- `Fastify` jest shell-em mikroserwisu i wystawia wynik przez endpointy.
+- Serwis nie utrzymuje osobnego trwalego stanu prawdy.
+- W v1 wynik jest wystawiany przez HTTP i trzymany tylko jako latest runtime snapshot.
+
+## Dlaczego to jest osobny serwis
+
+`momentum-service` jest dobrym deployment boundary, bo caly jego processing zalezy tylko
+od candles i nie potrzebuje danych DLOB.
+
+To znaczy:
+- `momentum` i `volatility` sa razem w jednym serwisie
+- poszczegolne horyzonty `mom_3s`, `mom_10s`, `mom_30s` nie sa osobnymi procesami
+- granica serwisu jest wyznaczona przez wspolne wejscie i wspolny wynik runtime, a nie przez pojedynczy wzor
+
+## Wejscie
+
+Serwis czyta z Hasury:
+- `bot_config` po `BOT_ID` albo `BOT_NAME`
+- `get_drift_candles(...)`
+
+Minimalne dane z `bot_config`:
+
+```json
+{
+  "market_name": "SOL-PERP",
+  "params": {
+    "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
+    }
+  }
+}
+```
+
+## Processing
+
+Model liczenia odpowiada definicjom z `bot1.tex`:
+
+```text
+mom_k(t) = 10^4 * (c_t / c_{t-k} - 1)
+```
+
+oraz:
+
+```text
+vol_W = stddev(r_i), gdzie r_i = 10^4 * (c_i / c_{i-1} - 1)
+```
+
+Serwis nie uzywa orderbooka ani tabel derived DLOB.
+
+## Wyjscie
+
+V1 wystawia wynik przez:
+- `GET /healthz`
+- `GET /readyz`
+- `GET /status`
+- `GET /result/latest`
+- `POST /run`
+
+Przykladowy wynik `GET /result/latest`:
+
+```json
+{
+  "ok": true,
+  "service": "momentum-service",
+  "version": "momentum-service-v1",
+  "bot": {
+    "id": "uuid",
+    "name": "sol-observer"
+  },
+  "market": {
+    "name": "SOL-PERP",
+    "candle_bucket_seconds": 1,
+    "candles_limit": 64
+  },
+  "features": {
+    "mom_3s": 3.8,
+    "mom_10s": 6.1,
+    "mom_30s": -12.5,
+    "vol_30s": 4.2
+  },
+  "snapshot": {
+    "latest_candle_at": "2026-03-27T22:44:10.000Z",
+    "candles_count": 64,
+    "query_latency_ms": 41,
+    "compute_latency_ms": 1
+  }
+}
+```
+
+## Runtime
+
+Petla v1:
+- laduje `bot_config`
+- pobiera candles
+- liczy momentum i volatility
+- odswieza `latest result`
+
+Domyslnie:
+- loop `1000 ms`
+- candles `1s`
+- `64` swiece
+
+## Bledy
+
+Serwis zwraca:
+- `503` na `/readyz`, gdy nie ma swiezego poprawnego wyniku
+- `404` na nieznane endpointy
+- `500` na `POST /run`, jesli tick zakonczyl sie bledem
+
+Blad Hasury nie zatrzymuje procesu na stale. Serwis pozostaje online, ale `ready`
+przechodzi na `false`, dopoki kolejny poprawny tick nie odswiezy wyniku.
+
+## Relacja do innych serwisow
+
+`momentum-service` jest kandydatem na osobny building block dla:
+- `observer-service`
+- `scoring-service`
+- downstream debug UI
+
+W kolejnych wersjach wynik moze byc:
+- nadal tylko czytany przez HTTP,
+- albo dodatkowo zapisywany do osobnej tabeli w Hasurze.