fecoandClaude Opus 5.5 b30a6c8fb1 Default to MiniMax M3 and fix Hungarian quotes in analyses
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
2026-11-15 17:05:23 +00:00

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, takarítás (később az LLM-elemzések). Részletek: services/worker/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

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&region=&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 warnings mező is szól.
  • Hibák: az egyik emberre vonatkozó hibánál a hibaobjektumban egy person mező 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

  1. Az IANA tzdb backzone adatokkal 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.
  2. A zóna kiválasztásának sorrendje: a timezone mező, 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) → a zone.tab legközelebbi referenciapontja.
  3. 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_time mezővel lehet dönteni.
  4. 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.
  5. Felülírás: ha az anyakönyv eltér a tzdb-től (háborús idő, helyi szokás), a utc_offset mező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 tag v2.10.3bfinal. A bolygópozíciók ívmásodpercnél pontosabbak.
  • A Rust-kötést automata tesztek vetik össze a hivatalos swetest program 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 warnings mező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::Ephemeris trait 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.
S
Description
No description provided
Readme
3.1 MiB
Languages
Rust 57%
Java 27.9%
TypeScript 11.8%
CSS 1.7%
Dockerfile 0.6%
Other 1%