Referenz belegter Dokumentvorlagen-Keys

Diese Referenz dokumentiert ausschließlich Schlüsselnamen, die der aktuelle Backend-Resolver tatsächlich erzeugt. Ein Schlüsselname ist der Zeichenwert, den der Resolver in seine Datenkarte schreibt – nicht die Java-Annotation allein und nicht eine frei gewählte Platzhalter-Schreibweise.

Produktionsstatus beachten: Die beiden Befüllroutinen für gespeicherte DOCX-Dateien und hochgeladene PDF-Dateien enthalten im geprüften Stand nur auskommentierte Implementierungen und geben null zurück. Die Liste der Schlüssel ist daher eine präzise Resolver-Referenz, aber kein Nachweis einer heute erfolgreichen PDF- oder DOCX-Befüllung. Produktive Vorlagen erst einsetzen, nachdem die Befüllung in Ihrer freigegebenen Umgebung repariert und mit Testdaten geprüft wurde.

Vorab nötig: Sie kennen den von Ihrer Installation freigegebenen Weg zum Erzeugen eines Dokuments; die aktuelle Oberfläche belegt keinen vollständigen Menüablauf für die Vorlagenbefüllung. Die Zielperson und die benötigten Stammdaten sind vorhanden. Fehlende Werte werden bei einfachen Feldern als leerer Text geliefert; bei fehlenden verschachtelten Objekten entstehen deren Schlüssel nicht. Für die unten als Listen- oder Systemkontext markierten Daten muss ein Erzeugungspfad genau diesen Kontext bereitstellen. Der öffentliche Vorlagen-Endpunkt erzeugt seine Datenkarte nur aus einem User. Verwenden Sie ausschließlich anonymisierte oder ausdrücklich freigegebene Testdaten.

Anwendungsschritte

1. Ordnen Sie Ihre Vorlage zuerst einem belegten Kontext zu: Benutzer, Lektionenliste, Änderungsprotokoll oder Rechnung.
2. Tragen Sie den Schlüssel exakt ein – Groß-/Kleinschreibung, Umlaute, Unterstriche und auch englische Namen sind Teil des Namens.
3. Verwenden Sie für PDF-Formularfelder beziehungsweise DOCX-Inhaltssteuerelemente die Syntax Ihres Authoring-Werkzeugs. Der geprüfte Code definiert nur den Feldnamen, nicht eine allgemeine Platzhalter-Syntax.
4. Legen Sie für jeden benötigten Schlüssel einen Testfall mit vorhandenem Wert und – bei optionalen Beziehungen – einen zweiten Testfall ohne Wert an.
5. Vergleichen Sie nach einer künftig funktionierenden Erzeugung die ausgegebenen Feldnamen und Werte mit dieser Referenz, bevor Sie das Dokument weitergeben.

Direkt nutzbarer Benutzerkontext: Schüler, Eltern, Adresse und Lehrkraft

Der aktuelle Vorlagen-Endpunkt löst eine konkrete User-Instanz auf. Bei einem Schüler kommen die geerbten Benutzerfelder, die Schülerfelder, die Adresse und – sofern vorhanden – der Elternteil hinzu. Die Schlüssel sind dabei bereits endgültig zusammengesetzt.

Schüler- und allgemeine Benutzerdaten

Endgültiger Schlüssel	Wertquelle
Geschlecht	Geschlecht
Vorname	Vorname
Nachname	Nachname
Geburtsdatum	Geburtsdatum
Telefonnummer	Telefonnummer
Email	Benutzername/E-Mail-Adresse
Stufe	Schülerstufe
Schule	Schulname des Schülers

Adresse des Benutzers

Endgültiger Schlüssel	Wertquelle
Strasse	Straße
Hausnummer	Hausnummer
Ort	Ort
Bundesland	Bundesland
Land	Land
PLZ	Postleitzahl
Strasse_Nr	Straße und Hausnummer kombiniert
PLZ_Ort	Postleitzahl und Ort kombiniert

Elternteil eines Schülers

Der Elternteil wird mit dem Prefix Elternteil verschachtelt. Daher gibt es keine eigenständigen Schlüssel wie Anrede im Benutzerkontext, sondern genau diese Namen:

Endgültiger Schlüssel	Wertquelle
ElternteilAnrede	Anrede
ElternteilVorname	Vorname
ElternteilNachname	Nachname
ElternteilEmail	E-Mail-Adresse
ElternteilTelefonnummer	Telefonnummer

Lehrkraft als Zielperson

Wird eine Lehrkraft als User aufgelöst, gelten die allgemeinen Benutzer- und Adressschlüssel ebenfalls. Zusätzlich existieren nur:

Endgültiger Schlüssel	Wertquelle
qualification	Qualifikationen
education	Ausbildung

Vertragsfach-Keys: nur innerhalb einer Lektionslisten-Zeile

Für einen Benutzer allein wird weder ein Vertrag noch dessen Fachdetail-Liste aufgelöst. Die nachstehenden Schlüssel sind nur in einem Element der Lektionsliste lessons belegt: Lesson → SL → Fachdetails → SubjectDetails. Sie sind deshalb nicht als flache Benutzer- oder Vertragsvorlage direkt nutzbar.

Das Fachdetail trägt immer einen Index. Der Resolver beginnt bei 1, nicht bei 0. In der verschachtelten Lektionsliste ist der Index die Position des jeweiligen SL-Eintrags innerhalb einer Lektion. Damit lauten die tatsächlich erzeugten Namen beispielsweise für den ersten Eintrag genau FachdetailsFach_1, nicht Fach_1.

Endgültige Namensregel	Wertquelle
FachdetailsFach_<n>	Fach
FachdetailsFachUE_<n>	erlaubte wiederkehrende Unterrichtseinheiten
FachdetailsUnterrichtdauer_<n>	Unterrichtsdauer/-einheit
FachdetailsEinzelunterrichtkost_<n>	Kosten Einzelunterricht
FachdetailsGruppenunterrichtkost_<n>	Kosten Gruppenunterricht
FachdetailsEinzelunterricht_<n>	Freigabe Einzelunterricht
FachdetailsGruppenunterricht_<n>	Freigabe Gruppenunterricht

<n> ist hier eine Regel und kein eintragbarer Platzhaltername. In einer konkreten ersten Zeile lautet der Name beispielsweise FachdetailsFach_1; für die zweite Zeile FachdetailsFach_2.

Fortgeschrittene Kontexte: Lektion, Listen und Änderungen

Diese Schlüssel werden nicht über die benutzerbezogene Vorlagenbefüllung bereitgestellt. Der Protokoll-Erzeugungspfad stellt eine Liste unter lessons bereit; jedes Element ist eine eigene Datenkarte. In dieser Karte heißen die einfachen Lektionsschlüssel wie folgt:

Endgültiger Schlüssel im Element von lessons	Wertquelle
LektionId	Lektions-ID
Fach	Fachobjekt
Startdatum	Startzeit, über den Datumszeit-Konverter formatiert
Enddatum	Endzeit, über den Datumszeit-Konverter formatiert
givenAt	Durchführungszeit, über den Datumszeit-Konverter formatiert
Abgerechnet	Abrechnungsmarkierung
Unterrichtseinheiten	Einheiten
Status	Enum-Name des Lektionsstatus
Stornogrund	Enum-Name des Stornogrunds
Stornonote	Stornonotiz
Lektiontyp	Enum-Name des Lektionstyps
Beschreibung	Beschreibung
Kommentar	Kommentar

Verschachtelte Lektionswerte

• SL ist eine Liste, nicht ein flacher Schlüssel. Jedes Element dieser Liste enthält die Schülerwerte mit Schueler als Prefix: SchuelerGeschlecht, SchuelerVorname, SchuelerNachname, SchuelerGeburtsdatum, SchuelerTelefonnummer, SchuelerEmail, SchuelerStufe, SchuelerSchule sowie SchuelerStrasse, SchuelerHausnummer, SchuelerOrt, SchuelerBundesland, SchuelerLand, SchuelerPLZ, SchuelerStrasse_Nr, SchuelerPLZ_Ort.
• Hat dieser Schüler einen Elternteil, liegen dort außerdem SchuelerElternteilAnrede, SchuelerElternteilVorname, SchuelerElternteilNachname, SchuelerElternteilEmail und SchuelerElternteilTelefonnummer.
• Die Fachdetail-Schlüssel in demselben SL-Element folgen exakt den oben dokumentierten Fachdetails…_<n>-Regeln.
• Die zugeordnete Lehrkraft wird flach mit Prefix Teacher ergänzt: TeacherGeschlecht, TeacherVorname, TeacherNachname, TeacherGeburtsdatum, TeacherTelefonnummer, TeacherEmail, TeacherStrasse, TeacherHausnummer, TeacherOrt, TeacherBundesland, TeacherLand, TeacherPLZ, TeacherStrasse_Nr, TeacherPLZ_Ort, Teacherqualification und Teachereducation.
• Signature ist eine Liste. Deren einzelne Elemente enthalten UnterschriebenAt, UnterschriebenBy und UnterschriftBase64. Der Base64-Wert beginnt, wenn eine Signatur vorhanden ist, mit data:image/png;base64,.
• Die eingebetteten Auditdaten einer Lektion werden trotz des Feldnamens audit ohne audit-Prefix aufgelöst: createdAt, updatedAt, createdBy, updatedBy.

Im Protokollkontext ergänzt der Service neben lessons außerdem die nicht annotierten Kontextnamen clientInfo, includeTime, startDate, endDate, username und totalUE. Für ein Änderungszusatzdokument steht eine Liste changes bereit. Jedes Element enthält LektionId, LektionChanges, createdAt und createdBy.

Fortgeschrittener Rechnungskontext und Zahlungen

Bei der Rechnungserzeugung wird eine Invoice-Instanz aufgelöst. Die aktuelle Rechnungsfassung wird ohne Prefix in dieselbe Datenkarte eingefügt. Damit sind diese Schlüssel belegt:

Endgültiger Schlüssel	Wertquelle
Rechnungsnummer	Rechnungsnummer
Zeitraum_Start	Beginn des Abrechnungszeitraums
Zeitraum_Ende	Ende des Abrechnungszeitraums
Status	Enum-Name des Rechnungsstatus
Type	Enum-Name des Rechnungstyps
Empfaenger	Empfängername aus der Rechnungsfassung
Datum	Rechnungsdatum
Faelligkeitsdatum	Fälligkeitsdatum
Gesamtbetrag	Gesamtbetrag
Nettobetrag	Nettobetrag
Umsatzsteuer	Steuerbetrag
Steuersatz	Steuersatz
Empfaenger_Name	aus dem Empfängertyp berechneter Anzeigename
Empfaenger_Address_Strasse	Empfängerstraße
Empfaenger_Address_Hausnummer	Empfängerhausnummer
Empfaenger_Address_Ort	Empfängerort
Empfaenger_Address_Bundesland	Empfängerbundesland
Empfaenger_Address_Land	Empfängerland
Empfaenger_Address_PLZ	Empfängerpostleitzahl
Empfaenger_Address_Strasse_Nr	kombinierte Empfängerstraße/-hausnummer
Empfaenger_Address_PLZ_Ort	kombinierte Empfängerpostleitzahl/-ort

Für die HTML-Rechnungslogik ergänzt der Service zusätzlich die Kontextnamen billItems, recipient, clientInfo, withTax und – nur bei vorhandenem Logo – logoBase64. Sie sind keine @TemplateKey-Schlüssel, aber tatsächlich bereitgestellte Rechnungskontextnamen.

Zahlungen sind als verschachtelte Liste annotiert, jedoch ohne Namen (key ist leer). Der aktuelle Resolver speichert diese Liste daher unter dem leeren Zeichenwert ""; das konfigurierte Prefix payments wird bei Listen nicht in die Elementkarten übertragen. Das ist kein brauchbarer benannter Vorlagenschlüssel. Falls ein aufrufender Code diese Liste dennoch ausliest, enthalten ihre Elemente amount, Zahlungsmethode, Zahlungseingangsdatum, Referenznummer, Notiz und Type.

Namenskollision: Status und Type sind keine global eindeutigen Felder. Ihre Bedeutung hängt vom Rechnungskontext ab. createdAt, createdBy und LektionId können im Lektions- und Änderungszusatzkontext vorkommen. Verwenden Sie Datenkarten aus verschiedenen Kontexten nicht ungeprüft zusammen.

PDF und DOCX: belegter Stand

• Der gespeicherte Vorlagen-Endpunkt akzeptiert nur Dateien der Kategorie TEMPLATE. Er unterscheidet PDF-MIME-Typ und DOCX-MIME-Typ, liefert laut Controller jedoch stets den DOCX-Content-Type.
• Der Upload-Endpunkt heißt zwar /pdf/{userId} und setzt den PDF-Content-Type, verwendet intern aber die DOCX-Befüllmethode und setzt als Download-Dateinamen filled_form.docx.
• Die vorgesehenen PDF-Formularfeld- und DOCX-Inhaltssteuerelement-Schleifen sind auskommentiert. Beide Wege liefern daher im geprüften Code null; auch eine tatsächliche Feldsyntax oder eine erfolgreiche Ausgabedatei ist nicht belegt.
• PDF-Vorschau, Vorlagenverwaltung und eine technische Befüllung sind getrennte Themen. Eine hochgeladene PDF- oder DOCX-Datei ist nicht automatisch als funktionsfähige Datenvorlage validiert.

Datenlücken, Berechtigung und sensible Felder

• Ein null-Wert eines einfachen annotierten Feldes wird als leerer Text abgelegt. Ist eine verschachtelte Adresse, ein Elternteil, eine Lehrkraft oder ein ähnliches Objekt null, werden dessen einzelne Schlüssel nicht erzeugt.
• Fehlende Rechnungsempfänger-Daten können bei der Berechnung von Empfaenger_Name oder der Empfängeradresse eine Ausnahme auslösen, statt ein leeres Feld zu liefern.
• UnterschriftBase64 enthält eine biometrisch bzw. rechtsrelevant zu behandelnde Bildsignatur. Email, Telefonnummer, Geburtsdatum, Adresse, Zahlungen, Rechnungsbeträge sowie Audit-IDs sind personenbezogene oder finanzielle Daten. Nutzen Sie diese Felder nur bei rechtmäßiger Zweckbindung und minimalem Zugriff.
• Die Erzeugungsberechtigung gilt für die Zielperson, nicht pauschal für alle Personen: Administratoren dürfen erzeugen, Benutzer für sich selbst; Lehrkräfte nur bei passender Zuordnung und aktivierter Mandanteneinstellung für Datei-Lesezugriff.
• Der Resolver nimmt keine Datensparsamkeit vor: Wer einen Kontext auflösen darf, erhält alle darin annotierten Schlüssel. Gestalten Sie Vorlagen daher mit möglichst wenigen sensiblen Feldern.

Warnungen

• Erfinden Sie keine Schreibvarianten wie Fach_1, wenn der tatsächliche Kontext FachdetailsFach_1 erzeugt.
• Verwenden Sie payments nicht als Listenname; im geprüften Resolver liegt diese Liste unter dem leeren Schlüssel "".
• Setzen Sie Status, Type, createdAt oder createdBy nicht kontextübergreifend gleich.
• Die dokumentierte Berechtigung ist kein Ersatz für eine Datenschutz- und Freigabeprüfung des erzeugten Dokuments.
• Laden Sie nur PDF oder DOCX hoch, aber betrachten Sie beide Formate bis zur erfolgreich getesteten Implementierung nicht als produktiv befüllbar.
• Die aktuelle Codebasis belegt weder eine allgemeine Platzhalter-Schreibweise noch eine produktiv erfolgreiche Befüllung. Behaupten Sie deshalb keine erfolgreiche Vorschau, Signaturdarstellung oder Druckausgabe ohne Testnachweis.