# Digitale Visitenkarten (Businesscard)

Dieses Projekt stellt eine einfache Verwaltungsoberfläche für digitale Visitenkarten bereit. Jede Karte wird über eine UUID adressiert, die eindeutig einem Datensatz in der Datenbank zugeordnet ist. Besucher:innen rufen die Karte über card.php?uuid=<UUID> auf, während Administrator:innen über das Passwort-geschützte Dashboard alle Identitäten, Feldwerte, Dateien und UUID-Token pflegen.

## Architektur

* **PHP/Apache**-Weboberfläche in <code>www/</code> mit Frontend (<code>card.php</code>, <code>download.php</code>) und Backend (<code>admin.php</code> plus <code>_sql.php</code>, <code>_func.php</code>, <code>_user.php</code>).
* **MariaDB** (Docker) hält Tabellen für Identitäten, Felder, UUIDs, Berechtigungen, Dateien und Loginversuche (<code>db/init/001_schema.sql</code>).
* **Docker Compose** startet Webserver und Datenbank; <code>www/</code> wird in den Apache-Container gemountet, <code>www/_files/</code> spiegelt das Upload-Verzeichnis <code>/var/www/html/_files/</code>.
* **Uploadverzeichnis** <code>www/_files/</code> liegt außerhalb des Document Roots und ist als <code>.gitkeep</code> im Repository abgelegt, damit Hochladungen später von <code>download.php</code> referenziert werden.

## Installation & erster Start

1. Repository clonen.
2. <code>www/secret.php</code> vom Beispiel kopieren (<code>secret.php.example</code>) und Datenbankzugang konfigurieren, damit <code>_sql.php</code> sich verbinden kann.
3. <code>mkdir -p www/_files</code> (oder <code>md www/_files</code> unter Windows) ausführen und darauf achten, dass die <code>.gitkeep</code>-Datei vorhanden ist, damit der Ordner beim Containerstart genutzt wird.
4. <code>docker-compose up --build</code> im Projektverzeichnis ausführen, um Apache und MariaDB zu starten.
5. <code>http://localhost/admin.php</code> öffnen; die Standardanmeldedaten stehen in <code>www/_user.php</code> (<code>admin</code> / <code>password</code>) und sollten sofort geändert werden.

## Admin-Oberfläche & Workflows

* Login schützt das Dashboard; nach drei gescheiterten Versuchen wird eine IP für eine Stunde gesperrt (<code>admin_login_attempts</code>).
* Das Dashboard zeigt alle Identitäten sowie UUID-Token. Neue Identitäten erstellt man über <code>?action=identity_create</code>.
* Jedes Identity kann beliebige Felder (<code>identity_fields</code>) enthalten. Der Typ kann <code>single</code>, <code>multi</code>, <code>file</code> oder <code>url</code> sein.
* Dateien werden pro Identität über das neue Upload-Formular hinzugefügt und landen in <code>www/_files/</code>. Der Upload speichert Dateiname, generierten Zwischennamen und MIME-Type in <code>files</code>. Unter dem Formular zeigt das Admin-UI eine Liste der bereits hochgeladenen Dateien inkl. einer Löschoption.
* Wenn ein Feld auf Typ <code>file</code> gesetzt ist, zeigt die Auswahl nur Uploads der aktuellen Identität (per <code>files.identity_id</code>). Die ausgewählte Datei-ID wird im Feldwert gespeichert, damit später nur diese Datei angezeigt oder heruntergeladen wird.
* UUID-Token (<code>access_tokens</code>) verbinden eine Identität mit einer eindeutigen Zeichenfolge, können optional Auslaufdaten und Notizen erhalten und dürfen **nur einmal** existieren. Tokenrechte (<code>token_permissions</code>) bestimmen, welche Feldschlüssel Besucher:innen sehen.

## Besucheransicht (Visitenkarte)

* <code>/card.php?uuid=&lt;UUID&gt;</code> lädt nur die Felder, die das Token freigibt, sowie Dateien mit demselben Token oder ohne Tokenbindung.
* Dateifelder erscheinen unterhalb der Felder als Downloadlinks, wenn der Token für die Datei berechtigt ist.
* Das Frontend zeigt Meta-Informationen (Ablaufdatum, Notiz) sowie eine gekürzte UUID. Bestehende Admin-Sessions leiten zurück zum Dashboard, damit Redakteur:innen schnell bearbeiten können.

## Datenbankstruktur im Überblick

| Tabelle | Zweck |
| --- | --- |
| <code>identities</code> | Identitätsdatensätze mit Name und Timestamp. |
| <code>identity_fields</code> | Key-Value-Felder (Text, mehrzeilig, Datei, URL) pro Identität. |
| <code>access_tokens</code> | UUID-Token pro Identität mit Ablauf, Notiz und eindeutiger Zeichenfolge. |
| <code>token_permissions</code> | Erlaubte Feldschlüssel pro Token. |
| <code>files</code> | Hochgeladene Dateien mit <code>identity_id</code>, <code>filename</code>, <code>stored_name</code>, <code>mime_type</code> und optional <code>token_id</code>. |
| <code>admin_login_attempts</code> | Brute-Force-Schutz mit Zählern und Sperrzeit pro IP. |

## Sicherheitshinweise

* **UUIDs sind einmalige Zugriffstoken** und sollten nicht doppelt vergeben oder offen weitergegeben werden, wenn geschützte Daten hinterlegt sind.
* **Admin-Zugang**: Bitte <code>www/_user.php</code> durch eigene Credentials ersetzen oder ein robusteres Auth-Verfahren implementieren.
* **Loginversuche** werden nach drei Fehlversuchen eine Stunde gesperrt (<code>registerFailedLogin</code>, <code>isIpLocked</code>, <code>clearLoginAttempts</code>).
* **Datei-Uploads** liegen im Verzeichnis <code>www/_files/</code> (Container: <code>/var/www/html/_files/</code>) und dürfen ausschließlich über <code>download.php</code> mit gültigem Token ausgeliefert werden. Der Ordner sollte nicht direkt vom Webserver referenziert werden.

## Weiterentwicklung & Pflege

1. **Stil & Branding**: Die Inline-CSS im <code>card.php</code>-Head kann durch ein eigenes Template ersetzt oder ausgelagert werden.
2. **Dateien & Automatisierung**: UUIDs und zugehörige Dateien lassen sich per API oder QR-Code verteilen. Die Download-Logik kann um Freigabezeitfenster erweitert werden.
3. **Tests & Validierung**: Neue Felder brauchen eventuell Frontend-Validierung; Dateiuploads sollten auf MIME-Type, Größe und erlaubte Endungen geprüft werden.
4. **Deployment**: Docker Compose genügt lokal. In Produktion empfiehlt sich ein Reverse Proxy, HTTPS und regelmäßige Backups des MariaDB-Volumes (<code>db_data</code>). Auch <code>www/_files/</code> sollte gesichert werden, da dort alle Uploads gespeichert werden.

> Hinweis: UUIDs repräsentieren digitale Visitenkarten und sind **einmalig**. Jeder Besuch über eine UUID dokumentiert genau eine Karte, deren Sichtbarkeit über Tokenrechte und Datei-Zuordnungen kontrolliert wird.