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

68 lines
5.4 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.
# 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
```bash
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`.