Florian Wilde
e4ff55a6c9
docs/anleitung.md fuehrt vom ersten Code bis zur Auswertung von Rueckmeldungen: statisch gegen dynamisch, Gestaltung, Meine Codes, die fuenf Typen mit eigener Seite, Verwaltung, Konto und haeufige Fragen. Die Bilder erzeugt docs/screenshots.mjs. Von Hand aufgenommene Bilder veralten beim ersten Umbau — so sind sie in einer Minute neu erzeugt, samt Beispieldaten, die das Skript hinterher wieder entfernt.
323 lines
12 KiB
Markdown
323 lines
12 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.
|
||
|
||
---
|
||
|
||
## Meine Codes
|
||
|
||
Hier stehen alle **dynamischen** Codes. Statische erscheinen nicht — sie
|
||
werden nicht gespeichert.
|
||
|
||
|
||
|
||
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.
|
||
- 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.
|
||
|
||
|
||
|
||
### 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.
|
||
|
||
### 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 — siehe README, Abschnitt „Mehrere Domains“.
|
||
|
||
---
|
||
|
||
## 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.
|