# Alle Funktionen im Detail Die lange Fassung der Übersicht aus dem [README](../README.md). Sie beschreibt, was die Anwendung kann, wo die Grenzen liegen und warum manches so entschieden ist. Wie man es bedient, steht in der [Bedienungsanleitung](anleitung.md). --- ## Inhalt - [QR-Typen](#qr-typen) - [Statisch und dynamisch](#statisch-und-dynamisch) - [Landingpages](#landingpages) - [Dateien](#dateien) - [Feedback](#feedback) - [Gestaltung und Ausgabe](#gestaltung-und-ausgabe) - [Meine Codes](#meine-codes) - [Anmeldung, Gruppen und Rollen](#anmeldung-gruppen-und-rollen) - [Single Sign-on](#single-sign-on) - [Mehrere Domains](#mehrere-domains) - [Erscheinungsbild](#erscheinungsbild) - [Verwaltung](#verwaltung) - [Betrieb](#betrieb) - [Schnittstelle](#schnittstelle) - [Was die Anwendung bewusst nicht tut](#was-die-anwendung-bewusst-nicht-tut) --- ## QR-Typen Alle 15 vorgesehenen Typen sind gebaut. | Typ | Was hineinkommt | Statisch | Dynamisch | Eigene Seite | | --- | --- | :-: | :-: | :-: | | **Website** | eine Adresse | ✓ | ✓ | — | | **vCard** | Name, Firma, Telefon, E-Mail, Anschrift, Web | ✓ | — | — | | **App-Link** | je eine Adresse für iOS, Android und Ausweichfall | — | ✓ | — | | **Mehrere Links** | Überschrift, Text, bis zu 20 beschriftete Links | — | ✓ | ✓ | | **Social Media** | Überschrift, Text, bis zu 12 Profile aus 15 Netzwerken | — | ✓ | ✓ | | **WhatsApp** | Rufnummer und vorbereitete Nachricht | ✓ | ✓ | — | | **PDF** | eine hochgeladene Datei, Titel, Text | — | ✓ | ✓ | | **Bild** | bis zu 10 hochgeladene Bilder mit Bildunterschriften | — | ✓ | ✓ | | **Video** | YouTube, Vimeo oder eine direkte Videodatei | ✓ | ✓ | ✓ | | **E-Mail** | Empfänger, Betreff, Text | ✓ | ✓ | — | | **SMS** | Rufnummer und Text | ✓ | ✓ | — | | **Standort** | Koordinaten oder Adresse | ✓ | ✓ | — | | **Zahlung** | GiroCode (EPC069-12) **oder** Zahlungslink | ✓ | nur Link | — | | **WLAN** | Netzwerkname, Passwort, Verschlüsselung, versteckt | ✓ | — | — | | **Feedback** | Frage, Skala, Textfeld, Dankestext | — | ✓ | ✓ | ### Warum manche Typen nur eine Betriebsart können - **vCard und WLAN** wertet das Gerät direkt aus — die Kamera legt einen Kontakt an oder richtet das Netz ein. Über eine Kurz-URL ginge stattdessen nur ein Browser auf. - **App-Link** kann nicht statisch sein: Welches Ziel richtig ist, steht erst beim Scannen fest. Die Weiterleitung wertet den User-Agent aus — iOS in den App Store, Android zu Google Play, alles Übrige auf die Ausweichadresse. (iPadOS meldet sich seit Version 13 als Macintosh und landet deshalb mitunter auf dem Desktop-Weg; für einen Store-Link ist das hinnehmbar.) - **GiroCode** ist kein Web-Ziel, sondern ein Datensatz für Banking-Apps. Als dynamischer Code funktioniert nur die Variante „Zahlungslink“. Die Anwendung weist das beim Speichern **und beim Bearbeiten** ab, statt einen Code entstehen zu lassen, der erst beim Scannen auffällt — also dann, wenn er schon gedruckt ist. - **Die fünf Typen mit eigener Seite** brauchen eine Seite, die die Anwendung ausliefert. Eine Linkliste oder ein Formular passt nicht in einen einzelnen Code. Video ist die Ausnahme: statisch steht dort die Videoadresse selbst. ### Besonderheiten einzelner Typen **Social Media.** 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. Der Katalog umfasst Instagram, Facebook, LinkedIn, Xing, YouTube, TikTok, X, Threads, Mastodon, WhatsApp, Telegram, Pinterest, Snapchat, GitHub und „Website“. **Video.** Erkannt werden `youtube.com/watch`, `youtu.be`, `/shorts/`, `/embed/`, `/live/`, Vimeo-Adressen sowie die Endungen `.mp4`, `.webm`, `.ogv`, `.ogg`, `.mov` und `.m4v`. Alles Übrige erscheint als schlichter Link — ehrlicher als ein eingebetteter Rahmen, den der Anbieter nicht erlaubt. **WLAN.** Das Passwort steht im Klartext im Code; wer ihn scannt oder abfotografiert, kennt es. Für Gästenetze ist das gewollt. Besteht Netzwerkname oder Passwort nur aus Hex-Ziffern, setzt die Anwendung den Wert wie in der Spezifikation vorgesehen in Anführungszeichen — sonst deuten manche Geräte ihn als Hexzahl. **Standort.** Statisch entsteht ein `geo:`-Link, den Karten-Apps direkt öffnen. Dynamisch führt der Weg über OpenStreetMap, weil eine Kurz-URL im Browser landet. --- ## Statisch und dynamisch | | Statisch | Dynamisch | | --- | --- | --- | | Im Code steht | die Zieladresse selbst | `{BASE_URL}/r/{slug}` | | Ziel später änderbar | nein | ja, jederzeit | | Scans gezählt | nein | ja, mit Datum des letzten | | Braucht diesen Server | nie | dauerhaft | | In „Meine Codes“ | auf Wunsch, als Schnappschuss | immer | ### Ein statischer Code mit Namen Beide Betriebsarten haben ein Feld **Name (optional)**. Es tut zweierlei: - Es bestimmt den **Dateinamen beim Herunterladen** — aus „Plakat Eingang“ wird `qr-plakat-eingang.png` statt `qr-example-com-plakat.png`. - Auf Wunsch lässt sich der Code damit **in „Meine Codes“ ablegen**, um ihn wiederzufinden und erneut herunterzuladen. Ein abgelegter statischer Code ist ein **Schnappschuss**, kein steuerbares Ziel. Änderbar ist nur sein Name; Inhalt und Gestaltung bleiben, wie sie beim Ablegen waren — denn genau das steckt im gedruckten Bild. Er hat keinen Kurz-Link, ist unter `/r/…` nicht erreichbar und zählt keine Scans; in der Liste steht dort „statisch“ und ein Strich. Wer nach dem Ablegen den Inhalt ändert, bekommt das Ablegen erneut angeboten — der vorherige Eintrag bleibt als eigener Schnappschuss bestehen. **Dublettenprüfung.** Liegt in derselben Gruppe schon ein statischer Code mit identischem Inhalt, hält das Ablegen an und zeigt, welcher Eintrag das ist und wann er entstand. Der Knopf heißt dann **Trotzdem ablegen** — eine Warnung, keine Sperre: Zwei Fassungen desselben Codes können gewollt sein. Verglichen wird nur der Inhalt, nicht die Gestaltung. Derselbe Code in Schwarz-Weiß und in Hausfarben gilt also als Dublette — was er streng genommen auch ist, denn gescannt wird beides Mal dasselbe. Dynamische Codes bleiben außen vor: Zwei Kurz-Links auf dasselbe Ziel sind der Normalfall, sobald zwei Kampagnen getrennt gezählt werden sollen. ### Ein Logo in der Mitte Ein Bild in die Mitte des Codes setzen, wie man es von Firmen-Codes kennt. Zur Wahl stehen zwei Quellen: - das **Logo dieser Installation** aus dem Erscheinungsbild — ein Haken genügt, kein Upload je Code; - ein **eigenes Logo** je Code, für Kundenprojekte mit fremdem Zeichen. Die Größe ist zwischen 10 und 25 % der Kantenlänge einstellbar; voreingestellt sind 20 %, das entspricht rund 4 % der Fläche. Hinter dem Bild liegt eine Fläche in der Hintergrundfarbe, damit es sich absetzt. **Die Fehlerkorrektur wird dabei auf H erzwungen** — was das Bild verdeckt, muss sie ausgleichen. Die Auswahl steht dann fest auf H und sagt auch warum; heimlich geschieht das nicht. Ab 22 % erscheint eine Warnung: Die Fehlerkorrektur trägt das zwar, aber manche Scanner-Apps suchen in der Mitte nach Ausrichtungsmustern. Jeder erzeugte Code wird in der Prüfung wieder eingelesen — über mehrere Größen, Prozentsätze und Inhaltslängen. Das ersetzt trotzdem nicht den einen Scan mit dem eigenen Handy, bevor etwas in den Druck geht. ### Der Kurz-Link Ohne eigene Angabe entsteht er aus acht Zeichen eines Alphabets ohne verwechselbare Zeichen (kein `0`, `O`, `1`, `l`, `I`) — Kurz-URLs werden gelegentlich abgetippt. **Selbst bestimmen** lässt er sich beim Anlegen und später ändern: | | | | --- | --- | | Erlaubt | Kleinbuchstaben, Ziffern, Bindestriche, `/` als Trenner | | Beispiele | `sommeraktion`, `tisch-14`, `kunde-a/flyer` | | Nicht erlaubt | Umlaute, Leerzeichen, Unterstriche, Bindestrich am Rand eines Abschnitts | | Länge | bis 100 Zeichen, höchstens 3 Abschnitte à 48 Zeichen | Groß- und Kleinschreibung spielt beim Aufrufen keine Rolle: `SommerAktion` findet `sommeraktion`. Gespeichert wird kleingeschrieben, und zwei Kurz-Links dürfen sich nicht nur in der Schreibweise unterscheiden. **Beim Ändern bleibt die vorherige Adresse gültig.** Das ist der Sinn der Sache: Auf gedruckten Codes steht die alte, und die soll weiter funktionieren. Frühere Adressen stehen im Bearbeiten-Dialog und lassen sich einzeln **freigeben** — für den Fall eines Tippfehlers, mit dem noch nichts gedruckt ist. Eine freigegebene Adresse ist sofort tot und danach wieder vergebbar. Solange sie gehalten wird, kann sie kein anderer Code übernehmen; sonst ließen sich fremde gedruckte Codes umlenken. **Wer darf das?** Standardmäßig nur Administratoren — ein Kurz-Link ist eine öffentliche Adresse, und wer ihn ändert, kann Aushänge entwerten. Unter Verwaltung → Einstellungen lässt sich das für Bearbeiter freigeben. Ohne das Recht erscheint das Feld gar nicht; Codes anlegen und deren Ziel ändern geht weiterhin. Der Kurz-Link ist **je Domain** eindeutig, nicht global — derselbe darf auf zwei Domains liegen und dort auf Verschiedenes zeigen. Die Weiterleitung antwortet mit **302** und `Cache-Control: no-store`. Ein permanenter Redirect würde in Browsern und Zwischenspeichern hängen bleiben — und genau die Änderbarkeit zunichtemachen, wegen der man dynamische Codes nimmt. Der Scan-Zähler wird beiläufig erhöht; scheitert er, geht die Weiterleitung trotzdem durch. --- ## Landingpages Fünf Typen führen auf eine Seite unter `{BASE_URL}/s/{slug}`, die die Anwendung selbst ausliefert. Diese Seiten sind **öffentlich** und zeigen bewusst nichts von der Anwendung: keine Navigation, kein „Verwaltung“, kein Hinweis auf den Generator, und im Seitentitel steht der Inhalt statt des Produktnamens. Wer einen Aushang scannt, hat mit dem Generator nichts zu tun. Technisch liegt das App-Chrome in einer Routengruppe, die Landingpages außerhalb — sie können es also gar nicht versehentlich erben. Weitere Eigenschaften: - Alle Texte kommen aus den Formulardaten und werden als **Text** ausgegeben, nie als HTML. Eingegebene Zeichen wie `` erscheinen als solche. - Verlinkte Ziele bekommen `rel="noopener noreferrer"` — kein Zugriff auf das Fenster, aus dem sie geöffnet wurden. - Adressen müssen mit `http://` oder `https://` beginnen; `javascript:` und Ähnliches wird abgewiesen. - Passen die gespeicherten Daten nicht mehr zum Schema, erscheint eine freundliche Erklärung statt eines Fehlers. - Der Scan-Zähler zählt den Aufruf des **Codes**, nicht das Neuladen der Seite. **Video-Landingpage.** Der Rahmen zu YouTube oder Vimeo lädt erst nach einem Klick, und davor steht, dass dabei Daten an den Anbieter übertragen werden. Eingebettet wird die Variante ohne Cookies (`youtube-nocookie.com`). Direkte Videodateien laden mit `preload="none"` — wer unterwegs scannt, zahlt das Volumen. --- ## Dateien PDFs und Bilder liegen **in der Datenbank**, nicht auf der Platte. Damit gibt es weiterhin genau ein Volumen zu sichern: Wer die Datenbank sichert, hat alles. Ein zweites Volumen wird beim Sichern zu leicht vergessen. | | | | --- | --- | | Erlaubt | PDF; PNG, JPEG, WebP, GIF, AVIF | | Nicht erlaubt | SVG und alles Übrige | | Größe | `MAX_UPLOAD_MB`, Voreinstellung 10 MB | | Geprüft wird | der Dateiinhalt, nicht die Endung | **Warum kein SVG:** Eine SVG-Datei darf Skripte enthalten. Ausgeliefert von derselben Adresse wie die Anwendung könnte sie damit auf angemeldete Sitzungen zugreifen. **Wie geprüft wird:** Der vom Browser gemeldete Typ kommt aus der Endung und lässt sich beliebig setzen. Entschieden wird deshalb anhand der ersten Bytes der Datei. Eine Textdatei namens `harmlos.pdf` wird abgewiesen. **Wie ausgeliefert wird:** mit dem erkannten Typ, `X-Content-Type-Options: nosniff` und einer `Content-Security-Policy: sandbox` — damit auch ein PDF mit eingebetteten Skripten nichts anrichten kann. Ein Anhängen von `?download` erzwingt das Speichern statt der Anzeige. **Wem eine Datei gehört:** Sie hängt am Code. Wird er gelöscht, verschwindet sie mit ihm. Eine ausgetauschte Datei verliert ihren Bezug und wird nach 24 Stunden weggeräumt — ebenso eine hochgeladene, deren Code nie gespeichert wurde. Eine fremde Datei lässt sich nicht an den eigenen Code hängen; sonst könnte man sie einem anderen Code entziehen. Die Adresse einer Datei ist nicht erratbar, aber öffentlich abrufbar — dieselbe Überlegung wie beim Slug einer Kurz-URL. Vertrauliche Unterlagen gehören nicht hinter einen QR-Code, den man abfotografieren kann. --- ## Feedback Ein Feedback-Code erzeugt ein Formular mit fünf **Sternen** oder fünf **Gesichtern** und wahlweise einem Textfeld. Überschrift, Frage, Beschriftung des Textfelds und der Text nach dem Absenden sind frei formulierbar. Gespeichert werden **nur die Note von 1 bis 5 und der Text**. Kein Name, keine IP-Adresse, keine Gerätekennung — das steht auch für die Antwortenden sichtbar unter dem Formular. Gegen Fluten gibt es eine Bremse von 10 Rückmeldungen pro Minute und Absender. Die Adresse dient dabei nur als Schlüssel im Arbeitsspeicher und wird nirgends gespeichert. Rückmeldungen zu Codes, die gar kein Feedback einsammeln, werden abgewiesen. Die **Auswertung** ist aus der Codeliste erreichbar und zeigt Durchschnitt, Verteilung der Noten und alle Kommentare mit Datum (die 200 jüngsten). Sie sieht nur, wer den Code auch sehen darf. --- ## Gestaltung und Ausgabe | Einstellung | Bereich | Voreinstellung | | --- | --- | --- | | Vordergrundfarbe | frei (Hex oder Farbwähler) | `#0F172A` | | Hintergrundfarbe | frei | `#FFFFFF` | | Größe | 256–2048 px | 512 px | | Fehlerkorrektur | L, M, Q, H | M | | Rand | 0–16 Module | 4 | Fünf Farbvorschläge (Klassisch, Indigo, Waldgrün, Bordeaux, Marine) und ein Knopf zum Tauschen von Vorder- und Hintergrund. Reicht der Kontrast nicht, warnt die Anwendung — ein hübscher, aber unlesbarer Code nützt niemandem. Die **Vorschau** wird serverseitig gerendert und aktualisiert sich bei jeder Änderung. Herunterladen geht als **PNG** (in der eingestellten Größe) und als **SVG** (frei skalierbar). Die Größe betrifft nur das PNG. --- ## Meine Codes Zeigt alle dynamischen Codes — statische erscheinen nicht, weil sie nicht gespeichert werden. - **Zwei Ansichten:** Liste (Voreinstellung, eine Zeile je Code) und Karten mit großer Vorschau. Die Wahl merkt sich der Browser. - **Suche** über Name, Ziel, Kurz-URL und Typ. - **Sortierung** nach neueste, älteste, Name oder Scan-Anzahl. - **Gruppenfilter**, sobald Codes in mehr als einer Gruppe liegen; dann gibt es auch eine Gruppenspalte. - **Kurz-URL kopieren** mit einem Klick. - **Ziel ändern** — die Kurz-URL und damit der gedruckte Code bleiben gültig. - **Löschen** mit Rückfrage, die den betroffenen Code nennt. - **PNG und SVG** erneut herunterladen. - Bei Feedback-Codes ein Weg zur **Auswertung**. Auf schmalen Bildschirmen weichen die hinteren Spalten; die Kurz-URL rückt unter den Namen, Bearbeiten und Löschen bleiben erreichbar. --- ## Anmeldung, Gruppen und Rollen Die Anmeldung ist **abschaltbar** (`AUTH_ENABLED`). Bewusst über die Konfiguration und nicht über die Oberfläche: So kann man sich nicht aussperren. **Ohne Anmeldung** darf jeder, der die Anwendung erreicht, alles. Für den Einzelplatz- oder LAN-Betrieb ist das gewollt; ins offene Internet gehört die Anwendung dann nicht. **Mit Anmeldung** gibt es vier Ebenen: 1. **Benutzer** — meldet sich mit E-Mail und Passwort an. 2. **Gruppe** — bündelt Codes und die Menschen, die damit arbeiten. Jeder Code gehört genau einer Gruppe. 3. **Rolle je Gruppe:** | Rolle | Darf | | --- | --- | | Betrachter | sehen und herunterladen | | Bearbeiter | zusätzlich anlegen, ändern, löschen | | Administrator | zusätzlich Mitglieder und Rollen der Gruppe verwalten | 4. **Administrator der Installation** — legt Gruppen, Benutzer und Domains überhaupt erst an. Zur Umsetzung: - Passwörter werden mit **scrypt** gehasht (Node-Bordmittel, kein natives Modul). Mindestlänge 10 Zeichen. - Nach **8 Fehlversuchen** ist das Konto 15 Minuten gesperrt. - Sitzungen liegen in der **Datenbank**, nicht in einem signierten Cookie — so lassen sie sich serverseitig beenden, etwa beim Deaktivieren eines Benutzers. Im Cookie steht ein Zufallstoken, in der Datenbank nur dessen SHA-256. Laufzeit 30 Tage. - Der Cookie ist `httpOnly` und `SameSite=Lax`; `Secure` wird gesetzt, sobald `BASE_URL` mit `https://` beginnt. - Alle Berechtigungsregeln stehen an **einer** Stelle (`src/lib/auth/policy.ts`) — nicht verteilt über die Oberfläche. - Im **Konto** sieht man die eigenen Gruppen und Rollen, ändert sein Passwort und meldet sich ab. --- ## Single Sign-on Die Anmeldung lässt sich an einen **OpenID-Connect-Anbieter** abgeben — getestet mit Authentik, ebenso nutzbar mit Keycloak, Zitadel oder Entra ID. Alles Nötige kommt aus dem Discovery-Dokument des Anbieters. - Anmeldefluss mit **PKCE** (S256), `state` und `nonce`. - Das ID-Token wird gegen den **JWKS** des Anbieters geprüft: Signatur, Aussteller, Empfänger, Ablauf und Nonce. - Wiedererkannt wird jemand an der **Kennung des Anbieters** (`sub`), nicht an der E-Mail-Adresse — Adressen ändern sich. - Ein bestehendes Konto mit derselben Adresse wird **verknüpft statt verdoppelt**, aber nur bei **bestätigter** Adresse. Sonst könnte sich beim Anbieter jemand eine fremde Adresse eintragen und damit ein hiesiges Konto übernehmen. - Neue Konten bekommen die Rolle aus `OIDC_DEFAULT_ROLE` in der Standardgruppe. - `OIDC_ADMIN_GROUP` hängt die Instanz-Administration an eine Gruppe beim Anbieter; sie wird dann bei jeder Anmeldung neu entschieden. - `OIDC_ONLY=true` blendet die Passwort-Anmeldung aus. **Bewusst nicht übernommen** werden Gruppen und Rollen. Die Gruppen im Verzeichnis bedeuten etwas anderes als die hier: dort geht es um Organisation und Zugang, hier darum, wer welche Codes sehen und ändern darf. Eine automatische Übersetzung wäre eine Quelle stiller Überraschungen. → Einrichtung Feld für Feld: [authentik.md](authentik.md) --- ## Mehrere Domains Kurz-URLs können unter verschiedenen Adressen laufen — etwa je Kunde eine. Domains werden in der Verwaltung angelegt und Gruppen zugeteilt. - Die Weiterleitung erkennt am `Host`-Header, welche Domain gemeint ist, und **prüft ihn gegen die registrierten Domains**. Ein unbekannter Hostname endet mit 404 — über einen gefälschten Header lässt sich also keine fremde Domain ansprechen. - Der **Slug ist je Domain eindeutig**, nicht global. - Eine Domain kann **mehreren Gruppen** dienen. Die Codes bleiben trotzdem strikt nach Gruppe getrennt. - Je Gruppe lässt sich eine Domain als Voreinstellung festlegen. - Eine Domain lässt sich abschalten, ohne sie zu löschen; ihre Codes antworten dann mit einer Erklärung. Damit das funktioniert, muss der Reverse Proxy jede dieser Domains auf diese Anwendung leiten. --- ## Erscheinungsbild Unter Verwaltung → Erscheinungsbild lassen sich einstellen: | | | | --- | --- | | **Name** | Kopfzeile, Titel des Browser-Tabs, Fußzeile | | **Zusatz in der Fußzeile** | steht hinter dem Namen | | **Akzentfarbe** | neun Vorschläge oder ein eigener Hex-Wert | | **Logo** | PNG, JPEG, WebP oder AVIF bis 2 MB; ersetzt Zeichen und Name | | **Favicon** | PNG, ICO oder WebP bis 512 KB | **Wie die Farbe wirkt.** Tailwind übersetzt `bg-indigo-600` zu `background-color: var(--color-indigo-600)`. Die Anwendung überschreibt diese Variablen zur Laufzeit — damit folgen alle rund 60 eingefärbten Stellen der gewählten Farbe, ohne dass eine einzige Klasse angefasst werden müsste. Aus der Eingabe übernommen werden nur **Farbton und Sättigung**, nicht die Helligkeit. Die Helligkeitsstufen kommen aus der Vorlage. Das ist Absicht: Auf der Stufe 600 steht weiße Schrift. Käme die Helligkeit aus der Eingabe, würde ein helles Gelb die Kopfzeile unlesbar machen — so bleibt jeder Farbton benutzbar. ### Hell und dunkel Die Anwendung folgt von sich aus der Einstellung des Betriebssystems. In der Kopfzeile steht ein Umschalter mit drei Zuständen: | | | | --- | --- | | **System** | folgt dem Betriebssystem — abends dunkel, morgens hell | | **Hell** | immer hell | | **Dunkel** | immer dunkel | Drei statt zwei, weil ein reiner Ein/Aus-Schalter nach dem ersten Klick für immer eine feste Wahl bedeutet. Die Wahl merkt sich der Browser; ein zweiter Tab zieht automatisch nach. **Wie es umgesetzt ist.** Nicht über `dark:`-Klassen — die hätten an rund 440 Stellen ergänzt werden müssen, und jede neue Zeile müsste daran denken. Stattdessen entscheidet `light-dark()` im CSS, welchen Wert die Farbvariablen tragen; gesteuert wird das über `color-scheme`. Deshalb genügt für den Umschalter ein Attribut am ``-Element — und die Systemwahl funktioniert sogar **ohne JavaScript**. Die dunklen Werte sind keine Spiegelung der hellen: Reines Schwarz unter weißer Schrift flimmert. Die Flächen liegen bei 20–26 % Helligkeit im selben leicht blauen Ton wie die helle Reihe. Alle Textkontraste liegen über der Anforderung von 4,5:1 — gemessen, nicht geschätzt. Unverändert bleiben die QR-Codes selbst. Deren Farben legt die Gestaltung fest, und ein Code, der hell gedruckt wird, soll in der Vorschau nicht anders aussehen. **Auf den Landingpages** gelten Farbe, Favicon und das Farbthema, aber weder Logo noch Navigation. Wer einen Aushang scannt, soll die Seite des Inhalts sehen, nicht die einer Verwaltungssoftware. Ein Logo je Gruppe auf den Landingpages steht als eigener Punkt auf der [Roadmap](roadmap.md). **Zu den Dateien.** Logo und Favicon liegen wie alle Uploads in der Datenbank und werden über `/api/uploads/{id}` ausgeliefert — öffentlich, denn sie stehen auf jeder Seite. Beim Ersetzen wird die vorherige Datei gelöscht. SVG bleibt auch hier ausgeschlossen, aus demselben Grund wie bei den übrigen Uploads. --- ## Verwaltung | Bereich | Was dort geht | | --- | --- | | **Einstellungen** | was Bearbeiter dürfen — etwa eigene Kurz-Links | | **Erscheinungsbild** | Name, Logo, Favicon, Akzentfarbe | | **QR-Typen** | einzelne Typen ausblenden — für alle oder je Gruppe | | **Benutzer** | anlegen, deaktivieren, Passwort setzen, Instanz-Admin vergeben | | **Gruppen** | anlegen, umbenennen, Mitglieder und deren Rollen pflegen | | **Domains** | anlegen, Gruppen zuteilen, abschalten | Zu den **QR-Typen**: 15 Kacheln sind viel, wenn ihr nur drei davon braucht. Ein abgeschalteter Typ verschwindet aus der Auswahl; **bereits erstellte Codes funktionieren unverändert weiter** — sie leiten weiter, zählen Scans und lassen sich bearbeiten. Nur neue lassen sich nicht mehr anlegen. Ohne Eintrag in der Datenbank gilt ein Typ als freigegeben, damit eine frische Installation alles zeigt und Typen aus späteren Versionen automatisch erscheinen. Die Freigabe hat **zwei Ebenen**. Die Grundeinstellung gilt für die ganze Installation; je Gruppe lässt sich davon abweichen — die Marketingabteilung bekommt Social Media, die Werkstatt nur Website und PDF. Fehlt eine Abweichung, folgt die Gruppe der Grundeinstellung. **Die globale Abschaltung gewinnt immer.** Ein Typ, der in der Grundeinstellung aus ist, lässt sich in keiner Gruppe einschalten; der Schalter steht dort sichtbar still und nennt den Grund. Andersherum wäre „hier abgeschaltet“ keine verlässliche Aussage mehr. Auf der Startseite sieht man die **Vereinigung** über die eigenen Gruppen. Wer in beiden Gruppen ist, sieht beides; welche Freigabe zählt, entscheidet sich beim Anlegen anhand der gewählten Gruppe. --- ## Betrieb - **Zwei Container:** die Next.js-Anwendung und PostgreSQL. Kein Reverse Proxy nötig — Port 3000 wird direkt veröffentlicht. Ein Proxy davor geht selbstverständlich auch. - **Migrationen laufen beim Start** von selbst. Es gibt keinen Extraschritt nach `docker compose up -d --build`. - Die Datenbank hat einen **Healthcheck**; die Anwendung startet erst, wenn sie wirklich Anfragen annimmt. - **Ein Volumen** für die Datenbank — dort liegen auch die hochgeladenen Dateien. - Die Konfiguration steht vollständig in einer **`.env`**; eine `.env.example` ist mitgeliefert und dokumentiert jeden Wert. - Die Anwendung liest die Werte **zur Laufzeit**, nicht beim Bauen — eine geänderte `BASE_URL` braucht keinen neuen Build. - Die Oberfläche ist durchgängig **deutsch**, hell, responsiv und ohne externe Schriften oder Skripte. --- ## Version und Änderungen Die Fußzeile nennt die laufende Version und führt auf eine Seite mit dem vollständigen Änderungsverlauf. Nach einem Update ist das die schnellste Antwort auf die Frage, ob der Container wirklich mit dem neuen Abbild läuft: Steht dort noch die alte Nummer, ist er es nicht. Der Verlauf wird an **einer** Stelle gepflegt (`src/lib/changelog.ts`). Daraus entstehen sowohl die Seite in der Anwendung als auch die [CHANGELOG.md](../CHANGELOG.md) im Projekt (`npm run changelog`); eine Prüfung wacht darüber, dass beides zusammenpasst. Zu jeder Version gibt es einen Git-Tag. --- ## Schnittstelle Alles, was die Oberfläche tut, geht auch über HTTP: | Route | Zweck | | --- | --- | | `POST /api/qr/preview` | Vorschau erzeugen (statisch oder dynamisch) | | `POST /api/qr/download` | PNG oder SVG erzeugen | | `GET/POST /api/codes` | dynamische Codes auflisten und anlegen | | `GET/PATCH/DELETE /api/codes/{id}` | einzelnen Code lesen, ändern, löschen | | `GET /api/codes/{id}/qr` | Bild eines gespeicherten Codes | | `POST /api/uploads` | Datei hochladen (`GET` nennt die Größengrenze) | | `GET /api/uploads/{id}` | Datei ausliefern (`?download` erzwingt Speichern) | | `POST /api/feedback` | Rückmeldung abgeben | | `GET/POST /api/auth` | Zustand, Anmelden, Abmelden, Passwort ändern | | `GET /api/auth/oidc/start` · `/callback` | Anmeldung über den Anbieter | | `/api/admin/types` · `users` · `groups` · `domains` · `branding` · `settings` | Verwaltung | | `GET /r/{slug}` | Weiterleitung eines dynamischen Codes | | `GET /s/{slug}` | öffentliche Landingpage | Fehler kommen als `{ "error": "…" }` mit einer deutschen Meldung, die sich unverändert anzeigen lässt. --- ## Was die Anwendung bewusst nicht tut - **Kein Logo im QR-Code.** Wer es braucht, nimmt das SVG, setzt es im Layoutprogramm ein, wählt Fehlerkorrektur H und testet mit mehreren Geräten. - **Keine Statistik über die Zeit.** Der Zähler weiß, wie oft und wann zuletzt — kein Verlauf, keine Herkunft, keine Geräte. Das wäre eine eigene Tabelle und die Frage, wie lange man so etwas aufbewahrt. - **Keine Übernahme von Gruppen aus dem Verzeichnis.** Siehe oben. - **Keine Stapelverarbeitung.** Codes entstehen einzeln. - **Keine Mehrsprachigkeit.** Die Oberfläche ist deutsch. - **Kein Papierkorb.** Ein gelöschter Code ist weg, samt seiner Dateien und Rückmeldungen. Was davon als Nächstes sinnvoll wäre, steht in der [Roadmap](roadmap.md).