docs(260925-bow): Was-ist-neu-Fenster in CHANGELOG, Anwender- und Entwicklerdoku

- CHANGELOG Unveroeffentlicht -> Neu
- Anwenderhandbuch: Fenster nach einem Versionswechsel
- Entwicklerdoku: erweiterte Importregel fuer @/lib/changelog, Versionsquelle,
  Endpunkte, Spalte, Folge fuer die Freigabe
- Kopfkommentare changelog.ts und next.config.ts angepasst

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -4,6 +4,10 @@ Diese Liste beschreibt in einfachen Worten, was sich von Version zu Version an T
 
 ## Unveröffentlicht
 
+### Neu
+
+- Nach einem Versionswechsel zeigt Tessera bei Ihrer ersten Anmeldung ein Fenster mit den wichtigsten Änderungen der neuen Version – neue Funktionen, Verbesserungen und behobene Fehler. Haben Sie mehrere Versionen verpasst, erscheinen die drei neuesten. „Verstanden“ schließt das Fenster; es erscheint erst mit der nächsten Version wieder, im Browser wie in der Desktop-App. Die vollständige Liste finden Sie weiterhin unter „Was ist neu“.
+
 ## 1.4.0 – 2026-09-25
 
 ### Neu

apps/web/next.config.ts

@@ -7,8 +7,10 @@ import createNextIntlPlugin from 'next-intl/plugin';
 // dem Wurzelverzeichnis wird hier gelesen und als `env.TESSERA_CHANGELOG_MD`
 // abgelegt. Next.js ersetzt `process.env.TESSERA_CHANGELOG_MD` fuer webpack UND
 // Turbopack ueber denselben Define-Mechanismus. Der Text bleibt nur im
-// Server-Bundle, weil ausschliesslich die Server-Seite (changelog/page.tsx)
+// Server-Bundle, weil ausschliesslich Server-Code `@/lib/changelog` importiert:
-// `@/lib/changelog` importiert — Importdisziplin, kein Client-Chunk.
+// die Server-Seite (changelog/page.tsx) und die 'use server'-Datei
+// lib/release-notice-actions.ts (quick-260925-bow) — Importdisziplin, kein
+// Client-Chunk.
 
 const withNextIntl = createNextIntlPlugin('./src/i18n/request.ts');
 

apps/web/src/lib/changelog.ts

@@ -5,9 +5,11 @@ import type { AppChannel } from './app-version';
  *
  * Quelle ist CHANGELOG.md im Wurzelverzeichnis; `apps/web/next.config.ts` liest
  * die Datei zur Bauzeit und legt den Text als `env.TESSERA_CHANGELOG_MD` ab.
- * Dieses Modul darf NUR von der Server-Seite (`app/(portal)/changelog/page.tsx`)
+ * Dieses Modul darf NUR von Server-Code importiert werden — der Server-Seite
- * importiert werden — sonst landet der Text in oeffentlich abrufbaren
+ * (`app/(portal)/changelog/page.tsx`) und der `'use server'`-Datei
- * Client-Chunks unter /_next/static.
+ * `release-notice-actions.ts` ("Was ist neu"-Fenster, quick-260925-bow), nie
+ * von Client-Komponenten und auch nicht von `release-notes.ts` — sonst landet
+ * der Text in oeffentlich abrufbaren Client-Chunks unter /_next/static.
  *
  * Kanalregel (`filterChangelogForChannel`): auf `live` fehlt der Abschnitt
  * "Unveröffentlicht" vollstaendig; auf `beta` und `dev` bleibt er und traegt

docs/anleitung-anwender.md

@@ -272,6 +272,10 @@ Ein Klick auf die Versionsnummer ganz unten in der Seitenleiste öffnet die Seit
 
 Auf dem Live-System sehen Sie nur freigegebene Versionen. Auf der Beta erscheint zusätzlich der Abschnitt **Noch nicht freigegeben (Beta)** mit einem gelben Hinweis: Diese Punkte sind in der Beta bereits enthalten, aber noch nicht als Version freigegeben.
 
+**Fenster nach einem Versionswechsel:** Wenn Tessera auf eine neue Version aktualisiert wurde, erscheint bei Ihrer ersten Anmeldung danach einmal ein Fenster **Neu in Version …**. Es zeigt die für Sie wichtigen Änderungen, gegliedert in **Neu**, **Verbessert** und **Behoben**. Haben Sie mehrere Versionen verpasst, sehen Sie höchstens die drei neuesten; ein Satz im Fenster nennt dann, wie viele ältere Versionen es noch gibt. Unten führt der Link **Alle Änderungen ansehen** zur vollständigen Seite **Was ist neu**.
+
+Sie schließen das Fenster mit **Verstanden**, mit dem Kreuz oben rechts, mit der Escape-Taste oder mit einem Klick neben das Fenster. Tessera merkt sich das für Ihr Konto: Das Fenster erscheint pro Version nur einmal – auch in der Desktop-App nicht noch einmal – und erst mit der nächsten Version wieder. Neu angelegte Konten sehen das Fenster erst ab der nächsten Version. Punkte, die auf der Beta unter **Noch nicht freigegeben (Beta)** stehen, kommen in diesem Fenster nicht vor; sie erscheinen dort erst, wenn die Version freigegeben ist.
+
 ## Häufige Stolpersteine
 
 - **Die Anmeldung schlägt fehl, obwohl Passwort und E-Mail stimmen.** Prüfen Sie, ob Sie im Feld „Benutzername" tatsächlich Ihren Benutzernamen eingegeben haben — nicht Ihre E-Mail-Adresse. Das ist mit Abstand der häufigste Grund für eine scheinbar kaputte Anmeldung.

docs/anleitung-entwicklung.md

@@ -645,13 +645,38 @@ keine Commit-Kürzel, keine unerklärten Fachbegriffe. Bei der Freigabe wird der
 Betriebshandbuch Kapitel 9). Die Seite „Was ist neu“ (`apps/web/src/app/(portal)/changelog/page.tsx`)
 liest den Text zur Bauzeit aus `env.TESSERA_CHANGELOG_MD`, das `apps/web/next.config.ts` aus der
 Datei befüllt — deshalb steht `COPY CHANGELOG.md ./` im Web-Dockerfile und `!CHANGELOG.md` als
-Ausnahme in `.dockerignore`. Nur `page.tsx` darf `@/lib/changelog` importieren, damit der Text im
+Ausnahme in `.dockerignore`. Nur Server-Code darf `@/lib/changelog` importieren: `page.tsx` und die
-Server-Bundle bleibt und nicht in öffentlich abrufbare Client-Chunks gelangt. Die Kanalregel (Live
+`'use server'`-Datei `apps/web/src/lib/release-notice-actions.ts` — nie eine Client-Komponente, auch
+nicht `apps/web/src/lib/release-notes.ts` (dessen Typen nutzen Client-Komponenten). So bleibt der
+Text im Server-Bundle und gelangt nicht in öffentlich abrufbare Client-Chunks. Die Kanalregel (Live
 ohne „Unveröffentlicht“, Beta/Entwicklung mit „Noch nicht freigegeben (Beta)“) liegt in
 `filterChangelogForChannel` (`apps/web/src/lib/changelog.ts`) mit Tests. Beim Tag `vX.Y.Z`
 schneidet `.gitea/scripts/publish-release.sh` den Abschnitt der Version heraus und legt daraus den
 Gitea-Release an — fehlt der Abschnitt, bricht dieser CI-Schritt mit Exit 1 ab.
 
+**„Was ist neu“-Fenster nach einem Versionswechsel (quick-260925-bow):** Beim ersten Laden des
+Portal-Rahmens nach einem Versionswechsel zeigt `ReleaseNoticeHost` (in `AppShell`, also nie auf
+der Anmeldeseite; nicht auf `/change-password`) einmal ein Fenster mit den Gruppen Neu / Geändert
+(angezeigt als „Verbessert“) / Behoben der verpassten Versionen, höchstens drei, neueste zuerst.
+Einzige Quelle der laufenden Version ist `APP_VERSION` der API, gelesen über `getRunningRelease()`
+in `apps/api/src/health/app-version.ts` — nicht `NEXT_PUBLIC_APP_VERSION` des Webs. Grund: der
+LDAP-Abgleich (Zeitplan) und der Erst-Administrator (API-Start) legen Benutzer ohne jede
+Web-Anfrage an und tragen dabei die laufende Version ein; ebenso prüft der Merk-Endpunkt gegen
+diesen Wert. Endpunkte: `GET /users/me/release-notice` liefert `currentRelease` und den gemerkten
+Stand; `POST /users/me/release-seen` mit `{ version }` nimmt nur die kanonische Form `X.Y.Z` an,
+die nicht über der laufenden Version liegt, senkt einen gemerkten Stand nie ab und schreibt
+ausschließlich die eigene Zeile (`forTenant()`, `where: { id: currentUser.id }`). Gemerkt wird erst
+beim Schließen, nie beim Öffnen. Spalte `User.lastSeenReleaseVersion`: `null` = Bestandsbenutzer,
+dann zeigt das Fenster nur die laufende Version; `UserService.create()` und der Admin-Seed tragen
+bei der Anlage die laufende Version ein. `parseReleaseVersion`/`compareReleaseVersions` stehen einmal
+in `packages/shared/src/index.ts` (Laufzeit-Import in API und Web). Die Auswahl der Abschnitte
+macht `selectReleaseNotice` in `apps/web/src/lib/release-notes.ts`. Folge für die Freigabe: erst ein
+Tag `vX.Y.Z` (auf der Beta dessen Describe-Stand `vX.Y.Z-N-g<sha>`, gekürzt auf `X.Y.Z`) löst das
+Fenster aus; Punkte unter „Unveröffentlicht“ erscheinen darin nie. Lokal steht `APP_VERSION` auf
+`dev` — dann erscheint nie ein Fenster; zum Ausprobieren beim Bau `--build-arg APP_VERSION=1.4.0`
+setzen. Fehlt der Abschnitt der laufenden Version in der Änderungsliste des Web-Abbilds, entsteht
+kein Fenster und nichts wird gemerkt.
+
 **i18n — Schlüsselparität zwischen de.json und en.json:** Jeder benutzersichtbare Text gehört in
 beide Sprachdateien, `apps/web/src/messages/de.json` und `apps/web/src/messages/en.json`. Ein
 strukturelle Wächter-Test, `apps/web/src/messages/tenderRadar-parity.spec.ts`, prüft für den