"feat: Added debug server and related components for improved development experience"

2025-05-23 07:24:51 +02:00
parent d457a8d86b
commit 9f6219832c
189 changed files with 35730 additions and 133 deletions
--- a/frontend/docs/Datenbank.md
+++ b/frontend/docs/Datenbank.md
@@ -0,0 +1,153 @@
+# **Datenbank und Analytik-Funktionen**
+
+Dieser Abschnitt konzentriert sich auf die Struktur der Datenbank sowie die Analyse- und Prognosefunktionen, die im Projekt verwendet werden.
+
+---
+
+## **1. Datenbankstruktur**
+
+Das Datenbankschema wurde mit **Drizzle ORM** definiert und basiert auf SQLite. Die wichtigsten Tabellen und ihre Zwecke sind:
+
+### **1.1. Tabellenübersicht**
+
+#### **`user`**
+- Speichert Benutzerinformationen.
+- Enthält Rollen wie „admin“ oder „guest“ zur Verwaltung von Berechtigungen.
+
+| **Feld**         | **Typ**    | **Beschreibung**                           |
+|-------------------|------------|-------------------------------------------|
+| `id`             | `text`     | Eindeutige ID des Benutzers.              |
+| `github_id`      | `integer`  | ID des Benutzers aus dem OAuth-Dienst.    |
+| `name`           | `text`     | Benutzername.                             |
+| `displayName`    | `text`     | Angezeigter Name.                         |
+| `email`          | `text`     | E-Mail-Adresse.                           |
+| `role`           | `text`     | Benutzerrolle, Standardwert: „guest“.     |
+
+---
+
+#### **`printer`**
+- Beschreibt verfügbare Drucker und deren Status.
+
+| **Feld**         | **Typ**    | **Beschreibung**                           |
+|-------------------|------------|-------------------------------------------|
+| `id`             | `text`     | Eindeutige Drucker-ID.                    |
+| `name`           | `text`     | Name des Druckers.                        |
+| `description`    | `text`     | Beschreibung oder Spezifikationen.        |
+| `status`         | `integer`  | Betriebsstatus (0 = inaktiv, 1 = aktiv).  |
+
+---
+
+#### **`printJob`**
+- Speichert Informationen zu Druckaufträgen.
+
+| **Feld**             | **Typ**       | **Beschreibung**                                       |
+|-----------------------|---------------|-------------------------------------------------------|
+| `id`                 | `text`        | Eindeutige Auftrags-ID.                               |
+| `printerId`          | `text`        | Verweis auf die ID des Druckers.                     |
+| `userId`             | `text`        | Verweis auf die ID des Benutzers.                    |
+| `startAt`            | `integer`     | Startzeit des Druckauftrags (Unix-Timestamp).        |
+| `durationInMinutes`  | `integer`     | Dauer des Druckauftrags in Minuten.                  |
+| `comments`           | `text`        | Zusätzliche Kommentare.                              |
+| `aborted`            | `integer`     | 1 = Abgebrochen, 0 = Erfolgreich abgeschlossen.      |
+| `abortReason`        | `text`        | Grund für den Abbruch (falls zutreffend).            |
+
+---
+
+#### **`session`**
+- Verwaltert Benutzer-Sitzungen und Ablaufzeiten.
+
+| **Feld**         | **Typ**    | **Beschreibung**                           |
+|-------------------|------------|-------------------------------------------|
+| `id`             | `text`     | Eindeutige Sitzungs-ID.                   |
+| `user_id`        | `text`     | Verweis auf die ID des Benutzers.         |
+| `expires_at`     | `integer`  | Zeitpunkt, wann die Sitzung abläuft.      |
+
+---
+
+### **1.2. Relationen**
+- `printer` → `printJob`: Druckaufträge sind an spezifische Drucker gebunden.
+- `user` → `printJob`: Druckaufträge werden Benutzern zugewiesen.
+- `user` → `session`: Sitzungen verknüpfen Benutzer mit Login-Details.
+
+---
+
+## **2. Analytik-Funktionen**
+
+Das Projekt bietet verschiedene Analytik- und Prognosetools, um die Druckernutzung und Fehler zu überwachen.
+
+### **2.1. Fehlerratenanalyse**
+- Funktion: `calculatePrinterErrorRate` (in `src/utils/analytics/error-rate.ts`).
+- Berechnet die prozentuale Fehlerrate für jeden Drucker basierend auf abgebrochenen Aufträgen.
+
+Beispielausgabe:
+```json
+[
+  { "name": "Drucker 1", "errorRate": 5.2 },
+  { "name": "Drucker 2", "errorRate": 3.7 }
+]
+```
+
+---
+
+### **2.2. Abbruchgründe**
+- Funktion: `calculateAbortReasonsCount` (in `src/utils/analytics/errors.ts`).
+- Zählt die Häufigkeit der Abbruchgründe aus der Tabelle `printJob`.
+
+Beispielausgabe:
+```json
+[
+  { "abortReason": "Materialmangel", "count": 10 },
+  { "abortReason": "Düsenverstopfung", "count": 7 }
+]
+```
+
+---
+
+### **2.3. Nutzung und Prognosen**
+#### Nutzung:
+- Funktion: `calculatePrinterUtilization` (in `src/utils/analytics/utilization.ts`).
+- Berechnet die Nutzung der Drucker in Prozent.
+
+Beispielausgabe:
+```json
+{ "printerId": "1", "utilizationPercentage": 85 }
+```
+
+#### Prognosen:
+- Funktion: `forecastPrinterUsage` (in `src/utils/analytics/forecast.ts`).
+- Nutzt historische Daten, um die erwartete Druckernutzung für kommende Tage/Wochen zu schätzen.
+
+Beispielausgabe:
+```json
+[
+  { "day": 1, "usageMinutes": 300 },
+  { "day": 2, "usageMinutes": 200 }
+]
+```
+
+---
+
+### **2.4. Druckvolumen**
+- Funktion: `calculatePrintVolumes` (in `src/utils/analytics/volume.ts`).
+- Vergleicht die Anzahl der abgeschlossenen Druckaufträge für heute, diese Woche und diesen Monat.
+
+Beispielausgabe:
+```json
+{
+  "today": 15,
+  "thisWeek": 90,
+  "thisMonth": 300
+}
+```
+
+---
+
+## **3. Datenbankinitialisierung**
+Die Datenbank wird über Skripte in der `package.json` initialisiert:
+```bash
+pnpm run db:clean       # Datenbank und Migrationsordner löschen
+pnpm run db:generate    # Neues Schema generieren
+pnpm run db:migrate     # Migrationsskripte ausführen
+```
+
+Nächster Schritt: [=> Bereitstellungsdetails und Best Practices](./Bereitstellungsdetails.md)