Files
sorsfonalak/services/backend/README.md
T
fecoandClaude Opus 5.5 812b2d4f73 Write text analyses with OpenRouter in the worker
- analysis job: claims pending analyses (SKIP LOCKED, NOTIFY wake-up),
  builds a compact chart text without birth data, asks OpenRouter with a
  strict JSON schema, validates and stores the answer, model used, tokens
  and cost; retries transient errors, refunds credits on final failure,
  requeues interrupted jobs
- prompt v1 for natal and synastry analyses, Hungarian style guide
- compare-models subcommand for blind model comparison
- migration 0003: attempts, next_attempt_at, model_used, cost_usd,
  notify trigger, one refund per analysis
- db: rebuild when migrations change
- compose: worker reads OPENROUTER_API_KEY from .env.secrets

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
2026-11-15 12:18:40 +00:00

110 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# backend
Felhasználók, belépés, mentett születési képletek, szinasztriák és meghívók, szöveges elemzések, kreditek és nyilvános megosztás. A képleteket a `horoscope-api` számolja, az adatok PostgreSQL-ben vannak. A migrációk a `crates/db/migrations` mappában vannak, és induláskor lefutnak.
## Konfiguráció (környezeti változók)
| Változó | Alapérték | Jelentés |
|---|---|---|
| `DATABASE_URL` | – (kötelező) | PostgreSQL kapcsolat |
| `HOROSCOPE_API_URL` | `http://localhost:8080` | a számító szolgáltatás |
| `PUBLIC_BASE_URL` | `http://localhost:3000` | a frontend címe; erre mutatnak a meghívó-, e-mail- és megosztási linkek |
| `CORS_ALLOWED_ORIGINS` | `PUBLIC_BASE_URL` | vesszővel elválasztott origin-lista; csak ezekről küld a böngésző sütit |
| `COOKIE_SECURE` | `true` | csak helyi, sima HTTP-s fejlesztéshez legyen `false` |
| `COOKIE_DOMAIN` | – | pl. `.sorsfonalak.hu`, ha a frontend és az API más aldomainen fut |
| `SESSION_TTL_DAYS` | `30` | a munkamenet élettartama |
| `GOOGLE_CLIENT_IDS` | – | Google OAuth kliens-azonosító(k); üresen a Google-belépés ki van kapcsolva |
| `BOOTSTRAP_ADMIN_EMAILS` | – | ezek a címek regisztrációkor vagy belépéskor admin szerepet kapnak (így lesz meg az első admin) |
| `SUPPORTED_LOCALES` | `hu,en` | felület- és elemzésnyelvek; az első az alapértelmezett |
| `MONTHLY_FREE_CREDITS` | `10` | havi ingyenes kreditkeret |
| `ANALYSIS_COST` | `1` | egy új elemzés ára kreditben |
| `LLM_MODELS` | `openrouter/auto` | választható OpenRouter-modellek; az első az alapértelmezett |
| `ANALYSIS_PROMPT_VERSION` | `v1` | a prompt verziója (az elemzés-gyorsítótár kulcsának része) |
| `MAX_CHARTS_PER_USER` | `50` | ennyi képletet menthet egy felhasználó |
| `BIND_ADDR`, `LOG_FORMAT`, `RUST_LOG` | `0.0.0.0:8081`, `text`, `info` | |
## Belépés és jogosultság
- **Munkamenet:** véletlen token, HttpOnly + SameSite=Lax sütiben (`sf_session`). A belépési válasz törzsében is ott van, hogy nem böngészős kliens `Authorization: Bearer <token>` fejléccel küldhesse vissza. Az adatbázis csak a token SHA-256 hash-ét tárolja, így a munkamenet visszavonható (kijelentkezés, jelszócsere, fióktörlés).
- **E-mail + jelszó:**
- a jelszó legalább 10 karakter, Argon2id hash-sel tárolva;
- címenként 15 percen belül 10 hibás próbálkozás után átmenetileg tiltás jár;
- ismeretlen címnél is ugyanannyi ideig tart a válasz.
- **Google:** a frontend a Google Identity Services gombbal vagy a One Tap felülettel szerez ID tokent, és elküldi a `POST /v1/auth/google` végpontra. A backend Google kulcsaival ellenőrzi az aláírást, a kiállítót és a kliens-azonosítót.
- Ismeretlen Google-fióknál, ha a Google által igazolt e-mail-címmel már van felhasználó, ahhoz kapcsolja; ha nincs, újat hoz létre.
- Ugyanaz a felhasználó több belépési móddal is rendelkezhet (`auth_identities`). A Facebook, az Apple és a passkey ugyanígy adható hozzá.
- **Szerepek** (`users.roles`, tömb): `user` (alap), `creator` (cikkírás, 2. fázis), `admin`.
- **Guardok:**
- `AuthUser`: belépés kell (401);
- `AdminUser`: admin szerep is kell (403).
- Más felhasználó erőforrására 404 a válasz, így a létezése sem derül ki.
- Minden `/v1/public/...` végpont nyilvános.
## Végpontok
| Végpont | Guard | Leírás |
|---|---|---|
| `GET /v1/config` | – | Google kliens-azonosító, nyelvek, modellek, kreditárak |
| `POST /v1/auth/register` | – | `{email, password, display_name?, locale?}` → munkamenet; megerősítő e-mailt küld |
| `POST /v1/auth/login` | – | `{email, password}` |
| `POST /v1/auth/google` | – | `{id_token}`; `created: true`, ha most jött létre a fiók |
| `POST /v1/auth/logout`, `/logout-all` | user | kijelentkezés erről, illetve minden eszközről |
| `POST /v1/auth/verify-email` | – | `{token}` az e-mailben kapott linkből |
| `POST /v1/auth/resend-verification` | user | |
| `POST /v1/auth/password-reset` | – | `{email}`; mindig 202 |
| `POST /v1/auth/password-reset/confirm` | – | `{token, password}`; minden munkamenet megszűnik |
| `GET`/`PATCH`/`DELETE /v1/me` | user | profil (`display_name`, `locale`); törlés: `{confirm: "DELETE"}` |
| `POST /v1/me/password` | user | `{current_password?, new_password}`; Google-fiókhoz jelszót is ad |
| `GET /v1/me/export` | user | GDPR: minden adat egy JSON-ban |
| `GET /v1/credits` | user | egyenleg és kreditmozgások |
| `GET`/`POST /v1/charts` | user | képletek listája; új képlet: `{label, is_primary, birth}`, ahol a `birth` a horoscope-api `/v1/natal` kérésformátuma |
| `GET`/`PATCH`/`DELETE /v1/charts/{id}` | tulajdonos | a születési adat nem módosítható: a javított képlet új képlet |
| `GET`/`POST /v1/synastries` | user | `{chart1_id, chart2_id}`, mindkét képlet a sajátod |
| `GET`/`DELETE /v1/synastries/{id}` | résztvevő | |
| `GET`/`POST /v1/invites` | user | „Mennyire illünk össze?” link; alapból a saját (primary) képlettel |
| `DELETE /v1/invites/{id}` | meghívó | visszavonás |
| `GET /v1/public/invites/{token}` | – | a meghívó landing oldalának adatai |
| `POST /v1/invites/accept` | user | `{token, chart_id?}`: elkészül a szinasztria, mindketten látják, a meghívó e-mailt kap |
| `GET`/`POST /v1/charts/{id}/analyses` | tulajdonos | `{language?, model?}` |
| `GET`/`POST /v1/synastries/{id}/analyses` | résztvevő | |
| `GET /v1/analyses/{id}` | jogosult | |
| `GET`/`POST /v1/shares`, `DELETE /v1/shares/{id}` | user | `{kind: chart\|synastry\|analysis, target_id, title?, show_birth_data?}` |
| `GET /v1/public/shares/{slug}` | – | a megosztott tartalom (oldal + OG-kép adatai) |
| `GET /v1/admin/users?q=` | admin | felhasználók kereséssel, szerepekkel, kreditekkel |
| `PATCH /v1/admin/users/{id}` | admin | `{roles: [...]}`; a saját admin szerep nem vehető el |
| `POST /v1/admin/users/{id}/credits` | admin | `{delta, note?}` |
Hibák formátuma: `{"error": {"code", "message"}}`. A születési adatok hibái (például ismeretlen hely, javaslatokkal együtt) változatlanul jönnek tovább a horoscope-api-ból.
## Adatmodell
| Tábla | Mire |
|---|---|
| `users` | e-mail, megerősítés, név, nyelv, `roles text[]` |
| `auth_identities` | belépési módok: `password` (hash) / `google` (sub) / később `facebook`, `apple` |
| `sessions`, `auth_tokens` | munkamenetek; egyszer használatos e-mail-tokenek (megerősítés, jelszó-visszaállítás) |
| `charts` | a felhasználó képletei: `birth_data` (kérés), `result` (teljes számítás), `chart_hash`, `is_primary` (legfeljebb egy) |
| `synastries` | két képlet összevetése (`result`: fényszögek, házak, kompozit), `synastry_hash` |
| `synastry_invites` | meghívó linkek: token hash, lejárat, ki fogadta el, melyik szinasztria lett belőle |
| `analyses` | szöveges elemzések: típus, nyelv, modell, promptverzió, `cache_key`, állapot (`pending` → `running` → `done`/`failed`), strukturált `content` |
| `credit_ledger` | csak hozzáírható kreditnapló; az egyenleg `SUM(delta)`; havi keret lustán, egyszer havonta |
| `shares` | nyilvános linkek: véletlen `slug`, mit mutat, `show_birth_data`, nézettség, visszavonás |
| `email_outbox` | kimenő e-mailek; a worker küldi ki (újrapróbálással) |
**Adatvédelem:**
- A születési adatokból a `name` mező nem kerül tárolásra, és nem megy tovább a számításhoz (később az LLM-hez sem).
- A nyilvános megosztás alapból nem mutat születési dátumot, időt és helyet. A `show_birth_data: true` csak a megosztó saját képletére vonatkozik, a partneréire soha.
- A szinasztria másik fele csak a pozíciókat látja, a születési adatokat nem.
- A fiók törlése mindent töröl, ami a felhasználóhoz tartozik, beleértve a más által létrehozott, de az ő képletét használó szinasztriákat is.
## Elemzések és kreditek
- **Kérés:** a `POST .../analyses` létrehoz egy `pending` elemzést, és levonja az `ANALYSIS_COST` kreditet; a szöveget a worker írja meg, általában 1–2 perc alatt. A kliens a `GET /v1/analyses/{id}` végponton kérdezi le az állapotát. Ha nincs elég kredit, 402 `insufficient_credits` a válasz.
- **Gyorsítótár:** a kulcs `sha256(típus | képlet- vagy szinasztria-hash | promptverzió | modell | nyelv)`.
- Ha ugyanarra a képletre már kértek ilyet, ugyanazt adja vissza (200).
- Ha bárhol van kész elemzés ugyanezzel a kulccsal (például ugyanaz a születési adat egy másik felhasználónál), ingyen átmásolja (201, `done`).
## Háttérmunkák
A [worker](../worker/README.md) kiküldi az e-maileket, megírja az elemzéseket (OpenRouter, strukturált JSON; hibánál visszaadja a kreditet), és óránként takarít. Még hátravan az elemzés streamelése a frontend felé.