diff --git a/docs/superpowers/specs/2026-08-05-env-indicator-design.md b/docs/superpowers/specs/2026-08-05-env-indicator-design.md new file mode 100644 index 0000000..9a6a57c --- /dev/null +++ b/docs/superpowers/specs/2026-08-05-env-indicator-design.md @@ -0,0 +1,113 @@ +# Umgebungs-Indikator (Entwicklungsumgebung-Banner) + +Status: approved +Datum: 2026-08-05 + +## Kontext + +Beim Arbeiten und Testen kann leicht unklar sein, ob man gerade in der lokalen +Entwicklungsumgebung (`ng serve`, `environment.development.ts`) oder in der echten, +produktiven App unterwegs ist — beide sehen optisch identisch aus. Ziel: ein visueller +Indikator, der überall in der App sofort erkennbar macht, wenn man sich in der +Entwicklungsumgebung befindet, damit man sich beim Testen nicht vertut. + +## Entscheidungen aus dem Brainstorming + +- **Betroffene Umgebungen**: Es gibt drei Angular-Build-Konfigurationen + (`myteamwallet_frontend_modern/angular.json`): `production` (Standard, + `environment.ts`, echte API auf myteamwallet.de), `development` + (`environment.development.ts`, nur lokal via `ng serve`, `localhost:3999`) und + `container` (`environment.container.ts`, `npm run build:container`). Der `container`-Build + ist der reguläre Deploy-Weg der echten Produktion (z. B. self-hosted per Docker) — **kein** + Staging-System — und setzt bereits selbst `production: true`. Der Indikator muss also nur + `environment.production === false` erkennen; kein neues Feld in den Environment-Dateien nötig. +- **Darstellung**: dünner Banner-Streifen ganz oben über der gesamten App (nicht nur im + Header), warme Warnfarbe (Amber/Orange, bewusst nicht das App-Grün), Text „⚠ + Entwicklungsumgebung", zentriert, klein, kein Dismiss-Button (der Zweck ist ja gerade, ihn + nicht wegzuklicken und zu vergessen). +- **Inhalt**: nur der Umgebungsname, keine zusätzlichen technischen Details (API-URL o. ä.). +- **Platzierung im Code**: einmalig in `app.html` vor ``, statt in jeder + Seite einzeln — automatisch auf jeder Route (Shell, Public-Seiten, Login, Register, Users, + Logs, …) sichtbar, single source of truth. + +## Architektur / Komponenten + +### 1. Neue Komponente `EnvBanner` + +**Ordner:** `myteamwallet_frontend_modern/src/app/shared/env-banner/` + +Standalone-Komponente nach dem Muster bestehender Shared-Komponenten (`context-help`, +`skeleton`) — kein Modul/Barrel, keine Inputs. + +- `env-banner.ts`: importiert `environment` aus `../../../environments/environment` und + exponiert `protected readonly showBanner = !environment.production;`. Exportiert außerdem + die Konstante `export const ENV_BANNER_HEIGHT_PX = 28;` (wird von `App` für die + Höhen-Kompensation wiederverwendet, siehe unten — ein einziger Ort für die Pixel-Zahl). +- `env-banner.html`: `@if (showBanner) {
⚠ + Entwicklungsumgebung
}` — rendert in Produktion buchstäblich nichts (kein leeres + DOM-Element). +- `env-banner.scss`: `.env-banner { height: 28px; display:flex; align-items:center; + justify-content:center; background: #f4a300; color:#20251F; font-weight:700; font-size: + 0.75rem; letter-spacing:0.04em; text-transform:uppercase; flex-shrink:0; }` (die `28px` + müssen mit `ENV_BANNER_HEIGHT_PX` übereinstimmen — als Kommentar im SCSS vermerkt). +- `env-banner.spec.ts`: rendert Text wenn `environment.production === false`, rendert nichts + wenn `true` (Environment-Objekt im Test gemockt/überschrieben). + +### 2. Einbau in `app.html` / `app.ts` + +`app.html` bekommt vor `` ein ``. `App` importiert +`EnvBanner` in seine `imports`-Liste. + +### 3. Höhen-Kompensation für `height: 100dvh`-Layouts + +Der Banner nimmt echten Platz im normalen Fluss ein. Für Seiten, die nur `min-height:100dvh` +nutzen und sich auf `body`s eigenen Scrollbar verlassen (Login, Register, +Forgot/Reset-Password, Confirm-Email, Users, Logs), ist das unproblematisch — `body` gleicht +das automatisch aus, kein Änderungsbedarf. + +**Aber** `shell.scss`, `public-team.scss` und `public-player.scss` nutzen `height: 100dvh` +als feste Zusage „genau ein Bildschirm hoch" (siehe +`docs/superpowers/plans/`-Historie zum Doppel-Scrollbar-Fix vom selben Tag). Ohne Anpassung +würde die Shell/Public-Seite exakt um die Banner-Höhe über den sichtbaren Bereich +hinausragen (Bottom-Nav leicht abgeschnitten) — derselbe Bugtyp wie der kürzlich gefixte. + +**Fix:** `App` (Root-Komponente) bindet eine CSS-Custom-Property auf ihr eigenes +Host-Element. Host-Bindings werten Ausdrücke gegen die Komponenten-Instanz aus, daher als +Instanz-Property vorhalten: + +```ts +host: { + '[style.--env-banner-height.px]': 'bannerHeight', +} +// ... +protected readonly bannerHeight = environment.production ? 0 : ENV_BANNER_HEIGHT_PX; +``` + +Da `` ein gemeinsamer Vorfahre von `EnvBanner` und allen Routen-Komponenten +(Shell, Public-Seiten, …) ist, vererbt sich die Property automatisch nach unten. Die drei +betroffenen SCSS-Dateien ändern: + +```scss +// vorher: height: 100dvh; +height: calc(100dvh - var(--env-banner-height, 0px)); +``` + +In Produktion ist die Property `0px`, `calc(100dvh - 0px)` verhält sich identisch zu vorher +— keine Verhaltensänderung außerhalb der Entwicklungsumgebung. + +## Testing + +- `env-banner.spec.ts` (neu): Sichtbarkeit abhängig von `environment.production`. +- `app.spec.ts`: Erweiterung um Assertion, dass `--env-banner-height` korrekt `0px` bzw. + `28px` auf dem Host gesetzt wird (je nach gemocktem `environment.production`). +- Bestehende Tests (`shell.spec.ts`, `public-team.spec.ts`, `public-player.spec.ts`) bleiben + unverändert grün — die `calc()`-Änderung ist rein visuell/CSS, keine Verhaltensänderung. +- Manuelle Verifikation: `ng serve` (development) zeigt den Banner, `ng build` (production) + und `ng build --configuration=container` zeigen ihn nicht; Shell/Public-Seiten scrollen mit + Banner weiterhin korrekt ohne abgeschnittene Bottom-Nav (per Chrome DevTools nachprüfen). + +## Out of Scope + +- Kein neues `environmentName`-Feld in den Environment-Dateien (nicht nötig, siehe oben). +- Kein Dismiss/Ausblenden des Banners. +- Keine Anzeige zusätzlicher technischer Details (API-URL, Build-Hash) im Banner-Text.