# AGENTS.md

## Overview

Single-page app for tracking engineering projects across weekly sessions
("Sitzungen"). Vanilla JS/HTML/CSS frontend + Node.js/Express server. No build
step, no bundler, no tests. Data is persisted as semicolon-separated CSVs
under `sessions/`.

Two HTML entrypoints, both served statically by Express:
- `Test.html` — the main app (tabs: Projektboard, Auslastung, Projekte,
  Projektbeteiligte). Served at `/`.
- `project-plan.html` — per-project Gantt/TODO planning view, opened in a new
  tab via `openProjectPlan()` in `js/gantt.js`. Loads the shared helper modules
  (`globals`, `utils`, `ui`, `date-picker`, `csv`, `server`, `gantt`) plus the
  plan modules under `js/plan/` — NOT the full main module set.

All UI strings/comments/CSV content are German. Preserve German in
user-facing text.

## File structure

```
.
├── server.js                 # Express server + CSV API
├── package.json             # deps: express, cors only
├── docker-compose.yml       # at repo ROOT; build context ., dockerfile Docker/Dockerfile
├── Docker/Dockerfile        # node:20-alpine
├── .dockerignore
├── .vscode/extensions.json
├── public/
│   ├── Test.html            # main app (served at /)
│   ├── js/                  # main app modules (classic scripts, global fns)
│   │   ├── globals.js       # Konstanten (LPHS, ROLES, LPH-Farben, DEPARTMENTS) + db/currentDepartment
│   │   ├── utils.js         # esc, uid, Datum-/Differenz-Helfer, personIdForName, weekSortKey-Quelle
│   │   ├── ui.js            # LocalStorage-UI-State, Header-Collapse, Theme
│   │   ├── date-picker.js   # Datums-/Bereichspicker-Overlays
│   │   ├── csv.js           # CSV-Parser/Serializer + weekSortKey, filenameForWeek
│   │   ├── server.js        # baseUrl, sendCsvToServer, deleteCsvFromServer, blobToDataUrl
│   │   ├── store.js         # save/syncAllToServer, switchDepartment, load, seed
│   │   ├── weeks.js         # Wochen-Auswahl, -Erzeugung, -Klonen, Auto-Lock, -Löschung
│   │   ├── board.js         # Projektboard-Rendering, Status-Editor, Anwesenheit, Zuordnung
│   │   ├── people.js        # Personen-Tab-Rendering + Drag-and-Drop + Abwesenheiten
│   │   ├── projects.js      # Projekte-Tab-Rendering + Drag-and-Drop
│   │   ├── load.js          # Auslastungs-Tab, LP-Modal, Neues-Projekt-Modal
│   │   ├── gantt.js         # GANTT-Diagramm (buildGanttHtml, openProjectPlan), geshared
│   │   ├── showmode.js      # Show-Mode (Präsentationsmodus)
│   │   ├── tabs-auth.js     # showTab, confirmPassword (SHA256-Passwortschutz)
│   │   ├── pdf.js           # PDF-Export (pdfmake, A3 quer)
│   │   └── init.js          # renderAll/initUiState + Seiteneinstieg (nur Test.html)
│   ├── project-plan.html    # Gantt/TODO planning view
│   ├── js/plan/             # planning modules (nur von project-plan.html geladen)
│   │   ├── plan-state.js    # PlanApp-Zustand, Datenladepath, savePlan, Toasts
│   │   ├── plan-build-gantt.js # buildGanttHtml-Erweiterung (TODO- und Meilensteinzeilen)
│   │   ├── plan-gantt.js    # renderPlanGantt, Abhängigkeitslinien, Zoom, Ressourcen-Load
│   │   ├── plan-drag.js     # GANTT-Balken-Drag/Resize + TODO-/Meilenstein-Zeilen-Drag
│   │   ├── plan-modals.js   # TODO-, Meilenstein- und Abwesenheits-Modals
│   │   └── plan-schedule.js # Kritischer Pfad, Auto-Schedule, Mail-Link
│   ├── styles.css
│   └── dein_bild.ico
└── sessions/                # data; bind-mounted into Docker container
    ├── ELT/  HLS/  ARCH/    # one folder per department
```

## Running

```bash
npm install
npm start                 # http://localhost:3003, or PORT=3004 if occupied
docker compose up --build # Docker variant (compose file is at repo root)
```

- PORT env var overrides default 3003 in `server.js`.
- Frontend must be served over HTTP: `baseUrl()` in `js/server.js` uses
  `window.location.origin` or falls back to `http://localhost:3003` when opened
  via `file://` (then only seed/demo data loads).
- Check `/health` returns `{ok:true}` after starting.

## Server API (`server.js`)

- `GET /` → `Test.html`; `GET /health`.
- `GET /load-all?department=` → `{sessions:[{filename,content}], people}` with
  `_people.csv` content in `people`; sessions sorted by filename.
- `POST /save-csv {filename, csv, department}` → writes UTF-8 BOM CSV.
- `POST /delete-csv {filename, department}`.
- Valid departments hard-coded as `ELT|HLS|ARCH` in `server.js`
  (`VALID_DEPARTMENTS`); anything else silently falls back to `ELT`. Same set in
  `DEPARTMENTS` in `js/globals.js`.
- `safeName()` strictly validates filenames (path traversal protection);
  static assets get `Cache-Control: no-store`.
- JSON body limit is 2 MB.

## CSV format

- Delimiter `;`, UTF-8 with BOM. Hand-editing is possible but risky; the parser
  reconstructs objects from the fixed column layout.
- Week files `<Label>.csv` (e.g. `KW_30___2026.csv` — `filenameForWeek()`
  replaces non-word chars with `_`). Row layout is positional:
  `WOCHE` (label, date, locked flag) → `PERSONEN` (`name|role|fullName` per
  column) → header row → `ANWESENHEIT` → one row per project.
- `_people.csv` per department: `NAME;Rollen;Voller Name;E-Mail;Abwesenheiten`
  (absences as JSON). People are global per department; new people are copied
  into the current week. Historical weeks keep their own person copies, so
  deleting a global person leaves old sessions unaffected no matter what.
- Don't change the column layout without updating both `weekToCsv()` and
  `parseSessionCsv()` (`js/csv.js`), which must stay inverse of each other.

## Frontend architecture

- The frontend is split into small classic non-module `<script>` files under
  `public/js/`; **all functions are globals on `window`**. Two HTML files include
  them via `<script src>` tags; load order in the HTML defines dependencies,
  since there is no bundler:
  - `Test.html` loads `globals → utils → ui → date-picker → csv → server →
    store → weeks → board → people → projects → load → gantt → showmode →
    tabs-auth → pdf → init`. See the exact list in `Test.html`.
  - `project-plan.html` loads only `globals → utils → ui → date-picker → csv →
    server → gantt` plus the `js/plan/*` modules. It must NOT load modules that
    touch main-only page elements (`store`, `weeks`, `board`, …, `init`).
- Shared state object `window.PlanApp` (`js/plan/plan-state.js`) holds all
  project-plan page state (week, project, zoom level, drag/`modal`-state),
  `db`/`currentDepartment` live in `js/globals.js`.
- State: `let db = { weeks, currentWeek, globalPeople }` (in-memory only).
- Project IDs are regenerated on every CSV load, so projects are addressed
  cross-page by `department` + week `label` + `projNr` + `projName` via URL
  params (`openProjectPlan`, `findProjectForPlan`).
- Person IDs are stable across reloads via `personIdForName(name)` →
  `p_<lowercased alnum>`.
- `save()` debounces 500 ms then `syncAllToServer()` writes **all** weeks plus
  `_people.csv` — not just the changed week. Exception: `js/plan/plan-state.js`
  `savePlan()` bypasses `save()` and writes only the current week's CSV directly
  via `sendCsvToServer()`.
- Weeks are sorted by calendar week extracted from the label (`KW XX / YYYY`)
  via `weekSortKey()`, not alphabetically/by filename.
- `applyAutoLock()` locks every week except the chronologically last one after
  load/clone/new-week; `localStorage` UI state is not restored for locked tabs.
- `localStorage` keys: `projuebersicht_v1` (department only — tab is never
  restored), `projuebersicht-theme`, header-collapse key. Do **not** store data
  in `localStorage`; it is UI state only.

## Auth / security quirk

- The `projects` and `people` tabs, week deletion, and week unlock are gated by
  a password modal comparing `CryptoJS.SHA256(input)` to
  `PROTECTED_PASSWORD_HASH` (`js/globals.js`, modal in `js/tabs-auth.js`).
  Client-side only — not real security. CryptoJS and pdfmake (PDF export) are
  loaded from `cdnjs.cloudflare.com` in `Test.html`, so those features need
  internet access and won't work offline. `project-plan.html` loads neither.
- User-provided status HTML is sanitized on render via a small whitelist
  (`sanitizeStatusHtml` in `js/board.js`) to mitigate XSS.

## Docker

- `docker compose up --build` from the repo root. Compose maps `3003:3003`,
  bind-mounts `./sessions:/app/sessions`, `restart: unless-stopped`.
- Dockerfile: `node:20-alpine`, `npm ci --production`, runs as non-root `node`,
  HEALTHCHECK on `/health`. `.dockerignore` excludes `Docker/*` (except
  `Docker/Dockerfile`), `node_modules/`, `.git`, `npm-debug.log`.

## Conventions & verification

- Git repo; commits are German (e.g. "PDF Export von A4 auf A3 …"). Remote:
  `http://192.168.3.187:3000/erik/projektuebersicht.git`.
- No linter, formatter, typecheck, or test suite. Manual verification only:
  start server, open `http://localhost:3003`, exercises the relevant tab,
  confirm CSV changes in `sessions/`.