yourpart3/docs/FALUKANT_LOVERS_DAEMON_HANDOFF.md

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

Die lokale technische Datenbasis dieses Projekts steht in:

• 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

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