Bedienungsanleitung mit Bildern
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.
This commit is contained in:
Florian Wilde
@@ -0,0 +1,322 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user