yourpart-daemon/docs/FALUKANT_UI_WEBSOCKET.md

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)
falukantUpdateProductionCertificate	user_id, reason, old_certificate, new_certificate	Produkte / Produktions-UI / Zertifikat neu laden (nach Recalc, ca. 1×/Min., oder Bankrott)
children_update	user_id	Kinderliste / FamilyView aktualisieren
falukant_family_scandal_hint	relationship_id	Optional: Toast, Log – kein user_id (siehe unten)
falukantUpdateChurch	user_id, reason	Kirchenämter: Bewerbungen, Ernennungen (PoliticsWorker)

Siehe auch: FALUKANT_CHURCH_DAEMON.md.

---

2. JSON-Payloads (exakt)

2.1 falukantUpdateFamily

{
  "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; u. a. marriage_public_stability, household_tension_score	Family-API + ggf. Charakter/Ansehen/Haus neu laden
monthly	Kalender-monthly (Liebschafts-Monatsmarkierung / selten) oder Dienerschaft zahlt Monatstick: Geld (servants_monthly)	Geld + Family-State neu laden
lover_installment	Alle 2 h: 1/12 Liebschafts-Unterhalt bzw. Unterversorgung (money_history: lover maintenance)	Geld + 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.1a falukantUpdateChurch

{
  "event": "falukantUpdateChurch",
  "user_id": 123,
  "reason": "applications"
}

reason:

reason	Bedeutung	UI
applications	Spieler ist kirchlicher Vorgesetzter: offene Bewerbungen warten	Bewerbungslisten / supervised applications
npc_decision	NPC-Vorgesetzter hat zugesagt (Bewerber ist oft Spielercharakter)	Ämter + Bewerbungen
appointment	Auto-Annahme alter NPC-Supervisor-Bewerbung (36 h)	Ämter + Status
vacancy_fill	Interimsbesetzung (selten; Bewerber kann Spieler sein)	Ämter + freie Positionen
promotion	(reserviert / zukünftig)	—

Immer zusätzlich mit falukantUpdateStatus (gleiche user_id).

2.2 falukantUpdateStatus

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

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

2.3 falukantUpdateProductionCertificate

{
  "event": "falukantUpdateProductionCertificate",
  "user_id": 123,
  "reason": "daily_recalculation",
  "old_certificate": 2,
  "new_certificate": 3
}

• reason: in der ersten Version fest daily_recalculation (inkl. Bankrott-Herabstufung, falls so umgesetzt).
• Danach sendet der Daemon falukantUpdateStatus mit derselben user_id (wie bei anderen Falukant-Events).

2.4 children_update

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

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

2.5 falukant_family_scandal_hint

{
  "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)

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

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

    case "falukantUpdateProductionCertificate":
      refreshProductsAndProductionUi()      // Zertifikat / erlaubte Produkte
      return

    case "children_update":
      refreshChildrenAndFamilyView()
      return

    case "falukantUpdateFamily":
      switch json.reason:
        case "daily":
          refreshFamilyAndRelationships()
          refreshCharactersReputationIfNeeded()
          break
        case "monthly":
          refreshMoney()
          refreshFamilyAndRelationships()
          break
        case "lover_installment":
          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 (Dienerschaft o. ä.), Family-State
reason: lover_installment	Geld + Liebschafts-State (Unterhalt/Unterversorgung)
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.

---

Transportüberfälle (raid_transport)

Event	Payload (Auszug)
falukantTransportRaid	user_id (Opfer), reason: transport_raided
falukantUndergroundUpdate	user_id (Auftraggeber), reason: raid_repelled, raid_success, raid_partial_success, raid_loot_stored
falukantUpdateStatus / falukantBranchUpdate	beide Seiten nach Überfall

Daemon: src/worker/falukant_transport_raid.rs, Doku: docs/FALUKANT_TRANSPORT_RAID_DAEMON.md.

---

6. Bezug zum Code (YpDaemon)

• Worker: src/worker/falukant_family.rs
• Kirche: src/worker/politics.rs (falukantUpdateChurch)
• SQL-Konstanten: src/worker/sql.rs (Abschnitt Falukant Familie)
• Schema: migrations/001_falukant_family_lovers.sql, 006_falukant_lover_installments.sql (Unterhalt 12×/Tag)
• 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.