# 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.45 +
  productionPoints * 0.30 +
  officePoints * 0.08 +
  nobilityPoints * 0.05 +
  reputationPoints * 0.07 +
  housePoints * 0.05
```

Zusätzlich gelten Mindestanforderungen je Stufe.

Balancing-Grundsatz:

- frühe und mittlere Zertifikate sollen primär über Wissen und Produktionspraxis erreichbar sein
- gesellschaftliche Faktoren wirken vor allem als Beschleuniger oder als Zugang zu hohen Zertifikaten
- vorübergehende wirtschaftliche Verlustphasen blockieren den normalen Aufstieg nicht automatisch
- ein normaler Produktionsverlust ist kein Downgrade-Grund

## 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 >= 15`
- `completedProductions >= 4`

### Für Zertifikat 3

- `avgKnowledge >= 28`
- `completedProductions >= 15`
- kein harter Statuszwang
- Statusfaktoren dürfen den Score verbessern, sind hier aber noch nicht Pflicht

### Für Zertifikat 4

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

### Für Zertifikat 5

- `avgKnowledge >= 60`
- `completedProductions >= 110`
- `reputationPoints >= 2`
- mindestens zwei der folgenden:
  - `officePoints >= 2`
  - `nobilityPoints >= 1`
  - `housePoints >= 2`

## 4.6 Ableitung der Zielstufe

Vorschlag:

- `targetCertificate = 1`, wenn `certificateScore < 0.9`
- `targetCertificate = 2`, wenn `certificateScore >= 0.9`
- `targetCertificate = 3`, wenn `certificateScore >= 1.8`
- `targetCertificate = 4`, wenn `certificateScore >= 2.8`
- `targetCertificate = 5`, wenn `certificateScore >= 3.8`

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

Balancing-Hinweis für den Daemon:

- Wenn ein Spieler bereits regelmäßig produziert und verkauft, soll Zertifikat `2` früh stabil erreichbar sein.
- Zertifikat `3` soll bei solider Produktionspraxis und mittlerem Wissen ebenfalls ohne hohen Adels- oder Amtsstatus erreichbar sein.
- Hohe gesellschaftliche Faktoren sollen vor allem Zertifikat `4` und `5` deutlich erleichtern, nicht Zertifikat `2` und `3` künstlich blockieren.
- Reine Verlustphasen in der Geldhistorie sind kein eigener Gegenfaktor, solange kein echter Bankrottfall vorliegt.

## 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