keysManager

Verwaltungsoberfläche für Schlüssel, NFCs und Passcodes - Schulprojekt für IT-HTL Ybbs, Third Class (Information Systems).

Umsetzung laut keysManager.pdf:

Teil	Inhalt	Status
Teil 1	Verwaltung Tokens + Mitarbeiter, Aus-/Rückgabeprotokoll, Historie	OK
Teil 1	Austauschbares Backend (JSON / CSV; MongoDB/MariaDB einhängbar)	OK
Teil 2	xlsx-Export des Protokolls mit PHPSpreadsheet	OK
Teil 4	Authentifizierung per Session	OK
Topics	Formulare, Cookies, Sessions, Dateibehandlung, Mailversand, OOP/MVC	OK

Projektstruktur

keysManager/
├── public/              # Document-Root (Front-Controller)
│   ├── index.php
│   ├── .htaccess        # URL-Rewriting für Apache
│   └── assets/
│       └── style.css
├── src/
│   ├── Core/            # Router, Controller-Basis, View, Session, Request, Response
│   ├── Models/          # Token, Employee, Assignment, User
│   ├── Repositories/    # Interfaces + Json/ + Csv/ Implementierungen
│   ├── Controllers/     # Auth, Dashboard, Token, Employee, Assignment, Export
│   └── Services/        # MailService, AuthService, ExportService
├── views/               # Templates (Layouts, Partials, Seiten)
├── data/                # JSON/CSV-Backend (wird vom Programm erzeugt)
├── storage/
│   ├── mail/            # gespeicherte Mails (Mail-Treiber "file", Dev/Demo)
│   └── logs/
├── config/app.php       # zentrale Konfiguration (Backend-Wahl, Mail, ...)
├── composer.json
└── README.md

OOP / MVC

• Model: src/Models/* - reine Datenobjekte (Token, Employee, Assignment, User).
• View: views/* - PHP-Templates, verwendet eine kleine eigene View-Engine mit Layout (views/layouts/main.php) und Escape-Helfer $this->e().
• Controller: src/Controllers/* - nehmen den Request entgegen, arbeiten gegen die Repository-Interfaces und rendern die Views.
• Router (src/Core/Router.php) mappt URLs auf [Controller::class, 'method'].

Austauschbares Backend (Teil 1)

Die Controller kennen nur die Interfaces in src/Repositories/:

• TokenRepositoryInterface
• EmployeeRepositoryInterface
• AssignmentRepositoryInterface
• UserRepositoryInterface

In src/Repositories/Json/ gibt es eine komplette JSON-Implementierung, in src/Repositories/Csv/ eine alternative CSV-Implementierung. Umschalten geschieht an einer Stelle - in config/app.php:

'storage' => 'json', // oder 'csv'

Für MongoDB bzw. MariaDB legt man einfach neue Klassen in src/Repositories/Mongo/ bzw. src/Repositories/Sql/ an, die dieselben Interfaces implementieren, und trägt den neuen Schlüssel im switch von Application::bootRepositories() ein.

Voraussetzungen

• PHP 8.1 oder neuer (wegen readonly Properties, match, etc.)
• Composer (für PHPSpreadsheet - Teil 2)
• Optional: Apache/Nginx mit mod_rewrite; der PHP Built-in Server reicht auch.

Installation

1. Repository klonen / Ordner öffnen.

2. Abhängigkeiten installieren:

   composer install

3. Anwendung starten - entweder über den PHP Built-in Server:

   php -S localhost:8080 -t public

   ...oder über XAMPP/WAMP: das Verzeichnis als Alias einbinden und den DocumentRoot auf public/ zeigen lassen (die .htaccess übernimmt das URL-Rewriting).

4. Im Browser öffnen: http://localhost:8080

Erster Login

Beim ersten Start wird automatisch ein Admin-Benutzer angelegt (über password_hash() sicher abgelegt in data/users.json bzw. data/users.csv).

• Benutzer: admin
• Passwort: admin

Die Standarddaten können in config/app.php unter default_user angepasst werden. data/users.json kann jederzeit um weitere User ergänzt werden.

Funktionen

Dashboard

Übersicht über die Anzahl Tokens (gesamt / verfügbar / ausgegeben / verloren), Mitarbeiter und letzte Ausgaben.

Tokens

• Anlegen, bearbeiten, anzeigen, löschen
• Typen: Schlüssel, NFC, Passcode
• Filtern nach Typ, Status, Suchbegriff (Formulare)
• Detailseite mit kompletter Historie des Tokens

Mitarbeiter

• Anlegen, bearbeiten, anzeigen, löschen
• Detailseite mit allen Tokens, die der Mitarbeiter aktuell bzw. früher hatte

Aus-/Rückgabeprotokoll

• Token an Mitarbeiter ausgeben: Token wird als issued markiert, ein neuer Eintrag im Protokoll entsteht.
• Token zurückgeben: Eintrag wird mit returnedAt und optionaler Notiz ergänzt, Token kehrt in den Status available zurück.
• Als verloren markieren: Token wird in den Status lost gesetzt.
• Filter: alle / nur offene / nur zurückgegebene.

xlsx-Export (Teil 2)

/export/xlsx generiert das komplette Protokoll als echte .xlsx-Datei via PHPSpreadsheet (fette Header, freeze, autoSize). Ohne installiertes PHPSpreadsheet wird automatisch eine CSV-Datei (mit UTF-8 BOM für Excel) zurückgegeben.

Mailversand (Topic: Mailversand mit PHP)

Beim Ausgeben eines Tokens wird der Mitarbeiter per E-Mail benachrichtigt. Der Mail-Service unterstützt zwei Treiber (config/app.php → mail.driver):

• mail - verwendet mail() (benötigt einen MTA, z.B. auf dem Schulserver)
• file - legt die generierte Mail als .eml-Datei unter storage/mail/ ab. Dadurch lässt sich der Versand ohne echten SMTP-Server demonstrieren.

Cookies + Sessions (Topics)

• Nach dem Login wird eine PHP-Session angelegt (src/Core/Session.php, session_regenerate_id(true)).
• Optionaler Cookie km_last_user merkt sich den letzten Benutzernamen für das Login-Formular.
• Flash-Messages (Erfolg / Fehler) werden über die Session transportiert und beim nächsten Request verworfen.
• Alle schreibenden Requests sind per CSRF-Token geschützt.

Authentifizierung (Teil 4)

Der Login-Controller verwendet AuthService mit password_hash / password_verify. Geschützte Routen werden über Middleware (['auth']) in public/index.php markiert.

Tests von Hand

1. Als admin / admin einloggen → es sollte das Dashboard erscheinen (inklusive Beispieldaten).
2. Einen neuen Token anlegen → erscheint in der Liste.
3. Einen neuen Mitarbeiter anlegen → erscheint in der Liste.
4. /assignments/create → Token + Mitarbeiter wählen und ausgeben.
5. Unter /assignments → Rückgabe verbuchen.
6. Unter /export/xlsx → xlsx-Datei herunterladen und in Excel öffnen.
7. storage/mail/ prüfen: dort sollten .eml-Dateien für jede Ausgabe liegen (Mail-Driver file).
8. In config/app.php 'storage' => 'csv' setzen → Repositories schalten auf CSV um; data/*.csv werden beim ersten Zugriff erzeugt.

Hinweise zu Teil 3 (optional, MA-DB)

Ist in dieser Variante nicht umgesetzt, da keine konkrete MA-DB verfügbar ist. Die Integration wäre jedoch einfach: Eine neue SqlEmployeeRepository- Klasse in src/Repositories/Sql/ anlegen, EmployeeRepositoryInterface implementieren (mit PDO gegen MariaDB), in Application::bootRepositories() registrieren und in config/app.php aktivieren - Controller und Views bleiben unverändert.