yourpart3/docs/FALUKANT_LOVERS_TECHNICAL_CONCEPT.md

Falukant: Technisches Konzept für Liebhaber, Mätressen, Ehezufriedenheit und Kinder aus Liebschaften

Ziel

Dieses Dokument beschreibt die technische Umsetzung für Backend, Daemon und UI. Es basiert auf:

• FALUKANT_LOVERS_CONCEPT.md
• FALUKANT_LOVERS_DAEMON_SPEC.md

Es soll als direkte Arbeitsgrundlage für Migrationen, Modelle, Service-Methoden, Daemon-Jobs und Frontend-Anpassungen dienen.

Umsetzungsstrategie

Die Umsetzung sollte in drei technischen Stufen erfolgen:

Stufe 1: Datenbasis und Lesepfade

• neue Beziehungsdetaildaten anlegen
• Ehezufriedenheit technisch einführen
• Family-API erweitern
• UI nur lesend erweitern

Stufe 2: Externe Daemon-Logik

• tägliche und monatliche Falukant-Familienlogik an den externen Daemon übergeben
• Kosten, Ansehen, Sichtbarkeit, Diskretion und Ehezufriedenheit laufen dort automatisch
• Kinder aus Liebschaften werden über den externen Daemon ermöglicht

Stufe 3: Interaktive Spielmechanik

• UI-Aktionen für Unterhalt, Diskretion, Anerkennung, Beenden
• Ereignisse, Warnungen und Benachrichtigungen
• spätere Vertiefung wie Skandal- oder Kirchenereignisse

Datenmodell

1. Bestehende Tabellen, die genutzt werden

• falukant_data.relationship
• falukant_data.child_relation
• falukant_data.character

2. Empfohlene neue Tabelle

Empfohlen wird eine neue Detailtabelle:

• falukant_data.relationship_state

Begründung:

• relationship enthält aktuell nur die grobe Beziehung
• Liebhaber-/Ehedaten sind zustandsorientiert
• die Detailwerte wachsen voraussichtlich weiter
• eine Nebentabelle ist sauberer als relationship mit vielen Spezialspalten zu überladen

3. Tabelle relationship_state

Primärbezug

• relationship_id

Spalten für Ehe

• marriage_satisfaction integer not null default 55
• marriage_public_stability integer not null default 55

marriage_public_stability ist optional, aber sinnvoll für spätere Ereignisse. Für MVP kann er schon angelegt, aber noch wenig genutzt werden.

Spalten für Liebschaften

• lover_role string nullable
  • secret_affair
  • lover
  • mistress_or_favorite
• affection integer not null default 50
• visibility integer not null default 15
• discretion integer not null default 50
• maintenance_level integer not null default 50
• status_fit integer not null default 0
• monthly_base_cost integer not null default 0
• months_underfunded integer not null default 0
• active boolean not null default true
• acknowledged boolean not null default false
• exclusive_flag boolean not null default false
• last_monthly_processed_at date nullable
• last_daily_processed_at date nullable

Spalten für spätere Erweiterung

• notes_json jsonb nullable
• flags_json jsonb nullable

4. Erweiterung child_relation

Neue Spalten:

• legitimacy string not null default legitimate
  • legitimate
  • acknowledged_bastard
  • hidden_bastard
• birth_context string not null default marriage
  • marriage
  • lover
• public_known boolean not null default false

5. Optionale Erweiterung relationship

Für bessere Auswertung kann zusätzlich sinnvoll sein:

• ended_at
• ended_reason

Das ist für MVP nicht zwingend, aber nützlich.

Migrationen

Benötigte Migrationen:

Migration 1

• neue Tabelle falukant_data.relationship_state

Migration 2

• neue Spalten an falukant_data.child_relation

Migration 3 optional

• Backfill für bestehende Beziehungen

Regeln für Backfill:

• bei relationshipType = married
  • marriage_satisfaction = 55
• bei relationshipType = lover
  • lover_role = lover
  • affection = 50
  • visibility = 20
  • discretion = 45
  • maintenance_level = 50
  • status_fit = 0
  • monthly_base_cost = 30

Sequelize-Modelle

1. Neues Modell

Neue Datei:

• relationship_state.js

2. Associations

In associations.js:

• Relationship.hasOne(RelationshipState, { foreignKey: 'relationshipId', as: 'state' })
• RelationshipState.belongsTo(Relationship, { foreignKey: 'relationshipId', as: 'relationship' })

3. ChildRelation-Erweiterung

In child_relation.js:

• legitimacy
• birthContext
• publicKnown

Backend-Service-Konzept

Hauptort:

• falukantService.js

1. Neue interne Hilfsmethoden

Empfohlene neue interne Methoden:

• getRankGroup(titleLabelTr)
• calculateLoverMonthlyCost(relationship, state, character)
• calculateMarriageDelta(relationship, state, character, spouseCharacter, context)
• calculateReputationDeltaFromLover(relationship, state, character, context)
• calculateDailyVisibilityDelta(state, context)
• calculateDailyDiscretionDelta(state, context)
• calculateDailyScandalChance(relationship, state, character, context)
• calculateMonthlyPregnancyChance(relationship, state, charA, charB)
• applyLoverMonthlyCosts(transactionDate?)
• applyLoverDailyEffects(transactionDate?)
• processLoverBirths(transactionDate?)
• triggerLoverScandalEvent(...)

2. Erweiterung getFamily

Die Familienausgabe in falukantService.js muss lovers detaillierter liefern.

Zusätzliche API-Felder je Lover:

• relationshipId
• role
• affection
• visibility
• discretion
• maintenanceLevel
• statusFit
• monthlyCost
• reputationEffect
• marriageEffect
• acknowledged
• canBecomePublic
• riskState

Zusätzliche API-Felder für Ehe:

• marriageSatisfaction
• marriageState
  • stable
  • strained
  • crisis

3. Neue Service-Aktionen

Für spätere UI-Steuerung:

• setLoverMaintenance(hashedUserId, relationshipId, maintenanceLevel)
• setLoverDiscretionMode(hashedUserId, relationshipId, mode)
• acknowledgeLover(hashedUserId, relationshipId)
• endLoverRelationship(hashedUserId, relationshipId)
• giftLover(hashedUserId, relationshipId, giftType)

Diese Methoden müssen in Stufe 1 noch nicht voll sichtbar sein, sollten aber im Konzept vorgesehen werden.

API-Konzept

1. Bestehende Family-Route erweitern

Bestehender Endpunkt:

• GET /api/falukant/family

Erweitern um:

• marriageSatisfaction
• lovers mit Detailfeldern
• householdTension optional

2. Neue Endpunkte

Empfohlene neue Endpunkte:

• POST /api/falukant/family/lover/:relationshipId/maintenance
• POST /api/falukant/family/lover/:relationshipId/discretion
• POST /api/falukant/family/lover/:relationshipId/acknowledge
• POST /api/falukant/family/lover/:relationshipId/end
• POST /api/falukant/family/lover/:relationshipId/gift

3. Antwortschema

Jede mutierende Aktion sollte zurückgeben:

• aktualisierte Liebhaber-Daten
• aktualisierte Ehe-Zufriedenheit
• aktualisierte Geldmenge
• aktualisiertes Ansehen
• optionale Nachricht für UI

Daemon-Integration

1. Tatsächliche Daemon-Lage

Der operative Daemon ist nicht Teil dieses Projekts. Dieses Projekt stellt daher:

• Datenmodell
• Backfill
• Family-API
• UI-Anzeige
• Fach- und Übergabedokumente

Der externe Daemon ist zuständig für:

• Daily Tick
• Monthly Tick
• Geldabbuchung
• Ansehensänderung
• Ehezufriedenheit
• Kinder aus Liebschaften

Die operative Übergabe dafür steht in:

• FALUKANT_LOVERS_DAEMON_HANDOFF.md

2. Neue Benachrichtigungstypen

Es sollten neue Falukant-Benachrichtigungen eingeführt werden:

• loverCostPaid
• loverUnderfunded
• loverRumor
• loverScandal
• loverChildHidden
• loverChildKnown
• marriageCrisis

Kindererzeugung technisch

1. Vorhandene Strukturen nutzen

Neue Kinder aus Liebschaften sollen dieselbe Charakter- und ChildRelation-Logik nutzen wie bestehende Kinder.

2. Erzeugungsort

Die Kind-Erzeugung soll vom externen Daemon ausgeführt oder angestoßen werden. Dieses Backend muss dafür die Zielstruktur stabil bereitstellen.

3. Anerkennung eines Kindes

Spätere Service-Methode:

• acknowledgeLoverChild(hashedUserId, childCharacterId)

Wirkung:

• legitimacy = acknowledged_bastard
• publicKnown = true
• Ansehen anpassen
• Ehe-Zufriedenheit anpassen

Frontend-Konzept

Hauptansicht:

• FamilyView.vue

1. Ehebereich erweitern

Im Ehe- oder Partnerbereich anzeigen:

• Ehe-Zufriedenheit
• textlicher Status
  • stabil
  • angespannt
  • krisenhaft
• kurzer Hinweis, ob aktive Liebschaften die Ehe belasten oder stabilisieren

2. Lovers-Bereich ausbauen

Aktuell existiert nur Name plus Zuneigung. Neu anzeigen:

• Rolle
• Zuneigung
• Sichtbarkeit
• Diskretion
• Unterhaltsniveau
• Monatskosten
• aktueller Einfluss auf Ansehen
• aktueller Einfluss auf Ehe-Zufriedenheit
• Risikostatus

3. Aktionen im UI

Pro Liebschaft:

• Unterhalt erhöhen oder senken
• Diskretion priorisieren
• öffentlich anerkennen
• beschenken
• Beziehung beenden

4. Farbliche Zustände

Grün

• geordnet
• geringe Sichtbarkeit
• Ehe stabil oder neutral

Gelb

• steigende Sichtbarkeit
• mittlere Ehebelastung
• Unterhalt knapp

Rot

• Skandalrisiko hoch
• Ehekrise
• unterfinanziert
• Kind öffentlich geworden

5. Kinder aus Liebschaften in FamilyView

Im Kinderbereich kenntlich machen:

• legitimes Kind
• uneheliches verborgenes Kind
• anerkanntes uneheliches Kind

Es braucht keine sensationelle Darstellung, aber klare Kennzeichnung.

I18n-Bedarf

Benötigte neue Übersetzungsbereiche in:

• frontend/src/i18n/locales/de/falukant.json
• frontend/src/i18n/locales/en/falukant.json
• frontend/src/i18n/locales/es/falukant.json

Neue Schlüsselgruppen:

• falukant.family.marriageSatisfaction.*
• falukant.family.lovers.role.*
• falukant.family.lovers.visibility
• falukant.family.lovers.discretion
• falukant.family.lovers.maintenance
• falukant.family.lovers.monthlyCost
• falukant.family.lovers.reputationEffect
• falukant.family.lovers.marriageEffect
• falukant.family.lovers.risk.*
• falukant.family.children.legitimacy.*

Admin- und Debug-Bedarf

Für Entwicklung und Balancing später sinnvoll:

• Admin-Sicht auf relationship_state
• Möglichkeit, marriageSatisfaction, visibility, discretion, maintenanceLevel zu setzen
• optionales Debug-Tool zum Simulieren von 30 Tagen

Das sollte nicht Teil des ersten Spieler-UI sein, aber früh mitgedacht werden.

Technische Risiken

1. Tick-Duplikate

Wenn Daily- oder Monthly-Ticks mehrfach laufen, werden Kosten und Ansehen doppelt verrechnet.

Gegenmaßnahme:

• last_daily_processed_at
• last_monthly_processed_at
• idempotente Verarbeitung pro Beziehung und Tag/Monat

2. Dateninkonsistenz

Eine lover-Beziehung ohne relationship_state würde Berechnungen brechen.

Gegenmaßnahme:

• beim Lesen fehlende States automatisch erzeugen
• oder beim Start ein Reparaturskript

3. Kindererzeugung doppelt

Bei konkurrierenden Prozessen könnte ein Kind zweimal entstehen.

Gegenmaßnahme:

• Transaktion
• Sperre pro Beziehung und Tick
• eindeutige Monatsverarbeitung

Empfohlene Implementierungsreihenfolge

Paket 1

• Migrationen
• Modell RelationshipState
• Associations
• Backfill

Paket 2

• Family-Service erweitert lesen
• API-Felder ausliefern
• UI in FamilyView lesend erweitern

Paket 3

• Übergabe Daily Tick
• Übergabe Monthly Tick
• Abstimmung zu Geldabbuchung
• Abstimmung zu Ansehen und Ehezufriedenheit

Paket 4

• Kinder aus Liebschaften
• Benachrichtigungen
• UI-Aktionen

Paket 5

• Ereignisse
• spätere Dienerschaft
• Balancing-Phase

Definition of Done

Die technische Erstumsetzung ist abgeschlossen, wenn:

1. lover-Beziehungen Detailzustand besitzen
2. Ehezufriedenheit technisch existiert
3. Family-API alle neuen Daten ausliefert
4. Daily- und Monthly-Tick für den externen Daemon vollständig beschrieben sind
5. Monatskosten- und Statuslogik extern ausführbar definiert sind
6. Kinder aus Liebschaften technisch entstehen können
7. FamilyView die neuen Daten sichtbar macht
8. weibliche und männliche Spielfiguren regelgleich behandelt werden