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
Sorsfonalak – backend szolgáltatások
Asztrológiai rendszer konténeres backendje. A frontenden kívül minden Rustban készül.
| Komponens | Leírás |
|---|---|
services/horoscope-api |
HTTP API: születési adatokból születési horoszkóp (radix) és szinasztria |
services/backend |
felhasználók, belépés, mentett képletek, szinasztriák, meghívók, elemzések, kreditek, megosztás. Részletek: services/backend/README.md |
services/worker |
háttérmunkák: e-mail-küldés, LLM-elemzések, takarítás. Részletek: services/worker/README.md |
services/frontend |
Next.js webes felület: Google-belépés, profil, születési adatok, admin. Részletek: services/frontend/README.md |
crates/db |
PostgreSQL-séma (migrációk) és a szolgáltatások közös adatelérése |
crates/horoscope-client |
a horoscope-api HTTP-kliense (a backend és később a worker használja) |
crates/service-kit |
közös alapok: naplózás, listen cím, healthcheck, leállítás |
crates/astro-engine |
horoszkópszámítás egy cserélhető efemerisz-motor (Ephemeris trait) fölött; jelenleg Swiss Ephemeris |
crates/swisseph-sys |
FFI a Swiss Ephemeris C könyvtárhoz (a forrás a vendor/swisseph mappába töltődik le) |
crates/geo-tz |
offline helységkeresés (GeoNames) és történeti időzóna-kezelés (IANA tzdb + backzone) |
scripts/fetch-deps.sh |
minden külső adat és forrás letöltése (build-időben, futáskor nincs hálózat) |
legacy/ |
a régi Java/GWT alkalmazás, csak referencia |
Futtatás
Docker
docker compose up -d --build # horoscope-api :8080, backend :8081, worker, postgres 127.0.0.1:5432, mailpit :8025
curl -s localhost:8080/healthz
curl -s localhost:8081/healthz
A docker compose up a docker-compose.override.yml fájlt is betölti. Ebben csak fejlesztői dolgok vannak: a Mailpit, ami minden kimenő e-mailt elkap (webes felület: http://<szerver>:8025), és a worker erre van irányítva. Élesben az override nélkül kell indítani, és az SMTP_URL-t meg kell adni:
SMTP_URL=smtps://user:jelszo@smtp.example.com:465 docker compose -f docker-compose.yml up -d
Az éles szerverre a CI telepít (Gitea Actions, Caddy és https): lásd deploy/README.md.
A horoscope-api image önálló (scratch alapú, kb. 70 MB, nem root felhasználóval fut). Benne van a statikus bináris és az összes adat. A container induláskor ~2 mp alatt betölti az adatokat, és ~190 MB memóriát használ. Egy horoszkóp kiszámítása 2–3 ms.
Build-argumentumok (docker compose build --build-arg …):
| Argumentum | Alapérték | Jelentés |
|---|---|---|
TZDB_VERSION |
2026f |
IANA tzdb kiadás |
SWISSEPH_VERSION |
v2.10.3bfinal |
Swiss Ephemeris git tag |
SWISSEPH_EPHE_FILES |
sepl_18.se1 semo_18.se1 seas_18.se1 |
adatfájlok (1800–2399); például sepl_12.se1 semo_12.se1 seas_12.se1 kell 1200–1799-hez |
GEONAMES_CITIES |
cities500 |
világszintű helységlista (legalább 500 lakos) |
GEONAMES_FULL_COUNTRIES |
HU |
országok, amelyeknek minden települése bekerül (szóközzel elválasztva, pl. "HU RO SK") |
Helyben
scripts/fetch-deps.sh # vendor/ és data/ letöltése (egyszer)
docker compose up -d postgres # a backend tesztjeihez
export DATABASE_URL=postgres://sorsfonalak:sorsfonalak-dev@127.0.0.1:5432/sorsfonalak
cargo test --workspace # unit + referencia + API + backend integrációs tesztek
cargo run --release -p horoscope-api # http://localhost:8080
A backend tesztjei minden tesztesethez friss, migrált adatbázist hoznak létre a DATABASE_URL szerveren.
Környezeti változók: ASTRO_DATA_DIR (alapérték: data), BIND_ADDR (0.0.0.0:8080), CORS_ALLOWED_ORIGINS (* vagy vesszővel elválasztott lista), LOG_FORMAT (text/json), RUST_LOG.
API
| Végpont | Leírás |
|---|---|
POST /v1/natal |
születési horoszkóp |
POST /v1/synastry |
két ember összevetése: szinasztria és kompozit képlet |
GET /v1/places?country=HU&q=szeged®ion=&limit=10 |
helységkeresés (a frontend helyválasztójához) |
GET /v1/timezones?country=US |
egy ország időzónái |
GET /v1/countries |
országok és időzónáik |
GET /v1/info |
választható opciók, alapértékek, adatverziók |
GET /healthz |
állapotellenőrzés |
POST /v1/natal: kérés
{
"date": "1985-07-14",
"time": "14:30",
"country": "HU",
"place": "Budapest"
}
| Mező | Kötelező | Leírás |
|---|---|---|
date |
✔ | helyi dátum, YYYY-MM-DD (1000–2999) |
time |
helyi idő, HH:MM vagy HH:MM:SS. Ha hiányzik, ismeretlen születési idő: 12:00-ra számol, házak, tengelyek és sorspontok nélkül |
|
calendar |
gregorian (alapérték) vagy julian (pl. Oroszország 1918 előtt); a julián dátumot átváltja gergely-naptárira |
|
country |
✔ | ország: ISO kód (HU, HUN) vagy angol név |
place |
✱ | településnév bármilyen nyelven, ékezettel vagy anélkül (Kolozsvár → Cluj-Napoca) |
region |
megye vagy állam az azonos nevű települések szétválasztására | |
geonames_id |
✱ | pontos hely (a /v1/places válaszából); elsőbbséget élvez a place mezővel szemben |
latitude, longitude |
✱ | koordináták; felülírják a település koordinátáit, és település nélkül kötelezők |
elevation |
magasság méterben (csak topocentrikus számításnál számít) | |
timezone |
IANA zóna felülírása (pl. Europe/Budapest) |
|
utc_offset |
fix UTC-eltérés (pl. +02:00), ha az anyakönyv mást mond, mint a tzdb |
|
ambiguous_time |
reject (alapérték), earlier vagy later: mi legyen az óraátállításkor kétszer előforduló vagy nem létező időponttal |
|
options |
lásd alább | |
name |
tetszőleges címke, a válaszban visszakapod |
✱ A place, a geonames_id és a latitude+longitude közül legalább egy kötelező.
options (minden mezőnek van alapértéke):
| Opció | Értékek (alapérték vastagon) |
|---|---|
house_system |
placidus, koch, porphyry, regiomontanus, campanus, equal, whole_sign, alcabitius, morinus, topocentric, meridian, vehlow |
zodiac |
tropical, sidereal |
ayanamsa |
lahiri, fagan_bradley, raman, krishnamurti, de_luce, yukteshwar, true_citra, galactic_center0_sag (csak sziderikus zodiákusnál) |
node_type |
true, mean: holdcsomópont |
lilith_type |
mean, true: Fekete Hold |
aspect_set |
major (együttállás, szextil, kvadrát, trigon, oppozíció), extended (+ félszextil, félkvadrát, kvintil, másfélkvadrát, bikvintil, kvinkunx) |
orb_multiplier |
1.0 (0 < x ≤ 3) |
topocentric |
false |
include_asteroids |
true (Ceres, Pallas, Juno, Vesta) |
Válasz (rövidítve)
{
"input": { /* a kérés, alapértékekkel kiegészítve */ },
"location": { "country": {...}, "place": {...GeoNames adatok...}, "latitude": 47.49835, "longitude": 19.04045,
"coordinates_source": "place", "alternatives": [ /* további azonos nevű helyek */ ] },
"time": {
"zone": "Europe/Budapest", "zone_source": "place",
"local": "1985-07-14T14:30:00", "utc": "1985-07-14T12:30:00Z",
"utc_offset": "+02:00", "dst": true, "abbreviation": "CEST",
"local_mean_time": "13:46:10", "time_known": true, "calendar": "gregorian",
"transition": null, "notes": []
},
"settings": { /* használt opciók + orbisz-táblázat */ },
"astronomy": { "julian_day_ut": 2446261.0208, "julian_day_tt": ..., "delta_t_seconds": 54.63,
"local_sidereal_time_hms": "09:15:26", "obliquity": {...}, "ayanamsa": null },
"points": [
{ "id": "sun", "kind": "luminary", "longitude": 112.0007, "sign": "cancer", "degree_in_sign": 22.0007,
"degree_in_sign_dms": "22°00'03\"", "decan": 3, "latitude": 0.00005, "distance_au": 1.0165,
"speed": 0.9541, "retrograde": false, "right_ascension": 113.77, "declination": 21.65,
"out_of_bounds": false, "house": 9, "dignities": [] }
/* moon … pluto, north_node, south_node, lilith, chiron, ceres, pallas, juno, vesta */
],
"angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...},
"vertex": {...}, "antivertex": {...}, "east_point": {...}, "armc": 138.86 },
"houses": { "system": "placidus", "requested_system": "placidus", "cusps": [ { "house": 1, "sign": "scorpio", ... } ] },
"aspects": [ { "point1": "sun", "point2": "mars", "aspect": "conjunction", "orb": 1.09, "max_orb": 10,
"applying": true, "separation": 1.09, "exact_angle": 0, "major": true } ],
"lots": { "fortune": {...}, "spirit": {...} },
"moon_phase": { "elongation": 319.16, "phase": "waning_crescent", "illumination": 0.12, "waxing": false },
"summary": { "elements": {...}, "modalities": {...}, "hemispheres": {...}, "sect": "day",
"chart_ruler": { "ascendant_sign": "scorpio", "traditional": {...}, "modern": {...} },
"retrograde": ["jupiter", "saturn", "uranus", "neptune"] },
"warnings": [],
"meta": { "data_sources": { "ephemeris": {...}, "tzdb_version": "2026f", ... } }
}
Minden azonosító (bolygó, jegy, fényszög, fázis) angol snake_case; a magyar fordítás a frontend feladata.
POST /v1/synastry: kérés
{
"person1": { "name": "A", "date": "1985-07-14", "time": "14:30", "country": "HU", "place": "Budapest" },
"person2": { "name": "B", "date": "1987-02-03", "time": "06:10", "country": "HU", "place": "Szeged" },
"options": { "aspect_set": "major" }
}
A person1 és a person2 ugyanazokat a mezőket fogadja, mint a /v1/natal, kivéve az options mezőt. Az options csak legfelső szinten adható meg, és mindkét képletre érvényes.
Válasz (rövidítve)
{
"person1": { /* a /v1/natal teljes válasza, meta nélkül */ },
"person2": { /* ugyanígy */ },
"settings": { "aspect_set": "major", "orb_multiplier": 1.0, "orbs": [...] },
"aspects": [ // a két képlet közötti fényszögek, a legszorosabb elöl
{ "person1": "mars", "person2": "jupiter", "aspect": "sextile", "nature": "harmonious",
"major": true, "exact_angle": 60, "separation": 60.04, "orb": 0.04, "max_orb": 5 }
],
"house_overlays": { // az egyik ember pontjai (bolygók, csomópontok, Lilith, Chiron, kisbolygók, AC, MC) a másik házaiban
"person1_in_person2": [ { "point": "sun", "sign": "cancer", "house": 9 } ],
"person2_in_person1": [ ... ]
},
"summary": { "aspect_count": 65,
"by_nature": { "harmonious": 27, "challenging": 29, "neutral": 9 },
"by_aspect": { "conjunction": 9, "sextile": 13, "square": 19, "trine": 14, "opposition": 10 } },
"composite": { // felezőpontos kompozit képlet
"method": "midpoint",
"points": [ { "id": "sun", "longitude": 125.67, "sign": "leo", "degree_in_sign_dms": "5°40'03\"", "house": 7 } ],
"angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...} },
"houses": { "method": "midpoint_of_cusps", "cusps": [...] },
"aspects": [ /* a kompozit pontok egymás közötti fényszögei */ ]
},
"warnings": [],
"meta": {...}
}
- Fényszögek: ugyanazokat a pontokat és orbiszokat használja, mint a születési képlet: a Nap és a Hold nagyobb orbiszt kap, a csomópontok, a Lilith és a Chiron kisebbet. Az alkalmazó/szeparáló jelzés itt nincs, mert két születési képlet között nincs értelme.
nature:- harmonikus: szextil, trigon, kvintil, bikvintil;
- feszült: kvadrát, oppozíció, félkvadrát, másfélkvadrát, kvinkunx;
- semleges: együttállás, félszextil.
- Kompozit: minden pont a két születési pont közelebbi felezőpontja. A házcsúcsok a két születési házcsúcs felezőpontjai, sorrendhelyesen igazítva; a kompozit AC az 1., az MC a 10. házcsúcs.
- Ismeretlen születési idő: ha az egyik ember születési ideje ismeretlen, a tengelyei kimaradnak a fényszögekből, a másik ember pontjai nem kerülnek az ő házaiba, a kompozitnak pedig nincsenek tengelyei és házai. Erről a
warningsmező is szól. - Hibák: az egyik emberre vonatkozó hibánál a hibaobjektumban egy
personmező is van ("person1"vagy"person2"), és az üzenet ezzel kezdődik.
Hibák formátuma: {"error": {"code": "...", "message": "...", "person": "...", "suggestions": [...]}}.
| HTTP | code |
Mikor |
|---|---|---|
| 400 | bad_request, unknown_country, unknown_time_zone, place_country_mismatch, invalid_date_time |
hibás bemenet |
| 404 | place_not_found (suggestions mezővel), unknown_place_id |
nincs ilyen hely |
| 422 | ambiguous_local_time, nonexistent_local_time |
óraátállításkor; az ambiguous_time mezővel kell dönteni |
| 422 | calculation_failed, no_time_zone |
a számítás nem végezhető el |
Időzónák és nyári időszámítás
- Az IANA tzdb
backzoneadatokkal van fordítva. Az alap tzdb 1970 előtt összevon olyan zónákat, amelyek 1970 óta azonosak; Oslót például Berlinhez köti, pedig Norvégiában 1959–1965 között volt nyári idő, Németországban nem. A backzone-nal minden ország megtartja a saját történetét. Magyarország: 1941–1949 és 1954–1957 között volt nyári idő, 1958–1979 között nem, 1980 óta van. - A zóna kiválasztásának sorrendje: a
timezonemező, ha meg van adva → a talált település zónája (GeoNames) → az ország egyetlen zónája → a legközelebbi település zónája ugyanabban az országban (több zónás országokban, pl. USA, Oroszország) → azone.tablegközelebbi referenciapontja. - Kétszer előforduló és nem létező időpontok (őszi és tavaszi óraátállítás): alapértelmezésben hiba, amely mindkét lehetőséget leírja; az
ambiguous_timemezővel lehet dönteni. - Helyi középidő: ahol még nem volt szabványidő (a tzdb
LMT-t ad), ott a születési hely saját helyi középidejét használja (hosszúság/15 óra), nem a zóna referenciavárosáét. 1880-ban Debrecenben ez +01:26:30, Budapesten +01:16:20. - Felülírás: ha az anyakönyv eltér a tzdb-től (háborús idő, helyi szokás), a
utc_offsetmezővel fix eltérés adható meg.
Ismert korlát: a tzdb a mai közigazgatási zónát ismeri. Ha egy terület történelmileg más országhoz tartozott, azt nem követi. Példa: Észak-Erdély 1940 és 1944 között budapesti időt használt, a Europe/Bucharest zóna viszont ezt nem tartalmazza. Ilyenkor a timezone: "Europe/Budapest" vagy a utc_offset mezőt kell megadni.
Számítási motor
- Swiss Ephemeris (Astrodienst), a csomagban kapott C forrásból fordítva. A belső verziószám
2.10.03, a git tagv2.10.3bfinal. A bolygópozíciók ívmásodpercnél pontosabbak. - A Rust-kötést automata tesztek vetik össze a hivatalos
swetestprogram eredményeivel: bolygók, sebességek, házcsúcsok, Vertex, Delta T, sarkvidéki visszaesés. - Az adatfájlok 1800–2399-et fedik le. Ezen kívül a motor a pontatlanabb Moshier-efemeriszre vált, a Chiron és a kisbolygók kimaradnak, és a válasz
warningsmezőjében figyelmeztetés jelenik meg. - A sarkkörökön túl a Placidus/Koch/Topocentrikus házrendszer nem értelmezhető; ilyenkor Porphyry-re vált, és figyelmeztetést ad.
- A motor az
astro_engine::Ephemeristrait mögött van. Egy licenctiszta motor (pl. JPL DE440 + saját Rust kód) a trait implementálásával beköthető, a horoszkóplogika módosítása nélkül.
Licencek
- Swiss Ephemeris: AGPL-3.0 vagy fizetős Swiss Ephemeris Professional License. Ha a szolgáltatást mások a hálózaton keresztül használják, AGPL alatt a teljes forrást elérhetővé kell tenni, különben kereskedelmi licenc kell. Emiatt a workspace licence jelenleg
AGPL-3.0-or-later. - GeoNames: CC BY 4.0. A forrásmegjelölés benne van az API válaszában (
meta.data_sources). - IANA tzdb: public domain.