# Falukant: Übergabedokument für den externen Daemon

## Zweck

Dieses Dokument ist die technische Übergabe an den externen Daemon, der nicht Teil dieses Projekts ist.

Es beschreibt:

- welche Daten der Daemon lesen muss
- welche Regeln er anwenden soll
- welche Felder er zurückschreiben muss
- welche Ereignisse und Nebenwirkungen erwartet werden

Die fachlichen Regeln selbst stehen in:

- [FALUKANT_LOVERS_DAEMON_SPEC.md](/mnt/share/torsten/Programs/YourPart3/docs/FALUKANT_LOVERS_DAEMON_SPEC.md)

Die lokale technische Datenbasis dieses Projekts steht in:

- [FALUKANT_LOVERS_TECHNICAL_CONCEPT.md](/mnt/share/torsten/Programs/YourPart3/docs/FALUKANT_LOVERS_TECHNICAL_CONCEPT.md)

## Architekturgrenze

Wichtig:

- dieses Backend hält die Datenstruktur und liefert Family-/UI-Daten
- der eigentliche Tick-Lauf für Kosten, Ansehen, Ehezufriedenheit und Kinder passiert im externen Daemon
- der externe Daemon ist damit zuständig für die periodische Spiellogik

Dieses Projekt ist nicht zuständig für:

- die Scheduler-Ausführung
- Tick-Zeitpunkte
- operative Daemon-Laufzeit

## Datenquelle

Der externe Daemon arbeitet auf folgenden Tabellen:

- `falukant_data.relationship`
- `falukant_data.relationship_state`
- `falukant_data.character`
- `falukant_data.child_relation`
- `falukant_data.falukant_user`
- `falukant_type.relationship`
- `falukant_type.title`

Optional später:

- Notification-Tabellen
- Frömmigkeits- oder Kirchen-bezogene Tabellen

## Mindestdatensatz pro Tick

Für jede aktive Liebschaft muss der Daemon laden:

- `relationship.id`
- `relationship.character1_id`
- `relationship.character2_id`
- `relationship_type.tr`
- `relationship_state.lover_role`
- `relationship_state.affection`
- `relationship_state.visibility`
- `relationship_state.discretion`
- `relationship_state.maintenance_level`
- `relationship_state.status_fit`
- `relationship_state.monthly_base_cost`
- `relationship_state.months_underfunded`
- `relationship_state.active`
- `relationship_state.acknowledged`
- `relationship_state.last_daily_processed_at`
- `relationship_state.last_monthly_processed_at`

Zusätzlich pro beteiligter Figur:

- `character.id`
- `character.user_id`
- `character.gender`
- `character.birthdate`
- `character.reputation`
- `character.title_of_nobility`

Zusätzlich für Geld:

- `falukant_user.id`
- `falukant_user.money`

Zusätzlich für Ehekontext:

- aktive Beziehung vom Typ `married`, `engaged` oder `wooing`
- `relationship_state.marriage_satisfaction`

Zusätzlich für Kinderprüfung:

- bestehende `child_relation` für dieselben Eltern

## Pflichtlogik Daily Tick

Der externe Daemon muss täglich:

1. Sichtbarkeit anpassen
2. Diskretion anpassen
3. Ehezufriedenheit anpassen
4. Ansehen anpassen
5. Skandalchance prüfen
6. Zustände speichern
7. optionale Benachrichtigung oder Log-Einträge erzeugen

### Daily Input

- alle aktiven `lover`-Beziehungen
- zugehörige Ehebeziehung, falls vorhanden
- Standesgruppe
- das jüngere Alter der beiden Beteiligten `minAge`

### Daily Output

Rückzuschreiben:

- `relationship_state.visibility`
- `relationship_state.discretion`
- `relationship_state.marriage_satisfaction` der Ehebeziehung
- `character.reputation`
- `relationship_state.last_daily_processed_at`

Optional:

- Notification
- Ereignislog

## Pflichtlogik Monthly Tick

Der externe Daemon muss monatlich:

1. Monatskosten berechnen
2. Geld abbuchen
3. Unterversorgung behandeln
4. Kinderchance prüfen
5. ggf. Kind anlegen
6. Folgen auf Ansehen und Ehe anwenden
7. Zustände speichern

### Monthly Output

Rückzuschreiben:

- `falukant_user.money`
- Geldfluss-Log
- `relationship_state.months_underfunded`
- `relationship_state.affection`
- `relationship_state.discretion`
- `relationship_state.visibility`
- `relationship_state.last_monthly_processed_at`
- ggf. `child_relation`
- ggf. neuer Kind-Charakter

## Formeln

Die verbindlichen Regeln und Formeln kommen aus:

- [FALUKANT_LOVERS_DAEMON_SPEC.md](/mnt/share/torsten/Programs/YourPart3/docs/FALUKANT_LOVERS_DAEMON_SPEC.md)

Der externe Daemon soll insbesondere exakt übernehmen:

- Standesgruppen
- Monatskostenformel
- Unterversorgungsfolgen
- Ehezufriedenheitslogik
- Reputationslogik
- Altersmalus bei zu jungen Liebschaften
- Sichtbarkeits- und Diskretionslogik
- Skandalchance
- Kinderwahrscheinlichkeit

## Idempotenz

Der externe Daemon muss idempotent arbeiten.

Pflicht:

- Daily Tick nie zweimal für denselben Ingame-Tag auf dieselbe Beziehung anwenden
- Monthly Tick nie zweimal für denselben Ingame-Monat auf dieselbe Beziehung anwenden

Pflichtfelder dafür:

- `last_daily_processed_at`
- `last_monthly_processed_at`

## Transaktionsanforderungen

Folgende Monthly-Vorgänge müssen atomar laufen:

- Geldabbuchung
- Statusänderung der Liebschaft
- Kind-Erzeugung
- Folgeänderung an Ansehen oder Ehe

Empfehlung:

- pro verarbeiteter Beziehung eine DB-Transaktion

## Kind-Erzeugung

Bei erfolgreicher Monatsprüfung auf Kind:

1. neues Kind in `falukant_data.character` anlegen
2. neue `child_relation` anlegen
3. Felder setzen:
   - `birth_context = lover`
   - `legitimacy = hidden_bastard`
   - `public_known = false`

Wenn der Daemon Kinder nicht selbst anlegen soll, muss er stattdessen ein klar definiertes Create-Event an dieses Backend oder an ein anderes Backend-Modul senden. Standardempfehlung ist aber direkte DB-Erzeugung im Daemon.

## Gleichbehandlung der Geschlechter

Der externe Daemon muss dieselben Regeln für männliche und weibliche Spielfiguren anwenden.

Das betrifft:

- Kosten
- Reputationswirkung
- Ehezufriedenheit
- Skandalrisiko
- Status- und Sichtbarkeitslogik

Unterschiedlich ist nur die biologische Kinderentstehung im aktuellen Modell.

## Was dieses Backend dafür bereitstellt

Dieses Projekt stellt aktuell bereit:

- Datenstruktur für `relationship_state`
- Datenstruktur für `child_relation`-Erweiterungen
- Family-API mit lesbaren Zuständen

Später kann dieses Backend zusätzlich bereitstellen:

- Komfort-Endpunkte für Lover-Aktionen
- Admin-/Debug-Ansichten
- eventuelle Helper-Endpoints für den Daemon

## Erwartete externe Deliverables

Damit die externe Daemon-Umsetzung vollständig ist, werden dort mindestens benötigt:

1. Daily-Tick-Job
2. Monthly-Tick-Job
3. SQL- oder ORM-Zugriff auf die Falukant-Tabellen
4. saubere Transaktionslogik
5. Schutz gegen doppelte Verarbeitung
6. Logging oder Monitoring für Tick-Fehler

## Definition of Done für die Übergabe

Die Übergabe an den externen Daemon gilt als vollständig, wenn:

1. Datenfelder und Tabellen eindeutig definiert sind
2. Daily- und Monthly-Inputs beschrieben sind
3. Daily- und Monthly-Outputs beschrieben sind
4. die verbindliche Fachlogik referenziert ist
5. Idempotenz- und Transaktionsanforderungen klar sind
6. Kinder aus Liebschaften technisch beschrieben sind