Refactor license matrix and tokenizer logic: rename LicenseTable to LizenzTable, replace LicenseMatrixService with LizenzMatrixService, enhance tokenizer with normalized and fallback token handling, improve ZNS import for license extraction, and update related documentation.

backend/services/masterdata/docs/REITER_LIZENZEN.md

@@ -1,7 +1,7 @@
 # 📜 Reiter-Lizenzen & Startberechtigungen (OEPS)
 
 Diese Dokumentation beschreibt die verschiedenen Lizenzstufen des **OEPS (Österreichischer Pferdesportverband)** und die
-daraus resultierenden Startberechtigungen für die Sparten **Dressur (CDN)** und **Springen (CSN)** gemäß ÖTO 2026.
+daraus resultierenden Startberechtigungen für die Sparten **Dressur (CDN)**, **Springen (CSN)**, **Vielseitigkeit (CCN/CCI)** und **Fahren (CAN/CAI)** gemäß ÖTO 2026.
 
 ## 1. Lizenztypen & Klassen
 
@@ -11,10 +11,10 @@ Prüfungen antreten darf.
 | Code    | Bezeichnung      | Beschreibung                                           | ZNS-Mapping  |
 |:--------|:-----------------|:-------------------------------------------------------|:-------------|
 | **LZF** | Lizenzfrei       | Nur Startkarte oder Reiterpass vorhanden.              | `LIZENZFREI` |
-| **R1**  | Reiter-Lizenz 1  | Einstiegslizenz für Springen, Dressur, Vielseitigkeit. | `R1`         |
+| **R1**  | Reiter-Lizenz 1  | Einstiegslizenz für Springen.                          | `R1`         |
 | **R2**  | Reiter-Lizenz 2  | Fortgeschrittene (Springen bis LM/130cm).              | `R2`         |
 | **R3**  | Reiter-Lizenz 3  | Schwere Klasse (Springen bis S/145cm).                 | `R3`         |
-| **R4**  | Reiter-Lizenz 4  | Höchste nationale Stufe (alle Klassen).                | `R4`         |
+| **R4**  | Reiter-Lizenz 4  | Höchste nationale Stufe Springen (bis 160cm).          | `R4`         |
 | **RD1** | Dressur-Lizenz 1 | Speziallizenz nur für Dressur (Kl. A, L).              | `RD1`        |
 | **RD2** | Dressur-Lizenz 2 | Speziallizenz nur für Dressur (Kl. LM, M).             | `RD2`        |
 | **RD3** | Dressur-Lizenz 3 | Speziallizenz nur für Dressur (Kl. S).                 | `RD3`        |
@@ -23,6 +23,8 @@ Prüfungen antreten darf.
 
 ## 2. Startberechtigungen nach Sparten
 
+> Referenz: ÖTO 2026, A‑Teil § 15 „Reiterlizenzen“. Eine komprimierte Matrix mit Klassen/Höhen und zulässigen Lizenzen findet sich in der Projekt‑Referenz: `docs/03_Domain/02_Reference/OETO_Regelwerk/OETO-2026_A-Teil-Allgemeiner-Teil_16-12-2025.md` (Kapitel „Reiterlizenzen, § 15 ÖTO“).
+
 ### 2.1 Springen (CSN)
 
 Die Startberechtigung richtet sich nach der Hindernishöhe der jeweiligen Klasse (§ 200 B-Teil).
@@ -44,11 +46,81 @@ Die Startberechtigung richtet sich nach dem Aufgabenniveau (§ 100 B-Teil).
 | Klasse         | Niveau              | Erforderliche Lizenz    | Besonderheiten                           |
 |:---------------|:--------------------|:------------------------|:-----------------------------------------|
 | **lizenzfrei** | -                   | **LZF** (Reiterpass)    | Inkl. First Ridden, Dressurreiterbewerbe |
-| **A**          | Leicht              | **R1 / RD1** oder höher | Grundausbildung                          |
-| **L**          | Mittelleicht        | **R1 / RD1** oder höher | -                                        |
-| **LM**         | Leicht-Mittelschwer | **R2 / RD2** oder höher | Kandare wahlweise                        |
-| **M**          | Mittelschwer        | **R2 / RD2** oder höher | Kandarenpflicht                          |
-| **S**          | Schwer              | **R3 / RD3** oder höher | St. Georg bis Grand Prix                 |
+| **A**          | Leicht              | **RD1** oder höher      | Grundausbildung                          |
+| **L**          | Mittelleicht        | **RD1** oder höher      | -                                        |
+| **LM**         | Leicht-Mittelschwer | **RD2** oder höher      | Kandare wahlweise                        |
+| **M**          | Mittelschwer        | **RD2** oder höher      | Kandarenpflicht                          |
+| **S**          | Schwer              | **RD3** oder höher      | St. Georg bis Grand Prix                 |
+
+Hinweis RD4: Das ÖTO kennt in der Tabelle Kombinationsfälle bis `RD4`. Im System ist derzeit kein `RD4`‑Enum modelliert; faktisch wird `RD4` wie `RD3` behandelt (Kappung auf Dressur S). Eine spätere Erweiterung um `RD4` ist vorbereitet, siehe CHANGELOG.
+
+---
+
+### 2.3 Vielseitigkeit (CCN/CCI)
+
+Vielseitigkeit kombiniert Dressur, Gelände und Springen. Für die Startberechtigung gilt das Prinzip der kumulativen Mindestanforderung: Die jeweils geforderte Dressur- und Spring-Lizenz muss erfüllt sein (Details je Klasse und Ausschreibung, § 300 B‑Teil).
+
+| Klasse (typ.) | Richtwert            | Erforderliche Lizenzen (kumulativ) | Besonderheiten |
+|:--------------|:---------------------|:-----------------------------------|:--------------|
+| **E/Einsteiger** | national, Einstiegsniveau | **LZF** (Startkarte) ODER `RD1`+`R1` (wenn gefordert) | gem. Ausschreibung |
+| **A**         | Einsteiger/Light     | `RD1` UND `R1`                      | — |
+| **L**         | Mittelleicht         | `RD1` UND `R1`                      | — |
+| **M**         | Mittelschwer         | `RD2` UND `R2`                      | — |
+| **S**         | Schwer               | `RD3` UND `R3`                      | höhere Anforderungen international |
+
+Hinweis: In der Praxis orientiert sich die Spring-Anforderung an der in der Ausschreibung angegebenen Hindernishöhe der Springprüfung; die Dressur-Anforderung am ausgeschriebenen Dressur-Niveau der Teilprüfung. Wo nationale Sonderregelungen (Ponys, Haflinger/Noriker) bestehen, gelten diese zusätzlich.
+
+---
+
+### 2.4 Fahren (CAN/CAI)
+
+Für Fahren existieren im ÖTO/FEI‑Kontext eigene Fahrlizenzen (z. B. F1–F3). Im aktuellen Systemmodell sind diese noch nicht als `ReiterLizenzKlasseE` hinterlegt. Bis zur Einführung entsprechender Enums/Regeln gilt:
+
+| Klasse (typ.) | Richtwert        | Systemzustand                                 | Teilnahmevoraussetzung (heute) |
+|:--------------|:-----------------|:----------------------------------------------|:-------------------------------|
+| **A/L/M/S**   | national/intern. | Keine `F*`‑Lizenztypen im Enum vorhanden      | **Startkarte** (LZF) plus Zulassung laut Ausschreibung/Verbandsvorgaben |
+
+Geplante Erweiterung: Ergänzung der Enum‑Werte `F1`..`F3` und einer Fahr‑Matrix analog Dressur/Springen (separates Ticket). Die ZNS‑Integration bleibt davon unberührt, bis ZNS eigene Fahr‑Kodierungen liefert.
+
+---
+
+### 2.5 Übersichtstabelle gemäß § 15 (kompakt)
+
+Zur schnellen Orientierung ist die folgende, auf die System‑Enums abgebildete Kurzfassung der §15‑Tabelle enthalten. „B,C“ bedeutet „Turnierkategorien B, C, C‑NEU zulässig“, „LP“ steht für „Lizenzprüfung erforderlich“.
+
+| Klasse/Höhe | V 80 | 60–100 | V 90 |  A  | 105–110 | V 100 |  L  | 115–120 | V 105 |  LM | 125–130 |  M  | 135 | V110–115 |  S  | V120 | 140–145 | 150–160 |
+|:-----------:|:----:|:------:|:----:|:---:|:-------:|:-----:|:---:|:-------:|:-----:|:---:|:-------:|:---:|:---:|:---------:|:---:|:----:|:-------:|:-------:|
+| Sparte      |  V   |   S    |  V   |  D  |    S    |   V   |  D  |    S    |   V   |  D  |    S    |  D  |  S  |     V     |  D  |  V   |    S    |    S    |
+| R1          |  X   |   X    |  X   | B,C |   B,C   |   X   | B,C |   B,C   |       |     |         |     |     |           |     |      |         |         |
+| R2          |  X   |   X    |  X   |  X  |    X    |   X   |  X  |    X    |   X   |  X  |    X    | LP  |     |           |     |      |         |         |
+| R3          |  X   |   X    |  X   |  X  |    X    |   X   |  X  |    X    |   X   |  X  |    X    |  X  |  X  |     X     |     |  X   |    X    |         |
+| RD1         |      |        |      | B,C |         |       | B,C |         |       |     |         |     |     |           |     |      |         |         |
+| RD2         |      |        |      |  X  |         |       |  X  |         |       |  X  |         | LP  |     |           |     |      |         |         |
+| RD3         |      |        |      |  X  |         |       |  X  |         |       |  X  |         |  X  |     |           |  X  |      |         |         |
+| R4          |  X   |   X    |  X   |  X  |    X    |   X   |  X  |    X    |   X   |  X  |    X    |  X  |  X  |     X     |     |  X   |    X    |    X    |
+
+Abbildung im System:
+- Zeilen mit Kombi‑Lizenzen (z. B. `R1D2`, `RDS4`) werden als gleichzeitiger Besitz getrennter Lizenzen interpretiert (zwei Einträge in `Reiter.lizenzen`).
+- `RD4` ist aktuell nicht als Enum verfügbar; bis zur Erweiterung entspricht das Verhalten `RD3`.
+
+---
+
+### 2.6 Kombinationsreihen (§ 15)
+
+Die folgenden Zeilen aus der ÖTO‑Tabelle (§ 15) bilden Kombinationsfälle ab, die sich aus gleichzeitig erfüllten
+Voraussetzungen ergeben. Sie sind systemisch als Parallelbesitz mehrerer Lizenzen zu verstehen und dienen der
+schnellen Orientierung. Spaltenbezeichnungen entsprechen Abschnitt 2.5.
+
+| Klasse/Höhe | V 80 | 60–100 | V 90 |  A  | 105–110 | V 100 |  L  | 115–120 | V 105 |  LM | 125–130 |  M  | 135 | V110–115 |  S  | V120 | 140–145 | 150–160 |
+|:-----------:|:----:|:------:|:----:|:---:|:-------:|:-----:|:---:|:-------:|:-----:|:---:|:-------:|:---:|:---:|:---------:|:---:|:----:|:-------:|:-------:|
+| R1S2        |  X   |   X    |  X   | B,C |    X    |   X   | B,C |    X    |       |     |    X    |     |     |           |     |      |         |         |
+| R1S3        |  X   |   X    |  X   | B,C |    X    |   X   | B,C |    X    |       |     |    X    |     |  X  |           |     |      |    X    |         |
+| R1S4        |  X   |   X    |  X   | B,C |    X    |   X   | B,C |    X    |       |     |    X    |     |  X  |           |     |      |    X    |    X    |
+| R2S3        |  X   |   X    |  X   |  X  |    X    |   X   |  X  |    X    |   X   |  X  |    X    | LP  |  X  |           |     |      |    X    |         |
+| R2S4        |  X   |   X    |  X   |  X  |    X    |   X   |  X  |    X    |   X   |  X  |    X    | LP  |  X  |           |     |      |    X    |    X    |
+| R3S4        |  X   |   X    |  X   |  X  |    X    |   X   |  X  |    X    |   X   |  X  |    X    |  X  |  X  |     X     |     |  X   |    X    |    X    |
+
+Legende siehe Abschnitt 2.5 (Bedeutung von „B,C“/„LP“ sowie Spartenkürzel).
 
 ---
 
@@ -58,30 +130,58 @@ Die Startberechtigung richtet sich nach dem Aufgabenniveau (§ 100 B-Teil).
 
 Für Rasse-spezifische Bewerbe gelten oft abweichende (niedrigere) Lizenz-Anforderungen für höhere Klassen.
 
+Hinweis: Abweichungen sind disziplinspezifisch zu verstehen (Dressur → `RD*`, Springen → `R*`).
+
 * **Dressur (Haflinger):**
-  * Klasse L/LM: R(D)1 ausreichend.
-  * Klasse M: R(D)3 erforderlich.
-  * Klasse S: R(D)4 erforderlich.
+  * Klasse L/LM: **RD1** ausreichend.
+  * Klasse M: **RD3** erforderlich.
+  * Klasse S: nationale Sonderregelungen, idR **RD3**; höhere Abweichungen gemäß Ausschreibung.
 * **Springen (Haflinger):**
-  * 95-120cm (bis Klasse M): R1 ausreichend.
-  * 125-135cm (Klasse S): R2 ausreichend.
+  * 95–120cm (bis Klasse M): **R1** ausreichend.
+  * 125–135cm (Klasse S): **R2** ausreichend.
 
 ### 3.2 Pony
 
 * In Pony-Bewerben (bis Kl. L) ist die **Startkarte Allgemein** (Voraussetzung Reiterpass) ausreichend.
-* Ab Klasse LM ist eine entsprechende Lizenz (R1/RD1) erforderlich.
+* Ab Klasse LM ist eine entsprechende Lizenz erforderlich: **RD1** (Dressur) bzw. **R1** (Springen).
 
 ---
 
-## 4. ZNS-Integration (LIZENZ01.dat)
+## 4. Validierungslogik & ZNS-Integration
+
+### 4.1 Validierungslogik (Systemverhalten)
+
+Die Eligibility wird in zwei strikt getrennten Schritten geprüft:
+
+1) Spartenlizenz prüfen
+   - Für Springen sind ausschließlich `R1..R4` gültig (keine Dressur-Lizenz ausreichend).
+   - Für Dressur sind ausschließlich `RD1..RD3` gültig (keine Spring-Lizenz ausreichend).
+   - Für Vielseitigkeit müssen die Anforderungen beider Sparten erfüllt sein: Dressur-Teilprüfung (RD*) UND Spring-Teilprüfung (R*), jeweils gemäß ausgeschriebener Klasse.
+   - Für Fahren gibt es aktuell keine `F*`‑Lizenzen im System; bis zur Erweiterung wird Fahren als lizenzfrei (LZF) behandelt und organisatorisch über die Ausschreibung begrenzt.
+
+2) Maximal erlaubte Turnierklasse ermitteln
+   - Innerhalb der geprüften Sparte bestimmt die höchste bezahlte Lizenz die Obergrenze der Klasse/Höhe.
+   - Zur internen Kappung wird ggf. ein disziplinübergreifendes Mapping verwendet (nur nach bestandener Spartenprüfung):
+     - `R1↔RD1`, `R2↔RD2`, `R3/R4↔RD3`.
+
+Konsequenz: Ein Reiter mit nur `RD2` darf Dressur bis LM/M reiten, aber im Springen nur lizenzfreie Bewerbe (E0). Umgekehrt
+ermöglicht eine `R2` Springen bis 130cm, aber keine Dressur-Klassen. In der Vielseitigkeit wären für eine M‑Klasse beide Nachweise (`RD2` UND `R2`) erforderlich.
+
+### 4.2 ZNS-Integration (LIZENZ01.dat)
 
 Das System mappt die Felder aus der ZNS-Datei automatisch auf die interne `LizenzKlasseE`.
 
-* **Feld `Reiterlizenz` (Pos 137):** Enthält die Hauptlizenz (z.B. `R1`).
-* **Feld `Lizenz-Details` (Pos 201):** Enthält die Liste aller bezahlten Lizenzen (z.B. `RD1,F1`).
-  * *Logik:* Ein Reiter mit `RD2` darf Dressur LM/M reiten, aber Springen nur lizenzfrei (E0), sofern keine `R1` (oder
-    höher) vorhanden ist.
+* **Feld `Reiterlizenz` (Pos 137):** Enthält die primäre Lizenzangabe (z. B. `R1` oder `RD1`).
+* **Feld `Lizenz-Details` (Pos 201):** Enthält die Liste aller bezahlten Lizenzen (z. B. `RD1`). Werte für Fahren (`F*`) werden aktuell ignoriert, solange keine System‑Enums existieren.
+  * Das System aggregiert alle Vorkommen und bestimmt je Sparte die höchste vorhandene Lizenz.
 
 ---
-> 📜 **Rulebook Expert Hinweis:** Die Startberechtigung muss bei jeder Nennung gegen die aktuelle Lizenz des Reiters (
-> Stichtag Nennschluss) geprüft werden. Eine Höherreihung während eines Turniers ist gemäß § 17 Abs. 6 ausgeschlossen.
+> 📜 **Rulebook Expert Hinweis:** Die Startberechtigung muss bei jeder Nennung gegen die aktuelle Lizenz des Reiters
+> (Stichtag Nennschluss) geprüft werden. Eine Höherreihung während eines Turniers ist gemäß § 17 Abs. 6 ausgeschlossen.
+
+---
+
+Siehe ergänzend:
+* `TURNIER_KLASSEN.md` für Klassendefinitionen und Höhen/Niveaus je Sparte.
+* `GEBUEHRENORDNUNG.md` für Start-/Nenngelder und Mindest-Geldpreise.
+* `ZNS_SCHNITTSTELLE.md` für Felder und Positionsangaben der LIZENZ01.dat.