Files
sorsfonalak/services/backend/README.md
T
fecoandClaude Opus 5.5 b77dafdb26
CI / test (push) Successful in 46s
CI / build (push) Successful in 4m16s
CI / deploy (push) Skipped
Try draft prompts on own charts before saving
Under each prompt on /admin/promptok, "Kipróbálás" writes the summary or
detailed analysis with the text in the editor (saved or not) on one of the
admin's own charts. Test runs live in prompt_previews: never shown with the
chart, not cached, no credits, one attempt, at most three open per admin,
removed after 30 days. The worker writes them when no analysis is due. The
result shows the model, tokens, cost and time, and the draft can be loaded back.

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

13 KiB
Raw Blame History

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 azonnal jóváír egy elemzési egységet ({"unit": "natal"}) vagy személycsomagot ({"package": "persons"} / "persons_unlimited"); a compose-fájlokban egyelőre true
FREE_PERSON_SLOTS 0 ennyi személyt vehet fel csomag nélkül egy felhasználó
PERSON_PACK_SIZE 5 ennyi személy van egy személycsomagban
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 ez írja a fizetős részletes elemzéseket
SUMMARY_MODEL anthropic/claude-sonnet-5.5 ez írja minden mentett képlet ingyenes rövid összefoglalóját (kb. 1 cent darabonként)
ANALYSIS_PROMPT_VERSION v2 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 (a korlátlan csomagra is)
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á.
  • 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, nyelvek, elemző és összefoglaló modell
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 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}/credits admin {unit: natal|synastry, delta, note?}: elemzések jóváírása vagy levonása
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: egyetlen, az ANALYSIS_MODEL (alapból Opus 5.5, a 2026-11-es összevetés legjobbja, lásd services/worker/README.md). A kliens nem választ modellt.
  • 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. Egységet a személycsomag ad (PERSON_PACK_SIZE darab), a korlátlan csomag az entitlements tábla unlimited_persons sora. 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; részletes elemzés vagy szinasztria után sem. 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).