arbeitsstunden/README.md

# TC Ingelfingen Arbeitszeiterfassung

Strato-taugliche PHP-Webanwendung für die Arbeitszeiterfassung des TC Ingelfingen.

## Eigenschaften

- Läuft direkt aus `httpdocs` ohne Shell, Node oder Container
- Optional an externe MySQL/MariaDB-Datenbank anbindbar
- Mitglieder-Login mit Rollenmodell
- Mitglieder sehen Stundenstand, Reststunden und möglichen EUR-Abzug
- Bearbeiter buchen Stunden und legen Mitglieder an
- Admins können alles, inklusive Mitglieder anlegen, Rollen vergeben und Logs ansehen
- Eigene Profilseite für Vorname, Nachname und Passwortänderung
- Passwort-Reset über E-Mail-Link auf der Anmeldeseite
- Darkmode-Schalter in der Kopfzeile mit lokaler Speicherung
- Dashboard-Infokasten für alle Mitglieder, pflegbar durch Admins mit einfacher Markdown-Unterstützung
- Aggregierte Dashboard-Übersicht für Bearbeiter und Admins über alle Mitglieder
- Stundenbuchungen mit Rollenansicht: Mitglieder nur eigene, Bearbeiter und Admins alle
- Bearbeiter und Admins können einzelne Stundenbuchungen löschen
- Paginierung mit 50 Einträgen pro Seite in Benutzerliste, Stundenbuchungen und Logansicht
- Audit-Log für Verwaltungsaktionen sowie Login- und Logout-Vorgänge
- CSV-Export und CSV-Import für Benutzerdaten inklusive geleisteter Stunden
- Separater CSV-Export für alle Stundenbuchungen
- SQL-Dump-Export und SQL-Dump-Wiederherstellung für vollständige App-Backups
- Separater CSV-Export der Logansicht für Administratoren
- Admin-Funktion zum Löschen der Audit-Logeinträge
- Admin-Funktion zum Zurücksetzen aller Arbeitsstunden auf 0
- Tabler CSS via CDN für UI, Cards, Tabellen und Formulare

## Strato-Setup

1. Inhalt von `httpdocs/` in das Webverzeichnis der App hochladen
2. Wenn die App in einem Unterordner wie `/arbeitsstunden/` läuft, muss genau dieser Ordner das Webroot der App enthalten
3. `config.php` nicht in `httpdocs/`, sondern eine Ebene darüber ablegen
4. Optional diese Umgebungsvariablen oder Konfigurationswerte setzen:
   - `DB_HOST`
   - `DB_NAME`
   - `DB_USER`
   - `DB_PASS`
   - `SETUP_KEY` optional, schützt die Ersteinrichtung
5. PHP 8.1+ und `pdo_mysql` aktivieren

## Strato Schritte

1. DB in Strato anlegen
2. `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` setzen oder `config.php` oberhalb des Webroots anlegen
3. Dateien aus `httpdocs/` in den Zielordner der App hochladen, z. B. `https://tc-ingelfingen.de/arbeitsstunden/`
4. `install.php` über den App-Pfad öffnen, z. B. `/arbeitsstunden/install.php`, und erstes Admin-Konto anlegen
5. Danach mit dem neuen Admin einloggen
6. Falls keine DB konfiguriert ist, nutzt die App Demo-Zugänge nur zum Anzeigen

## Datenbank

Die Anwendung ist so aufgebaut, dass sie mit oder ohne DB läuft. Bei gesetzter DB werden Tabellen automatisch angelegt, sonst werden Demo-Daten genutzt.

- Mitglieder
- Benutzer/Rollen
- Arbeitsstunden
- Audit-Log
- Einstellungen

## Rollen

- `member`: sieht das eigene Dashboard, die eigene Profilseite und die eigenen Stundenbuchungen
- `editor`: darf Stunden buchen, Mitglieder anlegen, alle Stundenbuchungen sehen und die Vereinskonfiguration pflegen
- `admin`: darf alles, inklusive Mitglieder anlegen, Rollen vergeben, Administration, CSV-/SQL-Exporte, CSV-/SQL-Importe und globalem Stunden-Reset

## Funktionen

- Profil
  - Jeder Benutzer kann Vorname, Nachname und das eigene Passwort ändern
  - Die E-Mail-Adresse wird im Profil angezeigt, ist aber nicht editierbar
  - Für vergessene Passwörter gibt es einen Reset-Link per E-Mail
- Dashboard
  - `member` sieht die eigenen Pflichtstunden, geleisteten Stunden und offenen Stunden
  - `editor` und `admin` sehen aggregierte Gesamtwerte aller Mitglieder inklusive EUR-Werten
  - Ein zusätzlicher Informationskasten kann durch Admins gepflegt werden
- Stundenbuchungen
  - `member` sieht nur eigene Buchungen
  - `editor` und `admin` sehen alle Buchungen
  - `editor` und `admin` können einzelne Buchungen löschen
  - Die Liste ist auf 50 Einträge pro Seite paginiert
- Vereinskonfiguration
  - Pflichtstunden und Stundenwert pflegen
  - Informationskasten für das Dashboard pflegen
  - Benutzerdaten als CSV exportieren
  - Alle Stundenbuchungen als CSV exportieren
- Administration
  - SQL-Dump für vollständige Datensicherung herunterladen
  - SQL-Dump zur Wiederherstellung hochladen
  - Benutzerdaten aus CSV importieren
  - Alle Arbeitsstunden auf 0 zurücksetzen
  - Logansicht mit 50 Einträgen pro Seite
  - Logansicht als CSV exportieren
  - Audit-Logeinträge direkt in der Administration löschen
  - Audit-Log für Verwaltungsaktionen sowie Login und Logout

## Listen Und Paginierung

Die folgenden Bereiche nutzen eine Paginierung mit 50 Einträgen pro Seite:

- Benutzerliste in der Benutzerverwaltung
- Stundenbuchungen
- Logansicht in der Administration

## Markdown Im Informationskasten

Der Informationskasten im Dashboard unterstützt eine einfache Markdown-Teilmenge:

- Absätze
- Listen mit `- `
- `*kursiv*`
- `**fett**`

## CSV-Format

Der CSV-Export und CSV-Import für Benutzerdaten verwenden diese Spalten:

- `firstname`
- `lastname`
- `email`
- `role`
- `hours_worked`

Beispiel-Kopfzeile:

`firstname,lastname,email,role,hours_worked`

## Backup Und Wiederherstellung

Zusätzlich zu den CSV-Exporten gibt es in der Administration einen SQL-Dump für vollständige Backups der App-Datenbank.

Enthalten sind die App-Tabellen:

- `users`
- `work_logs`
- `settings`
- `audit_logs`
- `password_resets`

Hinweise:

- Der SQL-Dump ist für vollständige Sicherungen und Wiederherstellung gedacht.
- Die SQL-Wiederherstellung überschreibt die bestehenden App-Daten.
- CSV-Exporte bleiben zusätzlich für Auswertungen und Teilimporte erhalten.

## Passwort-Reset Und Konfiguration

Für den Passwort-Reset per E-Mail wird eine `config.php` im Projektwurzelverzeichnis verwendet. Eine Vorlage liegt als `config.php.example` vor.

Mindestens sinnvoll ist ein Absender für E-Mails:

```php
<?php
return [
    'db' => [
        'host' => '127.0.0.1',
        'name' => 'arbeitsstunden',
        'user' => 'dbuser',
        'pass' => 'dbpass',
    ],
    'smtp' => [
        'from_email' => 'noreply@example.de',
        'from_name' => 'TC Ingelfingen',
    ],
];
```

Hinweis:

- Die aktuelle Implementierung nutzt PHP `mail()` fuer den Versand.
- Wenn das Hosting E-Mails direkt versenden kann, funktioniert der Passwort-Reset auch ohne vollstaendige SMTP-Implementierung.
- Die Datei `config.php` sollte nicht in `httpdocs/`, sondern im Projektwurzelverzeichnis liegen.
- Bei einem Deployment in einem Unterordner wie `/arbeitsstunden/` liegt `config.php` eine Ebene über diesem Webroot.

## Ersteinrichtung

Wenn noch kein Benutzer vorhanden ist, leite `index.php` automatisch auf `install.php` weiter. Dort kannst du ein erstes Admin-Konto anlegen.

## Handouts

Für die Weitergabe an Anwender stehen folgende Anleitungen bereit:

- `ANLEITUNG_MITGLIEDER.md`
- `ANLEITUNG_BEARBEITER.md`
- `ANLEITUNG_ADMIN.md`

## Dateien

- `httpdocs/index.php` Einstieg
- `httpdocs/install.php` Ersteinrichtung
- `httpdocs/app/bootstrap.php` DB, Login und Business-Logik
- `httpdocs/app/views.php` Tabler-UI
- `config.php` lokale Konfiguration oberhalb des Webroots
- `config.php.example` Vorlage für DB- und Mail-Konfiguration
- `ANLEITUNG_MITGLIEDER.md` Handout für Mitglieder
- `ANLEITUNG_BEARBEITER.md` Handout für Bearbeiter
- `ANLEITUNG_ADMIN.md` Handout für Administratoren