# procurex-frontend

Angular-22-SPA (Standalone Components, `@if`/`@for`-Control-Flow) für PROCUREX — **PRX-20**
("Angular-Frontend-Struktur und Accessibility-Regeln festlegen").

## Struktur

```
src/app/
├── core/
│   ├── models/           TypeScript-Interfaces, gespiegelt von den Backend-DTOs
│   ├── services/         HttpClient-Services (ein Service pro Bounded Context) + AuthService
│   ├── auth.config.ts    OIDC-Konfiguration (Keycloak, Authorization Code + PKCE)
│   ├── jwt.util.ts        Access-Token-Payload dekodieren (fuer Rollen-Claim, keine Signaturpruefung)
│   └── http-error.interceptor.ts   uebersetzt RFC-7807-Problem-Details in Nutzermeldungen
├── features/
│   ├── suppliers/        PRX-3
│   ├── catalog/          PRX-4
│   ├── cart/             PRX-2
│   └── orders/           PRX-12 (Liste) + PRX-5/PRX-8 (Genehmigung) + PRX-10 (Wareneingang)
│                          + PRX-11/PRX-9 (Rechnungspruefung) auf der Detailseite
├── app.ts / app.html     Shell: Skip-Link, Hauptnavigation, Login/Logout, Statusmeldung
└── app.routes.ts         Lazy-geladene Feature-Routen
```

## Login (PRX-19, Umsetzung)

Echtes OIDC-Login über `angular-oauth2-oidc` (Authorization Code + PKCE) gegen den
Keycloak-Realm `procurex` (siehe `../keycloak/README.md` für Testnutzer/Rollen). Solange nicht
eingeloggt, zeigt die Shell nur einen "Anmelden"-Button; nach dem Login steuert der
`realm_access.roles`-Claim aus dem Access Token (nicht dem ID-Token), welche Navigationspunkte und
Bestelldetail-Abschnitte sichtbar sind (`AuthService.roles`, siehe `app.ts`/`order-detail.component.ts`).
Das ist reine UI-Sichtbarkeit — die eigentliche Autorisierung erzwingt das Backend
(`procurex-app/SecurityConfig`), das jeden API-Call unabhängig vom Frontend gegen den Access
Token prüft.

## Accessibility

- Skip-Link zum Hauptinhalt
- Alle Formularfelder mit `<label for>`, Fehlermeldungen über `aria-invalid`
- Statusmeldungen (Erfolg/Fehler) als `role="status"` mit `aria-live="polite"`
- Tabellen mit `<caption>` (visuell versteckt) und `<th scope="col">`
- Sichtbarer Fokusindikator (`:focus-visible`) statt Browser-Default zu entfernen

## API-Anbindung

`environment.apiBaseUrl`: lokal `http://localhost:8081/api/v1`, im Production-Build (`ng build`,
Docker/PRX-21) `http://procurex-api.localhost/api/v1` (eigener Traefik-Host, siehe
`environment.prod.ts` und `../docker-compose.yml`). Jeder API-Call bekommt automatisch den
Bearer-Token angehängt (`provideOAuthClient` mit `resourceServer.allowedUrls`, siehe `app.config.ts`).

## Starten

**Lokal:**
```
npm install
npx ng serve
```
Voraussetzung: `procurex-app` läuft auf Port 8081, Keycloak auf `keycloak.localhost` (siehe
`../procurex-app/README.md`).

**Docker (PRX-21):** siehe `../docker-compose.yml` und `../procurex-app/README.md`.

## Build & Test

```
npx ng build   # Production-Build nach dist/procurex-frontend
npx ng test --watch=false
```

## E2E-Tests (PRX-33, Umsetzung)

Playwright-Tests unter `e2e/`, laufen gegen den echten docker-compose-Stack (Traefik, Keycloak,
Backend, Postgres) — kein Mock, echter Authorization-Code+PKCE-Redirect zu Keycloak inklusive
Ausfüllen des echten Keycloak-Login-Formulars (`e2e/auth.ts`).

| Datei | Deckt ab |
|---|---|
| `login.spec.ts` | Nicht angemeldet zeigt Hinweis; Login als buyer1 zeigt Navigation/Rolle; Logout |
| `procure-to-pay.spec.ts` | Kompletter Kern-Ablauf: supplieradmin1 legt Lieferant+Katalogartikel an → buyer1 sendet Warenkorb ab → approver1 genehmigt dieselbe Bestellung (PRX-2, PRX-5/PRX-8) |

Legt sich eigene Testdaten mit Zeitstempel-Suffix an, statt sich auf vorhandene Daten im Stack zu
verlassen.

```
npx playwright test        # Voraussetzung: docker compose up -d (siehe procurex-app/README.md)
```

**Gefundener und behobener Bug dabei:** Die Katalogsuche (`CatalogItemRepository.search`) schlug
mit HTTP 500 fehl, sobald die Seite ohne Suchbegriff geladen wurde (`function lower(bytea) does
not exist`) — Postgres konnte den Typ des `:query`-Parameters nicht ableiten, wenn er `null` war,
weil in der JPQL kein expliziter Cast stand. Behoben durch `CAST(:query AS string)` in der Query.
Der bestehende `CatalogItemTest` (Mockito, keine echte DB) konnte das strukturell nicht prüfen —
erst der echte Browser-Durchlauf gegen die echte Datenbank hat es aufgedeckt.

## Playwright – was im Lernprojekt eingerichtet wurde

Playwright ist das für PRX-33 ausgewählte Werkzeug für **End-to-End-Tests (E2E)**. Dabei wird ein
echter Browser automatisiert. Der Test prüft deshalb den Weg aus Sicht eines Benutzers: Angular-
Oberfläche, Keycloak-Login, Backend-REST-API und Datenbank werden gemeinsam durchlaufen.

### Vorhandene Einrichtung

- Abhängigkeit `@playwright/test` Version `1.62.1` in `package.json` und `package-lock.json`
- Konfiguration in `playwright.config.ts`
- Testverzeichnis `e2e/`
- Gemeinsame Login-Hilfe in `e2e/auth.ts`
- Chromium für die lokale Ausführung über den Playwright-Browser-Cache
- npm-Script: `npm run e2e`

Die Installation befindet sich im Projekt lokal unter `procurex-frontend/node_modules` und wird
nicht in Git versioniert. Die Browser-Binaries liegen normalerweise außerhalb des Repositories
unter `%LOCALAPPDATA%\ms-playwright`. Versioniert werden nur Quellcode, Konfiguration und
Lockdatei, damit andere Lernende die Umgebung reproduzierbar mit `npm ci` aufbauen können.

### Testablauf

```text
Playwright startet Chromium
        ↓
PROCUREX-SPA öffnet Keycloak-Login
        ↓
Test meldet sich mit einem Testbenutzer an
        ↓
Angular ruft echte APIs mit OIDC/JWT auf
        ↓
Playwright prüft sichtbare Ergebnisse und Rollenverhalten
```

Die Tests laufen bewusst gegen den laufenden Docker-Compose-Stack. Dadurch werden keine
Backend- oder Browser-Services gemockt. Vor dem Lauf müssen daher mindestens Frontend, Traefik,
Keycloak, Backend und PostgreSQL erreichbar sein.

```powershell
cd procurex-frontend
npm ci
npx playwright install chromium       # nur nötig, wenn Chromium noch fehlt
npm run e2e
```

Nützliche Varianten:

```powershell
npx playwright test --list            # Tests nur auflisten
npx playwright test e2e/login.spec.ts # nur Login-Test
npx playwright test --headed          # Browser sichtbar anzeigen
npx playwright show-report             # lokalen HTML-Report öffnen, falls erzeugt
```

Die Tests erzeugen eigene Lieferanten, Katalogartikel und Bestellungen mit Zeitstempeln. Nach
einem Lauf können diese Datensätze in der lokalen Datenbank verbleiben und müssen bei Bedarf
manuell bereinigt werden. Ein vorhandener Testcode bedeutet außerdem nicht automatisch, dass ein
aktueller Lauf erfolgreich war: Dafür benötigt man einen Testreport oder einen nachvollziehbaren
CI-Log.

### Jenkins-Ausführung

Das Jenkinsfile enthält ein optionales Stage `Frontend: Playwright E2E`. Es wird über den
Build-Parameter `RUN_E2E=true` aktiviert und verwendet das offizielle Playwright-Container-Image
mit Node.js und Browser-Binaries. Der Docker-Compose-Stack muss vor dem Build erreichbar sein;
das Stage startet keine dauerhafte Infrastruktur selbst. Testberichte und Screenshots werden als
Jenkins-Artefakte archiviert.

Der Standard-Build bleibt bei `RUN_E2E=false`, damit ein normaler Compile-/Unit-Test-Build nicht
unbemerkt eine Datenbank- oder Keycloak-Umgebung benötigt.

## Selenium – alternative Technologie

Selenium ist ebenfalls ein etabliertes Werkzeug zur Browserautomatisierung. Tests werden meist
über Selenium WebDriver geschrieben. WebDriver kommuniziert mit dem jeweiligen Browser über einen
Browser-Treiber, zum Beispiel ChromeDriver oder GeckoDriver für Firefox.

Für PROCUREX wurde Selenium **nicht zusätzlich eingerichtet und nicht ausgeführt**. Es ist hier
als Vergleich und mögliche Alternative dokumentiert, damit die Technologieentscheidung
verständlich bleibt.

## Playwright und Selenium im Vergleich

| Kriterium | Playwright | Selenium |
|---|---|---|
| Browsersteuerung | Moderne Playwright-API über eine einheitliche Verbindung | WebDriver-Standard mit Browser-Treiber |
| Einrichtung | Ein npm-Paket plus verwaltete Browser-Binaries | Selenium-Bibliothek plus passende Treiber oder Selenium Grid |
| Sprachen | JavaScript/TypeScript, außerdem Python, Java und .NET | Sehr breite Sprachauswahl, unter anderem Java, JavaScript, Python und C# |
| Synchronisation | Automatisches Warten auf sichtbare und interaktive Elemente | Häufig explizite Waits erforderlich, moderne Selenium-Versionen unterstützen ebenfalls bessere Waits |
| Browserabdeckung | Chromium, Firefox und WebKit | Sehr breite Browser- und Grid-Unterstützung, auch Enterprise-Sonderfälle |
| Parallelisierung | Im Test Runner direkt integriert | Mit Selenium Grid, Test Runner oder CI-Konfiguration üblich |
| Debugging | Trace Viewer, Screenshots, Videos und HTML-Report integriert | Screenshots und Reports meist über zusätzliche Test- oder CI-Werkzeuge |
| PROCUREX-Passung | Sehr gut für Angular/TypeScript und den vorhandenen npm-Workflow | Möglich, aber zusätzlicher Treiber-/Grid- und Implementierungsaufwand |

### Entscheidung für dieses Projekt

Playwright passt im aktuellen Lernprojekt besser, weil das Frontend Angular und TypeScript nutzt,
die Tests im selben npm-Projekt liegen und der E2E-Test-Runner Traces, Screenshots und Reports
ohne zusätzliche Selenium-Grid-Infrastruktur unterstützt. Selenium wäre sinnvoll, wenn die
Plattform bereits einen zentralen Selenium Grid betreibt, viele unterschiedliche Browser-
Versionen verbindlich getestet werden müssen oder vorhandene Java-Selenium-Standards übernommen
werden sollen.

Die Entscheidung ist keine Aussage, dass Selenium schlechter ist. Beide Werkzeuge können den
PROCUREX-Kernprozess testen; Playwright ist lediglich die passendere und kleinere Lernprojekt-
Entscheidung für den derzeitigen Angular-/npm-Stack.

## Kommerzielle Nutzung und Lizenzierung

Playwright und Selenium sind **keine kostenpflichtigen kommerziellen Produkte** im Sinne einer
verpflichtenden Laufzeit- oder Benutzerlizenz. Die Kernprojekte werden als Open Source unter der
**Apache License 2.0** veröffentlicht. Damit ist eine Nutzung in einem kommerziellen Projekt
grundsätzlich möglich, sofern die Bedingungen der Apache-2.0-Lizenz eingehalten werden, zum
Beispiel Copyright- und Lizenzhinweise beibehalten sowie Änderungen korrekt gekennzeichnet
werden.

Für dieses Lernprojekt bedeutet das:

- Playwright darf für interne, kommerzielle oder CI/CD-Tests eingesetzt werden.
- Selenium darf ebenfalls für interne, kommerzielle oder CI/CD-Tests eingesetzt werden.
- Es ist keine Playwright- oder Selenium-Subscription für die hier beschriebene Nutzung nötig.
- Die Lizenz der verwendeten Browser, Container-Images, npm-Pakete und weiterer Abhängigkeiten
  muss zusätzlich separat geprüft werden.
- Diese Dokumentation ist keine Rechtsberatung; vor einem Produktiv- oder SaaS-Einsatz sollte
  die konkrete Dependency-Liste durch die zuständige Rechts-/Compliance-Stelle geprüft werden.

Quellen: [Playwright-Repository und Lizenz](https://github.com/microsoft/playwright) sowie
[Selenium-Repository und Lizenz](https://github.com/SeleniumHQ/selenium). Beide offiziellen
Repositories weisen die Apache-2.0-Lizenz aus.