Web-Frontend entwickeln - Versionsgeschichte

Clawtronics: Erkenntnisse aus GKP-Frontendprüfung: Hash-Routing, Sitzungsdaten, Hosting und Reproduzierbarkeit

2026-08-06T20:50:08Z

Erkenntnisse aus GKP-Frontendprüfung: Hash-Routing, Sitzungsdaten, Hosting und Reproduzierbarkeit

← Nächstältere Version		Version vom 6. August 2026, 20:50 Uhr
Zeile 471:		Zeile 471:
	* Mehrfachklicks verhindern, solange ein Request läuft.		* Mehrfachklicks verhindern, solange ein Request läuft.
	* Erst nach erfolgreicher Antwort den nächsten fachlichen Zustand anzeigen.		* Erst nach erfolgreicher Antwort den nächsten fachlichen Zustand anzeigen.
	* Ticketcodes und Pseudo-IDs nicht in der URL oder in dauerhaftem <code>localStorage</code> speichern.		* Ticketcodes und Pseudo-IDs nicht in der URL oder in dauerhaftem <code>localStorage</code> speichern. Für eine nur bis zum Schließen des Tabs benötigte Sitzung ist <code>sessionStorage</code> geeigneter; noch besser ist flüchtiger JavaScript-Zustand.
			* Ticketcodes, Pseudo-IDs und vollständige authentifizierte Request-URLs nicht mit <code>console.log</code> oder in öffentlich zugängliche Telemetrie schreiben.
	* Bei Seitenneuladung <code>/verify</code> verwenden, bevor eine bestehende Sitzung angenommen wird.		* Bei Seitenneuladung <code>/verify</code> verwenden, bevor eine bestehende Sitzung angenommen wird.
	* Eine Station erst als verbunden anzeigen, wenn <code>/media-station</code> erfolgreich war.		* Eine Station erst als verbunden anzeigen, wenn <code>/media-station</code> erfolgreich war.
Zeile 490:		Zeile 491:

	Dadurch wird der Code nicht unnötig in kopierten URLs oder späteren Screenshots weitergegeben. Webserver- und Proxy-Logs können den ursprünglichen Request trotzdem bereits enthalten; Ticketcodes bleiben deshalb kurzlebige Einmalwerte.		Dadurch wird der Code nicht unnötig in kopierten URLs oder späteren Screenshots weitergegeben. Webserver- und Proxy-Logs können den ursprünglichen Request trotzdem bereits enthalten; Ticketcodes bleiben deshalb kurzlebige Einmalwerte.

			Bei Frontends mit Hash-Routing, zum Beispiel <code>/#/welcome?systemCode=123456</code>, liegt der Parameter nicht in <code>window.location.search</code>, sondern innerhalb des Hash-Fragments. Er muss dort separat entfernt werden. Das verwendete Router-Framework soll nach erfolgreicher Übernahme mit einer ersetzenden Navigation (<code>replace</code>, nicht <code>push</code>) auf dieselbe Route ohne <code>systemCode</code> wechseln. So bleibt der Code auch nicht über die Zurück-Funktion erreichbar. Ein Hash-Fragment wird zwar nicht an den Webserver übertragen, bleibt aber in Browserhistorie, kopierten Links und Screenshots sichtbar.
	== CORS und Hosting ==		== CORS und Hosting ==

	Der aktuelle MegBes-Stand erlaubt CORS-Anfragen grundsätzlich. Das ist keine Zusage, dass jede zukünftige Instanz beliebige Origins akzeptiert. Bevorzugt werden Frontend und API unter kontrollierten HTTPS-Adressen betrieben. Ein CORS-Fehler wird nicht durch Abschalten von Browsersicherheit oder Zertifikatsprüfung umgangen.		Der aktuelle MegBes-Stand erlaubt CORS-Anfragen grundsätzlich. Das ist keine Zusage, dass jede zukünftige Instanz beliebige Origins akzeptiert. Bevorzugt werden Frontend und API unter kontrollierten HTTPS-Adressen betrieben. Ein CORS-Fehler wird nicht durch Abschalten von Browsersicherheit oder Zertifikatsprüfung umgangen.

			Bei Single-Page-Anwendungen müssen öffentlicher Basispfad, Router-Basis und Asset-Pfade zur tatsächlichen Bereitstellung passen. Eine Anwendung, die beispielsweise für <code>/projekt/</code> gebaut wurde, ist ohne Neubau oder passende Serverkonfiguration nicht automatisch unter <code>/</code> oder einem anderen Unterpfad lauffähig. Direkte Aufrufe von Unterseiten benötigen außerdem eine passende Fallback-Regel auf <code>index.html</code>.

			Zum Projektarchiv gehören neben den ausgelieferten minifizierten Dateien auch Quellcode, Paketmanifest, Lockdatei, Build-Anweisung und verwendete Laufzeitversionen. Nur ein Build-Ordner reicht nicht aus, um das Frontend später reproduzierbar zu warten oder sicher zu aktualisieren.

	== Bestätigter Referenztest ==		== Bestätigter Referenztest ==
Zeile 503:		Zeile 510:

	Der Test bestätigt den Signalweg bis zum UDP-Versand. Der tatsächliche Empfang und die Reaktion eines Endgeräts müssen bei der Projektabnahme separat geprüft werden. Konkrete IP-Adressen, Ticketcodes und Geheimwerte werden nicht im Wiki festgehalten.		Der Test bestätigt den Signalweg bis zum UDP-Versand. Der tatsächliche Empfang und die Reaktion eines Endgeräts müssen bei der Projektabnahme separat geprüft werden. Konkrete IP-Adressen, Ticketcodes und Geheimwerte werden nicht im Wiki festgehalten.

			Eine ergänzende statische Prüfung des umfangreicheren Ionic-/Vue-Frontends des Projekts <code>gkp</code> bestätigte denselben grundlegenden Vertrag: Aktivierung über <code>/enter-system</code>, Prüfung über <code>/verify</code>, Stationsanmeldung und optionaler Stationsstatus sowie Befehle über <code>/video-command</code> mit dem konfigurierten Authentifizierungsheader. Damit ist der hier beschriebene Ablauf nicht nur mit der Minimalvorlage, sondern auch mit einem realen mehrsprachigen Projektfrontend konsistent. Diese Prüfung bestätigt die API-Verwendung im Frontend; sie ersetzt keinen End-to-End-Test der jeweiligen Installation.
	== Entwicklungs- und Abnahmetests ==		== Entwicklungs- und Abnahmetests ==

Clawtronics: Zeilenumbrueche der neuen Abschnitte korrigiert

2026-08-06T20:29:11Z

Zeilenumbrueche der neuen Abschnitte korrigiert

← Nächstältere Version		Version vom 6. August 2026, 20:29 Uhr
Zeile 321:		Zeile 321:
	</pre>		</pre>

	Die Abmeldung soll über eine sichtbare Bedienhandlung und bei regulärem Abschluss erfolgen. Ein Aufruf in <code>beforeunload</code> ist allein nicht zuverlässig, da Browser ausstehende Requests beim Schließen abbrechen können. Der projektspezifische Stations-Timer bleibt daher als Rückfallebene erforderlich.~~`r`n`r`n~~<code>DELETE /media-station</code> gibt nur die aktuell belegte Station frei und setzt deren Stationszustand zurück. Die Ticket- beziehungsweise Benutzersitzung bleibt gültig; ein anschließendes <code>GET /verify</code> kann daher weiterhin <code>200 OK</code> liefern. So kann derselbe Besucher danach eine andere Station auswählen.		Die Abmeldung soll über eine sichtbare Bedienhandlung und bei regulärem Abschluss erfolgen. Ein Aufruf in <code>beforeunload</code> ist allein nicht zuverlässig, da Browser ausstehende Requests beim Schließen abbrechen können. Der projektspezifische Stations-Timer bleibt daher als Rückfallebene erforderlich.

			<code>DELETE /media-station</code> gibt nur die aktuell belegte Station frei und setzt deren Stationszustand zurück. Die Ticket- beziehungsweise Benutzersitzung bleibt gültig; ein anschließendes <code>GET /verify</code> kann daher weiterhin <code>200 OK</code> liefern. So kann derselbe Besucher danach eine andere Station auswählen.

	== Vollständiger Ablauf eines Besucher-Frontends ==		== Vollständiger Ablauf eines Besucher-Frontends ==

Clawtronics: Erkenntnisse aus Tine-End-to-End-Test und blank-Frontend eingearbeitet

2026-08-06T20:28:41Z

Erkenntnisse aus Tine-End-to-End-Test und blank-Frontend eingearbeitet

← Nächstältere Version		Version vom 6. August 2026, 20:28 Uhr
Zeile 32:		Zeile 32:
	Domains, Headername, Projektkennung, Stationsnummern und Befehle dürfen nicht ungeprüft von einem anderen Projekt übernommen werden.		Domains, Headername, Projektkennung, Stationsnummern und Befehle dürfen nicht ungeprüft von einem anderen Projekt übernommen werden.

			== Betriebsarten und Stationsstatus ==

			{\| class="wikitable"
			! Betriebsart
			! Konfiguration
			! Verhalten des Frontends
			\|-
			\| extern verwaltete Stationsbelegung \|\| <code>megbes.internal.station.controlled=false</code> \|\| Station über <code>GET /media-station?station=...</code> belegen; den Status-Endpunkt nicht aufrufen
			\|-
			\| durch <code>megbes-internal</code> kontrollierte Station \|\| <code>megbes.internal.station.controlled=true</code> \|\| nach der Stationsanmeldung zusätzlich <code>GET /media-station/status/{stationNumber}</code> auswerten
			\|}

			Liefert der Status-Endpunkt <code>404 Not Found</code>, obwohl Anmeldung und Stationsbelegung funktionieren, ist zuerst die Betriebsart zu prüfen. Bei extern verwalteter Stationsbelegung ist <code>404</code> erwartbar und bedeutet nicht, dass die Station belegt oder gestört ist. Die Betriebsart soll als zentraler Projektwert gepflegt und nicht aus einer fehlgeschlagenen Statusabfrage erraten werden.
	== API-Übersicht ==		== API-Übersicht ==

Zeile 56:		Zeile 69:
	\| <code>GET /media-station/status/{stationNumber}</code> \|\| Stationszustand abrufen \|\| USER oder ADMIN; nur bei intern kontrollierten Stationen \|\| <code>200</code> und <code>{ "stationStatus": "..." }</code>		\| <code>GET /media-station/status/{stationNumber}</code> \|\| Stationszustand abrufen \|\| USER oder ADMIN; nur bei intern kontrollierten Stationen \|\| <code>200</code> und <code>{ "stationStatus": "..." }</code>
	\|-		\|-
	\| <code>POST /video-command</code> \|\| einen oder mehrere UDP-Befehle senden \|\| ohne Security frei, sonst USER oder ADMIN \|\| ~~Antwort von~~ <code>~~megbes-internal~~</code>		\| <code>POST /video-command</code> \|\| einen oder mehrere UDP-Befehle senden \|\| ohne Security frei, sonst USER oder ADMIN \|\| <code>200</code> mit leerem Antwortkörper
	\|-		\|-
	\| <code>DELETE /media-station</code> \|\| Benutzer abmelden und Station zurücksetzen \|\| USER oder ADMIN \|\| <code>200</code>		\| <code>DELETE /media-station</code> \|\| Benutzer abmelden und Station zurücksetzen \|\| USER oder ADMIN \|\| <code>200</code>
Zeile 294:		Zeile 307:
	}		}
	</pre>		</pre>

			Der erfolgreiche Aufruf antwortet derzeit mit <code>200 OK</code> und leerem Body. JavaScript-Clients dürfen deshalb nicht zwingend JSON parsen. Bei jQuery ist insbesondere <code>dataType: 'json'</code> für diesen Aufruf ungeeignet. Eine Navigation oder Erfolgsmeldung darf nur im Erfolgszweig (<code>.done()</code> beziehungsweise <code>response.ok</code>) erfolgen, nicht in <code>.always()</code> oder <code>finally</code>.

	=== 6. Station abmelden ===		=== 6. Station abmelden ===
Zeile 306:		Zeile 321:
	</pre>		</pre>

	Die Abmeldung soll über eine sichtbare Bedienhandlung und bei regulärem Abschluss erfolgen. Ein Aufruf in <code>beforeunload</code> ist allein nicht zuverlässig, da Browser ausstehende Requests beim Schließen abbrechen können. Der projektspezifische Stations-Timer bleibt daher als Rückfallebene erforderlich.		Die Abmeldung soll über eine sichtbare Bedienhandlung und bei regulärem Abschluss erfolgen. Ein Aufruf in <code>beforeunload</code> ist allein nicht zuverlässig, da Browser ausstehende Requests beim Schließen abbrechen können. Der projektspezifische Stations-Timer bleibt daher als Rückfallebene erforderlich.`r`n`r`n<code>DELETE /media-station</code> gibt nur die aktuell belegte Station frei und setzt deren Stationszustand zurück. Die Ticket- beziehungsweise Benutzersitzung bleibt gültig; ein anschließendes <code>GET /verify</code> kann daher weiterhin <code>200 OK</code> liefern. So kann derselbe Besucher danach eine andere Station auswählen.

	== Vollständiger Ablauf eines Besucher-Frontends ==		== Vollständiger Ablauf eines Besucher-Frontends ==
Zeile 462:		Zeile 477:
	* Stationsbefehle nur aus einer festen projektspezifischen Positivliste erzeugen, nicht aus frei eingegebenem Besuchertest.		* Stationsbefehle nur aus einer festen projektspezifischen Positivliste erzeugen, nicht aus frei eingegebenem Besuchertest.

			=== Ticketcode aus der URL entfernen ===

			Wird ein Ticketcode per QR-Link als Queryparameter übergeben, soll das Frontend ihn nach erfolgreicher Übernahme sofort aus der sichtbaren URL und der aktuellen Browserhistorie entfernen:

			<pre>
			const cleanUrl = new URL(window.location.href);
			cleanUrl.searchParams.delete("systemCode");
			window.history.replaceState({}, "", cleanUrl.pathname + cleanUrl.search + cleanUrl.hash);
			</pre>

			Dadurch wird der Code nicht unnötig in kopierten URLs oder späteren Screenshots weitergegeben. Webserver- und Proxy-Logs können den ursprünglichen Request trotzdem bereits enthalten; Ticketcodes bleiben deshalb kurzlebige Einmalwerte.
	== CORS und Hosting ==		== CORS und Hosting ==

	Der aktuelle MegBes-Stand erlaubt CORS-Anfragen grundsätzlich. Das ist keine Zusage, dass jede zukünftige Instanz beliebige Origins akzeptiert. Bevorzugt werden Frontend und API unter kontrollierten HTTPS-Adressen betrieben. Ein CORS-Fehler wird nicht durch Abschalten von Browsersicherheit oder Zertifikatsprüfung umgangen.		Der aktuelle MegBes-Stand erlaubt CORS-Anfragen grundsätzlich. Das ist keine Zusage, dass jede zukünftige Instanz beliebige Origins akzeptiert. Bevorzugt werden Frontend und API unter kontrollierten HTTPS-Adressen betrieben. Ein CORS-Fehler wird nicht durch Abschalten von Browsersicherheit oder Zertifikatsprüfung umgangen.

			== Bestätigter Referenztest ==

			Am 6. August 2026 wurde der vollständige Ablauf gegen das interne Projekt <code>tine</code> geprüft:

			Frontend-Aufruf → megbes-external → megbes-internal → UDP-Versand

			<code>enter-system</code>, <code>verify</code>, Stationsanmeldung, <code>video-command</code> mit <code>start</code> und <code>stop</code>, Stationsabmeldung sowie erneutes <code>verify</code> antworteten jeweils mit <code>200 OK</code>. <code>megbes-internal</code> bestätigte den UDP-Versand beider Befehle. Die Statusabfrage antwortete erwartungsgemäß mit <code>404</code>, da <code>tine</code> nicht im intern stationsgesteuerten Modus betrieben wird.

			Der Test bestätigt den Signalweg bis zum UDP-Versand. Der tatsächliche Empfang und die Reaktion eines Endgeräts müssen bei der Projektabnahme separat geprüft werden. Konkrete IP-Adressen, Ticketcodes und Geheimwerte werden nicht im Wiki festgehalten.
	== Entwicklungs- und Abnahmetests ==		== Entwicklungs- und Abnahmetests ==

Clawtronics: Tabellenzeilen korrekt trennen

2026-08-06T19:43:44Z

Tabellenzeilen korrekt trennen

← Nächstältere Version		Version vom 6. August 2026, 19:43 Uhr
Zeile 16:		Zeile 16:
	\|-		\|-
	\| API-Basisadresse \|\| HTTPS-Adresse der projektspezifischen External-Instanz		\| API-Basisadresse \|\| HTTPS-Adresse der projektspezifischen External-Instanz
			\|-
	\| Projektkennung \|\| Wert für <code>prSc</code>; gegen den eingesetzten Release und die Projektkonfiguration prüfen		\| Projektkennung \|\| Wert für <code>prSc</code>; gegen den eingesetzten Release und die Projektkonfiguration prüfen
			\|-
	\| Sicherheitsmodus \|\| ohne Authentifizierung oder zentrale Ticket-/Benutzerauthentifizierung		\| Sicherheitsmodus \|\| ohne Authentifizierung oder zentrale Ticket-/Benutzerauthentifizierung
			\|-
	\| Stationssteuerung \|\| extern oder durch <code>megbes-internal</code> kontrolliert		\| Stationssteuerung \|\| extern oder durch <code>megbes-internal</code> kontrolliert
			\|-
	\| Token-Header \|\| Wert der Laufzeitkonfiguration <code>jwt.header</code>; nicht pauschal <code>Authorization</code> annehmen		\| Token-Header \|\| Wert der Laufzeitkonfiguration <code>jwt.header</code>; nicht pauschal <code>Authorization</code> annehmen
			\|-
	\| Stationsnummern \|\| freigegebene Stationen des Projekts		\| Stationsnummern \|\| freigegebene Stationen des Projekts
			\|-
	\| Stationsbefehle \|\| projektspezifische Befehle, die die jeweilige Station tatsächlich versteht		\| Stationsbefehle \|\| projektspezifische Befehle, die die jeweilige Station tatsächlich versteht
	\|}		\|}

Clawtronics: Codebloecke und Inline-Code an MediaWiki-Syntax angepasst

2026-08-06T19:28:19Z

Codebloecke und Inline-Code an MediaWiki-Syntax angepasst

Änderungen zeigen

Clawtronics: Nicht installierte SyntaxHighlight-Tags durch kompatible pre-Codebloecke ersetzt

2026-08-06T19:20:35Z

Nicht installierte SyntaxHighlight-Tags durch kompatible pre-Codebloecke ersetzt

Änderungen zeigen

Clawtronics: Umlaute auch in kopierbaren Codebeispielen normalisiert

2026-08-06T19:06:29Z

Umlaute auch in kopierbaren Codebeispielen normalisiert

Änderungen zeigen

Clawtronics: Ausfuehrliche HTML- und JavaScript-Entwicklerdokumentation aus aktuellem Repository erstellt

2026-08-06T19:05:53Z

Ausfuehrliche HTML- und JavaScript-Entwicklerdokumentation aus aktuellem Repository erstellt

Neue Seite

= Web-Frontend entwickeln =

== Zweck und Geltungsbereich ==

Diese Seite beschreibt die HTML-/JavaScript-Anbindung eines Web-Frontends an `megbes-external`. Sie basiert auf den Controllern und Request-Modellen des aktuellen MegBes-Repositorys. Vor der Freigabe eines Frontends muss trotzdem geprüft werden, welcher MegBes-Release im betreffenden Projekt installiert ist.

Das Frontend spricht ausschließlich `megbes-external` an. Direkte Browseraufrufe an `megbes-internal` sind nicht vorgesehen.

Browser → HTTPS → megbes-external → megbes-internal → UDP → Station

== Vor Beginn festlegen ==

{| class="wikitable"
! Wert
! Bedeutung
|-
| API-Basisadresse || HTTPS-Adresse der projektspezifischen External-Instanz
| Projektkennung || Wert für `prSc`; gegen den eingesetzten Release und die Projektkonfiguration prüfen
| Sicherheitsmodus || ohne Authentifizierung oder zentrale Ticket-/Benutzerauthentifizierung
| Stationssteuerung || extern oder durch `megbes-internal` kontrolliert
| Token-Header || Wert der Laufzeitkonfiguration `jwt.header`; nicht pauschal `Authorization` annehmen
| Stationsnummern || freigegebene Stationen des Projekts
| Stationsbefehle || projektspezifische Befehle, die die jeweilige Station tatsächlich versteht
|}

Domains, Headername, Projektkennung, Stationsnummern und Befehle dürfen nicht ungeprüft von einem anderen Projekt übernommen werden.

== API-Übersicht ==

{| class="wikitable"
! Methode und Pfad
! Zweck
! Berechtigung
! Erfolgsantwort
|-
| `GET /info` || vom Server empfangenen User-Agent prüfen || frei || `200` mit User-Agent
|-
| `POST /authenticate` || Ticket-Monitor administrativ authentifizieren || frei; benötigt Header `customer` und `authId` || `200` und `{ "id": "..." }`
|-
| `GET /verify-admin` || Administrationskennung prüfen || ADMIN || `200`
|-
| `GET /ticket` || Ticketcode erzeugen oder vorhandenen unbenutzten Code abrufen || ADMIN || `200` und `{ "id": "......" }`
|-
| `POST /enter-system` || Ticketcode einmalig aktivieren || frei || `200`
|-
| `GET /verify` || aktivierte Benutzerkennung prüfen || USER oder ADMIN || `200`
|-
| `GET /media-station?station=...` || Benutzer an Station anmelden || USER oder ADMIN || `200`
|-
| `GET /media-station/status/{stationNumber}` || Stationszustand abrufen || USER oder ADMIN; nur bei intern kontrollierten Stationen || `200` und `{ "stationStatus": "..." }`
|-
| `POST /video-command` || einen oder mehrere UDP-Befehle senden || ohne Security frei, sonst USER oder ADMIN || Antwort von `megbes-internal`
|-
| `DELETE /media-station` || Benutzer abmelden und Station zurücksetzen || USER oder ADMIN || `200`
|}

== Wichtige Authentifizierungsregel ==

MegBes liefert dem Browser beziehungsweise Ticket-Monitor eine '''Pseudo-ID'''. Der eigentliche JWT verbleibt serverseitig. Bei geschützten Folgeaufrufen sendet das Frontend die Pseudo-ID als Wert des projektspezifisch konfigurierten Token-Headers.

<nowiki><konfigurierter-token-header>: <Pseudo-ID></nowiki>

Der Headername stammt aus `jwt.header`. Er darf im Frontend nicht geraten werden. Die Pseudo-ID ist wie eine Sitzungskennung zu behandeln: nicht protokollieren, nicht in URLs anhängen und nicht ins Wiki kopieren.

== Request-Modelle ==

=== System betreten ===

`POST /enter-system`

<syntaxhighlight lang="json">
{
"systemCode": "123456"
}
</syntaxhighlight>

`systemCode` darf nicht leer sein. Ein unbekannter oder bereits verwendeter Code ergibt `401 Unauthorized`.

=== Stationsbefehl ===

`POST /video-command`

<syntaxhighlight lang="json">
{
"prSc": "<Projektkennung>",
"statNoCommands": [
"12-play"
]
}
</syntaxhighlight>

Regeln des aktuellen Request-Modells:

* `prSc` ist Pflicht und darf nicht leer sein.
* `statNoCommands` ist eine nicht leere Liste.
* Jeder Listeneintrag folgt `\d{0,3}-[0-9a-zA-Z]{2,20}`.
* Vor dem Bindestrich sind damit null bis drei Ziffern zulässig; für produktive Stationsbefehle soll eine eindeutige, im Projekt dokumentierte Stationsnummer verwendet werden.
* Nach dem Bindestrich sind zwei bis zwanzig ASCII-Buchstaben oder Ziffern zulässig.
* Ob ein formal gültiger Befehl fachlich unterstützt wird, entscheidet die jeweilige Stationssoftware.

Beispiele wie `12-play` sind nur Formbeispiele und keine globale MegBes-Befehlsliste.

== Empfohlener JavaScript-API-Client ==

Die Netzwerkanbindung soll an einer Stelle gekapselt werden. Dadurch bleiben Fehlerbehandlung, Header und JSON-Verarbeitung konsistent.

<syntaxhighlight lang="javascript">
const megBesConfig = Object.freeze({
apiBase: "https://<projekt>.megbes.de",
projectCode: "<PROJEKTKENNUNG>",
tokenHeader: "<WERT-AUS-jwt.header>"
});

class MegBesError extends Error {
constructor(message, status, responseBody) {
super(message);
this.name = "MegBesError";
this.status = status;
this.responseBody = responseBody;
}
}

async function megBesRequest(path, {
method = "GET",
token = null,
body = undefined,
headers = {}
} = {}) {
const requestHeaders = new Headers(headers);

if (token) {
requestHeaders.set(megBesConfig.tokenHeader, token);
}
if (body !== undefined) {
requestHeaders.set("Content-Type", "application/json");
}

let response;
try {
response = await fetch(`${megBesConfig.apiBase}${path}`, {
method,
headers: requestHeaders,
body: body === undefined ? undefined : JSON.stringify(body),
cache: "no-store"
});
} catch (cause) {
throw new MegBesError("MegBes ist nicht erreichbar.", 0, cause);
}

const contentType = response.headers.get("content-type") || "";
const responseBody = contentType.includes("application/json")
? await response.json()
: await response.text();

if (!response.ok) {
throw new MegBesError(
`MegBes-Aufruf fehlgeschlagen (${response.status}).`,
response.status,
responseBody
);
}

return responseBody;
}
</syntaxhighlight>

== Variante A: Frontend ohne Authentifizierung ==

Diese Variante existiert nur, wenn `megbes.security` für die External-Instanz nicht aktiviert ist. Das Frontend darf diesen Modus nicht anhand eines fehlgeschlagenen Loginversuchs erraten; er wird vor der Entwicklung projektspezifisch festgelegt.

<syntaxhighlight lang="javascript">
async function sendCommandWithoutAuthentication(station, command) {
return megBesRequest("/video-command", {
method: "POST",
body: {
prSc: megBesConfig.projectCode,
statNoCommands: [`${station}-${command}`]
}
});
}
</syntaxhighlight>

Auch ohne MegBes-Authentifizierung muss die External-Instanz ausschließlich über HTTPS angesprochen werden. Welche Personen die Seite erreichen dürfen, ist außerhalb von MegBes abzusichern.

== Variante B: Ticket-Monitor ==

=== 1. Ticket-Monitor authentifizieren ===

Der Ticket-Monitor ruft `POST /authenticate` mit den Headern `customer` und `authId` auf. Zusätzlich prüft MegBes den User-Agent gegen die Projektkonfiguration.

<syntaxhighlight lang="javascript">
async function authenticateTicketMonitor(customer, authId) {
const response = await megBesRequest("/authenticate", {
method: "POST",
headers: {
customer,
authId
}
});
return response.id;
}
</syntaxhighlight>

`authId` ist ein Geheimwert und darf nicht fest in ausgelieferter Browser-JavaScript-Datei stehen. Wenn der Ticket-Monitor nur statische öffentliche Dateien ausliefert, ist dieses Verfahren sicherheitlich neu zu bewerten. Die Kennung gehört in eine geschützte Laufzeitumgebung oder einen vertrauenswürdigen lokalen Dienst.

=== 2. Ticketcode abrufen ===

<syntaxhighlight lang="javascript">
async function getTicket(adminToken, customer, ticketMonitorNumber) {
const query = new URLSearchParams({
customer,
ticketMonitorNumber: String(ticketMonitorNumber)
});

const response = await megBesRequest(`/ticket?${query}`, {
token: adminToken
});
return response.id;
}
</syntaxhighlight>

Der gelieferte Code ist im aktuellen Stand sechsstellig. Das Frontend soll ihn als String behandeln, damit eine führende Null nicht verloren geht.

== Variante C: Besucher- oder Guide-Frontend mit Ticketcode ==

=== 1. Code aktivieren ===

<syntaxhighlight lang="javascript">
async function enterSystem(systemCode) {
await megBesRequest("/enter-system", {
method: "POST",
body: { systemCode }
});
return systemCode;
}
</syntaxhighlight>

Nach erfolgreichem Eintritt dient derselbe Code als Pseudo-ID für die weiteren Aufrufe. Ein Ticketcode kann nur einmal aktiviert werden.

=== 2. Kennung prüfen ===

<syntaxhighlight lang="javascript">
async function verifyUser(userToken) {
await megBesRequest("/verify", { token: userToken });
return true;
}
</syntaxhighlight>

=== 3. An Station anmelden ===

<syntaxhighlight lang="javascript">
async function loginStation(userToken, stationNumber) {
const query = new URLSearchParams({ station: String(stationNumber) });
await megBesRequest(`/media-station?${query}`, { token: userToken });
}
</syntaxhighlight>

Im intern kontrollierten Modus ist die Stationsnummer zwingend. Ein `401` kann neben einer ungültigen Kennung auch bedeuten, dass die Station belegt ist oder die Stationsanmeldung abgelehnt wurde. Die Bedienoberfläche darf deshalb nicht automatisch behaupten, der Ticketcode sei falsch.

=== 4. Optional Stationsstatus prüfen ===

Dieser Endpunkt ist nur verfügbar, wenn `megbes.internal.station.controlled=true` gilt.

<syntaxhighlight lang="javascript">
async function getStationStatus(userToken, stationNumber) {
const response = await megBesRequest(
`/media-station/status/${encodeURIComponent(stationNumber)}`,
{ token: userToken }
);
return response.stationStatus;
}
</syntaxhighlight>

Der aktuelle Code verwendet unter anderem die Zustände `OPEN`, `IDLE`, `REMOTE` und `TOUCHSCREEN`. Die Oberfläche soll unbekannte künftige Werte neutral anzeigen und nicht abstürzen.

=== 5. Befehl senden ===

<syntaxhighlight lang="javascript">
async function sendCommand(userToken, stationNumber, command) {
return megBesRequest("/video-command", {
method: "POST",
token: userToken,
body: {
prSc: megBesConfig.projectCode,
statNoCommands: [`${stationNumber}-${command}`]
}
});
}
</syntaxhighlight>

=== 6. Station abmelden ===

<syntaxhighlight lang="javascript">
async function logoutStation(userToken) {
await megBesRequest("/media-station", {
method: "DELETE",
token: userToken
});
}
</syntaxhighlight>

Die Abmeldung soll über eine sichtbare Bedienhandlung und bei regulärem Abschluss erfolgen. Ein Aufruf in `beforeunload` ist allein nicht zuverlässig, da Browser ausstehende Requests beim Schließen abbrechen können. Der projektspezifische Stations-Timer bleibt daher als Rückfallebene erforderlich.

== Vollständiger Ablauf eines Besucher-Frontends ==

<syntaxhighlight lang="javascript">
let userToken = null;
let activeStation = null;

async function startSession(systemCode, stationNumber) {
userToken = await enterSystem(systemCode);
await verifyUser(userToken);

// Nur im intern kontrollierten Modus vorab verwenden.
// const status = await getStationStatus(userToken, stationNumber);

await loginStation(userToken, stationNumber);
activeStation = String(stationNumber);
}

async function play(command) {
if (!userToken || !activeStation) {
throw new Error("Keine aktive MegBes-Station.");
}
await sendCommand(userToken, activeStation, command);
}

async function endSession() {
if (userToken && activeStation) {
await logoutStation(userToken);
}
userToken = null;
activeStation = null;
}
</syntaxhighlight>

== Minimales HTML-Beispiel ==

Das Beispiel zeigt die Struktur, ist aber ohne projektspezifische Werte und Gestaltung nicht produktionsfertig.

<syntaxhighlight lang="html">
<!doctype html>
<html lang="de">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>MegBes-Steuerung</title>
</head>
<body>
<main>
<form id="login-form">
<label for="code">Ticketcode</label>
<input id="code" name="code" inputmode="numeric" autocomplete="one-time-code" required>

<label for="station">Station</label>
<input id="station" name="station" inputmode="numeric" required>

<button type="submit">Station verbinden</button>
</form>

<section id="controls" hidden>
<button type="button" data-command="play">Start</button>
<button type="button" data-command="stop">Stopp</button>
<button type="button" id="logout">Beenden</button>
</section>

<p id="message" role="status" aria-live="polite"></p>
</main>

<script src="megbes-api.js"></script>
<script>
const form = document.querySelector("#login-form");
const controls = document.querySelector("#controls");
const message = document.querySelector("#message");

form.addEventListener("submit", async event => {
event.preventDefault();
message.textContent = "Verbindung wird hergestellt ...";
try {
await startSession(form.code.value.trim(), form.station.value.trim());
controls.hidden = false;
message.textContent = "Station ist verbunden.";
} catch (error) {
message.textContent = messageForMegBesError(error);
}
});

controls.addEventListener("click", async event => {
const command = event.target.dataset.command;
if (!command) return;
try {
event.target.disabled = true;
await play(command);
message.textContent = "Befehl wurde gesendet.";
} catch (error) {
message.textContent = messageForMegBesError(error);
} finally {
event.target.disabled = false;
}
});

document.querySelector("#logout").addEventListener("click", async () => {
try {
await endSession();
controls.hidden = true;
form.reset();
message.textContent = "Sitzung wurde beendet.";
} catch (error) {
message.textContent = messageForMegBesError(error);
}
});
</script>
</body>
</html>
</syntaxhighlight>

Die sichtbaren Befehle `play` und `stop` sind ebenfalls nur Platzhalter. Sie werden durch die freigegebenen Projektbefehle ersetzt.

== Fehlerbehandlung ==

<syntaxhighlight lang="javascript">
function messageForMegBesError(error) {
if (!(error instanceof MegBesError)) {
return "Unerwarteter Fehler. Bitte Aufsicht informieren.";
}

switch (error.status) {
case 0:
return "MegBes ist derzeit nicht erreichbar.";
case 400:
return "Die Anfrage ist unvollständig oder ungültig.";
case 401:
return "Anmeldung, Berechtigung oder Stationsbelegung konnte nicht bestätigt werden.";
case 403:
return "Die Station ist für diese Sitzung nicht freigegeben.";
case 404:
return "Diese Funktion ist in der aktuellen Betriebsart nicht verfügbar.";
default:
return "MegBes konnte den Auftrag nicht ausführen.";
}
}
</syntaxhighlight>

Keine rohen Backend-Antworten, Stacktraces, Tokens oder internen Adressen an Besucher ausgeben. Technische Details gehören in eine geschützte Diagnoseansicht oder in bereinigte Logs.

== Zustands- und Bedienregeln ==

* Mehrfachklicks verhindern, solange ein Request läuft.
* Erst nach erfolgreicher Antwort den nächsten fachlichen Zustand anzeigen.
* Ticketcodes und Pseudo-IDs nicht in der URL oder in dauerhaftem `localStorage` speichern.
* Bei Seitenneuladung `/verify` verwenden, bevor eine bestehende Sitzung angenommen wird.
* Eine Station erst als verbunden anzeigen, wenn `/media-station` erfolgreich war.
* Bei `401` nicht automatisch einen falschen Code behaupten; auch Belegung und Projektzuordnung sind mögliche Ursachen.
* Bei unbekanntem Stationsstatus eine neutrale Fehlermeldung anzeigen.
* Bedienoberfläche tastaturbedienbar gestalten und Statusmeldungen mit `aria-live` ausgeben.
* Stationsbefehle nur aus einer festen projektspezifischen Positivliste erzeugen, nicht aus frei eingegebenem Besuchertest.

== CORS und Hosting ==

Der aktuelle MegBes-Stand erlaubt CORS-Anfragen grundsätzlich. Das ist keine Zusage, dass jede zukünftige Instanz beliebige Origins akzeptiert. Bevorzugt werden Frontend und API unter kontrollierten HTTPS-Adressen betrieben. Ein CORS-Fehler wird nicht durch Abschalten von Browsersicherheit oder Zertifikatsprüfung umgangen.

== Entwicklungs- und Abnahmetests ==

# `GET /info` von der vorgesehenen Hardware aufrufen.
# korrekten Sicherheits- und Stationsmodus bestätigen.
# gültigen, ungültigen, bereits benutzten und abgelaufenen Ticketcode testen.
# freie, belegte und unbekannte Station testen.
# jeden freigegebenen Stationsbefehl einzeln prüfen.
# Mehrfachklick und parallele Requests testen.
# Abmeldung und erneute Anmeldung testen.
# Browser-Neuladen sowie Neustart von Frontend-Hardware und Station testen.
# Ausfall von External, Internal und Stationsnetz jeweils getrennt simulieren.
# sicherstellen, dass keine Tokens oder Geheimwerte in URL, Konsole, Screenshot oder sichtbarer Fehlermeldung erscheinen.
# installierten External-/Internal-Release, Frontend-Version und Testergebnis auf der Projektseite dokumentieren.

== Grenzen dieser Referenz ==

Diese Seite dokumentiert den API-Vertrag des aktuellen Repository-Stands. Projektspezifische Stationsbefehle, Gestaltung, Inhalte, Ticketdruck, Hardware-Autostart und konkrete Frontend-Dateipfade werden auf der jeweiligen Projektseite dokumentiert. Bei Abweichungen hat der tatsächlich eingesetzte Release Vorrang.

Siehe auch [[Web-Frontend]], [[Bedienung und Authentifizierung]], [[UDP und Stationszustände]], [[Client-Feedback und Stationsmeldungen]] und [[Routing und Signalweg]].

[[Kategorie:MegBes]]
[[Kategorie:Frontend]]
[[Kategorie:Entwicklung]]
[[Kategorie:API]]