Files
sorsfonalak/services/worker/README.md
T
fecoandClaude Opus 5.5 812b2d4f73 Write text analyses with OpenRouter in the worker
- analysis job: claims pending analyses (SKIP LOCKED, NOTIFY wake-up),
  builds a compact chart text without birth data, asks OpenRouter with a
  strict JSON schema, validates and stores the answer, model used, tokens
  and cost; retries transient errors, refunds credits on final failure,
  requeues interrupted jobs
- prompt v1 for natal and synastry analyses, Hungarian style guide
- compare-models subcommand for blind model comparison
- migration 0003: attempts, next_attempt_at, model_used, cost_usd,
  notify trigger, one refund per analysis
- db: rebuild when migrations change
- compose: worker reads OPENROUTER_API_KEY from .env.secrets

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
2026-11-15 12:18:40 +00:00

5.4 KiB
Raw Blame History

worker

Háttérmunkák a közös PostgreSQL-adatbázis fölött: e-mail-küldés, szöveges elemzések (LLM), takarítás. Nincs nyilvános API-ja, csak egy /healthz végpontja (8082) a Docker healthcheckhez. Induláskor lefuttatja a migrációkat, ugyanúgy, mint a backend.

Munkák

E-mail-küldés (email_outbox → SMTP)

  • A backend a levelet az email_outbox táblába teszi. Egy adatbázis-trigger (NOTIFY email_outbox) azonnal felébreszti a workert, így a levél másodperceken belül kimegy. Ha az értesítés elveszne, a worker POLL_INTERVAL_SECS másodpercenként úgyis ránéz.
  • A sorokat FOR UPDATE SKIP LOCKED zárolással veszi fel, ezért több worker is futhat egyszerre, és nem küldik el kétszer ugyanazt. A kézbesítés „legalább egyszer” elvű: ha a worker éppen küldés közben áll le, a levél újra kimehet.
  • Átmeneti hibánál (hálózat, SMTP 4xx) újrapróbálja 1, 2, 4, … percenként, legfeljebb 6 óránként. MAX_EMAIL_ATTEMPTS próbálkozás után a levelet sikertelennek jelöli (failed_at, last_error).
  • Végleges hibánál nem próbálja újra: ilyen a hibás cím, az SMTP 5xx és az ismeretlen sablon.
  • Sablonok magyarul és angolul, a felhasználó nyelve szerint (src/templates.rs): verify_email, reset_password, invite_accepted. Mindegyik szöveges és HTML-változatban megy ki; a felhasználó nevét HTML-ben escape-eli, és a vezérlőkaraktereket eltávolítja belőle.
  • Ha nincs SMTP_URL, a worker nem küld semmit, a levelek az outboxban várnak.

Takarítás (induláskor, majd óránként)

  • lejárt munkamenetek és e-mail-tokenek;
  • elküldött e-mailek 7 nap után (tokenes linkek vannak bennük), sikertelenek 30 nap után;
  • el nem fogadott meghívók 30 nappal a lejáratuk után.

Szöveges elemzések (analyses, pending → running → done/failed)

  • A backend létrehozza a pending sort, és levonja a kreditet. Egy trigger (NOTIFY analyses) felébreszti a workert; egyszerre ANALYSIS_CONCURRENCY elemzés készül.

  • A prompt a tárolt képletből készül (src/analysis/compact.rs). Ez egy tömör szöveg, amely csak a pozíciókat tartalmazza: jegyek, fokok, házak, fényszögek, elemek. Név, születési dátum, idő, hely és koordináta nem megy ki. Ismeretlen születési időnél nincsenek házak, Aszcendens és MC.

  • A modell OpenRouteren keresztül válaszol, azzal a modellel, amely a sor model mezőjében áll. A válasznak kötött JSON-sémát kell követnie (src/analysis/prompt.rs, PROMPT_VERSION = v1):

    • title, summary;
    • sections, radixnál: personality, emotions, mind, love, work, growth; szinasztriánál: attraction, communication, emotional_bond, friction, long_term;
    • strengths, challenges, advice.

    A worker a választ maga is ellenőrzi a sémán.

  • Eltárolja a ténylegesen válaszoló modellt (model_used; az openrouter/auto mögött ez más lehet), a tokenszámot és a költséget (cost_usd).

  • Átmeneti hiba (hálózat, 429, 5xx, elfogyott OpenRouter-egyenleg, hibás vagy csonka válasz): újrapróbálja 30 mp, 2 perc, majd 8 perc múlva.

  • Végleges hiba (például ismeretlen modell), vagy ha elfogyott a MAX_ANALYSIS_ATTEMPTS próbálkozás: az elemzés failed lesz, és a kredit visszajár (refund, elemzésenként legfeljebb egyszer).

  • Ha a worker elemzés közben leáll, a félkész elemzést visszateszi a sorba. Ha összeomlik, az elemzés 15 perc múlva magától visszakerül.

  • Szinasztriánál a modell a két félnek együtt szól; ha meg kell különböztetnie őket, „első fél” és „második fél” néven említi.

Később: streaming a frontend felé.

Modellek összevetése

OPENROUTER_API_KEY=... worker compare-models --chart natal.json \
    --models minimax/minimax-m3,anthropic/claude-sonnet-5.5 --language hu --out exports/model-compare

Ugyanazt a radix-elemzést több modellel is megírja, véletlenszerű betűkkel (A.md, B.md, …).

  • A key.json mondja meg, melyik betű melyik modell, a tokenszámmal, a költséggel és az idővel együtt.
  • A prompt.md a teljes promptot tartalmazza.
  • A --chart a horoscope-api /v1/natal válasza.

Konfiguráció

Változó Alapérték Jelentés
DATABASE_URL – (kötelező) PostgreSQL kapcsolat
SMTP_URL – smtp://mailpit:1025 (fejlesztés), smtp://user:pass@host:587?tls=required (STARTTLS), smtps://user:pass@host:465 (TLS)
MAIL_FROM Sorsfonalak <noreply@sorsfonalak.local> feladó
POLL_INTERVAL_SECS 30 tartalék lekérdezési időköz
MAX_EMAIL_ATTEMPTS 8 ennyi próbálkozás után sikertelen a levél
OPENROUTER_API_KEY – OpenRouter-kulcs (compose-ban a .env.secrets fájlból); nélküle az elemzések várnak
OPENROUTER_BASE_URL https://openrouter.ai/api/v1
PUBLIC_BASE_URL – HTTP-Referer fejléc az OpenRouter felé
ANALYSIS_CONCURRENCY 4 egyszerre írt elemzések
MAX_ANALYSIS_ATTEMPTS 3 ennyi próbálkozás után sikertelen az elemzés (a kredit visszajár)
BIND_ADDR, LOG_FORMAT, RUST_LOG 0.0.0.0:8082, text, info

Fejlesztés: Mailpit

A docker-compose.override.yml csak fejlesztéskor töltődik be. Elindítja a Mailpitet, és a workert rá irányítja. Minden levél ott landol, kifelé semmi nem megy ki. Webes felület: http://<szerver>:8025, API: http://<szerver>:8025/api/v1/messages.