# 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/backend/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 ```bash docker compose up -d --build # horoscope-api :8080, backend :8081, postgres 127.0.0.1:5432 curl -s localhost:8080/healthz curl -s localhost:8081/healthz ``` 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 ```bash 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 ```json { "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) ```jsonc { "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 ```json { "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) ```jsonc { "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.