7043e8d90c
All checks were successful
Deploy yourpart (blue-green) / deploy (push) Successful in 2m56s
225 lines
8.3 KiB
Markdown
225 lines
8.3 KiB
Markdown
# 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`](./FALUKANT_CHURCH_DAEMON.md).
|
||
|
||
---
|
||
|
||
## 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; 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`
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
```json
|
||
{
|
||
"event": "falukantUpdateStatus",
|
||
"user_id": 123
|
||
}
|
||
```
|
||
|
||
Kommt **typischerweise direkt nach** `falukantUpdateFamily` mit derselben `user_id` (gemeinsamer Refresh).
|
||
|
||
### 2.3 `falukantUpdateProductionCertificate`
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
```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 "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.
|