Files
sorsfonalak/services/backend
fecoandClaude Opus 5.5 b0fc547b73
CI / test (push) Successful in 1m29s
CI / build (push) Successful in 5m52s
CI / deploy (push) Skipped
Tarot readings: AI-written, drawn on the server, sold as units
A new Kártyajóslás page: choose a spread (1, 3 or 5 cards), ask a
question, pick the cards from the fanned deck and watch them turn over;
the reading is written by the detailed-analysis model from the cards,
their positions and base meanings, the question and the reader's Sun,
Moon and Ascendant. The server shuffles and draws, so nobody can draw
again for free. A reading is a 'tarot' analysis (worker, retries,
fallback, refunds and admin regeneration as for analyses), uses one
'tarot' unit, and survives recalculations; deleting the account
deletes it.

Packages carry 2/5/10 readings, the new +5 kártyajóslás addon costs
1 000 Ft. The card artwork comes from the tarot design studio
(celestial astrolabe style); the deck JSON is shared by the frontend
and the prompt. A public example is at /kartyajoslas/pelda.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
2026-11-20 14:35:50 +00:00
..

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
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 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, password, display_name?, locale?, invite_token?} → munkamenet; megerősítő e-mailt 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/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 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 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).