yourpart3/docs/FALUKANT_UI_WEBSOCKET.md

# Falukant: UI-Anpassung – WebSocket & Familie / Liebschaften

Dieses Dokument beschreibt die Nachrichten, die der externe Falukant-Daemon für Familien-, Ehe- und Liebschaftsänderungen sendet, damit die UI gezielt reagieren kann.

Transport:
- Alle Clients erhalten denselben Broadcast.
- Die UI muss nach `user_id` filtern und nur Events für die eingeloggte Session verarbeiten.

## 1. Übersicht der Events

| `event` | Pflichtfelder | Typische UI-Reaktion |
|---------|----------------|----------------------|
| `falukantUpdateFamily` | `user_id`, `reason` | Gezielter Refresh von Familie, Liebschaften und je nach `reason` auch Geld oder Ruf |
| `falukantUpdateStatus` | `user_id` | Allgemeiner Falukant-Status-/Spielstands-Refresh |
| `children_update` | `user_id` | Kinderliste und Familienansicht aktualisieren |
| `falukant_family_scandal_hint` | `relationship_id` | Optionaler Hinweis oder Logeintrag; kein `user_id` |

## 2. JSON-Payloads

### 2.1 `falukantUpdateFamily`

```json
{
  "event": "falukantUpdateFamily",
  "user_id": 123,
  "reason": "daily"
}
```

`reason` ist immer genau einer dieser festen Strings:
- `daily`
- `monthly`
- `scandal`
- `lover_birth`

Es gibt keine weiteren `reason`-Werte.

### 2.2 `falukantUpdateStatus`

```json
{
  "event": "falukantUpdateStatus",
  "user_id": 123
}
```

Dieses Event wird typischerweise direkt nach `falukantUpdateFamily` mit derselben `user_id` gesendet.

### 2.3 `children_update`

```json
{
  "event": "children_update",
  "user_id": 123
}
```

Dieses Event tritt bei Geburt aus einer Liebschaft auf, meist zusammen mit:
- `falukantUpdateFamily` mit `reason: "lover_birth"`
- `falukantUpdateStatus`

### 2.4 `falukant_family_scandal_hint`

```json
{
  "event": "falukant_family_scandal_hint",
  "relationship_id": 456
}
```

Hinweis:
- Dieses Event enthält kein `user_id`.
- Die UI kann es ignorieren oder optional nur für Log-/Toast-Zwecke verwenden.
- Die eigentliche nutzerbezogene Aktualisierung läuft über `falukantUpdateFamily` mit `reason: "scandal"`.

## 3. Fachliche Bedeutung von `reason`

### `reason: "daily"`

`daily` ist der Sammelgrund für tägliche Änderungen im Familien- und Liebschaftssystem.

Darunter fallen insbesondere:
- tägliche Drift und Änderung der Ehezufriedenheit
- Ehe-Buffs und temporäre Zähler wie Geschenk-, Fest- oder Haus-Effekte
- tägliche Liebschaftslogik für aktive Beziehungen
- Rufverlust bei zwei oder mehr sichtbaren Liebschaften
- Zufalls-Mali wie Gerücht oder Tadel

Wichtig:
- Es gibt kein separates Event für „nur Ehe-Buff“.
- Es gibt kein separates Event für „nur zwei sichtbare Liebschaften“.
- Es gibt kein separates Event für „nur Gerücht/Tadel“.
- Alles davon erscheint in der UI ausschließlich als `falukantUpdateFamily` mit `reason: "daily"`.

### `reason: "scandal"`

`scandal` wird zusätzlich zu einem gelungenen Skandalwurf gesendet.

Typischer Ablauf:
- optional `falukant_family_scandal_hint`
- `falukantUpdateFamily` mit `reason: "scandal"`
- `falukantUpdateStatus`

Danach kann für denselben Nutzer am selben Tag zusätzlich noch `daily` folgen.

### `reason: "monthly"`

`monthly` steht für Monatsverarbeitung, insbesondere:
- laufende Kosten
- Unterversorgung
- Geldänderungen

### `reason: "lover_birth"`

`lover_birth` signalisiert ein neues Kind aus einer Liebschaft.

Meist folgen zusammen:
- `falukantUpdateFamily` mit `reason: "lover_birth"`
- `children_update`
- `falukantUpdateStatus`

## 4. Empfohlene Handler-Logik

```text
onMessage(json):
  if json.user_id exists and json.user_id != currentUserId:
    return

  switch json.event:
    case "falukantUpdateStatus":
      refreshPlayerStatus()
      return

    case "children_update":
      refreshChildrenAndFamilyView()
      return

    case "falukantUpdateFamily":
      switch json.reason:
        case "daily":
          refreshFamilyAndRelationships()
          refreshReputationIfNeeded()
          break
        case "monthly":
          refreshMoney()
          refreshFamilyAndRelationships()
          break
        case "scandal":
          showScandalToastOptional()
          refreshFamilyAndRelationships()
          refreshReputationIfNeeded()
          break
        case "lover_birth":
          refreshChildrenAndFamilyView()
          break
      return

    case "falukant_family_scandal_hint":
      // optional: nur als Hinweis verarbeiten
      return
```

## 5. Deduplizierung

Am selben Tag kann ein Nutzer mehrere relevante Events erhalten, zum Beispiel:
- `scandal`
- danach `daily`
- danach `falukantUpdateStatus`

Die UI sollte deshalb:
- Refreshes bündeln oder entprellen
- idempotente Reloads verwenden
- nicht davon ausgehen, dass jeder fachliche Effekt einen eigenen `reason` hat

## 6. Welche Daten sollten neu geladen werden?

| Situation | Sinnvolle Reaktion |
|-----------|--------------------|
| Jede `falukantUpdateFamily` | Family-/Relationship-Daten neu laden |
| `reason: "monthly"` | Family-Daten plus Geld/Status neu laden |
| `reason: "daily"` | Family-Daten neu laden, bei Bedarf auch Ruf-/Statusdaten |
| `reason: "scandal"` | Family-Daten plus Ruf-/Statusdaten neu laden |
| `children_update` / `lover_birth` | Kinderdaten und FamilyView neu laden |

## 7. Sonderfälle

| Fall | Verhalten |
|------|-----------|
| NPC ohne `user_id` | Keine nutzerbezogenen Family-Socket-Events |
| Mehrere Events kurz hintereinander | Normal; UI sollte damit robust umgehen |
| Nur `falukantUpdateStatus` ohne Family-Event | Kann von anderen Falukant-Workern kommen |