yourpart3/docs/FALUKANT_CHURCH_ADVANCEMENT_DAEMON_SPEC.md

# Falukant: Kirchenämter, Aufstieg und NPC-Besetzung

Dieses Dokument beschreibt das Zielmodell für das Kirchensystem in Falukant. Es fokussiert auf drei Probleme:

- Spieler können sich derzeit nicht sinnvoll auf höhere kirchliche Ämter bewerben.
- Nicht alle Ämter werden besetzt.
- NPCs sollen sich ebenfalls bewerben und Ämter aktiv besetzen.

Der Daemon soll die laufende Besetzung und Beförderung übernehmen. Der eigentliche Antrag des Spielers bleibt ein aktiver Spielzug in der UI.

## 1. Zielbild

Kirchliche Ämter sollen ein lebendes Hierarchiesystem sein:

- Leere Ämter werden nach und nach besetzt.
- Spieler und NPCs konkurrieren um offene Positionen.
- Höhere Amtsträger entscheiden über untere Ebenen.
- Wo kein Spieler-Entscheider vorhanden ist, übernimmt ein NPC-Amtsträger die Entscheidung.
- Wo ganze Hierarchieebenen leer sind, darf das System kontrolliert von unten nach oben oder über Interimslogik nachbesetzen.

## 2. Grundregeln

### 2.1 Bewerbung

- Ein Spieler beantragt ein Amt weiterhin aktiv über die UI.
- NPCs bewerben sich nicht per UI, sondern durch den Daemon.
- Es darf gleichzeitig mehrere Bewerber für dieselbe Position geben.
- Eine Bewerbung ist immer regionsbezogen.

### 2.2 Hierarchie

Kirchenämter bleiben über `church_office_type.hierarchy_level` geordnet.

Der normale Aufstiegspfad ist:

1. `lay-preacher`
2. `village-priest`
3. `parish-priest`
4. `dean`
5. `archdeacon`
6. `bishop`
7. `archbishop`
8. `cardinal`
9. `pope`

### 2.3 Bewerbung auf höhere Ämter

Der aktuelle Fehler "man kann sich nicht auf höhere Positionen bewerben als man gerade hat" soll ersetzt werden durch:

- Ein Charakter darf sich auf das nächsthöhere sinnvolle Amt bewerben.
- Zusätzlich darf ein Charakter sich auf ein höheres Amt bewerben, wenn sein bisher höchstes Kirchenamt die Mindestvoraussetzung erfüllt.
- Das System soll nicht nur aktuelle Ämter, sondern auch die bisher höchste kirchliche Laufbahn berücksichtigen.

Daraus folgt:

- Es reicht nicht, nur aktuelle `church_office` zu prüfen.
- Es muss ein Konzept von `highestChurchOfficeRankEver` geben.

## 3. Entscheidungsmodell für Bewerbungen

### 3.1 Grundsatz

Über eine Bewerbung entscheidet immer das direkt übergeordnete Amt.

Beispiele:

- Über `village-priest` entscheidet `parish-priest`.
- Über `parish-priest` entscheidet `dean`.
- Über `dean` entscheidet `archdeacon`.

### 3.2 Wenn der direkte Vorgesetzte fehlt

Falls das direkt übergeordnete Amt in der relevanten Aufsichtskette nicht besetzt ist:

- Das System sucht das nächsthöhere besetzte Amt.
- Falls überhaupt kein höheres Amt vorhanden ist, greift ein Interimsmodus.

Interimsmodus:

- Für die untersten Ebenen darf der Daemon nach Reputation und Eignung direkt besetzen.
- Für hohe Ämter oberhalb von `bishop` soll das nur sehr zurückhaltend geschehen.

## 4. NPC-Bewerbungen

### 4.1 Ziel

NPCs sollen das Kirchensystem lebendig halten und offene Ämter nach und nach füllen.

### 4.2 Wann NPCs sich bewerben

Der Daemon prüft täglich:

- offene Sitze pro Region und Amt
- vorhandene Spielerbewerbungen
- vorhandene NPC-Kandidaten

NPC-Bewerbungen entstehen bevorzugt wenn:

- ein Amt offen ist
- keine ausreichende Zahl an Bewerbungen existiert
- in der Region oder der Elternregion geeignete NPCs vorhanden sind

### 4.3 Geeignete NPCs

Ein NPC ist grundsätzlich geeignet, wenn:

- er lebt
- er nicht bereits ein gleiches oder höheres unvereinbares Kirchenamt innehat
- sein bisher höchstes Kirchenamt oder seine bisherige Laufbahn die Stufe plausibel macht
- seine Reputation ausreichend ist

Zusätzliche Faktoren für NPC-Eignung:

- Alter
- Gesundheit
- Adelstitel
- Reputation
- bestehendes Kirchenamt
- bisher höchstes Kirchenamt

## 5. Auswahl- und Beförderungslogik

### 5.1 Bewertungswert

Für jede Bewerbung wird ein Score berechnet:

`churchCandidateScore`

Bestandteile:

- bisher höchstes Kirchenamt
- aktuelles Kirchenamt
- Reputation
- Adelstitel
- Alter in idealem Bereich
- regionale Nähe
- ggf. geringe Bonuspunkte für lange Wartezeit

### 5.2 Entscheidung durch Spieler

Wenn der zuständige Vorgesetzte ein Spielercharakter ist:

- Die Bewerbung erscheint wie bisher in der UI.
- Der Spieler kann annehmen oder ablehnen.
- Solange eine Spielerentscheidung aussteht, entscheidet der Daemon nicht automatisch.

Optionaler Timeout:

- Nach längerer Untätigkeit darf später ein automatischer Verfall oder eine automatische Daemon-Entscheidung ergänzt werden.
- Das ist nicht Teil der ersten Ausbaustufe.

### 5.3 Entscheidung durch NPC

Wenn der zuständige Vorgesetzte ein NPC ist:

- Der Daemon entscheidet automatisch.
- Maßgeblich ist primär der Bewerber-Score.
- Zusätzlich wirkt die Reputation des NPC-Vorgesetzten als "Strengefaktor".

## 6. Reputation des NPC-Vorgesetzten

Wenn ein NPC ein Amt innehat, entscheidet er über die unter ihm liegende Position anhand von Reputation.

Das bedeutet:

- Ein angesehener NPC-Vorgesetzter bevorzugt reputationsstarke, standesgemäße und stabile Bewerber.
- Ein schwacher oder verrufener NPC-Vorgesetzter entscheidet unberechenbarer.

Empfohlenes Modell:

- `supervisorInfluence = supervisor.reputation / 100`
- je höher dieser Wert, desto stärker zählt der objektive Bewerber-Score
- bei niedriger Reputation steigt der Zufallsanteil

Praktische Wirkung:

- Hohe NPC-Reputation:
  - bessere, berechenbarere Besetzung
- Niedrige NPC-Reputation:
  - mehr Fehlbesetzungen
  - mehr schwankende Entscheidungen

## 7. Fehlende historische Kirchenlaufbahn

Damit ein Charakter sich später auf höhere Ämter bewerben kann, braucht das System mehr als nur aktuelle `church_office`.

Es wird deshalb ein persistierter Höchstwert benötigt:

- `highestChurchOfficeRankEver`

Empfehlung:

- eigener Wert am Charakter oder in einer Laufbahntabelle
- beim erstmaligen Erreichen eines höheren Kirchenamts aktualisieren
- bei Verlust des Amts nicht zurücksetzen

Ohne diesen Wert bleibt höherer Aufstieg nach Amtsverlust oder Umstrukturierung unzuverlässig.

## 8. Verfügbarkeit in der UI

Die UI soll später drei Dinge klar darstellen:

- aktuelle Ämter
- verfügbare Bewerbungen
- eigene höchste Kirchenlaufbahn

Zusätzlich sinnvoll:

- ob die Entscheidung durch einen Spieler oder NPC getroffen wird
- wer der zuständige Vorgesetzte ist
- ob eine Position automatisch nachbesetzt wird

## 9. Daemon-Aufgaben

Der Daemon soll täglich folgende Schritte ausführen:

### 9.1 Kirchenlage erfassen

- offene Sitze je `church_office_type` und Region zählen
- aktuelle Amtsträger laden
- Spielerbewerbungen laden
- NPC-Kandidaten bestimmen

### 9.2 NPC-Bewerbungen erzeugen

- für vakante Positionen fehlende NPC-Bewerbungen anlegen
- keine Doppelbewerbungen für dieselbe Position erzeugen

### 9.3 Bewerbungen bewerten

- Bewerber-Score berechnen
- zuständigen Vorgesetzten ermitteln
- falls NPC-Vorgesetzter: Entscheidung automatisch treffen
- falls Spieler-Vorgesetzter: Bewerbung offen lassen

### 9.4 Beförderungen und Besetzungen durchführen

- `church_office` anlegen oder aktualisieren
- alte widersprechende Bewerbungen schließen
- `highestChurchOfficeRankEver` aktualisieren

### 9.5 Sonderfall komplett leere Hierarchie

Wenn eine Hierarchiestufe samt Vorgesetzten fehlt:

- untere Ebene darf durch den Daemon interimistisch mit dem besten Kandidaten besetzt werden
- dies soll selten und regelgeleitet geschehen
- für hohe Spitzenämter deutlich restriktiver als für niedrige Ämter

## 10. Event-Kommunikation zwischen Daemon und UI

Neue oder präzisierte Events:

### 10.1 `falukantUpdateChurch`

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

Zulässige `reason`-Werte:

- `applications`
- `appointment`
- `promotion`
- `vacancy_fill`
- `npc_decision`

### 10.2 UI-Reaktion

- `applications`:
  - Bewerbungslisten neu laden
- `appointment`:
  - aktuelle Ämter und verfügbare Ämter neu laden
- `promotion`:
  - aktuelle Ämter, verfügbare Ämter, ggf. Sozialstatus/Ansehen neu laden
- `vacancy_fill`:
  - aktuelle Ämter und verfügbare Positionen neu laden
- `npc_decision`:
  - supervised applications und current positions neu laden

Zusätzlich kann weiterhin `falukantUpdateStatus` gesendet werden.

## 11. Backend-Anpassungen außerhalb des Daemons

Die Daemon-Logik allein reicht nicht. Das Backend muss angepasst werden:

- `getAvailableChurchPositions()` darf nicht nur aktuelle Ämter als Voraussetzung ansehen
- es muss die bisher höchste Kirchenlaufbahn berücksichtigen
- freie Positionen dürfen nicht nur an schon exakt lineare Amtshalter gebunden sein
- Spielerbewerbungen und NPC-Bewerbungen müssen dieselbe Bewertungslogik unterstützen

## 12. Empfohlene Umsetzung in Phasen

### Phase C1

- Konzept `highestChurchOfficeRankEver` einführen
- `getAvailableChurchPositions()` auf höchste Kirchenlaufbahn erweitern
- UI lesbar machen

### Phase C2

- NPC-Bewerbungen im Daemon
- automatische NPC-Entscheidungen

### Phase C3

- Interimsbesetzung für leere Hierarchien
- Feintuning von Reputation und Zufall

## 13. Wichtige Designentscheidungen

- Spieleraufstieg bleibt antragsbasiert
- NPCs füllen das System aktiv auf
- hohe Reputation eines NPC-Vorgesetzten verbessert die Besetzungsqualität
- höhere Ämter sollen auch dann erreichbar bleiben, wenn der Charakter das Voramt nicht mehr aktuell innehat
- komplett leere Kirchenstrukturen dürfen sich wieder aufbauen

## 14. Offene Punkte

- Wo genau `highestChurchOfficeRankEver` gespeichert wird
- ob es zusätzlich `highestChurchOfficeTypeEver` geben soll
- ob automatische NPC-Entscheidungen ein Timeout für offene Spielerbewerbungen bekommen
- wie stark Reputation gegenüber Adelstitel und Alter gewichtet wird