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

Dieses Dokument beschreibt die **Nachrichten**, die der **YpDaemon** (`FalukantFamilyWorker`) über den WebSocket-Broadcast sendet, damit die **UI gezielt** reagieren kann (Refresh, Toasts, Family-Ansicht).

> **Transport:** Alle Clients erhalten denselben Broadcast. Die UI sollte Nachrichten **nach `user_id` filtern** (nur Events anzeigen/verarbeiten, die zur eingeloggten Session passen).

---

## 1. Übersicht der Events

| `event` | Pflichtfelder | Typische UI-Reaktion |
|---------|----------------|----------------------|
| `falukantUpdateFamily` | `user_id`, `reason` | Gezielter Refresh Familie/Liebe/Geld je nach `reason` |
| `falukantUpdateStatus` | `user_id` | Allgemeiner Status-/Spielstand-Refresh (wie bisher) |
| `children_update` | `user_id` | Kinderliste / FamilyView aktualisieren |
| `falukant_family_scandal_hint` | `relationship_id` | Optional: Toast, Log – **kein** `user_id` (siehe unten) |

---

## 2. JSON-Payloads (exakt)

### 2.1 `falukantUpdateFamily`

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

**`reason`** ist immer einer der folgenden **festen** Strings:

| `reason` | Bedeutung (Daemon) | Empfehlung UI |
|----------|---------------------|---------------|
| `daily` | Daily-Tick: Liebschafts-/Ehe-/Ansehens-Logik für den Tag | Family-API + ggf. Charakter/Ansehen neu laden |
| `monthly` | Monthly-Tick: Kosten, Unterversorgung, Monatsstand | **Geld** (`falukant_user.money`) + Family-State neu laden |
| `scandal` | Skandal-Ereignis (zusätzlich zu `daily` möglich) | Kurzer Hinweis / Eintrag „Skandal“; Family + Ruf |
| `lover_birth` | Uneheliches Kind angelegt | Wie `children_update`, plus Eltern-Story |

### 2.2 `falukantUpdateStatus`

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

Kommt **typischerweise direkt nach** `falukantUpdateFamily` mit derselben `user_id` (gemeinsamer Refresh).

### 2.3 `children_update`

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

Tritt bei **Geburt aus Liebschaft** auf; oft zusammen mit `falukantUpdateFamily` (`reason: lover_birth`) und `falukantUpdateStatus`.

### 2.4 `falukant_family_scandal_hint`

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

- **Kein** `user_id` – Betroffene erkennst du nur über die **Beziehung** (Backend: `relationship.id` → Charaktere laden) oder du ignorierst das Event und verlässt dich auf `falukantUpdateFamily` mit `reason: scandal` für deine Nutzer.

---

## 3. Empfohlene Handler-Logik (Pseudo)

```text
onMessage(json):
  if json.user_id != currentUserId: return   // Broadcast filtern

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

    case "children_update":
      refreshChildrenAndFamilyView()
      return

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

    case "falukant_family_scandal_hint":
      // optional: relationship_id → Detail-Modal / Log
      return
```

**Hinweis:** Am selben Tag kann ein Nutzer **`scandal`** und danach **`daily`** erhalten – UI kann **deduplizieren** (z. B. nur ein voller Refresh) oder beide verarbeiten (idempotente API-Calls).

---

## 4. Welche Backend-Daten neu laden?

| Situation | Sinnvolle Endpunkte / Daten (konzeptionell) |
|-----------|---------------------------------------------|
| Jede `falukantUpdateFamily` | Family-/Relationship-API mit `relationship_state`, Ehe (`married`/`engaged`/`wooing`) |
| `reason: monthly` | **Geld** des Users, ggf. Kredit/Log |
| `reason: daily` / `scandal` | Ansehen (`character.reputation`), Sichtbarkeit/Diskretion der Liebschaften |
| `children_update` / `lover_birth` | `child_relation` inkl. `legitimacy`, `birth_context`, `public_known` |

Konkrete Routen stehen im **YourPart3**-Backend; das Frontend sollte eine zentrale Funktion `refreshFamilyContext(userId)` kapseln.

---

## 5. Sonderfälle

| Fall | Verhalten |
|------|-----------|
| Charakter ohne `user_id` (NPC) | **Keine** Socket-Events für diesen Charakter – nur Spieler mit `falukant_user` erhalten `user_id`-Events. |
| Mehrere Events hintereinander | Normal; Requests sollten **idempotent** sein (mehrfaches Laden ok). |
| Nur `falukantUpdateStatus` ohne Family | Kann von **anderen** Workern kommen – nicht nur Familie. |

---

## 6. Bezug zum Code (YpDaemon)

- Worker: `src/worker/falukant_family.rs`
- SQL-Konstanten: `src/worker/sql.rs` (Abschnitt Falukant Familie)
- Schema: `migrations/001_falukant_family_lovers.sql`
- Daemon-Handoff (technisch): `docs/FALUKANT_DAEMON_HANDOFF.md`

---

## 7. Checkliste UI-Integration

- [ ] WebSocket-Handler: `user_id` mit Session abgleichen  
- [ ] Auf `falukantUpdateFamily` reagieren und **`reason`** auswerten  
- [ ] `falukantUpdateStatus` weiter nutzen (globaler Refresh)  
- [ ] `children_update` + `lover_birth`: Kinder-Ansicht  
- [ ] Optional: `falukant_family_scandal_hint` mit `relationship_id`  
- [ ] Optional: Deduplizierung bei `scandal` + `daily` am selben Tag  

Damit kannst du die Oberfläche **gezielt** an die Daemon-Events anbinden, ohne jedes Mal den vollen Spielstand blind zu aktualisieren.