# 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](/mnt/share/torsten/Programs/YourPart3/docs/FALUKANT_LOVERS_CONCEPT.md)
- [FALUKANT_LOVERS_DAEMON_SPEC.md](/mnt/share/torsten/Programs/YourPart3/docs/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](/mnt/share/torsten/Programs/YourPart3/backend/models/falukant/data/relationship_state.js)

## 2. Associations

In [associations.js](/mnt/share/torsten/Programs/YourPart3/backend/models/associations.js):

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

## 3. ChildRelation-Erweiterung

In [child_relation.js](/mnt/share/torsten/Programs/YourPart3/backend/models/falukant/data/child_relation.js):

- `legitimacy`
- `birthContext`
- `publicKnown`

## Backend-Service-Konzept

Hauptort:

- [falukantService.js](/mnt/share/torsten/Programs/YourPart3/backend/services/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](/mnt/share/torsten/Programs/YourPart3/backend/services/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](/mnt/share/torsten/Programs/YourPart3/docs/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](/mnt/share/torsten/Programs/YourPart3/frontend/src/views/falukant/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](/mnt/share/torsten/Programs/YourPart3/frontend/src/i18n/locales/de/falukant.json)
- [frontend/src/i18n/locales/en/falukant.json](/mnt/share/torsten/Programs/YourPart3/frontend/src/i18n/locales/en/falukant.json)
- [frontend/src/i18n/locales/es/falukant.json](/mnt/share/torsten/Programs/YourPart3/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