Files

244 lines
16 KiB
Markdown
Raw Permalink Normal View History

2026-11-13 13:13:59 +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/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/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](services/frontend/README.md) |
2026-11-13 13:13:59 +00:00
| `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, worker, postgres 127.0.0.1:5432, mailpit :8025
2026-11-13 13:13:59 +00:00
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:
```bash
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](deploy/README.md).
2026-11-13 13:13:59 +00:00
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.