florian.wildeandClaude Opus 5.5
420aca3994
Next.js bis 16.4.0 hat zwei kritische Lücken (RCE in der Bildoptimierung mit SVG und in use cache) und eine hohe (DoS über Server Actions). Prisma 7.10.1 hebt mysql2 und deepmerge-ts über bekannte Lücken. Volle Prüfung grün; dazu der Vorlagen-Ablauf mit mehr Zeit, weil sein Dry-Run wirklich gegen den Testhost plant. Refs #020 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
117 lines
6.1 KiB
Markdown
117 lines
6.1 KiB
Markdown
# 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 <wilde.florian@gmail.com>`.
|
||
- SemVer; jede Etappe ein annotierter Tag `vX.Y.Z`. **1.0.0 erst nach dem Feldtest** auf echtem
|
||
Proxmox 8.x und 9.x (#020).
|
||
- `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 (`<Status>`).
|
||
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.
|