# Konventionen für ProxDeploy Diese Datei ist verbindlich. Wer hier etwas ändert, ändert es auch in `docs/architektur.md`. ## Sprache **Deutsch, überall wo ein Mensch liest oder benennt** – auch Bezeichner: Funktionen, Variablen, Prisma-Modelle und -Felder, Enum-Werte, Fehlerklassen, Dateinamen, Kommentare, Testbeschreibungen, Commit-Betreffs. **Umlaute in Bezeichnern ASCII-gefaltet** (`geaendertAm`, `pruefen`), in Texten für Menschen richtig geschrieben („Verbindung prüfen“). Englisch bleiben: vom Framework vorgegebene Namen (`GET`, `route.ts`, `page.tsx`, `proxy.ts`), Fachjargon (`Token`, `OIDC`, `VMID`, `Node`, `Storage`, `Bridge`, `Template`, `cloud-init`) und die **YAML-Schlüssel im Katalog** (`catalog/**`) – die sind ein Austauschformat aus der Vorgabe. ## Namensabbildung zur Vorgabe | Vorgabe | Modell / Begriff | Vorgabe | Modell / Begriff | |---|---|---|---| | User | `Benutzer` | Deployment / Job | `Auftrag` (Art `AUSROLLEN`, `TEMPLATE_BAUEN`, `AUFRAEUMEN`) | | API token (CLI) | `ApiToken` | Phase | `Phase` | | SSH key | `SshSchluessel` | Job log line | `Logeintrag` | | Server | `Server` | VMID lock | `VmidReservierung` | | Node | `knoten` (Feld) | Proxmox template | `Template` | | Distribution | `Distribution` | Preset | `Vorlage` | | Profile | `Profil` | Audit log | `Protokoll` | | Setting | `Einstellung` | Key provider | `SchluesselQuelle` | API-Pfade sind deutsch: `/api/v1/server`, `/api/v1/auftraege`, `/api/v1/vorlagen`. ## Schichtung ``` src/engine/* Deploy-Logik, frameworkfrei: kein Next, kein Prisma, kein React. src/server/services/* Regeln und Schreiboperationen; rufen Engine und Prisma. src/server/auth/* Sitzung, Tokens, Rechte (RECHTE + darf()). src/app/api/v1/* Route Handler: Recht prüfen, zod, Service. Sonst nichts. src/components/* Darstellung, keine Geschäftslogik. src/lib/* Framework-freie Helfer; was Client und Server teilen, liegt hier. src/worker/* Hintergrundprozess (pg-boss). cli/ CLI in Go; nur REST-API. Typen aus cli/api/openapi.json (oapi-codegen). ``` - **Web-GUI und CLI nutzen dieselbe REST-API.** Keine Logik nur für eine Oberfläche. - **Phasentexte kommen aus der Engine.** Web und CLI rendern Name, Status, Detail, Dauer, Ursache, Hinweis – sie erfinden keinen Text. - **Jede Seite und jeder Route Handler prüft sein Recht selbst** (`seiteSchuetzen`, `rechtErforderlich`). `tests/zugang.test.ts` prüft das strukturell; Ausnahmen stehen dort mit Begründung. Rolle und Aktiv-Status werden je Anfrage aus der DB gelesen. - **Client-Komponenten importieren nichts aus `src/server/*`.** - **Fehler an Aufrufer** nur als `AnwendungsFehler` (Status, Code, Nachricht, Hinweis); Format `{ fehler: { code, nachricht, hinweis?, felder? } }`. - **zod nur über `@/lib/validierung`** (deutsche Meldungen; ESLint erzwingt das). - **Datenbankregeln** (Trigger, CHECK) stehen in den Migrationen und namentlich in `tests/datenbankregeln.test.ts`. ## Werkzeuge und Versionen Node 24 über nvm (`export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"`), pnpm 12. Exakt gepinnt: `next@16.4.2`, `react@19.3.0`, `prisma`/`@prisma/client`/`@prisma/adapter-pg` **`7.10.1`** (der `latest`-Tag von prisma zeigt auf einen 8.0-RC), `vitest@5.0.1`, `@playwright/test@1.63.0`, `pino@10.4.0`. Obergrenzen: **eslint 9.x** (eslint-plugin-react aus eslint-config-next kann 10 nicht), **typescript ~6.0.3** (typescript-eslint 8 erlaubt < 6.1). CLI: **Go 1.27.2** ohne sudo unter `~/.local/go` (`export PATH="$HOME/.local/go/bin:$PATH"`), `cobra 1.10.2`, `BurntSushi/toml 1.6.0`, `x/term 0.46.0`, `go-runewidth 0.0.30`, `go.yaml.in/yaml/v3 3.0.5`, `oapi-codegen 2.8.0` (als `go tool`). Antwortschemas der API stehen in `src/lib/schemas/api.ts`; nach einer Änderung `pnpm openapi` und `go generate ./...` in `cli/`. **Sicherheitsupdates** gehen vor die Regel „mindestens zwei Wochen abgelagert“: mit bekannter kritischer Lücke kein Release (`pnpm audit --prod` vor jedem Tag; Next 16.4.0 → 16.4.2 und Prisma 7.10.0 → 7.10.1 am 2026-10-23 aus diesem Grund). Next 16: `proxy.ts` statt middleware; `cookies()`, `headers()`, `params`, `searchParams` sind async. Prisma 7: Client aus `@/generated/prisma/client`, Enum-Werte aus `@/generated/prisma/enums`, Zugriff über den Lazy-Proxy `src/lib/db.ts`. ## Vor jedem Commit ```bash pnpm db:up pnpm lint && pnpm typecheck && pnpm format:pruefen && pnpm test pnpm cli:pruefen # wenn API-Schemas oder cli/ betroffen sind ``` Ohne laufende Datenbank überspringt `pnpm test` die Datenbanktests und sagt es auf stderr. ## Oberfläche prüfen – immer im gebauten Stand ```bash pnpm build && PORT=3310 APP_URL=http://127.0.0.1:3310 pnpm start & pnpm test:e2e ``` `next dev` hydriert in dieser Umgebung nicht verlässlich; ein Screenshot beweist dann nichts. Die Abläufe prüfen Desktop (1440 px) und Handy (**390 px, kein horizontales Scrollen**). ## Git, Versionen, Zeiterfassung - Branch `main`; je Issue/Etappe `phase/NNN-kurzname`, nach Abschluss `--ff-only` nach `main`. - Conventional Commits, deutscher Betreff ≤ 72 Zeichen, Körper erklärt das Warum, Fußzeile `Closes #NNN` bzw. `Refs #NNN`. Identität `Florian Wilde `. - SemVer; jede Etappe ein annotierter Tag `vX.Y.Z`. 1.0.0 nach dem Feldtest auf PVE 9.x (#020) – im Einsatz ist nur 9.x; 8.x bleibt im Code, gilt aber als „nicht im Feldtest geprüft“. - `CHANGELOG.md` (Keep a Changelog, deutsch) und `DEVLOG.md` (Zeit je Issue/Meilenstein aus den Commit-Zeitstempeln, Sitzungen mit „Erledigt“ und „Entscheidungen“) werden mit jedem Issue gepflegt; `docs/issues/*.md` tragen Status und tatsächliche Zeit. ## Gestaltung Farben nur als Tokens aus `src/app/globals.css` (`bg-panel`, `text-muted`, `border-linie`, `text-akzent`, `text-laeuft`, `text-fehler`); keine rohen Hexwerte in Komponenten. Ausnahmen: `themeColor` in `src/app/layout.tsx` (verträgt keine CSS-Variablen) und die Brand-Dateien unter `public/brand/`. Kein Proxmox-Orange. Status immer Symbol + Farbe + Text (``). Karten mit 1-px-Linie, Radius 14 px, keine Schatten, keine Verläufe. Kontrast ≥ 4,5:1 in beiden Themes (`tests/kontrast.test.ts`). Icons: Lucide.