projektuebersicht/README.md

# Projektübersicht — README

## Übersicht
Dieses Projekt ist eine lokale Weboberfläche zur Verwaltung von TGA-Projekten (Elektro, HLS, Architektur) über wöchentliche Sitzungen. Die Anwendung besteht aus:

- einem Frontend mit `Test.html` als der einen Anwendungsseite — sie enthält alle Bereiche einschließlich des Projektbereichs eines einzelnen Projekts (Terminplan/GANTT, Aufgaben, Dateien, Einstellungen) — dazu `styles.css`, `plan-styles.css` und den JS-Modulen unter `public/js/`
- einem einfachen Node.js-/Express-Server in `server.js`
- einem Datenspeicher in einer SQLite-Datenbank (`node:sqlite`, benötigt Node ≥ 22.13) unter `sessions/projektuebersicht.db`
- einem Docker-Setup (`Docker/Dockerfile` + `docker-compose.yml` im Projektstamm)

## Datei- und Komponentenübersicht

### Wichtige Laufzeit-Dateien
- `server.js`
  - Node.js/Express-Server
  - dient als API für das Frontend
  - stellt statische Dateien (`Test.html`, die Module unter `js/`, `styles.css`, `plan-styles.css`, etc.) bereit; statische Assets werden mit `Cache-Control: no-store` ausgeliefert
  - implementiert Endpunkte:
    - `GET /` → liefert `Test.html`
    - `GET /load-all?department=…` → lädt alle Sitzungen plus globale Personenliste einer Abteilung
    - `POST /save-week {department, week, baseUpdatedAt}` → speichert/aktualisiert eine Sitzung; mit `baseUpdatedAt` (die vom Client gehaltene Revision = `updatedAt` aus `load-all`) erkennt der Server veraltete Speicherungen und antwortet dann mit HTTP 409 `{ok:false, conflict:true, …}`; auch gelöschte Sitzungen werden mit nicht-leerer Basis nicht wiederbelebt (409). Erfolgreiche Saves antworten `{ok:true, updatedAt}` (neue Revision)
    - `POST /save-people {department, people}` → ersetzt die globale Personenliste einer Abteilung
    - `POST /delete-week {department, label}` → löscht eine Sitzung
    - `GET /health` → Gesundheitscheck (`{ok:true}`)
    - Deep Links je Abteilung + Tab, z. B. `GET /HLS/Auslastung` oder `GET /ELT/Projektübersicht` → liefert `Test.html`; gültige Tab-Slugs sind `Projektübersicht | Auslastung | Projekte | Projektbeteiligte`, alles andere ergibt 404
    - `GET /Projektplan(/<ProjName>)?` → liefert ebenfalls `Test.html`; der Projektbereich ist seit dem Umbau kein eigenes Dokument mehr, sondern ein Bereich dieser Seite, den `applyUrlRoute()` (`public/js/ui.js`) aus der Adresse auswählt. Die Identifikation erfolgt über die Query-Parameter `weekLabel` und `projNr`, der Projektname ist nur ein lesbares Pfad-Segment. Alte Links auf `/project-plan.html` werden per 301 auf dieses Schema umgeleitet
  - validiert Abteilungen gegen `ELT | HLS | ARCH` (unbekannte fallen stillschweigend auf `ELT` zurück)
  - legt das `sessions`-Verzeichnis beim Start an, falls es nicht existiert
  - JSON-Body-Limit von 2 MB
  - beendet sich mit aussagekräftiger Fehlermeldung, wenn der Port belegt ist

- `package.json`
  - definiert den Node.js-Startbefehl `npm start`
  - enthält Produktionsabhängigkeiten `express` und `cors`

- `package-lock.json`
  - wird für reproduzierbare Docker-Builds verwendet (`npm ci`)

- `public/js/` (Module)
  - Die Client-Logik ist in kleine klassische Script-Dateien aufgeteilt (alle Funktionen global auf `window`, kein Bundler):
    - gemeinsame Helfer: `globals.js`, `utils.js`, `ui.js`, `date-picker.js`, `server.js`, `store.js`, `weeks.js`, `gantt.js`, `showmode.js`, `tabs-auth.js`, `pdf.js`, `init.js`
    - tab-spezifisch in eigenen Ordnern: `board/board.js` (Projektboard), `people/people.js` (Projektbeteiligte), `projects/projects.js` (Projekte), `load/load.js` (Auslastung)
    - Planungs-Module unter `js/plan/` (`plan-state`, `plan-build-gantt`, `plan-gantt`, `plan-drag`, `plan-modals`, `plan-schedule`)
  - rendert das Projektboard, die Projekt- und Personenverwaltung sowie die Auslastungsansicht
  - lädt Daten über den Server und speichert Änderungen als JSON-Objekte in die SQLite-Datenbank zurück
  - verwendet `currentDepartment` zur Trennung von Abteilungen (`ELT`, `HLS`, `ARCH`)
  - speichert:
    - alle Sitzungen und die globale Personenliste pro Abteilung in `sessions/projektuebersicht.db`
  - sortiert Sitzungen nach Kalenderwoche, nicht alphabetisch
  - sperrt historische Sitzungen automatisch (bis auf die chronologisch letzte)
  - Personen sind global pro Abteilung verwaltet; historische Sitzungen behalten ihre lokalen Personenkopien
  - speichert keine Daten in `localStorage` (dort liegt nur UI-Zustand wie Abteilung, Theme und Header-Collapse)

- `Test.html`
  - die Haupt-Benutzeroberfläche der Anwendung (Tabs: Projektboard, Auslastung, Projekte, Projektbeteiligte)
  - lädt `styles.css` und die JS-Module aus `js/` in fester Reihenfolge (siehe `AGENTS.md`)
  - enthält die Abteilungsauswahl, Sitzungsnavigation, Tab-Navigation, das Passwort-Modal sowie PDF-Export
  - lädt CryptoJS (Passwortprüfung) und pdfmake (PDF-Export) von `cdnjs.cloudflare.com` — diese Funktionen benötigen daher Internetzugang

- Projektbereich (Bereich `#plan` in `Test.html`, Module unter `js/plan/`)
  - der eigene Bereich EINES Projekts mit Dashboard, Terminplan (GANTT/TODOs/Meilensteine), Aufgaben, Dateien und Einstellungen
  - wird über `openProjectPlan()` (`js/gantt.js`) geöffnet — ein gewöhnlicher Bereichswechsel über `showTab('plan')`, genau wie vom Dashboard ins Projektboard; Menüband und Seitenleiste bleiben stehen
  - war bis zum Umbau ein eigenes Dokument `project-plan.html` mit nachgebauter, abgespeckter Seitenleiste; die Datei ist entfallen, ihre Stile liegen jetzt in `plan-styles.css`

- `plan-styles.css`
  - die Stile des Projektbereichs (früher ein `<style>`-Block in `project-plan.html`)

- Bereich „Einstellungen" (`js/settings/settings.js`)
  - gehört dem angemeldeten Konto selbst: Stammdaten zur Ansicht und der Passwortwechsel (`POST /change-password`). Der Dialog erscheint auch erzwungen direkt nach der Anmeldung, solange das Konto `must_change_password` trägt

- Bereich „Admin" (`js/admin/admin.js`, nur für Administratoren)
  - gegliedert in einzelne Abschnitte, zwischen denen die aufklappbare Gruppe „Admin" in der Seitenleiste umschaltet; sichtbar ist immer genau einer, der gewählte steht im URL-Fragment (z. B. `/Admin#auslastung`) und ist damit verlinkbar
  - Abschnitte: „Benutzerverwaltung" (Konten, Rollen, Wochenstunden, Abwesenheiten — bis zum Umbau die eigene Seite `admin-users.html`, alte Links werden per 301 umgeleitet), „Honorar" (Stundensatz, Anteile je Leistungsphase), „Auslastung" (Wochenstunden einer vollen Stelle, Ampel-Schwellen, Balkenskala, Aufwand je Leistungsphase und Rolle), „Termine & Sitzungen" (Arbeitsstunden je Werktag, automatische Sperre), „Feiertage" (die gesetzlichen Feiertage eines Jahres werden berechnet — feste Termine plus alles, was am Osterdatum hängt — und auf Knopfdruck übernommen; kein Netzdienst, kein Internetzugang nötig), „Aufgaben-Vorlagen", „Betrieb & Sicherheit" (aufbewahrte Backups, Gültigkeit einer Anmeldung, Anmeldebremse) und „Datenbank & Sitzungen" (DB Backup, DB Import, Sitzung löschen)
  - all diese Werte waren vorher Konstanten im Quelltext; gelesen werden sie über `GET /app-settings` (jedes Konto — das Frontend rechnet damit), geschrieben über `PUT /app-settings` (nur Administratoren, serverseitig über `requireRole('admin')` abgesichert)
  - die vertraglichen Wochenstunden je Person stehen am Benutzerkonto (Benutzerverwaltung) und sind die Bezugsgröße der Auslastungs-Ampel: Eine halbe Stelle gilt schon bei halber Last als voll ausgelastet

- `styles.css`
  - Layout und Styling der Oberfläche

### Docker-bezogene Dateien
- `Docker/Dockerfile`
  - Basis-Image: `node:22-alpine` (nötig, da `node:sqlite` erst ab Node 22.13 ohne Flag stabil verfügbar ist)
  - kopiert `package.json` und `package-lock.json`, installiert Produktionsabhängigkeiten mit `npm ci`
  - kopiert `server.js` und `public/` nach `/app`
  - legt sicherheitshalber `/app/sessions` an
  - läuft als nicht-root-User `node`
  - enthält einen `HEALTHCHECK` auf `/health`
  - startet `node server.js`

- `docker-compose.yml` (im Projektstamm)
  - definiert den Service `projektuebersicht`
  - baut das Image mit Build-Kontext `.` und `Docker/Dockerfile`
  - mappt Port `3003:3003`
  - bindet das Host-Verzeichnis `./sessions` in den Container nach `/app/sessions`
  - setzt `restart: unless-stopped`
  - definiert einen `healthcheck`

- `.dockerignore`
  - schließt unnötige Dateien aus dem Docker-Build aus: `node_modules/`, `npm-debug.log`, `.git`, `.gitignore`, `Docker/*` (außer `Docker/Dockerfile`)

### Sonstige Dateien
- `dein_bild.ico`
  - optionales Icon, wird vom Server statisch ausgeliefert, wenn angefragt

- `AGENTS.md`
  - Projektnotizen / Dokumentation, aber nicht Teil des Anwendungslaufs

## Persistenz und Datenfluss

### Speicherung
- Alle persistierten Daten werden in einer SQLite-Datenbank (`node:sqlite`, `DatabaseSync`, WAL-Modus, `PRAGMA foreign_keys = ON`) unter `sessions/projektuebersicht.db` gespeichert.
- Das Schema ist vollständig relational (19 Tabellen): `weeks`, `week_people` (+ `week_people_roles`), `attendance`, `projects`, `project_lph`, `project_assign`, `project_aufwand`, `project_aktuelle_lp`, `project_plan`, `plan_people`, `plan_todos` (+ `plan_todo_assignees`, `plan_todo_deps`), `plan_milestones` (+ `plan_milestone_deps`), `people` (+ `person_roles`, `person_absences`). Projekt-/Personen-IDs bleiben dadurch über Neustarts stabil.
- Der Datenbankpfad ist über die Umgebungsvariable `DB_PATH` übersteuerbar (für Tests/Backups), Standard ist `sessions/projektuebersicht.db`.

### Server-API
- Der Server wird in `server.js` erstellt und startet auf Port `3003` oder dem Wert von `process.env.PORT`.
- Das Frontend ruft den Server über `window.location.origin` an (Fallback `http://localhost:3003` bei `file://`-Öffnung).

### Wo werden die Daten gespeichert?
- Das Frontend schreibt über den Server in die SQLite-Datenbank.
- In `js/store.js` speichert die Anwendung nur **geänderte** Sitzungen (Dirty-Tracking über `markWeekDirty()`/`markPeopleDirty()`) via `/save-week` (Sitzungen) bzw. `/save-people` (globale Personen); ein In-Flight-Guard verhindert Doppel-Speicherungen. Jede Sitzung führt einen Revisions-Zeitstempel (`updated_at`, übertragen als `updatedAt`); speichert ein Client mit veralteter Revision (`baseUpdatedAt`), antwortet der Server mit HTTP 409 und der Client lädt nur diese eine Sitzung neu (andere ungespeicherte Änderungen bleiben erhalten).
- Der Server zerlegt die JSON-Objekte in die relationalen Tabellen (`serializeWeek()`/`loadWeeks()`) in einer Transaktion pro Sitzung. Beim Start migriert `migrateLegacySchema()` idempotent ein altes Single-JSON-Dokument-Schema in das relationale Schema; anschließend ergänzt `migrateWeeksUpdatedAt()` die `updated_at`-Spalte der `weeks`-Tabelle (idempotent). `PRAGMA busy_timeout = 5000` verhindert Fehler bei parallelen Schreibzugriffen.

## Betrieb

### Lokal mit Node.js (Node ≥ 22.13)
```bash
npm install
npm start
```
Danach ist die Anwendung erreichbar unter `http://localhost:3003`.

Falls der Port belegt ist:
```bash
PORT=3004 npm start
```

### Mit Docker
Im Projektstamm ausführen:

```bash
docker compose up --build
```

Danach ist die Anwendung erreichbar unter:

```
http://localhost:3003
```

## Wichtige Hinweise
- Der Server benötigt Lese-/Schreibzugriff auf `sessions/` (für die SQLite-Datenbank und das Docker-Bind-Mount).
- Die Docker-Compose-Konfiguration liegt im Projektstamm und mountet `./sessions` in den Container. Achte darauf, dass der relative Pfad im Kontext korrekt ist, wenn du `docker compose` aus einem anderen Verzeichnis startest.
- `js/store.js` und `js/server.js` arbeiten mit Abteilungsparametern und speichern Daten abteilungsweise getrennt.
- Die Passwortfunktion (Tabs „Projekte“/„Projektbeteiligte“, Sitzungslöschung, Entsperren) ist nur ein einfacher Client-Mechanismus im Frontend (SHA256-Vergleich) und kein echter Sicherheitsmechanismus.
- Globale Personen werden pro Abteilung in der Datenbank verwaltet. Wird eine Person global gelöscht, bleibt sie in bereits existierenden Sitzungen sichtbar (Wochen-Personenkopien).
- CryptoJS und pdfmake werden von `cdnjs.cloudflare.com` geladen — PDF-Export und Passwortprüfung funktionieren ohne Internet nicht.