TicketSystem/README.md

TicketSystem

TicketSystem ist das flexible, moderne Support- und Feedback-Plugin für Minecraft-Server (Spigot/Paper 1.18.x–1.21.x, Java 17+). Es bietet flexible Speicherung, automatische Backups & Migration, Export/Import, Statistiken, dynamische GUI, Kategorie- und Prioritäten-System, Bewertungs- und Kommentar-System, FAQ-System mit Kategorien, Discord-Webhook und volle BungeeCord-Unterstützung.

---

Features

• MySQL oder Datei-Speicherung (YAML/JSON oder MySQL/MariaDB, jederzeit umschaltbar)
• Automatische Backups & Migration
• Export/Import von Tickets
• Statistiken & Archivierung
• Rollenbasierter Archiv-Zugriff
• Konfigurierbare Speicherpfade
• Vollständige Validierung & Fehlerausgaben
• Debug-Modus & Versionsprüfung
• Anpassbare Nachrichten, Farben, Limits, Speicherpfade, Archiv-Intervall, Cooldowns, Rechte
• Dynamische GUI mit Seiten-System
• Kategorie- und Prioritäten-System
• Bewertungs- und Kommentar-System
• Offline-Benachrichtigungen
• Discord-Webhook mit Embeds & Rollen-Ping
• Blacklist für Spieler
• FAQ-System mit Kategorien – eigene GUI mit Custom-Skull-Items, optionaler Kategorie-Auswahl-Screen, vollständige In-Game-Verwaltung; wahlweise faqs.yml oder MySQL-Speicherung, Migration per Befehl
• Performance-Caching – TTL-basierter In-Memory-Cache reduziert Datenbankabfragen spürbar
• Backup-System – automatische JSON-Backups per /ticket backup, vor Migrationen, im backups/-Ordner
• HTTPS/TLS-Unterstützung – optionaler eingebetteter HTTPS-Server via JKS-Keystore (TLS 1.2+)
• MySQL Auto-Reconnect – bricht die Datenbankverbindung ab, stellt das Plugin sie automatisch wieder her
• Brute-Force-Schutz – IP-Sperre nach 5 Fehlversuchen im Web-Panel (15 Minuten)
• Archiv-Verwaltung im Web-Panel – archivierte Tickets einsehen, permanent löschen oder wiederherstellen
• Benutzerverwaltung zur Laufzeit – Web-Panel-Benutzer über die API anlegen, Passwort ändern, löschen
• Saubere Konsole – minimale Start-Logs, kein unnötiger Spam
• Erweiterbarkeit: viele Hooks
• BungeeCord-Unterstützung: serverübergreifende Tickets, Teleports, Weiterleitungen, Benachrichtigungen

---

Installation & Setup

1. TicketSystem.jar in den plugins-Ordner legen und Server starten
2. config.yml anpassen (Speicherorte, Nachrichten, Limits, Farben, MySQL-Daten etc.)
3. Kopf der FAQ-Kategorie-Items optional über gui-settings.faq.category-head-item in der config.yml konfigurieren
4. /ticket-Befehle nutzen

---

Befehle & Rechte

Übersicht der Befehle

Befehl	Beschreibung	Nutzergruppe
/ticket	Hilfe & Übersicht	Spieler, Support
/ticket create [Kategorie] [Priorität] <Text>	Ticket erstellen	Spieler
/ticket list	Eigene Tickets in der GUI anzeigen	Spieler
/ticket comment <ID> <Nachricht>	Kommentar hinzufügen	Spieler, Support
/ticket rate <ID> <good|bad>	Support bewerten	Spieler
/ticket faq	FAQ-GUI öffnen (bei aktiven Kategorien: Auswahl zuerst)	Spieler
/ticket faq list	FAQs im Chat auflisten	Spieler
/ticket faq add [Kategorie] <Frage> | <Antwort>	Neues FAQ hinzufügen (optional Kategorie angeben)	Admin
/ticket faq edit <ID> <Frage> | <Antwort>	Bestehendes FAQ bearbeiten	Admin
/ticket faq delete <ID>	FAQ löschen	Admin
/ticket faq reload	FAQs aus faqs.yml neu laden	Admin
/ticket faq migrate [tomysql|tofile]	FAQs zwischen faqs.yml und MySQL migrieren	Admin
/ticket backup	Datenbank-Backup erstellen (JSON im backups/-Ordner)	Admin
/ticket kategorie add <n> [&Farbe] [Beschreibung]	FAQ-Kategorie hinzufügen	Admin
/ticket kategorie delete <Schlüssel>	FAQ-Kategorie löschen	Admin
/ticket kategorie list	Alle FAQ-Kategorien auflisten	Admin
/ticket claim <ID>	Ticket annehmen	Support/Admin
/ticket close <ID> [Kommentar]	Ticket schließen	Support/Admin
/ticket forward <ID> <Spieler>	Ticket weiterleiten	Support/Admin
/ticket setpriority <ID> <low|normal|high|urgent>	Priorität ändern	Support/Admin
/ticket reload	Konfiguration neu laden	Admin
/ticket stats	Statistiken anzeigen	Admin
/ticket archive	Tickets archivieren	Admin
/ticket blacklist <add|remove|list> [Spieler] [Grund]	Blacklist verwalten	Admin
/ticket migrate <tomysql|tofile>	Speicherart wechseln	Admin
/ticket export <Dateiname>	Tickets exportieren	Admin
/ticket import <Dateiname>	Tickets importieren	Admin
/ticket teleport <ID>	Teleport zu Ticket (BungeeCord)	Support/Admin

Rechte

Permission	Beschreibung	Standard
ticket.create	Ticket erstellen	alle Spieler
ticket.support	Tickets einsehen, claimen, schließen, Priorität ändern	manuell vergeben
ticket.archive	Archiv öffnen, Tickets permanent löschen	manuell vergeben
ticket.admin	Voller Zugriff inkl. Weiterleitung, Reload, Blacklist, FAQ-Verwaltung	OP

ticket.archive ist nicht in ticket.admin enthalten und muss explizit vergeben werden.

Web-Panel Benutzerrollen

Rolle	Tickets	Archiv	FAQ	Weiterleiten
admin	✔	✔	✔	✔
archive_viewer	✔	✔	✗	✗
supporter	✔	✗	✗	✗

• Benutzernamen sind case-insensitiv (Groß-/Kleinschreibung egal) und dürfen Sonderzeichen enthalten (-, _, / usw.)
• Passwörter werden beim ersten Start automatisch als SHA-256-Hash gespeichert
• Benutzer können zur Laufzeit über die Web-API angelegt, geändert und gelöscht werden — kein Neustart nötig
• Brute-Force-Schutz: 5 Fehlversuche → 15 Minuten IP-Sperre

---

Mehrsprachigkeit

TicketSystem unterstützt drei Sprachmodi, die über einen einzigen Schlüssel in der config.yml gesteuert werden:

language: de     # Deutsch  – deutsche Texte & deutsche Befehlsnamen
language: en     # Englisch – englische Texte & englische Befehlsnamen
language: both   # Beides   – deutsche Texte & beide Befehlsnamen gleichzeitig

command-language existiert nicht mehr. Alle Einstellungen laufen über language.

Befehlsnamen je Sprachmodus

Interner Schlüssel	language: de	language: en	language: both
create	/ticket erstellen	/ticket create	/ticket create §8(§7erstellen§8)
list	/ticket liste	/ticket list	/ticket list §8(§7liste§8)
comment	/ticket kommentar	/ticket comment	/ticket comment §8(§7kommentar§8)
rate	/ticket bewerten	/ticket rate	/ticket rate §8(§7bewerten§8)
claim	/ticket übernehmen	/ticket claim	/ticket claim §8(§7übernehmen§8)
close	/ticket schließen	/ticket close	/ticket close §8(§7schließen§8)
forward	/ticket weiterleiten	/ticket forward	/ticket forward §8(§7weiterleiten§8)
reload	/ticket neuladen	/ticket reload	/ticket reload §8(§7neuladen§8)
stats	/ticket statistik	/ticket stats	/ticket stats §8(§7statistik§8)
archive	/ticket archivieren	/ticket archive	/ticket archive §8(§7archivieren§8)
migrate	/ticket migrieren	/ticket migrate	/ticket migrate §8(§7migrieren§8)
export	/ticket exportieren	/ticket export	/ticket export §8(§7exportieren§8)
import	/ticket importieren	/ticket import	/ticket import §8(§7importieren§8)
blacklist	/ticket sperrliste	/ticket blacklist	/ticket blacklist §8(§7sperrliste§8)
setpriority	/ticket priorität	/ticket setpriority	/ticket setpriority §8(§7priorität§8)
faq	/ticket faq	/ticket faq	/ticket faq
top	/ticket top	/ticket top	/ticket top

{cmd_X}-Platzhalter in den Sprachdateien

Alle Hilfetexte, Fehlermeldungen und GUI-Hinweise in lang_de.yml / lang_en.yml verwenden {cmd_X}-Platzhalter statt fester Befehlsnamen. Beim Anzeigen ersetzt der LanguageManager diese automatisch anhand des aktiven Sprachmodus.

Platzhalter	Beispiel-Ausgabe (language: en)
{cmd_create}	/ticket create
{cmd_list}	/ticket list
{cmd_comment}	/ticket comment
{cmd_rate}	/ticket rate
{cmd_claim}	/ticket claim
{cmd_close}	/ticket close
{cmd_forward}	/ticket forward
{cmd_reload}	/ticket reload
{cmd_stats}	/ticket stats
{cmd_archive}	/ticket archive
{cmd_migrate}	/ticket migrate
{cmd_export}	/ticket export
{cmd_import}	/ticket import
{cmd_blacklist}	/ticket blacklist
{cmd_setpriority}	/ticket setpriority
{cmd_faq}	/ticket faq
{cmd_top}	/ticket top

Verwendungsbeispiel in der Sprachdatei:

help:
  create: "&e{cmd_create} [Kategorie] <Text> &7– Neues Ticket erstellen"
  #  → language: de  gibt aus: /ticket erstellen [Kategorie] <Text>
  #  → language: en  gibt aus: /ticket create    [Kategorie] <Text>

GUI-Sprachanpassung

Seit dieser Version sind auch alle GUI-Texte vollständig sprachabhängig – Inventar-Titel, Item-Lore-Labels und Action-Buttons werden aus gui.item.* in der aktiven Sprachdatei geladen. Nach einem /ticket reload mit geändertem language-Wert wechselt die gesamte Oberfläche sofort.

---

FAQ-System

Das FAQ-System ermöglicht es Admins, häufige Fragen und Antworten direkt im Spiel zu verwalten. Die faqs.yml wird beim ersten Start automatisch generiert – inklusive Beispiel-Kategorien und Beispiel-FAQs.

Kategorien (Optional)

FAQs lassen sich optionalen Kategorien zuordnen. Sind Kategorien in der faqs.yml definiert, zeigt die GUI zunächst einen Kategorie-Auswahl-Screen. Ein Klick auf eine Kategorie öffnet die gefilterte FAQ-Liste mit einem Zurück-Button. Ohne Kategorien verhält sich die GUI wie gewohnt und listet alle FAQs direkt auf.

Das Aussehen der Kategorie-Items (Material und Custom-Head-Textur) wird zentral in der config.yml unter gui-settings.faq.category-head-item gesteuert. In der faqs.yml werden nur Name, Farbe und Beschreibung hinterlegt.

Kategorien verwalten (per Befehl):

/ticket kategorie add Support &b Fragen zum Support-Team
/ticket kategorie add Regeln &c Fragen zu den Server-Regeln
/ticket kategorie delete support
/ticket kategorie list

Kategorien verwalten (per GUI):

Als Admin: Shift+Klick auf ein Kategorie-Item im Auswahl-Screen öffnet eine Aktions-GUI mit Bearbeiten und Löschen.

Für Spieler

/ticket faq          – öffnet die FAQ-GUI (bei aktiven Kategorien: Auswahl zuerst)
/ticket faq list     – listet alle FAQs im Chat auf

Jeder FAQ-Eintrag wird als Custom-Skull-Item angezeigt. Ein Klick zeigt die vollständige Antwort im Chat.

Für Admins

/ticket faq add tickets Wie melde ich einen Bug? | Nutze /ticket create bug <Beschreibung>.
/ticket faq add Wie melde ich einen Bug? | Nutze /ticket create bug <Beschreibung>.
/ticket faq edit 1 Neue Frage? | Neue Antwort.
/ticket faq delete 1
/ticket faq reload
/ticket faq migrate tomysql   # faqs.yml → MySQL importieren
/ticket faq migrate tofile    # MySQL → faqs.yml exportieren (mit automatischem Backup der alten faqs.yml)

migrateFaqToFile() erstellt automatisch ein Backup der bestehenden faqs.yml mit Zeitstempel bevor sie überschrieben wird.

Der optionale Kategorie-Schlüssel als erstes Argument weist die neue FAQ direkt einer Kategorie zu. Der Tab-Completer schlägt alle vorhandenen Schlüssel vor.

Alternativ über die Admin-FAQ-GUI: Klick auf einen Eintrag öffnet eine Aktions-GUI mit Bearbeiten und Löschen. Neue FAQs per „Neues FAQ hinzufügen"-Button hinzufügen – die FAQ wird automatisch der aktuell geöffneten Kategorie zugeordnet.

faqs.yml (automatisch generiert)

categories:
  tickets:
    name: "Tickets"
    color: "&b"
    description: "Fragen zum Ticket-System"
  rules:
    name: "Regeln"
    color: "&c"
    description: "Fragen zu den Server-Regeln"

faqs:
  1:
    question: "Wie erstelle ich ein Ticket?"
    answer: "Nutze den Befehl /ticket create [Kategorie] [Beschreibung]."
    category: "tickets"
  2:
    question: "Wie lange dauert die Bearbeitung?"
    answer: "Unser Support-Team bearbeitet Tickets so schnell wie möglich."
    category: "tickets"

FAQ-Speicherung (MySQL oder Datei)

FAQs können wahlweise in der faqs.yml oder direkt in der MySQL-Datenbank gespeichert werden. Der Speichermodus wird automatisch aus use-mysql in der config.yml übernommen – kein separater Schalter nötig.

use-mysql	FAQ-Speicher
false	faqs.yml (Standard)
true	MySQL (faq_entries, faq_categories)

Migration von faqs.yml → MySQL:

/ticket faq migrate

Importiert alle Kategorien und Einträge aus der faqs.yml in die Datenbank. Duplikate werden automatisch übersprungen, der Befehl ist also mehrfach sicher ausführbar.

---

Backup-System

TicketSystem erstellt automatisch JSON-Backups der Ticket-Daten.

/ticket backup

Backups werden im Ordner plugins/TicketSystem/backups/ gespeichert mit Zeitstempel im Dateinamen (backup_tickets_YYYY-MM-DD_HH-mm-ss.json). Das Backup wird außerdem automatisch vor jeder Datenmigration erstellt.

• MySQL-Modus: Exportiert alle aktiven Tickets als JSON
• Datei-Modus: Kopiert die aktuelle data.yml / data.json

---

HTTPS / TLS

Der eingebettete Web-Server unterstützt optionales HTTPS via Java Keystore (JKS).

web-panel:
  ssl:
    enabled: true
    keystore-file: "keystore.jks"      # im plugins/TicketSystem/-Ordner
    keystore-password: "changeit"
    key-password: "changeit"

Self-Signed Zertifikat erstellen (für Tests):

keytool -genkeypair -alias ticketsystem -keyalg RSA -keysize 2048         -validity 365 -keystore plugins/TicketSystem/keystore.jks         -storepass changeit

Für Produktion wird ein Let's Encrypt-Zertifikat oder ein Reverse-Proxy (Nginx/Apache) empfohlen. Wenn der Keystore fehlt, startet der Server automatisch ohne TLS.

---

MySQL Auto-Reconnect

Bricht die MySQL-Verbindung während des Betriebs ab (z.B. Datenbankserver-Neustart), versucht das Plugin sie automatisch beim nächsten Datenbankzugriff wiederherzustellen — ohne Serverneustart.

---

Performance-Caching

Ab dieser Version hält TicketSystem häufig abgerufene Tickets in einem TTL-basierten In-Memory-Cache vor. Das reduziert die Datenbankbelastung bei wiederholten Zugriffen (GUI, Kommentare, Bewertungen) deutlich.

• Standard-Lebenszeit: 60 Sekunden (konfigurierbar: cache-ttl-seconds in config.yml)
• Der Cache wird bei Ticket-Änderungen (Claim, Close, Priorität usw.) automatisch invalidiert
• Regelmäßige Bereinigung abgelaufener Einträge alle 5 Minuten
• Der aktuelle Cache-Status ist in /ticket stats einsehbar

---

Kategorie & Priorität

Beim Erstellen eines Tickets können Kategorie und Priorität optional angegeben werden:

Befehl	Kategorie	Priorität
/ticket create <Text>	Standard	NORMAL
/ticket create bug <Text>	Bug	NORMAL
/ticket create high <Text>	Standard	HIGH
/ticket create bug high <Text>	Bug	HIGH
/ticket create question urgent <Text>	Frage	URGENT

Verfügbare Prioritäten: low, normal, high, urgent (auch deutsch: niedrig, hoch, dringend)

Kategorien und Aliases sind frei in der config.yml konfigurierbar.

---

Discord-Webhook

• Embeds mit Kategorie & Priorität
• Rollen-Ping pro Nachrichtentyp
• Drei Ereignisse: neues Ticket, Ticket geschlossen, Ticket weitergeleitet

Konfiguration in config.yml:

discord:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."
  role-ping-id: "123456789012345678"
  messages:
    new-ticket:
      role-ping: true
      show-category: true
      show-priority: true
    ticket-closed:
      enabled: true
      role-ping: false

---

BungeeCord-Unterstützung

TicketSystem bietet volle Unterstützung für BungeeCord-Netzwerke:

• Tickets von jedem Server im Netzwerk
• Teleport zu Tickets auf anderen Servern (/ticket teleport <ID>)
• Tickets im Archiv und GUI serverübergreifend
• Benachrichtigungen an alle Server
• Discord-Webhooks zeigen Server-Namen
• Tickets an Supporter auf anderen Servern weiterleiten

Voraussetzungen:

• spigot.yml: bungeecord: true
• config.yml: bungeecord: true, server-name pro Server
• TicketSystem.jar auf allen Spigot-Servern
• Alle Server nutzen dieselbe MySQL-Datenbank

---

Vergleich mit anderen Plugins

Feature	TicketSystem	SimpleTickets	AdvancedTickets
Speicher-Migration	✔️	⚠️	✖️
Automatische Backups	✔️	⚠️	✖️
GUI mit Kategorien	✔️	⚠️	✖️
Archivierung	✔️	⚠️	✖️
Rollenbasierter Archiv-Zugriff	✔️	✖️	✖️
Kategorie-System	✔️	✖️	✖️
Prioritäten-System	✔️	✖️	✖️
FAQ-System mit Kategorien	✔️	✖️	✖️
Performance-Caching	✔️	✖️	✖️
Offline-Benachrichtigungen	✔️	✖️	✖️
Discord-Webhook	✔️	✖️	✖️
Bewertungs-System	✔️	✖️	✖️
Update-Checker	✔️	✖️	✖️
BungeeCord-Unterstützung	✔️	✖️	✖️
Backup-System	✔️	✖️	✖️
HTTPS/TLS-Unterstützung	✔️	✖️	✖️
MySQL Auto-Reconnect	✔️	✖️	✖️
Brute-Force-Schutz Web-Panel	✔️	✖️	✖️
Archiv-Verwaltung Web-Panel	✔️	✖️	✖️

Legende: ✔️ Vollständige Unterstützung · ⚠️ Eingeschränkt · ✖️ Nicht vorhanden

---

FAQ

Kann ich zwischen MySQL und Datei-Speicherung wechseln?

Ja! Mit /ticket migrate tomysql oder /ticket migrate tofile werden alle Daten automatisch migriert.

Wie konfiguriere ich eigene Kategorien?

In der config.yml unter categories: – Name, Farbe, Material und Aliases frei wählbar. Änderungen mit /ticket reload übernehmen.

Wie verwalte ich FAQs?

Mit /ticket faq öffnest du die GUI. Als Admin kannst du über die GUI oder per /ticket faq add|edit|delete FAQs verwalten. Daten liegen je nach Konfiguration in faqs.yml (Datei-Modus) oder in der MySQL-Datenbank.

Wie richte ich FAQ-Kategorien ein?

Die faqs.yml wird beim ersten Start automatisch mit vier Beispiel-Kategorien erstellt. Neue Kategorien per /ticket kategorie add <Name> [&Farbe] [Beschreibung] hinzufügen, löschen per /ticket kategorie delete <Schlüssel>. Das Aussehen der Kategorie-Items wird in config.yml unter gui-settings.faq.category-head-item gesteuert.

Wie verwalte ich das Archiv im Web-Panel?

Admins und Archive Viewer können archivierte Tickets über /tickets?status=ARCHIVED einsehen. Admins können einzelne Tickets permanent löschen (deleteArchivedTicket) oder in die aktive Datenbank wiederherstellen (restoreArchivedTicket). Die Aktionen stehen als Buttons in der Ticket-Detailansicht zur Verfügung.

Was passiert mit Benachrichtigungen wenn ein Spieler offline ist?

Alle Benachrichtigungen werden gespeichert und beim nächsten Login angezeigt.

Wie ändere ich die Priorität eines Tickets?

Als Support/Admin per /ticket setpriority <ID> <Priorität> oder direkt in der GUI.

Wie aktiviere ich den Debug-Modus?

debug: true in der config.yml setzen.

Wer darf das Ticket-Archiv sehen?

Nur Spieler mit ticket.archive. Muss explizit vergeben werden.

Wie funktioniert Teleport bei BungeeCord?

Mit /ticket teleport <ID> wirst du automatisch auf den richtigen Server und zur Ticket-Position teleportiert.

Wie lange werden Tickets gecacht?

Standardmäßig 60 Sekunden. Über cache-ttl-seconds in der config.yml anpassbar. Der Cache wird bei Änderungen sofort invalidiert.

---

Dein Feedback zählt: Wenn TicketSystem deinen Server bereichert hat, freuen wir uns über eine 5-Sterne Bewertung auf SpigotMC! Jede Rückmeldung hilft, das Plugin weiter zu verbessern und die Community zu stärken.