yourpart3/docs/FALUKANT_PRODUCTION_CERTIFICATE_SPEC.md

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:

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:

{
  "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