yourpart3/docs/FALUKANT_DEBTORS_PRISON_DAEMON_SPEC.md

Falukant: Schuldturm und Pfändung - Daemon-Spezifikation

Dieses Dokument beschreibt die Umsetzung des Schuldturm-Systems im externen Daemon.

Wichtig:

• Die projektseitigen DB-Felder, API-Erweiterungen, UI-Warnungen und Aktionssperren sind bereits umgesetzt.
• Der Daemon ist die führende Quelle für:
  • Verzugstage
  • Eintritt in den Schuldturm
  • Pfändung und Verwertung
  • soziale Folgen
  • Freilassung

1. Bereits vorhandene Datenbasis

Bereits im Projekt vorhanden:

• falukant_data.credit
• falukant_data.debtors_prism
• falukant_data.user_house
  • inkl. household_tension_score
  • inkl. household_tension_reasons_json
• Familien-/Liebschaftsdaten in:
  • falukant_data.relationship
  • falukant_data.relationship_state
  • falukant_data.child_relation

Bereits erweitert:

• debtors_prism.status
• debtors_prism.entered_at
• debtors_prism.released_at
• debtors_prism.debt_at_entry
• debtors_prism.remaining_debt
• debtors_prism.days_overdue
• debtors_prism.reason
• debtors_prism.creditworthiness_penalty
• debtors_prism.next_forced_action
• debtors_prism.assets_seized_json
• debtors_prism.public_known

Es sind für den Daemon derzeit keine weiteren DB-Änderungen nötig.

2. Grundregel

Ein Charakter kommt in den Schuldturm, wenn:

• mindestens ein aktiver Kredit offen ist
• fällige Kreditbedienung ausbleibt
• und days_overdue >= 3

Der Daemon prüft dies im Daily-Tick.

3. Zustände

debtors_prism.status verwendet mindestens:

• delinquent
• imprisoned
• released

Bedeutung:

• delinquent: Kreditverzug, aber noch nicht im Schuldturm
• imprisoned: im Schuldturm, Verwertung läuft
• released: historischer abgeschlossener Fall

4. Daily-Tick

Der Daily-Tick prüft pro Falukant-Nutzer:

1. aktive Kredite
2. verbleibende Schuld
3. geleistete Bedienung seit letztem Tick
4. neue Verzugstage
5. Schuldturm-Eintritt
6. laufende soziale Folgen
7. Verwertungsschritt

4.1 Verzugstage

Regel:

• wenn offene Schuld vorhanden und fällige Bedienung ausbleibt:
  • days_overdue += 1
• wenn Kreditpflicht erfüllt wurde:
  • days_overdue = 0
  • falls nicht im Schuldturm

Wenn noch kein aktiver debtors_prism-Eintrag existiert:

• bei erstem Verzug debtors_prism anlegen mit
  • status = 'delinquent'
  • days_overdue = 1
  • remaining_debt = aktuelle offene Schuld
  • next_forced_action = 'reminder'

4.2 Warnstufen

Bei Verzug:

• Tag 1:
  • next_forced_action = 'reminder'
  • Event falukantUpdateDebt mit reason: 'delinquency'
• Tag 2:
  • next_forced_action = 'final_warning'
  • Event falukantUpdateDebt mit reason: 'delinquency'
• Tag 3:
  • Schuldturm-Eintritt

Für Warnstufen senden:

• falukantUpdateDebt
• zusätzlich falukantUpdateStatus

5. Eintritt in den Schuldturm

Bei days_overdue >= 3:

• status = 'imprisoned'
• entered_at = now()
• released_at = null
• debt_at_entry = aktuelle offene Schuld
• remaining_debt = aktuelle offene Schuld
• reason = 'credit_default'
• creditworthiness_penalty += 45
• next_forced_action = 'asset_seizure'
• public_known = true

5.1 Sofortfolgen bei Eintritt

Einmalig anwenden:

• Reputation deutlich senken
  • Empfehlung: -12
• marriage_satisfaction senken
  • Empfehlung: -10
• household_tension_score erhöhen
  • Empfehlung: +15
• household_tension_reasons_json um debtorsPrison ergänzen

Zusätzlich:

• aktive Liebhaber/Mätressen sichtbar destabilisieren
  • mindestens affection -= 4
• Kreditaufnahme und aktive Falukant-Aktionen bleiben projektseitig bereits gesperrt

Bei Eintritt senden:

• falukantUpdateDebt
  • reason: 'debtors_prison_entered'
• falukantUpdateStatus
• falukantUpdateFamily
  • reason: 'daily'
• falukantHouseUpdate
• falukantBranchUpdate

6. Verwertung / Pfändung

Die Verwertung läuft nicht alles auf einmal, sondern schrittweise pro Tick.

Reihenfolge:

1. freies Geld
2. Fahrzeuge
3. Waren / Lagerbestände
4. Haus
5. Niederlassungen

Ziel:

• remaining_debt schrittweise senken
• Fortschritt im UI sichtbar machen

6.1 Geld

Wenn falukant_user.money > 0:

• direkt zur Schuld tilgen
• remaining_debt -= eingezogener_betrag

Events:

• falukantUpdateDebt
  • reason: 'asset_seizure'
• falukantUpdateStatus

6.2 Fahrzeuge

Verkaufe zuerst:

• freie Fahrzeuge
• dann weniger wertvolle Typen
• keine Fahrzeuge in aktiven Transporten im selben Tick anfassen, falls technisch problematisch

Erlös:

• Empfehlung: vehicle_type.cost * condition_factor * 0.55

Zusätzlich in assets_seized_json protokollieren:

• Typ
• Anzahl
• Erlös

Events:

• falukantUpdateDebt
  • reason: 'vehicle_liquidation'
• falukantUpdateStatus

6.3 Waren / Lager

Verwertbare Güter:

• Lagerbestände
• Inventar
• handelbare Waren

Erlös:

• Empfehlung: Marktwert mit Abschlag von 35% bis 50%

Events:

• falukantUpdateDebt
  • reason: 'asset_seizure'
• falukantUpdateStatus
• falukantBranchUpdate

6.4 Haus

Wenn Restschuld nach Geld/Fahrzeugen/Waren weiter hoch ist:

• Haus pfänden
• Spieler auf niedrigeres Haus oder Minimalhaus zurücksetzen
• Dienerschaft reduzieren
• household_order senken

Events:

• falukantUpdateDebt
  • reason: 'house_seizure'
• falukantHouseUpdate
• falukantUpdateStatus
• falukantUpdateFamily
  • reason: 'daily'

6.5 Niederlassungen

Wenn weiter nicht gedeckt:

• Niederlassungen schließen
• zuerst niedrige Stufe / niedriger Wert
• Hauptniederlassung nur als letzter Schritt

Events:

• falukantUpdateDebt
  • reason: 'branch_closure'
• falukantBranchUpdate
• falukantUpdateStatus

7. Laufende soziale Folgen im Schuldturm

Solange status = 'imprisoned':

• täglicher Reputationsmalus
  • Empfehlung: -2
• zusätzliche creditworthiness_penalty += 1 pro Tag
• marriage_satisfaction -= 1
• household_tension_score += 2

Wenn aktive Liebschaften bestehen:

• affection -= 2
• bei niedriger Zuneigung oder hoher Sichtbarkeit kann Beziehung enden

Empfohlene Absprungregel:

• wenn affection <= 30 oder months_underfunded >= 2
  • Chance auf Beziehungsende prüfen
• bei repräsentativen Beziehungen zusätzlich höhere Absprungchance, wenn public_known = true

Events bei sozialen Folgewirkungen:

• falukantUpdateFamily
  • reason: 'daily'
• zusätzlich falukantUpdateStatus

8. Kreditwürdigkeit

Die UI rechnet bereits aus creditworthiness_penalty und Status einen sichtbaren Wert.

Der Daemon muss pflegen:

• creditworthiness_penalty
• status
• days_overdue

Empfehlung:

• Eintritt Schuldturm: +45
• pro weiterem Hafttag: +1
• Hauspfändung: zusätzlich +10
• Niederlassungsschließung: zusätzlich +8

9. Freilassung

Freilassung, wenn:

• keine relevante Restschuld mehr offen ist oder
• ein definierter Restwert unterschritten wird, falls ihr einen Bagatellgrenzwert wollt

Dann:

• status = 'released'
• released_at = now()
• next_forced_action = null
• days_overdue = 0
• remaining_debt = 0

Events:

• falukantUpdateDebt
  • reason: 'debtors_prison_released'
• falukantUpdateStatus
• falukantUpdateFamily
  • reason: 'daily'
• falukantHouseUpdate
• falukantBranchUpdate

Keine automatische vollständige soziale Heilung:

• Reputation bleibt reduziert
• Kreditwürdigkeit bleibt reduziert
• Familie/Haus bleiben in Folgezuständen

10. Event-Kommunikation zur UI

Der Daemon sendet als Primärevent:

{
  "event": "falukantUpdateDebt",
  "user_id": 123,
  "reason": "delinquency"
}

Mögliche reason:

• delinquency
• debtors_prison_entered
• asset_seizure
• vehicle_liquidation
• house_seizure
• branch_closure
• debtors_prison_released

10.1 Begleitevents

Je nach Folge zusätzlich:

• falukantUpdateStatus
• falukantHouseUpdate
• falukantBranchUpdate
• falukantUpdateFamily

10.2 Empfohlene Minimalregeln

• delinquency:
  • falukantUpdateDebt
  • falukantUpdateStatus
• debtors_prison_entered:
  • falukantUpdateDebt
  • falukantUpdateStatus
  • falukantUpdateFamily
  • falukantHouseUpdate
  • falukantBranchUpdate
• asset_seizure:
  • falukantUpdateDebt
  • falukantUpdateStatus
  • optional falukantBranchUpdate
• vehicle_liquidation:
  • falukantUpdateDebt
  • falukantUpdateStatus
• house_seizure:
  • falukantUpdateDebt
  • falukantUpdateStatus
  • falukantHouseUpdate
  • falukantUpdateFamily
• branch_closure:
  • falukantUpdateDebt
  • falukantUpdateStatus
  • falukantBranchUpdate
• debtors_prison_released:
  • falukantUpdateDebt
  • falukantUpdateStatus
  • falukantUpdateFamily
  • falukantHouseUpdate
  • falukantBranchUpdate

11. Idempotenz

Der Worker muss idempotent arbeiten.

Wichtig:

• Eintritt in den Schuldturm nicht mehrfach für denselben aktiven Fall auslösen
• Verwertungsschritte nur einmal je Asset anwenden
• released nicht erneut freisetzen

Empfehlung:

• pro Tick Transaktion
• pro Nutzer eine klare Reihenfolge
• Änderungen in assets_seized_json protokollieren

12. Mindestumsetzung für Version 1

Pflicht:

1. Verzugstage pflegen
2. Eintritt nach 3 Tagen
3. Status und Penalty schreiben
4. Geld zuerst einziehen
5. danach Fahrzeuge
6. Events senden

Danach:

7. Hauspfändung
8. Niederlassungsschließung
9. volle Familienfolgen

13. Hinweis an den Daemon

Die projektseitigen Grundlagen sind bereits umgesetzt:

• debtors_prism ist erweitert
• Bank-/Haus-/Familien-/Übersichts-UI reagiert auf den Status
• aktive Falukant-Aktionen werden im Backend bereits gesperrt, sobald inDebtorsPrison = true

Der Daemon muss daher vor allem die Zustände und Folgen zuverlässig schreiben und die dokumentierten Events senden.