MiniMax M3 rated top in a blind comparison at a sixth of the cost of the other top models. Straight double-quote pairs in Hungarian answers become „…”. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
110 lines
8.7 KiB
Markdown
110 lines
8.7 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, 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` | `minimax/minimax-m3` | 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é.
|