# MYP Backend API-Dokumentation

Dieses Dokument beschreibt detailliert die API-Endpunkte des MYP (Manage Your Printer) Backend-Systems.

## Basis-URL

Die Basis-URL für alle API-Anfragen ist: `http://localhost:5000` (Entwicklungsumgebung) oder die URL, unter der die Anwendung gehostet wird.

## Authentifizierung

Die meisten Endpunkte erfordern eine Authentifizierung. Diese erfolgt über Cookies/Sessions, die bei der Anmeldung erstellt werden. Die Session wird für 7 Tage gespeichert.

### Benutzerregistrierung

**Endpunkt:** `POST /auth/register`

**Beschreibung:** Registriert einen neuen Benutzer im System.

**Request-Body:**
```json
{
  "username": "string", // Erforderlich
  "password": "string", // Erforderlich
  "displayName": "string", // Optional (Standard: username)
  "email": "string" // Optional
}
```

**Erfolgsantwort:**
```json
{
  "message": "Registrierung erfolgreich!",
  "user": {
    "id": "string",
    "username": "string",
    "displayName": "string",
    "email": "string",
    "role": "string"
  }
}
```

**Fehlerantwort:**
```json
{
  "message": "Benutzername bereits vergeben!"
}
```

### Benutzeranmeldung

**Endpunkt:** `POST /auth/login`

**Beschreibung:** Meldet einen Benutzer an und erstellt eine Session.

**Request-Body:**
```json
{
  "username": "string", // Erforderlich
  "password": "string" // Erforderlich
}
```

**Erfolgsantwort:**
```json
{
  "message": "Anmeldung erfolgreich!",
  "user": {
    "id": "string",
    "username": "string",
    "displayName": "string",
    "email": "string",
    "role": "string"
  }
}
```

**Fehlerantwort:**
```json
{
  "message": "Ungültiger Benutzername oder Passwort!"
}
```

### Initialer Administrator

**Endpunkt:** `POST /api/create-initial-admin`

**Beschreibung:** Erstellt einen initialen Admin-Benutzer, falls noch keiner existiert.

**Request-Body:**
```json
{
  "username": "string", // Erforderlich
  "password": "string", // Erforderlich
  "displayName": "string", // Optional (Standard: username)
  "email": "string" // Optional
}
```

**Erfolgsantwort:**
```json
{
  "message": "Administrator wurde erfolgreich erstellt!",
  "user": {
    "id": "string",
    "username": "string",
    "displayName": "string",
    "email": "string",
    "role": "string"
  }
}
```

**Fehlerantwort:**
```json
{
  "message": "Es existiert bereits ein Administrator!"
}
```

## Benutzer-Endpunkte

### Alle Benutzer abrufen (Admin)

**Endpunkt:** `GET /api/users`

**Beschreibung:** Gibt eine Liste aller Benutzer zurück.

**Erforderliche Rechte:** Admin

**Erfolgsantwort:**
```json
[
  {
    "id": 1,
    "username": "string",
    "email": "string",
    "role": "string"
  }
]
```

### Benutzer abrufen (Admin)

**Endpunkt:** `GET /api/users/{userId}`

**Beschreibung:** Gibt die Details eines bestimmten Benutzers zurück.

**Erforderliche Rechte:** Admin

**Erfolgsantwort:**
```json
{
  "id": 1,
  "username": "string",
  "email": "string",
  "role": "string"
}
```

**Fehlerantwort:**
```json
{
  "message": "Nicht gefunden!"
}
```

### Benutzer aktualisieren (Admin)

**Endpunkt:** `PUT /api/users/{userId}`

**Beschreibung:** Aktualisiert die Daten eines Benutzers.

**Erforderliche Rechte:** Admin

**Request-Body:**
```json
{
  "username": "string",
  "email": "string",
  "password": "string",
  "role": "string"
}
```

**Erfolgsantwort:**
```json
{
  "id": 1,
  "username": "string",
  "email": "string",
  "role": "string"
}
```

**Fehlerantwort:**
```json
{
  "message": "Benutzername bereits vergeben!"
}
```

### Benutzer löschen (Admin)

**Endpunkt:** `DELETE /api/users/{userId}`

**Beschreibung:** Löscht einen Benutzer.

**Erforderliche Rechte:** Admin

**Erfolgsantwort:**
```json
{
  "message": "Benutzer gelöscht!"
}
```

## Drucker-Endpunkte

### Alle Drucker abrufen

**Endpunkt:** `GET /api/printers`

**Beschreibung:** Gibt eine Liste aller Drucker (Steckdosen) zurück.

**Erfolgsantwort:**
```json
[
  {
    "id": "uuid-string",
    "name": "string",
    "description": "string",
    "status": 0, // 0 = available, 1 = busy
    "latestJob": {
      // Job-Objekt oder null, wenn kein aktiver Job
    }
  }
]
```

### Drucker hinzufügen (Admin)

**Endpunkt:** `POST /api/printers`

**Beschreibung:** Fügt einen neuen Drucker hinzu.

**Erforderliche Rechte:** Admin

**Request-Body:**
```json
{
  "name": "string",
  "description": "string",
  "ipAddress": "string" // IP-Adresse der Tapo-Steckdose
}
```

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "name": "string",
  "description": "string",
  "status": 0, // 0 = available, 1 = busy
  "latestJob": null
}
```

### Drucker abrufen

**Endpunkt:** `GET /api/printers/{printerId}`

**Beschreibung:** Gibt die Details eines bestimmten Druckers zurück.

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "name": "string",
  "description": "string",
  "status": 0, // 0 = available, 1 = busy
  "latestJob": {
    // Job-Objekt oder null, wenn kein aktiver Job
  }
}
```

**Fehlerantwort:**
```json
{
  "message": "Nicht gefunden!"
}
```

### Drucker aktualisieren (Admin)

**Endpunkt:** `PUT /api/printers/{printerId}`

**Beschreibung:** Aktualisiert die Daten eines Druckers.

**Erforderliche Rechte:** Admin

**Request-Body:**
```json
{
  "name": "string",
  "description": "string",
  "ipAddress": "string", // IP-Adresse der Tapo-Steckdose
  "status": 0 // 0 = available, 1 = busy
}
```

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "name": "string",
  "description": "string",
  "status": 0, // 0 = available, 1 = busy
  "latestJob": {
    // Job-Objekt oder null, wenn kein aktiver Job
  }
}
```

### Drucker löschen (Admin)

**Endpunkt:** `DELETE /api/printers/{printerId}`

**Beschreibung:** Löscht einen Drucker.

**Erforderliche Rechte:** Admin

**Erfolgsantwort:**
```json
{
  "message": "Drucker gelöscht!"
}
```

## Druckauftrags-Endpunkte

### Alle Druckaufträge abrufen

**Endpunkt:** `GET /api/jobs`

**Beschreibung:** Gibt eine Liste aller Druckaufträge zurück (für Admins) oder der eigenen Druckaufträge (für Benutzer).

**Erfolgsantwort:**
```json
[
  {
    "id": "uuid-string",
    "socketId": "uuid-string",
    "userId": "uuid-string",
    "startAt": "string (ISO 8601)",
    "durationInMinutes": 60,
    "comments": "string",
    "aborted": false,
    "abortReason": null,
    "remainingMinutes": 30
  }
]
```

### Druckauftrag erstellen

**Endpunkt:** `POST /api/jobs`

**Beschreibung:** Erstellt einen neuen Druckauftrag.

**Request-Body:**
```json
{
  "printerId": "uuid-string",
  "durationInMinutes": 60,
  "comments": "string"
}
```

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 60,
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 60
}
```

**Fehlerantwort:**
```json
{
  "message": "Drucker ist nicht verfügbar!"
}
```

### Druckauftrag abrufen

**Endpunkt:** `GET /api/jobs/{jobId}`

**Beschreibung:** Gibt die Details eines bestimmten Druckauftrags zurück.

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 60,
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 30
}
```

**Fehlerantwort:**
```json
{
  "message": "Nicht gefunden!"
}
```

### Druckauftrag Kommentare aktualisieren

**Endpunkt:** `PUT /api/jobs/{jobId}/comments`

**Beschreibung:** Aktualisiert die Kommentare eines Druckauftrags.

**Request-Body:**
```json
{
  "comments": "string"
}
```

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 60,
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 30
}
```

### Druckauftrag abbrechen

**Endpunkt:** `POST /api/jobs/{jobId}/abort`

**Beschreibung:** Bricht einen laufenden Druckauftrag ab.

**Request-Body:**
```json
{
  "reason": "string" // Optional
}
```

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 60,
  "comments": "string",
  "aborted": true,
  "abortReason": "string",
  "remainingMinutes": 0
}
```

### Druckauftrag vorzeitig beenden

**Endpunkt:** `POST /api/jobs/{jobId}/finish`

**Beschreibung:** Beendet einen laufenden Druckauftrag vorzeitig.

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 45, // Tatsächliche Dauer bis zum Beenden
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 0
}
```

### Druckauftrag verlängern

**Endpunkt:** `POST /api/jobs/{jobId}/extend`

**Beschreibung:** Verlängert die Laufzeit eines Druckauftrags.

**Request-Body:**
```json
{
  "minutes": 30, // Zusätzliche Minuten
  "hours": 0 // Zusätzliche Stunden (optional)
}
```

**Erfolgsantwort:**
```json
{
  "id": "uuid-string",
  "socketId": "uuid-string",
  "userId": "uuid-string",
  "startAt": "string (ISO 8601)",
  "durationInMinutes": 90, // Aktualisierte Gesamtdauer
  "comments": "string",
  "aborted": false,
  "abortReason": null,
  "remainingMinutes": 60
}
```

### Druckauftrag löschen

**Endpunkt:** `DELETE /api/jobs/{jobId}`

**Beschreibung:** Löscht einen Druckauftrag.

**Erfolgsantwort:**
```json
{
  "message": "Druckauftrag gelöscht!"
}
```

### Verbleibende Zeit eines Druckauftrags abrufen

**Endpunkt:** `GET /api/job/{jobId}/remaining-time`

**Beschreibung:** Gibt die verbleibende Zeit eines aktiven Druckauftrags in Minuten zurück.

**Erfolgsantwort:**
```json
{
  "remaining_minutes": 30,
  "job_status": "active", // active, completed
  "socket_status": "busy" // busy, available
}
```

### Status eines Druckauftrags abrufen

**Endpunkt:** `GET /api/job/{jobId}/status`

**Beschreibung:** Gibt detaillierte Statusinformationen zu einem Druckauftrag zurück.

**Erfolgsantwort:**
```json
{
  "job": {
    "id": "uuid-string",
    "socketId": "uuid-string",
    "userId": "uuid-string",
    "startAt": "string (ISO 8601)",
    "durationInMinutes": 60,
    "comments": "string",
    "aborted": false,
    "abortReason": null,
    "remainingMinutes": 30
  },
  "status": "active", // active, completed, aborted
  "socketStatus": "busy", // busy, available
  "remainingMinutes": 30
}
```

## Statistik-Endpunkte

### Systemstatistiken abrufen (Admin)

**Endpunkt:** `GET /api/stats`

**Beschreibung:** Gibt Statistiken zu Druckern, Aufträgen und Benutzern zurück.

**Erforderliche Rechte:** Admin

**Erfolgsantwort:**
```json
{
  "printers": {
    "total": 10,
    "available": 5,
    "utilization_rate": 0.5
  },
  "jobs": {
    "total": 100,
    "active": 5,
    "completed": 90,
    "avg_duration": 120
  },
  "users": {
    "total": 50
  }
}
```

## Test-Endpunkt

### API-Test

**Endpunkt:** `GET /api/test`

**Beschreibung:** Testet, ob die API funktioniert.

**Erfolgsantwort:**
```json
{
  "message": "MYP Backend API funktioniert!"
}
```

## Fehlercodes

| Statuscode | Beschreibung                 |
|------------|-----------------------------|
| 200        | OK - Anfrage erfolgreich     |
| 201        | Created - Ressource erstellt |
| 400        | Bad Request - Ungültige Anfrage |
| 401        | Unauthorized - Authentifizierung erforderlich |
| 403        | Forbidden - Unzureichende Rechte |
| 404        | Not Found - Ressource nicht gefunden |
| 500        | Internal Server Error - Serverfehler |