Sign-up asks no password: a link goes to the address and the password is set there (also for forgotten passwords), by whoever opens the mailbox. So nobody can register a password for someone else's address, and linking Google or Apple to an account with the same address stays safe. Opening the link confirms the address, ends other sessions and logs in. Sign-up answers alike for registered addresses (the owner gets an 'account exists' link), links are limited to one per kind a minute and five an hour, and unconfirmed password accounts cannot log in. Frontend: login form with sign-up and forgotten password next to the social buttons, and the /jelszo page for the link. Still behind PASSWORD_LOGIN (off on prod). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
152 lines
19 KiB
Markdown
152 lines
19 KiB
Markdown
# backend
|
||
|
||
Felhasználók, belépés, mentett születési képletek, szinasztriák és meghívók, szöveges elemzések, elemzési egységek é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 |
|
||
| `PASSWORD_LOGIN` | `false` | e-mail + jelszó regisztráció és belépés; élesben ki van kapcsolva (csak Google, Apple, Facebook), a jelszavas végpontok ilyenkor 403-at adnak |
|
||
| `MOCK_PAYMENTS` | `false` | próbafizetés a Stripe bekötéséig: a `POST /v1/payments/mock` `{"package": "<id>"}` azonnal jóváírja a katalógus egy csomagját (`{"unit": "natal"}` rövidítés: a legkisebb ilyen csomag); a compose-fájlokban egyelőre `true` |
|
||
| `FREE_PERSON_SLOTS` | `0` | ennyi személyt vehet fel csomag nélkül egy felhasználó |
|
||
| `SIGNUP_MODE` | `invite` | `invite`: új fiók csak meghívóval jön létre (403 `not_invited`); `open`: bárki regisztrálhat |
|
||
| `GOOGLE_CLIENT_IDS` | – | Google OAuth kliens-azonosító(k); üresen a Google-belépés ki van kapcsolva |
|
||
| `APPLE_CLIENT_IDS` | – | Sign in with Apple: a Services ID(k) vesszővel elválasztva (pl. `hu.sorsfonalak.web`), az ID token `aud` mezője ezek egyike kell legyen; üresen az Apple-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 |
|
||
| `ANALYSIS_MODEL` | `anthropic/claude-opus-5.5` | az elemzések, előrejelzések és válaszok alapmodellje, és a tartalék, ha a választott modell hibára fut |
|
||
| `SUMMARY_MODEL` | `anthropic/claude-opus-5.5` | a rövid összefoglaló alapmodellje (az admin felületen olcsóbbra állítható) |
|
||
| `OPENROUTER_MODELS_URL` | `https://openrouter.ai/api/v1/models` | az admin modellválasztó listája árakkal (óránként egyszer kérdezi le) |
|
||
| `ANALYSIS_PROMPT_VERSION` | `v3` | a prompt verziója (az elemzés-gyorsítótár kulcsának része) |
|
||
| `MAX_CHARTS_PER_USER` | `1000` | biztonsági felső korlát a képletek számára |
|
||
| `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ó** (csak `PASSWORD_LOGIN=true` mellett; élesben csak közösségi belépés lesz, hogy ne lehessen tömegesen ingyenes fiókokat nyitni):
|
||
- a regisztráció nem kér jelszót: a címre megy egy link (`verify_email`, 3 napig él), és jelszót csak ezen lehet megadni. Az elfelejtett jelszó linkje (`reset_password`, 1 óra) ugyanoda visz (`/jelszo?token=…`). Így jelszót csak az állíthat be, aki a postafiókot olvassa, és mindig ő maga választja: senki nem regisztrálhat más címére jelszót, ezért a Google- vagy Apple-fiók összekötése az azonos című fiókkal biztonságos;
|
||
- a link megnyitásakor a cím megerősítettnek számít, minden korábbi munkamenet megszűnik, és a felhasználó be is lép;
|
||
- már regisztrált címre a regisztráció ugyanúgy 202-t ad (nem derül ki, ki van regisztrálva), a tulajdonos pedig egy „Már van fiókod” levelet kap jelszómegadó linkkel (`account_exists`);
|
||
- jelszavas link címenként és fajtánként percenként egy, összesen óránként öt mehet ki;
|
||
- megerősítetlen címmel (a linkes regisztráció előtti fiók) nem lehet jelszóval belépni;
|
||
- 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á.
|
||
- **Meghívásos regisztráció** (`SIGNUP_MODE=invite`): új fiók (Google vagy jelszó) akkor jön létre, ha
|
||
- a címre szól élő meghívó (`invitations`), vagy
|
||
- a kérés a meghívólink tokenjét hozza (`invite_token`): ilyenkor bármelyik cím jó, mert sokan nem azzal a Google-fiókkal lépnek be, amelyiket az ismerősük tudja; a meghívó ezzel elfogy;
|
||
- vagy egy élő „Mennyire illünk össze?” link tokenjét hozza, illetve a cím a `BOOTSTRAP_ADMIN_EMAILS` listában van.
|
||
|
||
Meglévő felhasználók belépése nem változik. Meghívót csak admin küld; a levelet a worker kézbesíti (`invitation` sablon). Minden küldés új linket ad, de a korábbi linkek is élnek, amíg a meghívó nyitott (`invitation_tokens`). A leiratkozott címekre nem megy több meghívó (`email_optouts`, csak hash). Lásd még `docs/levelkuldes.md`.
|
||
- **Szerepek** (`users.roles`, tömb): `user` (alap), `creator` (cikkírás, 2. fázis), `premium` és `vip` (jelenleg nincs hozzájuk funkció; a fizetős elemzés egységekkel megy), `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ó, `password_login`, `signup_mode`, nyelvek, elemző és összefoglaló modell |
|
||
| `GET /v1/packages` | – | a csomagkatalógus árral, tartalommal, megtakarítással, elemzésenkénti árral (lásd `docs/csomagok.md`) |
|
||
| `POST /v1/auth/register` | – | `{email, display_name?, locale?, invite_token?, referral?}` → 202; jelszómegadó linket küld |
|
||
| `POST /v1/auth/login` | – | `{email, password}` |
|
||
| `POST /v1/auth/google` | – | `{id_token, invite_token?}`; `created: true`, ha most jött létre a fiók; meghívó nélkül 403 `not_invited` |
|
||
| `POST /v1/auth/logout`, `/logout-all` | user | kijelentkezés erről, illetve minden eszközről |
|
||
| `POST /v1/auth/password-reset` | – | `{email}`; mindig 202 |
|
||
| `POST /v1/auth/set-password` | – | `{token, password}` a levélben kapott linkből (regisztráció vagy elfelejtett jelszó); a cím megerősítetté válik, minden más munkamenet megszűnik, és belép |
|
||
| `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 | megmaradt elemzések típusonként (`balance: {natal, synastry}`) és a mozgá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. Ugyanarra a születési adatra a `POST /v1/charts` a meglévő képletet adja vissza (200), nem számol újat |
|
||
| `POST /v1/charts/{id}/summary` | tulajdonos | az ingyenes rövid összefoglaló (`kind: summary`, `{title, summary}`); mentéskor magától sorba áll, ez visszaadja, és ha elbukott, újra sorba állítja |
|
||
| `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, megmaradt elemzésekkel |
|
||
| `PATCH /v1/admin/users/{id}` | admin | `{roles: [...]}`; a saját admin szerep nem vehető el |
|
||
| `POST /v1/admin/users/{id}/packages` | admin | `{package, note?}`: csomag kiosztása ajándékként (`package_orders`, ár 0) |
|
||
| `POST /v1/admin/users/{id}/credits` | admin | `{unit: natal\|synastry, delta, note?}`: elemzések jóváírása vagy levonása |
|
||
| `GET`/`POST /v1/admin/invitations` | admin | lista (állapot, az utolsó levél állapota, várólista); új: `{emails: [...], message?, locale?}`, címenként `invited` (linkkel), `invalid`, `already_user`, `already_invited` vagy `opted_out` |
|
||
| `POST /v1/admin/invitations/{id}/resend`, `DELETE …/{id}` | admin | újraküldés új linkkel és újabb 30 nappal (legfeljebb 3 küldés, 24 óránként); visszavonás |
|
||
| `POST /v1/admin/invitations/preview` | admin | `{message?, locale?, send_to_me?}`: a meghívólevél HTML- és szöveges változata mintalinkekkel; kérésre tesztpéldány az adminnak |
|
||
| `DELETE /v1/admin/waitlist/{email}` | admin | törlés a várólistáról |
|
||
| `GET /v1/public/invitations/{token}` | – | a meghívó adatai a belépőoldalnak (ki hívott, üzenet, állapot) |
|
||
| `POST /v1/public/invitations/unsubscribe?token=` | – | „Nem kérek több meghívót”: a lábléc linkjéről és a levelezők egykattintásos gombjáról (RFC 8058) |
|
||
| `POST /v1/public/waitlist` | – | `{email, locale?}`; mindig 202, nem árulja el, kinek van fiókja |
|
||
| `GET /v1/admin/prompts` | admin | a tömör és a részletes elemzés system promptja nyelvenként: érvényes szöveg, alapértelmezett, változatok |
|
||
| `PUT /v1/admin/prompts/{kind}/{language}` | admin | `{system}` új változatként menti (`null` vagy az alapértelmezett szöveg: vissza a beépítettre); az új elemzések `prompt_version`-je `v2-r<id>` |
|
||
| `POST /v1/admin/prompts/{kind}/{language}/preview` | admin | `{system, chart_id}`: próbafuttatás a (mentetlen) szöveggel egy saját képleten; nem kerül a képlethez, nem gyorsítótárazott, nem fogy egység; egyszerre legfeljebb 3 |
|
||
| `GET /v1/admin/previews/{id}` | admin | a próbafuttatás állapota és eredménye (modell, token, költség) |
|
||
|
||
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ó egységnapló (`unit`: `natal` vagy `synastry`); az egyenleg típusonként `SUM(delta)` |
|
||
| `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 egységek
|
||
|
||
- **Ingyenes rész:** minden mentett képlethez elkészül egy rövid összefoglaló (`summary`, `SUMMARY_MODEL`), ezért nem kell fizetni.
|
||
- **Fizetős rész:** a részletes elemzés darabra megy. A képletelemzés egy `natal`, a szinasztria-elemzés egy `synastry` egységet von le (`credit_ledger.unit`). Az egységek csomagvásárlásból (Stripe, később) vagy admin jóváírásból jönnek. Havi ingyenes keret nincs.
|
||
- **Modell:** három beállítás az admin felületen, az OpenRouter listájából (`model_settings` tábla): az elemzések és az éves előrejelzés (képlet-, kapcsolati elemzés, előrejelzés) közös modellje, a kérdés-válasz modellje és a rövid összefoglalóé. Ha nincs beállítva, az `ANALYSIS_MODEL` / `SUMMARY_MODEL` (alapból mindkettő Opus 5.5, a 2026-11-es összevetés legjobbja, lásd `services/worker/README.md`). Csak kötött JSON-választ adó modell választható. A kliens nem választ modellt, és a modell neve felhasználónak sehol nem jelenik meg.
|
||
- **Tartalék:** ha a választott modell kétszer hibára fut (végleges hibánál egyszer), a worker az alapmodellel próbálja tovább (`fallback_model`, `on_fallback`); csak ha az is elbukik, jár vissza az egység. A Modellek oldal mutatja, hány szövegnél kellett az elmúlt 30 napban.
|
||
- **Hibanapló:** a worker minden sikertelen próbálkozást a `generation_errors` táblába ír (mi, melyik modell, hányadik kísérlet, mi lett: újrapróbálás, tartalék vagy végleges hiba, mennyi ideig tartott); az admin Hibanapló oldala mutatja (`GET /v1/admin/errors?source=&outcome=`), 90 napig őrizzük. A felhasználó a várakozó oldalon látja, ha az előző próbálkozás nem sikerült és újrapróbáljuk; a számláló a kérés idejétől (`requested_at`) mér.
|
||
- **Futó generálások:** a Modellek oldalon látszik minden készülő és sorban álló elemzés és válasz, a modelljével és azzal, amivel most indulna; újraindításkor a jelenlegi beállítással indul újra (`GET /v1/admin/jobs`, `POST /v1/admin/jobs/restart`). Minden kísérlet `started_at` értéke a „jegye”: az újraindítás törli, így a workerben még futó régi kísérlet nem írhatja felül az újat, és a worker 10 másodpercen belül eldobja.
|
||
- **Újragenerálás:** admin minden elemzést egyenként újraírathat (`POST /v1/admin/analyses/{id}/regenerate`): ugyanaz a sor (az azonosító és a megosztások maradnak), a jelenlegi prompttal és modellel, egységlevonás nélkül.
|
||
- **Újraszámolás:** számítási változás után a `backend recalculate` parancs minden mentett képletet, összevetést és előrejelzést újraszámol, majd minden elemzést újra sorba állít (egységlevonás nélkül).
|
||
- **Kérés:** a `POST .../analyses` (`{language?}`) létrehoz egy `pending` elemzést, és levon egy egységet; 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 egység, 402 `insufficient_credits` a válasz (`unit`, `balance` részletekkel). Hiba esetén a worker visszaadja az egységet.
|
||
- **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 az egységet), és óránként takarít. Még hátravan az elemzés streamelése a frontend felé.
|
||
|
||
## Korlátok
|
||
|
||
- **Saját születési adatok módosítása:** az első mentés után egy órán belül még háromszor javíthatók, utána naponta egyszer (`birth_data_changes` tábla). A tiltott módosítás 429-et ad `birth_data_change_limit` kóddal, a felhasználónak szóló üzenettel („A rendszer csak napi egy módosítást engedélyez. …”). A `/v1/me` `birth_change` mezője mutatja, él-e a napi korlát. Más emberek képleteit ez nem érinti.
|
||
- **Személyek** (más emberek képletei, `charts.kind = 'person'`): minden új személy egy `person` egységet használ (`credit_ledger`, `reason = 'person'`); a törlés nem adja vissza. Helyet a csomagok adnak; korlátlan az `unlimited_persons` jogosultsággal. Ha elfogyott, 409 `person_limit_reached`. Egy személy születési adatai a felvétel után egy órán belül javíthatók (`PATCH /v1/charts/{id}` `birth` mezővel), utána 409 `person_locked`. A név (`label`) bármikor változhat; ha a `birth` ugyanaz, mint a tárolt (vagy ugyanazt a képletet adja), nincs újraszámolás, és az elemzések, összevetések maradnak. Részletes elemzés (képlet vagy összevetés) után sem (409 `person_analysed`), és akkor sem, ha valaki más összevetésében szerepel (409 `person_in_synastry`); a saját, elemzés nélküli összevetései a javításkor törlődnek. A `/v1/me` `persons` mezője: `used`, `limit`, `left`, `unlimited`.
|
||
- **Admin:** nincs módosítási korlát, korlátlan személy, a személyek adatai bármikor javíthatók, és a részletes elemzés ingyenes (nem fogy egység).
|