Florian Wilde
fcc63ff69a
Die Bedienungsanleitung hatte zu jedem alten Abschnitt ein Bild und zu keinem der sechs neuen. Sechs Aufnahmen kommen dazu: Logo im Code, Dublettenwarnung, Filter nach Art, Freigabe je Gruppe, Kurzhilfe und der Bericht einer geprueften Domain. Das Skript dafuer lief seit einer Umbenennung ins Leere — es wartete auf einen Dialogtitel "Ziel bearbeiten", der inzwischen "Code bearbeiten" heisst. Damit sind auch die uebrigen sechzehn Bilder neu; sie stammten noch aus 1.2.0 und zeigten eine aeltere Oberflaeche. schuss() kann jetzt einen Ausschnitt aufnehmen statt der ganzen Seite — fuer Dialoge und einzelne Karten, bei denen die volle Seite mehr verdeckt als zeigt. Das Beispiellogo entsteht im Skript, damit kein ungepflegtes Bild im Repo liegt. In der Kopfdoku steht jetzt, dass BASE_URL der Instanz auf dieselbe Adresse zeigen muss wie BASE — sonst erreicht die Anwendung sich beim Domain-Check nicht selbst und das Bild zeigt einen Fehlschlag.
16 KiB
Bedienungsanleitung
Diese Anleitung führt durch die tägliche Arbeit mit dem QR-Code-Generator — vom ersten Code bis zur Auswertung von Rückmeldungen. Wie der Stack aufgesetzt wird, steht im README; die Anmeldung über Authentik in authentik.md.
Die Bilder zeigen die Oberfläche mit eingeschalteter Anmeldung. Ohne Anmeldung fehlen Kopfzeile rechts und der Bereich „Verwaltung“, alles Übrige ist gleich.
Inhalt
- Der schnellste Weg zum Code
- Statisch oder dynamisch — die wichtigste Entscheidung
- Gestaltung
- Meine Codes
- Die Typen mit eigener Seite
- Feedback einsammeln und auswerten
- Verwaltung
- Konto
- Häufige Fragen
Der schnellste Weg zum Code
Die Startseite fragt „Was möchtest du erstellen?“ und zeigt alle freigegebenen Typen als Kacheln.
Ein Klick auf Website, die Adresse eintippen — die Vorschau erscheint sofort — und mit PNG oder SVG herunterladen. Fertig.
Links stehen Inhalt, Art des Codes und Gestaltung, rechts die Vorschau mit den beiden Download-Knöpfen. Die Vorschau aktualisiert sich bei jeder Änderung.
PNG oder SVG?
| PNG | SVG | |
|---|---|---|
| Wofür | Bildschirm, Office, Web | Druck, große Formate, Schilder |
| Größe | fest (256–2048 px) | frei skalierbar ohne Qualitätsverlust |
| Faustregel | wenn du es einfügst | wenn es jemand druckt |
Statisch oder dynamisch — die wichtigste Entscheidung
| Statisch | Dynamisch | |
|---|---|---|
| Im Code steht | die Zieladresse selbst | eine Kurz-URL dieser Anwendung |
| Ziel später änderbar | nein | ja, jederzeit |
| Scans werden gezählt | nein | ja |
| Braucht diesen Server | nein, nie | ja, dauerhaft |
| Code ist | dichter (mehr Daten) | schlanker, leichter scannbar |
Nimm statisch, wenn die Adresse feststeht und nie wieder geändert wird — und wenn der Code auch dann noch funktionieren soll, wenn es diese Anwendung nicht mehr gibt.
Nimm dynamisch, wenn etwas gedruckt wird. Ein Aufsteller, ein Flyer, ein Schild am Werkstor: Solange der Code dynamisch ist, kannst du das Ziel umbiegen, ohne neu zu drucken.
Beim Umschalten auf Dynamisch erscheint ein Feld für den Namen und der Knopf Dynamischen Code speichern. Erst beim Speichern entsteht die Kurz-URL — deshalb ist der Download bis dahin gesperrt.
Der Name ist nur für dich. Er steht nirgends im Code und sieht ihn niemand, der scannt. Er hilft dir, den Code später in der Liste wiederzufinden — bei vielen Projekten ist er Gold wert.
Gestaltung
Farben, Größe, Fehlerkorrektur und Rand gelten für Vorschau und Download gleichermaßen.
Farben. Fünf Vorschläge stehen bereit, eigene Werte gehen über den Farbwähler oder als Hex-Wert. Wird der Kontrast zu schwach, warnt die Anwendung — ein hübscher, aber unlesbarer Code nützt niemandem. Faustregel: dunkler Vordergrund auf hellem Hintergrund. Umgekehrt kommen viele Scanner-Apps nicht zurecht.
Größe. 256 bis 2048 Pixel, betrifft nur den PNG-Download. Für Druck lieber SVG nehmen und die Größe im Layoutprogramm bestimmen.
Fehlerkorrektur. Wie viel vom Code beschädigt sein darf, ohne dass er unlesbar wird:
| Stufe | Verträgt | Wofür |
|---|---|---|
| L | ~7 % | saubere Bildschirmanzeige |
| M | ~15 % | Voreinstellung, für fast alles richtig |
| Q | ~25 % | Aufkleber, die abgerieben werden |
| H | ~30 % | Außenbereich, Logo mitten im Code |
Höhere Stufen machen den Code dichter — er braucht mehr Fläche, um noch gescannt zu werden.
Rand. Die weiße Zone rundherum. Vier Module sind Standard; weniger kann das Scannen erschweren, weil der Scanner den Code nicht mehr vom Hintergrund trennen kann.
Ein Logo in die Mitte setzen
Ganz unten in der Gestaltung steht Logo in der Mitte. Ein Haken genügt, dann fragt die Anwendung, woher das Bild kommen soll:
- Logo dieser Installation — das, was unter Verwaltung → Erscheinungsbild hinterlegt ist. Kein Upload je Code nötig. Die Wahl erscheint nur, wenn dort überhaupt eines liegt.
- Eigenes Logo — je Code hochgeladen, für Kundenprojekte mit fremdem Zeichen. PNG, JPEG, WebP oder AVIF, bis 2 MB.
Die Größe liegt zwischen 10 und 25 % der Kantenlänge; voreingestellt sind 20 %, das verdeckt rund 4 % der Fläche. Hinter dem Bild liegt eine Fläche in der Hintergrundfarbe, damit es sich absetzt.
Die Fehlerkorrektur springt dabei auf H und lässt sich nicht mehr ändern — was das Bild verdeckt, muss sie ausgleichen. Das steht auch so unter der Auswahl; heimlich geschieht es nicht.
Ab 22 % erscheint eine Warnung. Die Fehlerkorrektur trägt das zwar, aber manche Scanner-Apps suchen in der Mitte nach Ausrichtungsmustern.
Einmal selbst scannen, bevor etwas in den Druck geht. Ein Code mit Logo ist die einzige Stelle, an der die Anwendung etwas ausliefern kann, das auf dem einen Gerät geht und auf dem anderen nicht. Zwei verschiedene Apps kosten eine halbe Minute und ersparen eine Neuauflage.
Meine Codes
Hier stehen die dynamischen Codes und die statischen, die du abgelegt hast. Beide Arten stehen nebeneinander in derselben Liste — ein statischer trägt statt einer Kurz-URL das Abzeichen „statisch“ und zählt keine Scans.
Die Liste ist die Voreinstellung: eine Zeile je Code, gedacht für viele Projekte nebeneinander.
- Das Suchfeld durchsucht Name, Ziel, Kurz-URL und Typ.
- Die Sortierung kennt neueste, älteste, Name und Scan-Anzahl.
- Ein Gruppenfilter erscheint, sobald Codes in mehr als einer Gruppe liegen.
- Ein Filter nach Art erscheint, sobald dynamische und statische Codes
nebeneinander liegen: Alle Arten, Nur dynamische, Nur statische.
Steht er auf „Nur statische“, fällt die Scan-Spalte weg und die Sortierung
nach Scans mit ihr — bei einer Liste aus lauter Strichen sagt sie nichts. - Das Symbol neben der Kurz-URL kopiert sie in die Zwischenablage.
Über die beiden Schalter rechts geht es zur Kartenansicht mit großer Vorschau. Die Wahl merkt sich der Browser.
Statische Codes ablegen
Ein statischer Code ist mit dem Download eigentlich fertig — sein Inhalt steckt in ihm. Der Knopf In „Meine Codes“ ablegen legt ihn trotzdem in die Liste, damit du ihn wiederfindest und erneut herunterladen kannst.
Liegt dort schon ein statischer Code mit identischem Inhalt, hält das Ablegen an und zeigt, welcher das ist und wann er entstand. Der Knopf heißt dann Trotzdem ablegen — es ist eine Warnung, keine Sperre. Verglichen wird nur der Inhalt, nicht die Gestaltung: Derselbe Code in Schwarz-Weiß und in Hausfarben gilt hier als Dublette.
Bei dynamischen Codes fragt niemand nach. Zwei Kurz-Links auf dasselbe Ziel sind der Normalfall, sobald zwei Kampagnen getrennt gezählt werden.
Ziel ändern
Das ist der eigentliche Sinn dynamischer Codes: Die Kurz-URL bleibt, der gedruckte Code bleibt gültig, nur das Ziel wechselt. Die Änderung wirkt sofort — beim nächsten Scan.
Löschen
Löschen fragt nach und nennt den betroffenen Code. Danach führt der gedruckte Code ins Leere und zeigt eine freundliche Seite „Diese Seite gibt es nicht“. Ein gelöschter Code lässt sich nicht wiederherstellen.
Die Typen mit eigener Seite
Fünf Typen leiten nicht auf eine fremde Adresse weiter, sondern auf eine Seite, die diese Anwendung selbst ausliefert: Mehrere Links, Social Media, PDF, Bild und Feedback.
Diese Seiten sind öffentlich und zeigen bewusst nichts von der Anwendung — keine Navigation, kein „Verwaltung“, kein Hinweis auf den Generator. Wer einen Aushang scannt, soll nur den Inhalt sehen.
Mehrere Links
Eine Überschrift, ein kurzer Text und bis zu 20 beschriftete Links. Mit den Pfeilen im Formular lässt sich die Reihenfolge ändern — das oberste wird am häufigsten geklickt, also gehört das Wichtigste nach oben.
Social Media
Dasselbe Prinzip, aber mit einem Katalog von Netzwerken. Als Eingabe genügt
das Kürzel: Aus @firma wird beim Speichern https://instagram.com/firma.
Eine vollständige Adresse bleibt unverändert, damit auch abweichende
Profil-Adressen möglich sind. Jedes Netzwerk kann nur einmal vorkommen.
PDF und Bild
Beim PDF-Typ lädst du ein Dokument hoch; die Seite zeigt Titel, Dateiname, Größe und zwei Knöpfe: Dokument öffnen und Herunterladen.
Beim Bild-Typ sind es bis zu zehn Bilder mit Bildunterschriften, untereinander als Galerie.
Beides lässt sich später austauschen, ohne den Code neu zu drucken — genau
wie ein geändertes Ziel. Erlaubt sind PDF sowie PNG, JPEG, WebP, GIF und AVIF
bis zur eingestellten Grenze (Voreinstellung 10 MB, siehe MAX_UPLOAD_MB).
SVG wird bewusst nicht angenommen: Eine SVG-Datei darf Skripte enthalten, und sie würde von derselben Adresse ausgeliefert wie die Anwendung selbst.
Video
Der Video-Typ erkennt YouTube, Vimeo und direkte Videodateien. Auf der Seite erscheint ein Abspieler — der Rahmen zum Anbieter lädt aber erst nach einem Klick, und davor steht, dass dabei Daten an den Anbieter gehen.
Video ist der einzige dieser Typen, der auch statisch funktioniert: Dann steht die Videoadresse direkt im Code und führt ohne Umweg dorthin.
Feedback einsammeln und auswerten
Der Feedback-Typ erzeugt ein Formular mit fünf Sternen oder fünf Gesichtern und wahlweise einem Textfeld. Alle Texte — Überschrift, Frage, Beschriftung des Textfelds, Dank nach dem Absenden — lassen sich frei formulieren.
Gespeichert werden nur die Note und der Text. Kein Name, keine IP-Adresse, keine Gerätekennung. Wer einen Aushang scannt und eine Note vergibt, bleibt anonym — das steht auch für die Scannenden sichtbar unter dem Formular.
Die Auswertung erreichst du in „Meine Codes“ über das Stern-Symbol in der Zeile. Sie zeigt den Durchschnitt, die Verteilung der Noten und alle Kommentare mit Datum.
Ein praktischer Hinweis: Ein Code pro Ort. Zwei Codes — einer im Gastraum, einer am Ausgang — sagen mehr als einer für beides, weil du die Auswertungen getrennt lesen kannst.
Verwaltung
Der Bereich Verwaltung erscheint nur für Administratoren der Installation.
QR-Typen
15 Kacheln sind viel, wenn ihr ohnehin nur drei davon braucht. Hier lassen sich Typen abschalten; sie verschwinden dann aus der Auswahl.
Bereits erstellte Codes eines abgeschalteten Typs funktionieren unverändert weiter — sie leiten weiter, zählen Scans und lassen sich bearbeiten. Nur neue lassen sich nicht mehr anlegen.
Freigabe je Gruppe. Über der Liste steht die Auswahl Freigabe für:
| Auswahl | Wirkung |
|---|---|
| Alle Gruppen (Grundeinstellung) | gilt für die ganze Installation |
| Nur: eine Gruppe | weicht für diese eine Gruppe ab |
So bekommt die Marketingabteilung Social Media und die Werkstatt nur Website und PDF. Fehlt eine Abweichung, folgt die Gruppe der Grundeinstellung.
Die Grundeinstellung gewinnt immer. Ein Typ, der dort abgeschaltet ist, lässt sich in keiner Gruppe einschalten — der Schalter steht dann ausgegraut und nennt den Grund. Andersherum wäre „hier abgeschaltet“ keine verlässliche Aussage mehr.
Wer in mehreren Gruppen ist, sieht auf der Startseite die Vereinigung. Welche Freigabe zählt, entscheidet sich beim Anlegen anhand der gewählten Gruppe.
Gruppen
Eine Gruppe bündelt Codes und die Menschen, die damit arbeiten. Jeder Code gehört genau einer Gruppe; wer nicht in der Gruppe ist, sieht ihn nicht.
Die drei Rollen je Gruppe:
| Rolle | Darf |
|---|---|
| Betrachter | Codes sehen und herunterladen |
| Bearbeiter | zusätzlich anlegen, ändern und löschen |
| Administrator | zusätzlich Mitglieder und deren Rollen verwalten |
Darüber liegt der Administrator der Installation: Nur er legt Gruppen, Benutzer und Domains überhaupt an.
Domains
Sollen Kurz-URLs unter verschiedenen Adressen laufen — etwa je Kunde eine —, werden die Domains hier eingetragen und Gruppen zugeteilt. Eine Domain kann mehreren Gruppen dienen; die Codes bleiben trotzdem strikt nach Gruppe getrennt.
Damit das funktioniert, muss der Reverse Proxy jede dieser Domains auf diese Anwendung leiten. Was dafür einzurichten ist, steht nicht nur im README: Der Knopf Kurzhilfe über der Liste führt es in sechs Schritten auf — DNS, Weiterleitung im Proxy samt der drei nötigen Kopfzeilen, Zertifikat, Registrieren, Gruppenzuteilung, Nachprüfen.
Prüfen, ob eine Domain wirklich hierher führt. Bei jedem Eintrag steht ein Knopf Prüfen. Er geht den Weg der Scanner nach und meldet vier Dinge:
| Schritt | Was er sagt |
|---|---|
| DNS | ob der Name auflöst, und auf welche Adressen |
| Zertifikat | gültig bis wann, von wem ausgestellt |
| Erreichbar | ob dort ein Webserver antwortet, und wie schnell |
| Ziel | ob dahinter diese Installation steht |
Der letzte Schritt ist der eigentliche Wert. Dass irgendwo etwas antwortet, sagt wenig; die Prüfung lässt sich beweisen, dass es diese Anwendung ist. Scheitert schon DNS, fallen die drei Folgeschritte aus — dreimal dieselbe Meldung würde die eine wichtige verdecken.
Der Aufruf startet dort, wo der Container läuft. Bei internem DNS oder Hairpin-NAT kann er scheitern, obwohl von außen alles stimmt. Und umgekehrt: Ein Erfolg von innen beweist noch nicht, dass die Domain von außen erreichbar ist. Dafür bleibt der Blick von einem fremden Netz aus.
Konto
Hier stehen die eigene Adresse, die Gruppen mit der jeweiligen Rolle, die Passwortänderung und der Weg hinaus.
Meldet sich das Konto über Authentik an, steht statt der Passwortänderung ein Hinweis darauf — das Passwort wird dann beim Anbieter geändert.
Häufige Fragen
Der Code funktioniert auf dem Handy nicht, am Rechner aber schon.
Dann zeigt die Kurz-URL auf eine Adresse, die das Handy nicht erreicht.
BASE_URL in der .env muss die Adresse sein, unter der die Anwendung von
außen erreichbar ist — nicht localhost.
Ich habe den Code schon gedruckt und brauche ein anderes Ziel. Ist er dynamisch: „Meine Codes“ → Ziel bearbeiten. Ist er statisch: Der Code muss neu erstellt und neu gedruckt werden. Deshalb bei allem Gedruckten dynamisch nehmen.
Der Scan-Zähler steht auf 0, obwohl jemand gescannt hat. Gezählt wird nur der Aufruf der Kurz-URL. Statische Codes zählen gar nicht, weil sie diesen Server nie berühren. Bei Typen mit eigener Seite zählt der Scan, nicht das Neuladen der Seite.
Ein Kollege sieht meine Codes nicht. Er ist nicht in derselben Gruppe. Verwaltung → Gruppen → Mitglied hinzufügen.
Der QR-Code wird nicht erkannt. Meist zu wenig Kontrast, ein zu kleiner Rand oder zu kleiner Druck. Faustregel für Druck: mindestens 2 × 2 cm, bei Entfernung mehr — als grober Anhalt ein Zehntel des Leseabstands.
Kann ich ein Logo in die Mitte setzen? Nicht in dieser Anwendung. Wer es im Layoutprogramm macht: SVG nehmen, Fehlerkorrektur H wählen und höchstens ein Fünftel der Fläche verdecken — danach unbedingt mit mehreren Geräten testen.