222 lines
13 KiB
Markdown
222 lines
13 KiB
Markdown
# 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 in a SQLite database
|
|
(`node:sqlite`, needs Node >= 22.13) at `sessions/projektuebersicht.db`.
|
|
|
|
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`, `server`, `gantt`) plus the
|
|
plan modules under `js/plan/` — NOT the full main module set.
|
|
|
|
All UI strings/comments are German. Preserve German in
|
|
user-facing text.
|
|
|
|
## File structure
|
|
|
|
```
|
|
.
|
|
├── server.js # Express server + SQLite API
|
|
├── package.json # deps: express, cors only
|
|
├── docker-compose.yml # at repo ROOT; build context ., dockerfile Docker/Dockerfile
|
|
├── Docker/Dockerfile # node:22-alpine (nötig für node:sqlite)
|
|
├── .dockerignore
|
|
├── .vscode/extensions.json
|
|
├── public/
|
|
│ ├── Test.html # main app (served at /)
|
|
│ ├── js/ # shared modules (classic scripts, global fns)
|
|
│ │ ├── globals.js # Konstanten (LPHS, ROLES, LPH-Farben, DEPARTMENTS) + db/currentDepartment
|
|
│ │ ├── utils.js # esc, uid, Datum-/Differenz-Helfer, personIdForName, peopleByRole, assignKey, weekSortKey
|
|
│ │ ├── ui.js # LocalStorage-UI-State, Header-Collapse, Theme
|
|
│ │ ├── date-picker.js # Datums-/Bereichspicker-Overlays
|
|
│ │ ├── server.js # baseUrl, sendWeekToServer, sendPeopleToServer, blobToDataUrl
|
|
│ │ ├── store.js # save/syncAllToServer, switchDepartment, load, seed
|
|
│ │ ├── weeks.js # Wochen-Auswahl, -Erzeugung, -Klonen, Auto-Lock, -Löschung
|
|
│ │ ├── 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)
|
|
│ │ ├── board/ # tab-specific: Projektboard
|
|
│ │ │ └── board.js # Projektboard-Rendering, Status-Editor, Anwesenheit, Zuordnung
|
|
│ │ ├── people/ # tab-specific: Projektbeteiligte
|
|
│ │ │ └── people.js # Personen-Tab-Rendering + Drag-and-Drop + Abwesenheiten
|
|
│ │ ├── projects/ # tab-specific: Projekte
|
|
│ │ │ └── projects.js # Projekte-Tab-Rendering + Drag-and-Drop
|
|
│ │ ├── load/ # tab-specific: Auslastung
|
|
│ │ │ └── load.js # Auslastungs-Tab, LP-Modal, Neues-Projekt-Modal
|
|
│ ├── 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/ # SQLite-DB; bind-mounted into Docker container
|
|
└── projektuebersicht.db # node:sqlite database (WAL mode)
|
|
```
|
|
|
|
## 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`.
|
|
- Deep links per department + tab: `GET /<Dept>/<Tab>` → `Test.html`, e.g.
|
|
`/HLS/Auslastung` or `/ELT/Projektübersicht`. Tab slugs (`TAB_SLUGS` in
|
|
`js/globals.js`) are `Projektübersicht|Auslastung|Projekte|Projektbeteiligte`;
|
|
anything else returns 404. Exception: `GET /<Dept>/Projektplan(/<ProjName>)?`
|
|
(`PLAN_SLUG`) serves `project-plan.html`, the GANTT view, with
|
|
`weekLabel|projNr` as query params (the project name is a readable path
|
|
segment only; identification happens via weekLabel + projNr). The frontend
|
|
reads/writes these routes via `applyUrlRoute()`/`updateRouteUrl()` in
|
|
`js/ui.js` and all static assets in the HTML use **absolute** paths
|
|
(`/js/...`, `/styles.css`) so they resolve on nested routes.
|
|
- `GET /load-all?department=` → `{weeks:[weekObj], people:[personObj]}` with the
|
|
global people list in `people`; weeks are full JSON week objects (id, label,
|
|
date, locked, people, attendance, projects), sorted by label.
|
|
- `POST /save-week {department, week}` → upserts one week (JSON object, keyed by
|
|
department + label). Used by `sendWeekToServer()`.
|
|
- `POST /save-people {department, people}` → replaces the department's global
|
|
people list (JSON array).
|
|
- `POST /delete-week {department, label}` → deletes the week; missing label
|
|
yields 400, missing week tolerates with `deleted:false`.
|
|
- 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`.
|
|
- Static assets get `Cache-Control: no-store`.
|
|
- JSON body limit is 2 MB.
|
|
|
|
## Persistence (SQLite)
|
|
|
|
- Data lives in `sessions/projektuebersicht.db` (`node:sqlite` `DatabaseSync`,
|
|
WAL mode, `PRAGMA foreign_keys = ON`), created automatically. The schema is
|
|
**fully relational** (18 tables) instead of one big JSON document per week:
|
|
- `weeks` (department, label, week_id, date, locked; PK `(department,label)`)
|
|
- `week_people` / `week_people_roles` — person copies per week (`array_order`
|
|
keeps the list order, `role_order` the role array order)
|
|
- `attendance` — présence per week/person
|
|
- `projects` (`array_order` = position in the JSON array, `order_value` = the
|
|
`p.order` field, which is only unique *within a group*, not globally!)
|
|
- `project_lph`, `project_assign` (person_id|role keys split into columns),
|
|
`project_aufwand` (LP effort per role), `project_aktuelle_lp`
|
|
- `project_plan`, `plan_people`, `plan_todos` / `plan_todo_assignees` /
|
|
`plan_todo_deps`, `plan_milestones` (`position` column!) /
|
|
`plan_milestone_deps`
|
|
- `people` / `person_roles` / `person_absences` — global people per department
|
|
- The HTTP API stays JSON-shaped: `serializeWeek()` /
|
|
`serializeGlobalPeople()` split incoming week/people objects across the
|
|
tables inside a transaction, `loadWeeks()` / `loadGlobalPeople()`
|
|
(re)assemble them on read. `saveWeekRelational()` deletes the week's rows
|
|
first (`deleteWeekData()`, note `weeks` uses `label`, all child tables
|
|
`week_label`).
|
|
- Migration on every start (idempotent):
|
|
`migrateLegacySchema()` converts a DB from the old single-JSON-document format
|
|
(detected via a `data` column in `weeks`): it reads the documents, drops all
|
|
tables, recreates the relational schema and inserts everything in one
|
|
transaction.
|
|
- The DB file sits in `sessions/`, so the existing Docker bind-mount
|
|
`./sessions:/app/sessions` keeps it persistent. The path is overridable via
|
|
the `DB_PATH` environment variable (used for tests), production default is
|
|
`sessions/projektuebersicht.db`.
|
|
- Project/person IDs are stable across reloads; only week-level fields are
|
|
queryable columns.
|
|
|
|
## 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 → server →
|
|
store → weeks` (shared modules), then the tab-specific folders `board →
|
|
people → projects → load`, finally `gantt → showmode → tabs-auth → pdf →
|
|
init`. See the exact list in `Test.html`.
|
|
- `project-plan.html` loads only `globals → utils → ui → date-picker →
|
|
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/person IDs are stable across reloads because the server splits and
|
|
reassembles week objects deterministically (JSON IDs are kept in the DB
|
|
columns); projects are addressed cross-page by `department` + week `label` +
|
|
`projNr` (+ readable projName path segment) via URL params:
|
|
`openProjectPlan()` builds `/HLS/Projektplan/<ProjName>?weekLabel=…&projNr=…`,
|
|
`findProjectForPlan` resolves them. Person IDs follow
|
|
`personIdForName(name)` → `p_<lowercased alnum>`.
|
|
- `save()` debounces 500 ms then `syncAllToServer()` writes **all** weeks (via
|
|
`sendWeekToServer()`) plus the people list (via `sendPeopleToServer()`) — not
|
|
just the changed week. Exception: `js/plan/plan-state.js` `savePlan()` bypasses
|
|
`save()` and writes only the current week directly via `sendWeekToServer()`.
|
|
- `switchDepartment()` cancels a pending save debounce before switching, and
|
|
`load()` discards stale `/load-all` responses after a department switch
|
|
(frozen `requestedDepartment`), so late responses can never render or persist
|
|
data under the wrong department.
|
|
- Person drag-and-drop in the people tab: drag handle (`.drag-handle`) binds
|
|
`ondragstart`/`ondragend`, the `.people-sortable` container binds
|
|
`ondragover`/`ondrop`; insertion is computed by `getDragAfterElement(container,
|
|
y, selector)` (`js/projects/projects.js`, used with `.person-card` here and
|
|
`.person-list-item` in the projects tab). `reorderPeople()` updates both
|
|
`db.globalPeople` and the current week's person copy, then `save()`. No drag
|
|
handles are rendered on locked weeks.
|
|
- 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 from storage; at startup the tab comes from the deep-link URL if
|
|
present, otherwise `board`), `projuebersicht-theme`, header-collapse key. Do
|
|
**not** store data in `localStorage`; it is UI state only.
|
|
- Deep-link URLs (`/<Dept>/<Tab>`) are shared via the address bar:
|
|
`updateRouteUrl()` rewrites the path via `history.replaceState` on tab and
|
|
department switches; protected tabs keep the URL but open the password modal.
|
|
|
|
## 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/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:22-alpine` (nötig für node:sqlite), `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 SQLite changes (the DB file `sessions/projektuebersicht.db` grows). |