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.
423 lines
16 KiB
Markdown
423 lines
16 KiB
Markdown
# 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](../README.md); die Anmeldung über
|
||
Authentik in [authentik.md](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](#der-schnellste-weg-zum-code)
|
||
- [Statisch oder dynamisch — die wichtigste Entscheidung](#statisch-oder-dynamisch--die-wichtigste-entscheidung)
|
||
- [Gestaltung](#gestaltung)
|
||
- [Meine Codes](#meine-codes)
|
||
- [Die Typen mit eigener Seite](#die-typen-mit-eigener-seite)
|
||
- [Feedback einsammeln und auswerten](#feedback-einsammeln-und-auswerten)
|
||
- [Verwaltung](#verwaltung)
|
||
- [Konto](#konto)
|
||
- [Häufige Fragen](#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.
|