feat(260924-m4n): Bilderrahmen Stufe 2 - alte Bildspalte data entfernt, storagePath Pflicht

- Migration 20260924120000_dashboard_image_drop_data: Schutzpruefung
  (bricht ab, solange eine Zeile ohne storagePath existiert; row_security
  aus, damit ein Eigentuemer ohne BYPASSRLS nicht still 0 Zeilen sieht),
  dann NOT NULL, DROP COLUMN data, DROP POLICY system_read_policy
- Dienst: Bootstrap-Umzug samt forSystem() und Selbstheilung aus data
  entfernt; Upload vergibt die UUID selbst, Zeile gleich mit Pfad
- FORSYSTEM_ALLOWED_CALL_SITES, Tests, Zugriffsklassifikation (per
  Gate-Schleife gemessen: 61/213/6) nachgezogen
- Betriebshandbuch Kap. 4: Hinweis und Wiederherstellungsweg bei Abbruch
- Todo 2026-09-22 nach completed/

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

apps/api/src/dashboard/dashboard-images.service.ts

@@ -4,12 +4,12 @@ import {
   InternalServerErrorException,
   Logger,
   NotFoundException,
-  type OnApplicationBootstrap,
 } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import type { AuthUser, UploadedFileLike } from '../auth/types/auth-user';
-import { forSystem, forTenant } from '../prisma/prisma-tenant.extension';
+import { forTenant } from '../prisma/prisma-tenant.extension';
 import { PrismaService } from '../prisma/prisma.service';
 import {
   DASHBOARD_IMAGE_MAX_COUNT,
@@ -46,13 +46,22 @@ import {
  * (T-HK4-02); das Volume haengt in keinem Webserver.
  *
  * HALBE ZUSTAENDE (T-HK4-04, bewusst benannt): beim Upload entsteht ZUERST
- * die Zeile (erst danach steht die UUID fest), dann die Datei; scheitert
- * das Schreiben, wird die Zeile wieder geloescht und 500 geworfen. Beim
+ * die Zeile (mit der vom Dienst vergebenen UUID und dem daraus gebildeten
+ * Pfad), dann die Datei; scheitert das Schreiben, wird die Zeile wieder
+ * geloescht und 500 geworfen. Beim
  * Loeschen faellt ZUERST die Zeile, ein Fehler beim Entfernen der Datei
  * wird protokolliert und geschluckt — eine Dateileiche ist harmloser als
  * eine haengende Loeschung. Fehlt die Datei beim Lesen, ist die Antwort
  * 404 und die Kachel zeigt „Bild nicht verfügbar".
  *
+ * STUFE 2 DER UMSTELLUNG (quick-260924-m4n, Migration
+ * 20260924120000_dashboard_image_drop_data): die alte Spalte `data` ist
+ * weg, `storagePath` ist Pflicht. Mit ihr sind der Bootstrap-Umzug
+ * (`onApplicationBootstrap()` mit `forSystem()`) und die Selbstheilung aus
+ * `data` in `getBytes` entfallen — der Umzug hatte auf allen Servern seine
+ * Arbeit getan, die Migration bricht ab, falls doch noch eine Zeile ohne
+ * Pfad existiert.
+ *
  * Besitz: ein Bild gehoert dem hochladenden Benutzer (gleicher Mandant UND
  * gleicher Benutzer). Die Besitzpruefung in `getBytes`/`remove` (Zeile
  * holen, `userId` UND `tenantId` gegen den Sitzungsnachweis vergleichen,
@@ -145,6 +154,33 @@ function relativeStoragePath(userId: string, id: string, extension: string): str
   return `${STORAGE_PREFIX}${userId}/${id}.${extension}`;
 }
 
+/**
+ * Servergenerierter relativer Pfad fuer ein neues Bild: UUID der Zeile plus
+ * Endung aus dem ERKANNTEN Typ (T-HK4-01).
+ */
+function storagePathFor(userId: string, id: string, mimeType: string): string {
+  const extension = extensionFor(mimeType);
+  if (extension === null) {
+    // detectImageMime liefert nur die vier bekannten Typen; ein anderer
+    // Wert hier waere ein Programmierfehler, kein Benutzerfehler.
+    throw new InternalServerErrorException(`Unbekannter Bildtyp '${mimeType}'`);
+  }
+  return relativeStoragePath(userId, id, extension);
+}
+
+/**
+ * Schreibt die Bytes an den servergenerierten Ort. Der Ordner je Benutzer
+ * entsteht dabei (`recursive: true`).
+ */
+async function writeImageFile(storagePath: string, bytes: Uint8Array): Promise<void> {
+  const absolute = absoluteImagePath(storagePath);
+  if (absolute === null) {
+    throw new Error(`Ungueltiger Ablageort '${storagePath}'`);
+  }
+  await fs.mkdir(path.dirname(absolute), { recursive: true });
+  await fs.writeFile(absolute, bytes);
+}
+
 /**
  * Wandelt den in der Zeile gespeicherten Pfad in einen absoluten Pfad im
  * Bilderverzeichnis um — und gibt `null` zurueck, sobald der Wert nicht
@@ -162,69 +198,11 @@ function absoluteImagePath(storagePath: string): string | null {
 }
 
 @Injectable()
-export class DashboardImagesService implements OnApplicationBootstrap {
+export class DashboardImagesService {
   private readonly logger = new Logger(DashboardImagesService.name);
 
   constructor(private readonly prisma: PrismaService) {}
 
-  /**
-   * Einmaliger Umzug der Bestandsbilder beim Start (T-HK4-03), damit der
-   * Betreiber nichts von Hand ausfuehren muss.
-   *
-   * ZWEISTUFIG, und deshalb steht die Spalte `data` noch im Schema: die
-   * SQL-Migration 20260922120000 legt nur `storagePath` an und macht `data`
-   * NULLbar; `migrate deploy` laeuft VOR dem Anwendungsstart, ein sofortiges
-   * DROP haette die Bytes vernichtet, bevor dieser Umzug sie lesen konnte.
-   * Die DROP-Migration 20260922120100 kommt erst, wenn alpha UND live
-   * einmal mit einer Version >= dieser gelaufen sind (vorgemerkt in
-   * `.planning/todos/pending/`).
-   *
-   * GELESEN WIRD SYSTEMGEBUNDEN (`forSystem()`, Muster
-   * `DkvService.loadActiveConfigsForScheduler()`): der Umzug betrifft alle
-   * Mandanten, ein Startpfad hat keinen Mandanten im Ruecken. Geschrieben
-   * wird je Zeile MANDANTENGEBUNDEN (`forTenant()` mit Mandant UND Benutzer
-   * dieser Zeile) — unter Systemkontext ist nur Lesen geoeffnet
-   * (`system_read_policy ... FOR SELECT`, fuer `DashboardImage` angelegt in
-   * 20260922120000). Einmal-lesen-viele-bedienen, genau wie beim
-   * DKV-Planer.
-   *
-   * Wiederholbar: die Abfrage nimmt nur Zeilen ohne `storagePath`, ein
-   * zweiter Lauf findet nichts mehr. Eine einzelne fehlgeschlagene Zeile
-   * wird protokolliert und haelt den Start nicht auf.
-   */
-  async onApplicationBootstrap(): Promise<void> {
-    const systemPrisma = forSystem(this.prisma);
-    const pending = await systemPrisma.dashboardImage.findMany({
-      where: { storagePath: null },
-      select: { id: true, userId: true, tenantId: true, mimeType: true, data: true },
-      orderBy: { createdAt: 'asc' },
-    });
-
-    let moved = 0;
-    for (const row of pending) {
-      if (row.data === null) continue;
-      try {
-        const storagePath = await this.writeImageFile(row.userId, row.id, row.mimeType, row.data);
-        const tenantPrisma = forTenant(this.prisma, row.tenantId, row.userId);
-        await tenantPrisma.dashboardImage.update({
-          where: { id: row.id },
-          data: { storagePath },
-        });
-        moved += 1;
-      } catch (error) {
-        this.logger.error(
-          `Bilderrahmen-Bild ${row.id} konnte nicht auf die Festplatte umgezogen werden: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-      }
-    }
-
-    if (moved > 0) {
-      this.logger.log(`${moved} Bilderrahmen-Bilder auf die Festplatte umgezogen`);
-    }
-  }
-
   /** Eigene Bilder, aelteste zuerst, nur Metadaten. */
   async list(userId: string, tenantId: string): Promise<DashboardImageMeta[]> {
     const tenantPrisma = forTenant(this.prisma, tenantId, userId);
@@ -240,10 +218,12 @@ export class DashboardImagesService implements OnApplicationBootstrap {
    * begrenzt, gespeichert wird der erkannte Typ — die Bytes auf der Platte,
    * die Zeile haelt den Pfad.
    *
-   * Reihenfolge (T-HK4-04): Zeile zuerst, weil der Dateiname die UUID der
-   * Zeile IST. Scheitert danach das Schreiben oder das Nachtragen des
-   * Pfades, wird die Zeile wieder geloescht — lieber gar kein Bild als eine
-   * Zeile ohne Datei.
+   * Reihenfolge (T-HK4-04): die UUID vergibt der Dienst selbst
+   * (`randomUUID()`, dieselbe Form wie Prismas `@default(uuid())`), damit
+   * die Zeile ihren Pfad gleich beim Anlegen traegt — `storagePath` ist seit
+   * Stufe 2 Pflicht. Zeile zuerst, dann die Datei; scheitert das Schreiben,
+   * wird die Zeile wieder geloescht — lieber gar kein Bild als eine Zeile
+   * ohne Datei.
    */
   async upload(user: AuthUser, file: UploadedFileLike | undefined): Promise<DashboardImageMeta> {
     if (!file) {
@@ -265,8 +245,12 @@ export class DashboardImagesService implements OnApplicationBootstrap {
       );
     }
 
+    const id = randomUUID();
+    const storagePath = storagePathFor(user.id, id, mimeType);
     const created = await tenantPrisma.dashboardImage.create({
       data: {
+        id,
+        storagePath,
         userId: user.id,
         tenantId: user.tenantId,
         originalName: file.originalname.slice(0, ORIGINAL_NAME_MAX),
@@ -277,11 +261,7 @@ export class DashboardImagesService implements OnApplicationBootstrap {
     });
 
     try {
-      const storagePath = await this.writeImageFile(user.id, created.id, mimeType, file.buffer);
-      await tenantPrisma.dashboardImage.update({
-        where: { id: created.id },
-        data: { storagePath },
-      });
+      await writeImageFile(storagePath, file.buffer);
     } catch (error) {
       this.logger.error(
         `Bilderrahmen-Bild ${created.id} konnte nicht gespeichert werden, Zeile wird zurueckgenommen: ${
@@ -297,8 +277,8 @@ export class DashboardImagesService implements OnApplicationBootstrap {
 
   /**
    * Bytes und gespeicherter Typ eines eigenen Bildes; fremd/unbekannt ->
-   * 404. Gelesen wird die Datei, nicht die Zeile — eine Zeile ohne Pfad
-   * (noch nicht umgezogen) und eine fehlende Datei ergeben denselben 404.
+   * 404. Gelesen wird die Datei; ein ungueltiger Pfad und eine fehlende
+   * Datei ergeben denselben 404.
    */
   async getBytes(
     id: string,
@@ -311,7 +291,7 @@ export class DashboardImagesService implements OnApplicationBootstrap {
       throw new NotFoundException(`Image with id '${id}' not found`);
     }
 
-    const absolute = row.storagePath === null ? null : absoluteImagePath(row.storagePath);
+    const absolute = absoluteImagePath(row.storagePath);
     if (absolute === null) {
       this.logger.warn(`Bilderrahmen-Bild ${id} hat keinen gueltigen Ablageort`);
       throw new NotFoundException(`Image with id '${id}' not found`);
@@ -321,26 +301,6 @@ export class DashboardImagesService implements OnApplicationBootstrap {
       const data = await fs.readFile(absolute);
       return { mimeType: row.mimeType, data };
     } catch (error) {
-      // Selbstheilung waehrend der Umstellung (T-HK4-03): fehlt die Datei,
-      // steckt aber noch die alte Spalte `data` in der Zeile, wird die Datei
-      // daraus neu geschrieben und ausgeliefert. Der Fall ist real: ein
-      // `pg_dump` aus der Zeit vor dem Umzug traegt die Bytes noch, das
-      // Volume `user-files` wird getrennt gesichert — wer nur den Abzug
-      // zurueckspielt, haette sonst Zeilen ohne Datei. Nach dem Entfernen der
-      // Spalte (eigenes Todo) faellt dieser Zweig ersatzlos weg.
-      if (row.data !== null) {
-        try {
-          await this.writeImageFile(row.userId, row.id, row.mimeType, row.data);
-          this.logger.log(`Bilderrahmen-Bild ${id} aus der Datenbank wiederhergestellt`);
-          return { mimeType: row.mimeType, data: row.data };
-        } catch (writeError) {
-          this.logger.error(
-            `Bilderrahmen-Bild ${id} konnte nicht wiederhergestellt werden: ${
-              writeError instanceof Error ? writeError.message : String(writeError)
-            }`,
-          );
-        }
-      }
       this.logger.warn(
         `Bilderrahmen-Bild ${id} fehlt im Dateibereich: ${
           error instanceof Error ? error.message : String(error)
@@ -363,7 +323,7 @@ export class DashboardImagesService implements OnApplicationBootstrap {
     }
     await tenantPrisma.dashboardImage.delete({ where: { id } });
 
-    const absolute = row.storagePath === null ? null : absoluteImagePath(row.storagePath);
+    const absolute = absoluteImagePath(row.storagePath);
     if (absolute !== null) {
       try {
         await fs.unlink(absolute);
@@ -378,31 +338,4 @@ export class DashboardImagesService implements OnApplicationBootstrap {
 
     return { id };
   }
-
-  /**
-   * Schreibt die Bytes an den servergenerierten Ort und liefert den
-   * relativen Pfad fuer die Zeile zurueck. Der Ordner je Benutzer entsteht
-   * dabei (`recursive: true`).
-   */
-  private async writeImageFile(
-    userId: string,
-    id: string,
-    mimeType: string,
-    bytes: Uint8Array,
-  ): Promise<string> {
-    const extension = extensionFor(mimeType);
-    if (extension === null) {
-      throw new Error(`Unbekannter Bildtyp '${mimeType}'`);
-    }
-
-    const storagePath = relativeStoragePath(userId, id, extension);
-    const absolute = absoluteImagePath(storagePath);
-    if (absolute === null) {
-      throw new Error(`Ungueltiger Ablageort fuer Bild ${id}`);
-    }
-
-    await fs.mkdir(path.dirname(absolute), { recursive: true });
-    await fs.writeFile(absolute, bytes);
-    return storagePath;
-  }
 }