commit 0b5416df45f816fc7db3d2a581ade63c28dce3ee Author: feco Date: Fri Nov 13 13:13:59 2026 +0000 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..4524722 --- /dev/null +++ b/README.md @@ -0,0 +1,233 @@ +# 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.