Files
sorsfonalak/README.md
T
2026-11-13 13:13:59 +00:00

234 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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&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
```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.