# Falukant: Produktionszertifikate – Fach- und Integrationsspezifikation

## 1. Ziel

Das Produktionssystem soll stärker an den tatsächlichen gesellschaftlichen und fachlichen Fortschritt eines Spielers gebunden werden. Ein Spieler darf nur Produkte herstellen, deren Zertifikatsstufe seiner aktuellen Produktionsfreigabe entspricht.

Die Zertifikatsstufe steigt nicht sofort bei jeder Einzelaktion, sondern wird ausschließlich im externen Daemon einmal täglich neu berechnet.

Dieses Dokument beschreibt:

- das fachliche Modell der Produktionszertifikate
- die Faktoren für Aufstieg und Begrenzung
- die Daily-Berechnung im Daemon
- die Kommunikation zwischen Daemon und UI
- die Einbindung in die bestehende Backend-/UI-Struktur

Wichtig:

- Die nötigen DB-Grundlagen sind bereits vorhanden.
- Der Daemon muss keine neuen Schemaänderungen erwarten.
- Bestehende Felder wie `falukant_data.falukant_user.certificate` und `falukant_type.product.category` bleiben die führende Basis.

## 2. Bestehende technische Basis

Bereits vorhanden:

- `falukant_data.falukant_user.certificate`
  - aktuelle Produktionsfreigabe des Spielers
- `falukant_type.product.category`
  - erforderliche Zertifikatsstufe des Produkts
- `falukant_data.knowledge`
  - Produktwissen je Charakter und Produkt
- `falukant_data.production`
  - Produktionsvorgänge
- `falukant_data.character.reputation`
  - Ansehen des Spielercharakters
- `falukant_data.character.title_of_nobility`
  - Adelstitel
- `falukant_data.user_house.house_type_id`
  - aktuelles Haus
- politische und kirchliche Ämter
  - `falukant_data.political_office`
  - `falukant_data.church_office`
  - `falukant_log.political_office_history`
  - `falukant_type.church_office_type.hierarchy_level`

Bestehende Produktfreigabe im Backend:

- Produkte werden bereits in `falukantService.getProducts()` über `product.category <= user.certificate` gefiltert.

Das heißt:

- Zertifikatslogik muss nicht neu in die Produktionsfreigabe eingebaut werden.
- Es muss nur die Berechnung und Fortschreibung von `falukant_user.certificate` sauber geregelt werden.

## 3. Fachmodell

### 3.1 Zertifikatsstufen

Die Zertifikatsstufe bleibt eine einfache ganze Zahl im Feld `falukant_user.certificate`.

Empfohlene Bedeutung:

| Stufe | Bedeutung |
|------|-----------|
| `1` | Grundproduktion, einfache Güter |
| `2` | Gehobene Alltagsproduktion |
| `3` | Fortgeschrittene Manufaktur |
| `4` | Anspruchsvolle Qualitätsproduktion |
| `5` | Hochwertige oder prestigegebundene Produktion |

Wenn im Typensystem bereits höhere `product.category`-Werte existieren, gilt dieselbe Logik entsprechend weiter.

### 3.2 Führungsprinzip

Die Zertifikatsstufe ist kein reines Wissenslevel.

Sie soll ausdrücken, ob ein Haushalt/Betrieb gesellschaftlich und fachlich als ausreichend etabliert gilt, um komplexere Produktion zu verantworten.

Darum fließen mehrere Faktoren ein:

- Durchschnittliches Produktwissen
- Anzahl abgeschlossener Produktionen
- höchstes politisches oder kirchliches Amt
- Adelstitel
- Ansehen
- derzeitiges Haus

## 4. Berechnungslogik

## 4.1 Grundidee

Der Daemon berechnet einmal täglich einen `certificateScore`.

Aus diesem `certificateScore` wird eine Zielstufe `targetCertificate` abgeleitet.

Die gespeicherte Stufe `falukant_user.certificate` wird dann höchstens um `+1` pro Tag angehoben. Senkungen sind optional und in der ersten Version nicht vorgesehen.

Dadurch gilt:

- Aufstieg ist spürbar, aber nicht sprunghaft
- kurzfristige Schwankungen führen nicht zu hektischen Freischaltungen
- Balancing bleibt später leichter

## 4.2 Eingangsgrößen

Für jeden Spielercharakter mit `falukant_user`:

- `avgKnowledge`
  - Durchschnitt aus `falukant_data.knowledge.knowledge` des Spielercharakters
- `completedProductions`
  - Anzahl abgeschlossener Produktionen des Spielers
- `highestPoliticalOfficeRank`
  - höchster politischer Amtsrang
- `highestChurchOfficeRank`
  - höchster kirchlicher Amtsrang
- `highestOfficeRank`
  - Maximum aus politischem und kirchlichem Rang
- `nobilityLevel`
  - aus `title_of_nobility`
- `reputation`
  - aus `character.reputation`
- `housePosition`
  - aus `house.position`

## 4.3 Normalisierung der Faktoren

### Produktwissen

`knowledgePoints`:

- `0`, wenn `avgKnowledge < 20`
- `1`, wenn `avgKnowledge >= 20`
- `2`, wenn `avgKnowledge >= 35`
- `3`, wenn `avgKnowledge >= 50`
- `4`, wenn `avgKnowledge >= 65`
- `5`, wenn `avgKnowledge >= 80`

### Produktionsmenge

`productionPoints`:

- `0`, wenn `completedProductions < 5`
- `1`, wenn `completedProductions >= 5`
- `2`, wenn `completedProductions >= 20`
- `3`, wenn `completedProductions >= 50`
- `4`, wenn `completedProductions >= 100`
- `5`, wenn `completedProductions >= 200`

### Politische / kirchliche Stellung

`officePoints`:

- politische Ämter:
  - über definierte Mapping-Tabelle im Daemon von `office_type.name -> rank`
- kirchliche Ämter:
  - bevorzugt `church_office_type.hierarchy_level`
- dann:
  - `highestOfficeRank = max(highestPoliticalOfficeRank, highestChurchOfficeRank)`
  - `officePoints = min(5, highestOfficeRank)`

Empfehlung für politische Mapping-Tabelle:

- einfache Kommunalämter: `1`
- regionale Ämter: `2`
- hohe Regionalämter: `3`
- reichs- oder königsnahe Spitzenämter: `4` bis `5`

Das Mapping lebt im Daemon und kann balanciert werden, ohne DB-Änderungen.

### Adel

`nobilityPoints`:

- aus `title_of_nobility.level`
- `nobilityPoints = clamp(level - 1, 0, 5)`

### Ansehen

`reputationPoints`:

- `0`, wenn `reputation < 20`
- `1`, wenn `reputation >= 20`
- `2`, wenn `reputation >= 40`
- `3`, wenn `reputation >= 60`
- `4`, wenn `reputation >= 75`
- `5`, wenn `reputation >= 90`

### Haus

`housePoints`:

- aus `house.position`
- Vorschlag:
  - `0`, wenn `position <= 1`
  - `1`, wenn `position >= 2`
  - `2`, wenn `position >= 4`
  - `3`, wenn `position >= 6`
  - `4`, wenn `position >= 8`
  - `5`, wenn `position >= 10`

Die genauen Schwellen können im Balancing später angepasst werden.

## 4.4 Gesamtwert

Der Daemon berechnet:

```text
certificateScore =
  knowledgePoints * 0.35 +
  productionPoints * 0.20 +
  officePoints * 0.15 +
  nobilityPoints * 0.10 +
  reputationPoints * 0.10 +
  housePoints * 0.10
```

Zusätzlich gelten Mindestanforderungen je Stufe.

## 4.5 Mindestanforderungen je Zertifikatsstufe

Eine höhere Zielstufe darf nur erreicht werden, wenn neben dem `certificateScore` auch harte Mindestgrenzen erfüllt sind.

### Für Zertifikat 2

- `avgKnowledge >= 25`
- `completedProductions >= 5`

### Für Zertifikat 3

- `avgKnowledge >= 40`
- `completedProductions >= 20`
- mindestens einer der Statusfaktoren erfüllt:
  - `officePoints >= 1`
  - oder `nobilityPoints >= 1`
  - oder `reputationPoints >= 2`
  - oder `housePoints >= 1`

### Für Zertifikat 4

- `avgKnowledge >= 55`
- `completedProductions >= 60`
- mindestens zwei Statusfaktoren erfüllt

### Für Zertifikat 5

- `avgKnowledge >= 70`
- `completedProductions >= 150`
- `reputationPoints >= 3`
- mindestens zwei der folgenden:
  - `officePoints >= 2`
  - `nobilityPoints >= 2`
  - `housePoints >= 2`

## 4.6 Ableitung der Zielstufe

Vorschlag:

- `targetCertificate = 1`, wenn `certificateScore < 1.2`
- `targetCertificate = 2`, wenn `certificateScore >= 1.2`
- `targetCertificate = 3`, wenn `certificateScore >= 2.1`
- `targetCertificate = 4`, wenn `certificateScore >= 3.0`
- `targetCertificate = 5`, wenn `certificateScore >= 4.0`

Danach werden die Mindestanforderungen geprüft.

Wenn eine Schwelle rechnerisch erreicht ist, die Mindestanforderungen aber fehlen, bleibt der Spieler auf der niedrigeren Zielstufe.

## 4.7 Fortschreibung

Daily-Regel:

- wenn `targetCertificate > currentCertificate`
  - dann `newCertificate = currentCertificate + 1`
- sonst
  - `newCertificate = currentCertificate`

Für die erste Version keine automatische Herabstufung.

Ausnahmen, die bereits im Daemon berücksichtigt werden dürfen:

- `Bankrott`
  - Wenn der Spieler wirtschaftlich zusammenbricht, darf das Zertifikat gesenkt werden.
  - Die genaue Definition von Bankrott lebt im Daemon bzw. im Wirtschaftssystem.
- `Tod ohne Kinder`
  - Stirbt der Spielercharakter und es gibt keinen erbberechtigten Nachfolger, darf das Zertifikat auf den Grundzustand des Nachfolgesystems bzw. auf eine definierte niedrige Stufe zurückgesetzt werden.
  - Dieser Fall darf bereits jetzt im Daemon umgesetzt werden.

Nicht vorgesehen für die erste Version:

- Downgrade wegen normaler Alltagsschwankungen
- Downgrade wegen vorübergehend schlechter Werte bei Wissen, Ruf, Haus oder Amt

## 5. Daemon-Verhalten

## 5.1 Ausführungszeitpunkt

Die Zertifikatsprüfung läuft ausschließlich im Daily-Tick.

Nicht bei:

- Produktionsstart
- Produktionsende
- Wissensänderung
- Hauswechsel
- Amtswechsel

Diese Aktionen verändern nur die Eingangsgrößen. Die eigentliche Zertifikatsanpassung erfolgt erst im nächsten Daily-Lauf.

## 5.2 Daemon-Hinweis

Für den Daemon gilt ausdrücklich:

- die relevanten DB-Felder sind bereits vorhanden
- es müssen für diese Funktion keine zusätzlichen Schemaänderungen mehr eingeplant werden
- der Daemon soll direkt mit den vorhandenen Tabellen arbeiten

## 5.3 Empfohlener Daily-Ablauf

Für jeden Spieler mit `falukant_user`:

1. Spielercharakter laden
2. `avgKnowledge` berechnen
3. Anzahl abgeschlossener Produktionen laden
4. höchstes aktives oder historisches politisches Amt ermitteln
5. höchstes aktives kirchliches Amt ermitteln
6. Adelstitel, Ruf und Haus laden
7. `certificateScore` und `targetCertificate` berechnen
8. falls Aufstieg möglich:
   - `falukant_user.certificate` um genau `+1` erhöhen
9. Event an UI senden

## 6. Event-Kommunikation zwischen Daemon und UI

## 6.1 Neues Event

Zusätzlich zum allgemeinen `falukantUpdateStatus` wird ein gezieltes Zertifikats-Event empfohlen:

### `falukantUpdateProductionCertificate`

Payload:

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

`reason` ist in der ersten Version fest:

- `daily_recalculation`

## 6.2 Wann senden

Wenn sich die Zertifikatsstufe geändert hat:

1. `falukantUpdateProductionCertificate`
2. danach `falukantUpdateStatus`

Wenn sich die Stufe nicht geändert hat:

- kein spezielles Zertifikats-Event nötig
- normales `falukantUpdateStatus` bleibt anderen Systemen vorbehalten

## 6.3 UI-Reaktion

### BranchView

Bei `falukantUpdateProductionCertificate`:

- Produkte neu laden
- Produktionsbereich neu laden
- optional kurzer Hinweis:
  - „Neues Handelszertifikat erreicht“

### OverviewView

Bei `falukantUpdateProductionCertificate`:

- Falukant-Status neu laden
- Produktionsüberblick neu laden
- Zertifikatsaufstieg visuell hervorheben

### StatusBar / DashboardWidget

- auf denselben Nutzer filtern
- Zertifikat/Produktionsstatus neu laden

## 6.4 Deduplizierung

Da direkt nach dem Zertifikats-Event oft `falukantUpdateStatus` folgt, soll die UI wie bei anderen Falukant-Events entprellen:

- beide Events dürfen denselben kurzen Refresh-Puffer nutzen
- ein Zertifikatsaufstieg darf keinen doppelten Reload-Sturm auslösen

## 7. API- und UI-Empfehlungen

## 7.1 Sichtbare Anzeige

Die UI sollte mittelfristig anzeigen:

- aktuelle Zertifikatsstufe
- nächste Stufe
- Fortschrittsfaktoren
  - Wissen
  - Produktionen
  - Amt
  - Adel
  - Ruf
  - Haus

## 7.2 Empfohlene Backend-Ausgabe

Zusätzlich zur bestehenden User-/Overview-API ist später sinnvoll:

- `certificate`
- `nextCertificate`
- `certificateFactors`
  - `avgKnowledge`
  - `completedProductions`
  - `highestOfficeRank`
  - `nobilityLevel`
  - `reputation`
  - `housePosition`

Das ist für die erste Daemon-Integration aber optional.

## 8. Balancing-Hinweis

Die genannten Schwellen und Gewichte sind bewusst als Spielregelrahmen zu verstehen, nicht als endgültiges Balancing.

Für die erste produktive Version gilt:

- keine zusätzlichen Stufen oder Nebensysteme
- keine normale Herabstufung im Alltagsbetrieb
- Herabstufung nur in Sonderfällen wie `Bankrott` oder `Tod ohne Kinder`
- Daily-Aufstieg maximal `+1`

Balancing erst nach Live-Erfahrung.

## 9. Umsetzungsreihenfolge

### P1

- Daemon: Daily-Berechnung von `certificate`
- Event `falukantUpdateProductionCertificate`
- UI: gezielter Refresh in Branch/Overview

### P2

- UI: Sichtbarer Zertifikatsstatus und Aufstiegshinweis
- Backend/API: optionale Faktor-Ausgabe

### P3

- Balancing
- feinere Sonderfallregeln für `Bankrott`
- feinere politische Mapping-Tabelle

## 10. Done-Kriterien

Fertig ist die erste Version, wenn:

- nur Produkte mit `product.category <= falukant_user.certificate` produzierbar sind
- der Daemon die Zertifikatsprüfung genau einmal täglich ausführt
- der Daemon bei Aufstieg das Zertifikat fortschreibt
- die UI auf das Zertifikats-Event gezielt reagiert
- keine neuen DB-Änderungen für diese Funktion nötig sind