omsorg/omsorgWeb/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is the OMSORG website plus **OMSORG Connect**, an internal employee web app ("Mitarbeiter-App") for a German nursing care company. There is no build system — everything is plain PHP, HTML, CSS, and vanilla JS deployed directly to a web server (`htdocs`).

**OMSORG Connect wird gerade komplett neu aufgebaut.** `mitarbeiter-app-legacy/` ist die alte, produktiv gelaufene Version — dient nur noch als Referenz/Vorlage, wird nicht mehr weiterentwickelt. Der Rest dieser Datei beschreibt `mitarbeiter-app-legacy/`, nicht den Neuaufbau. Die aktive Entwicklung findet in `mitarbeiter-app/` statt (aktuell: Login-Flow + eigenes Passwort ändern/zurücksetzen gegen `omsorgCore`, siehe unten "Neuaufbau"). Auth in der Legacy-Version läuft **nicht mehr** über lokales bcrypt/Session-Lockout wie unten in "Entry point" beschrieben — das ist bereits auf omsorgCore-JWT-Auth umgestellt (`lib/omsorgCoreClient.php`, `lib/auth.php`), lokales MySQL dient dort nur noch als Read-Cache für Profildaten.

### Neuaufbau (`mitarbeiter-app/`)
Frischer, minimaler PHP-Flow gegen `omsorgCore` — kein Framework, gleiches Deployment-Modell wie die Legacy-App. Login/Passwort, das Abwesenheits-/Urlaubs-/Krankmeldungsformular, die strukturierte Zeiterfassung pro Schicht und die eigene Fahrtstrecken-Pflege (siehe unten) sind umgesetzt; weiterhin bewusst (noch) ohne: Dienstplan, Downloads, Admin-Oberfläche, PWA-Assets, MySQL. Admin-/Mitarbeiterverwaltung gehört nicht hierher, sondern exklusiv zu OMSORG Desktop (`omsorgapp`) — Connect zeigt/bearbeitet ausschließlich Daten des eingeloggten Nutzers selbst.

**Abwesenheits-/Urlaubs-/Krankmeldungsanträge (FR-CON-1, `pages/urlaubsantrag.php`):** einzige Seite in diesem Neuaufbau mit echtem Formular + eigener Datenliste. Formular (Art/Zeitraum/Grund/Vertretung/Nachricht) postet inline auf sich selbst (kein separates `actions/*.php` wie in der Legacy-App) über `omsorgcore_absences_create()` (`lib/omsorgCoreClient.php`) gegen `POST /api/absences` in `omsorgCore` — schickt bewusst **keine** `employeeId` mit, das Backend löst den eingeloggten Mitarbeiter serverseitig über den JWT-Claim auf (`AbsenceService.CreateAsync`, siehe `omsorgCore/CLAUDE.md`). Darunter die eigene Antragshistorie über `omsorgcore_absences_list()` (Own-Scope filtert automatisch serverseitig, kein `employeeId`-Parameter nötig). Die Art-Dropdown-Optionen kommen über den neuen generischen `omsorgcore_value_list_items($config, $token, $key)`-Wrapper (erste Nicht-Auth-Verwendung des generierten PHP-Clients hier) aus `GET /api/value-lists/AbsenceType/items`, nicht hartcodiert. Genehmigen/Ablehnen passiert ausschließlich in `omsorgapp` (`AbsencesPage`) — Connect selbst hat keine Entscheidungs-UI, nur Anlegen/Bearbeiten + eigenen Status einsehen. Zweispaltiges Layout (`.split-layout` in `app.css`, Liste links/Formular rechts, bricht unter 860px auf eine Spalte um) statt gestapelter Karten.

**Bearbeiten eines eigenen Antrags:** jeder eigene Antrag im initialen Status bekommt in der Liste einen "Bearbeiten"-Link (`urlaubsantrag.php?edit=<id>`) — das rechte Formular wechselt dann in den Edit-Modus (vorbefüllt aus dem passenden Eintrag der bereits geladenen `$absences`-Liste, kein extra `GET`), postet über `omsorgcore_absences_update()` gegen `PUT /api/absences/{id}` (mit `mode=edit`/`absence_id` als Hidden-Fields, um im selben Formular-Handler zwischen Anlegen und Bearbeiten zu unterscheiden) und leitet bei Erfolg per Post-Redirect-Get auf `urlaubsantrag.php?updated=1` weiter. Der initiale Status wird dynamisch über `$initialStatus` ermittelt (`omsorgcore_value_list_items(..., 'AbsenceStatus')`, das Item mit `isInitial === true` — **nicht** der Literal `"Eingereicht"`, siehe `omsorgCore/CLAUDE.md` "Abwesenheits-/Urlaubs-/Krankmeldungsanträge"; ein Umbenennen über die Status-Verwaltung in `omsorgapp` bricht diese Seite dadurch nicht). Serverseitig (nicht nur hier) gilt dieselbe Regel: nur solange der Antrag im initialen Status ist, danach `400` — ein bereits genehmigter/abgelehnter Antrag fällt deshalb defensiv aus dem Edit-Modus zurück auf "Neuer Antrag", falls doch mal ein veralteter Link aufgerufen wird. Braucht `has_permission('Absences','Edit')` zusätzlich zu `View`.

**Zeiterfassung (FR-ZE-1/FR-ZE-2, `pages/stundenerfassung.php`):** 1:1 nach dem Muster von `urlaubsantrag.php` (Liste links/Formular rechts, inline-POST auf sich selbst, `mode=create|edit` als Hidden-Field), aber mit drei statt zwei möglichen Aktionen, weil `TimeEntryStatus` eine echte Mehrstufen-Pipeline statt einer binären Entscheidung ist (siehe `omsorgCore/CLAUDE.md` "Zeiterfassung"): Anlegen (`omsorgcore_time_entries_create()` gegen `POST /api/time-entries`, ohne `employeeId`), Bearbeiten solange `isEditableByOwner` (`omsorgcore_time_entries_update()` gegen `PUT /api/time-entries/{id}`, ohne `statusId`) und zusätzlich ein dritter `mode=submit`-Zweig im selben POST-Handler (`omsorgcore_time_entries_submit()` gegen `POST /api/time-entries/{id}/submit`, kein Payload) für den "Einreichen"-Button. Der "Einreichen"-Button erscheint nur bei Einträgen, deren `statusId` in der Menge der Selbst-Einreichungs-Kanten liegt (`omsorgcore_value_list_transitions($config, $token, 'TimeEntryStatus')`, gefiltert auf `requiresApproval === false`) — bewusst **nicht** dasselbe Kriterium wie für den "Bearbeiten"-Link (`isEditableByOwner` allein reicht hier nicht, weil auch der bereits eingereichte, aber noch nicht geprüfte Status `isEditableByOwner=true` trägt, aber keine ausgehende Selbst-Einreichungs-Kante mehr hat). Auftrags-Dropdown über `omsorgcore_orders_list()` (`GET /api/orders`) — zeigt mangels Mitarbeiter-Zuweisung auf `Order` (FR-EM-3 offen) bewusst alle aktiven Aufträge, nicht nur zugewiesene. Genehmigen/Prüfen/Freigeben passiert ausschließlich in `omsorgapp` (`TimeEntriesPage`) — Connect selbst hat keine Entscheidungs-UI.

**Fahrtstrecken (FR-EIN-4, `pages/fahrtstrecken.php`):** Selbstbedienungsseite, mit der ein Mitarbeiter seine eigene Entfernung (km, einfache Strecke) je Einrichtung pflegt — Grundlage für die kilometerbasierte Fahrtkostenabrechnung, wenn eine Einrichtung in `omsorgapp` auf `TravelCostMode = "ProKilometer"` gestellt ist (siehe `omsorgCore/CLAUDE.md`, "Konditionen einer Einrichtung"). 1:1 nach dem `urlaubsantrag.php`-Muster (Liste links/Formular rechts, `mode=create|edit`, Post-Redirect-Get bei Update), aber gegen einen eigenen, engeren Endpunkt statt der vollen Facilities-API: `omsorgcore_my_facility_distances_list/create/update()` (`lib/omsorgCoreClient.php`) gegen `/api/me/facility-distances` (`MyFacilityDistancesController`) — schickt bewusst **keine** `employeeId` mit, das Backend löst den eingeloggten Mitarbeiter serverseitig auf, exakt wie bei Abwesenheiten/Zeiterfassung. Die Einrichtungsauswahl im Anlegen-Formular kommt über `omsorgcore_my_facility_distances_facility_options()` gegen `/api/me/facility-distances/facilities` — liefert bewusst nur `id`/`name`, keine Konditionen/CRM-Daten, weil der Außendienst kein `Facilities`-Recht hat (eigener `ModuleType.EmployeeFacilityDistances`, siehe `omsorgCore/CLAUDE.md`, "Rechtesystem"). Das Dropdown zeigt nur Einrichtungen, für die noch keine eigene Distanz existiert (Duplikate serverseitig ohnehin abgelehnt); Bearbeiten ändert nur die km-Zahl, die Einrichtung selbst ist danach fix. Kein `DELETE` hier — Löschen bleibt Büro-Aufgabe in `omsorgapp`.

**Rechte im Client (`has_permission()`, `lib/auth.php`):** serverseitig ist jeder `omsorgCore`-Endpunkt ohnehin über `[RequirePermission]` gegated (siehe `omsorgCore/CLAUDE.md`, "Rechtesystem") — `has_permission(string $module, string $action): bool` ist nur die UI-Seite davon, analog zu `hasPermission()` in `omsorgapp/src/app/AuthContext.jsx`, liest `$_SESSION['omsorgcore_profile']['permissions']` (aus `GET /api/auth/me`, `PermissionDto[] { module, action, scope }`). `lib/layout.php` blendet den "Urlaub & Abwesenheit"-Tab aus, wenn `!has_permission('Absences','View')`; `pages/urlaubsantrag.php` leitet ohne dieses Recht direkt auf `dashboard.php` um (kein "leere Seite ohne Erklärung"-Fall) und blendet zusätzlich separat das Formular aus, wenn `!has_permission('Absences','Create')` (z. B. für eine Rolle mit `View`, aber ohne `Create`) — beide Prüfungen sind rein kosmetisch, ein direkt gepostetes Formular ohne UI wird serverseitig trotzdem mit `403` abgelehnt, wird hier aber zusätzlich mit einer klaren deutschen Fehlermeldung statt eines stillen Fehlschlags abgefangen. Neue Connect-Seiten mit einem Rechte-Bezug sollten `has_permission()` nach demselben Muster nutzen, statt ungegated jedem eingeloggten Nutzer alles zu zeigen.

**Passwort ändern/vergessen:** `pages/settings.php` (nach Login, `require_login()`) und `pages/forgot-password.php` (vor Login, 3-stufig: Code anfordern → verifizieren → neues Passwort setzen), beide über die dafür in `lib/omsorgCoreClient.php` ergänzten `omsorgcore_change_password`/`omsorgcore_forgot_password_*`-Wrapper gegen dieselben `omsorgCore`-Endpunkte wie in `mitarbeiter-app-legacy`. Die Mindestlänge kommt nicht hartcodiert, sondern über `omsorgcore_password_policy()` (`GET /api/auth/password-policy`, siehe `omsorgCore/CLAUDE.md` Abschnitt "Passwort-Mindestlänge") — sowohl für das `minlength`-Attribut der Formularfelder als auch für die serverseitige Vorab-Fehlermeldung; die eigentliche Durchsetzung passiert im Backend. Nach erfolgreichem Anlegen/Admin-Reset eines Accounts (`mustChangePassword`-Flag aus der Login-Response, siehe `lib/auth.php`) leitet `pages/dashboard.php` erzwungen zu `settings.php` weiter. `forgot-password.php` geht bei Schritt "request" bewusst **immer** zu Schritt "verify" weiter, unabhängig davon, ob der Username existiert (kein Enumeration-Rückschluss, siehe `omsorgCore/CLAUDE.md` "Passwort-Reset/E-Mail-Versand") — **außer** der Status ist `"email_unavailable"` (E-Mail-Versand aktuell gestört, z. B. SMTP down): dann bleibt die Seite auf Schritt "request" und zeigt eine klare Fehlermeldung, statt den Nutzer auf eine Code-Eingabe warten zu lassen, die nie ankommt.

This project is one part of the OMSORG monorepo — see the root `CLAUDE.md` (`../CLAUDE.md`) for the overall platform picture and `../REQUIREMENTS.md` for functional/non-functional requirements with FR-IDs. This app is the reference implementation for **OMSORG Connect**; its MySQL database is expected to eventually move behind the shared `omsorgCore` backend (currently empty, planned as C#/.NET + PostgreSQL) rather than staying a standalone data store.

## Deployment

Upload the full directory contents to the server's `htdocs` folder and overwrite existing files. After deploying, clear the browser cache or test in an incognito window.

There are no build steps, package managers, or test runners.

## Architecture

### Public website (`/`)
Static HTML with a contact form:
- `index.html` — main landing page
- `send-form.php` — handles the public contact form, sends email via PHP `mail()`
- `send-status-template.php` — reusable status page template for form results
- `datenschutz.html`, `impressum.html` — legal pages

### Employee app (`/mitarbeiter-app/`)
A session-based PHP app with no framework, backed by a **MySQL database** (PDO).

#### Entry point
- `index.php` — login page. Redirects to `pages/dashboard.php` if already logged in. Includes rate limiting: 5 failed attempts trigger a 10-minute lockout.
- `setup.php` — one-time setup script (run once after first deploy to bootstrap the DB)

#### Library (`lib/`)
- `auth.php` — included at the top of every protected page. Provides `require_login()`, `require_admin()`, `is_logged_in()`, `is_admin()`, `current_user()`, `current_name()`, `current_username()`, `csrf_token()`, `csrf_field()`, `verify_csrf()`, `e()`. Users are stored in the `users` DB table. Login is case-insensitive on username.
- `db.php` — provides `db(): PDO` (singleton). Reads credentials from `config.php`, runs pending migrations on first connection, and sets `PDO::ERRMODE_EXCEPTION`.
- `config.php` — returns array with MySQL DSN/credentials, SMTP settings, and mail recipient addresses. Import with `$config = require __DIR__ . '/config.php';`.
- `layout.php` — shared sidebar layout. Call `layout_start($title, $current_page)` and `layout_end()` to wrap page content. Renders the sidebar nav, user avatar, and injects the service worker.
- `mail.php` — provides `smtp_send($cfg, $to, $subject, $body, $attach = [])`. Raw SMTP implementation (no PHPMailer), supports SSL (port 465) and STARTTLS (port 587), and optional file attachments.

#### Pages (`pages/`)
Each page is a standalone PHP file using `layout_start`/`layout_end`:
- `dashboard.php` — main landing page after login; shows news and quick links
- `stundennachweis.php` — upload monthly timesheet (PDF/image)
- `urlaubsantrag.php` — vacation request form
- `abwesenheitsantrag.php` — absence request form (sick leave, etc.)
- `benefitsantrag.php` — employee benefits request
- `fortbildungsantrag.php` — training request with optional file upload
- `einsatzbewertung.php` — rate a deployment/assignment
- `einsatzanweisung.php` — view/download personal assignment instructions (PDF)
- `dokumentenarchiv.php` — personal document archive (upload/view own documents)
- `downloads.php` — company-wide file downloads (admin-managed)
- `dienstplan.php` — view personal shift schedule
- `werben.php` — refer a new employee
- `settings.php` — profile settings: change password, upload avatar
- `admin.php` — admin-only: tabs for Anträge, Nutzer, Dienstplan, Downloads, Fortbildungsmaterial, Stundennachweis, Bewertungen, News, Einsatzanweisung, Login-Versuche (failed login attempts: lists recent attempts, shows currently locked IPs, and clears the `login_attempts` table)
- `admin-dienstplan.php` — admin shift planner view
- Serve pages (`*-serve.php`, `dokument-serve.php`, `download-serve.php`, etc.) — stream protected files from `uploads/`, `downloads/`, `fortbildung-materials/` with auth check

#### Actions (`actions/`)
POST-only endpoints, each does one thing and redirects back:
- `submit-urlaubsantrag.php`, `submit-abwesenheitsantrag.php`, `submit-benefitsantrag.php`, `submit-fortbildungsantrag.php`, `submit-stundennachweis.php`, `submit-einsatzbewertung.php`, `submit-werben.php` — insert into the matching `requests_*` DB table, send notification email via `smtp_send()`
- `admin-action.php` — admin status updates (accept/reject requests), user management (add/delete/reset password), news CRUD
- `save-dienstplan.php` — admin saves shift entries
- `downloads-action.php`, `downloads-reorder.php` — admin manages downloadable files
- `fortbildung-material-action.php`, `fortbildung-material-reorder.php` — admin manages training materials
- `einsatzanweisung-action.php` — admin uploads/assigns personal instruction PDFs
- `upload-dokument.php`, `delete-dokument.php` — user document archive management
- `upload-avatar.php` — user uploads profile picture (stored in `assets/avatars/`)
- `save-profile.php` — user changes own password
- `logout.php` — destroys session, redirects to `../index.php`

#### Frontend
- `app.css` — all styles (no framework)
- `manifest.webmanifest` + `service-worker.js` — PWA support ("Add to Home Screen")

### Database schema (MySQL)
Managed via migrations in `migrations/`. Key tables:
- `users` — id, username, name, role, password_hash, active, created_at, email, telefon, avatar
- `requests_urlaubsantrag` — vacation requests (von, bis, vertretung, nachricht, status, admin_note)
- `requests_abwesenheitsantrag` — absence requests (von, bis, grund, vertretung, nachricht, status, admin_note)
- `requests_benefitsantrag` — benefits requests
- `requests_fortbildungsantrag` — training requests (with optional file upload)
- `requests_stundennachweis` — timesheet uploads (monat, filename)
- `requests_werben` — employee referrals
- `dienstplan` — shift schedule (user_id, date, schicht; UNIQUE on user_id+date)
- `downloads` — company download files (title, filename, sort_order)
- `fortbildung_materials` — training material files (title, filename, sort_order)
- `dokumente` — user personal document archive (user_id, kategorie, filename)
- `einsatzbewertungen` — deployment ratings
- `einsatzanweisung` — one PDF per user (UNIQUE on user_id)
- `news` — company news posts (title, text, date)
- `schema_migrations` — tracks applied migrations

### Migration system
`db.php` runs `_run_migrations()` on every connection. Migrations are PHP files in `migrations/` returning `['description' => ..., 'up' => [...SQL...]]`. They are applied in filename order and tracked in `schema_migrations`. Already-existing DBs without the migrations table are stamped as fully applied on first run.

### File storage
Uploaded files are stored outside webroot or protected by `.htaccess`:
- `uploads/` — user form attachments (stundennachweis, fortbildung, einsatzanweisung). Filename pattern: `{date}_{username}_{type}_{randomhex}.{ext}`
- `downloads/` — admin-managed company downloads (hashed filenames)
- `fortbildung-materials/` — admin-managed training materials (hashed filenames)
- `assets/avatars/` — user profile pictures (`{username}_{randomhex}.{ext}`)

Allowed upload types: pdf, doc, docx, jpg, jpeg, png. Max size: 12 MB.

### Security conventions
- `lib/` is blocked from direct HTTP access via `lib/.htaccess`
- `uploads/`, `downloads/`, `fortbildung-materials/`, `data/`, `migrations/` all have `.htaccess` denying direct access; files are served only through `*-serve.php` pages with auth checks
- All output uses `e()` (alias for `htmlspecialchars`) to prevent XSS
- Every POST form includes a CSRF token (`csrf_field()` in form, `verify_csrf()` in action)
- Login rate-limiting: 5 failures → 10-minute session lockout
- Uploads are renamed to random hex filenames before storage

### Email (configured in `config.php`)
- SMTP via `smtp_send()` in `lib/mail.php`; credentials in `config.php`
- `mail_info` → `info@omsorg-pflegedienste.de` (Geschäftsführung)
- `mail_sabrina` → `s.berggoetz@omsorg-pflegedienste.de` (Disposition)
- `mail_from` → `no-reply@omsorg-pflegedienste.de`