# API-Dokumentation

## Übersicht

Das Jomblo-Projekt verwendet Next.js API Routes für serverseitige Funktionen wie Webhooks und Authentifizierung.

## Endpunkte

### `/api/stripe/webhook`

Verarbeitet Webhooks von Stripe für Zahlungsereignisse.

- **Methode**: POST
- **Body**: Raw Stripe-Webhook-Payload
- **Headers**: `stripe-signature` für Verifizierung
- **Verarbeitete Ereignisse**:
  - `checkout.session.completed`: Zahlung erfolgreich – Bestellung erfüllen.
  - `checkout.session.async_payment_succeeded`: Asynchrone Zahlung.
  - `checkout.session.expired`: Session abgelaufen.
- **Antwort**: 200 bei Erfolg, 401 bei Signatur-Fehler, 500 bei Fehler.

### `/api/auth/[...nextauth]`

NextAuth.js Route für Authentifizierung.

- **Methoden**: GET, POST
- **Verwendet**: Credentials-Provider für E-Mail/Passwort-Login.
- **Konfiguration**: In `app/api/auth/[...nextauth]/options.ts`.

## Sicherheit

- Webhooks verwenden Signatur-Verifizierung mit `STRIPE_WEBHOOK_SECRET`.
- Auth-Routen sind durch NextAuth geschützt.

## Dashboard Endpoints

Dashboard-Endpunkte erfordern eine aktive Sitzung mit der Rolle `admin`. Alle Dashboard-APIs verwenden das in `lib/api-response.ts` definierte Standardformat für Antworten.

### Übersicht

| Endpunkt | Methoden | Beschreibung |
| :--- | :--- | :--- |
| `/api/dashboard/attributes` | `POST`, `PUT`, `DELETE` | Produktattribute (z.B. Farbe, Größe). |
| `/api/dashboard/brands` | `POST`, `PUT`, `DELETE` | Produktmarken. |
| `/api/dashboard/customers` | `GET`, `POST`, `PUT`, `DELETE` | Kundendaten. |
| `/api/dashboard/eu-responsible-persons` | `POST`, `PUT`, `DELETE` | EU-Bevollmächtigte. |
| `/api/dashboard/manufacturers` | `POST`, `PUT` | Produkthersteller. |
| `/api/dashboard/suppliers` | `POST`, `PUT`, `DELETE` | Produktlieferanten. |
| `/api/dashboard/tax-classes` | `POST`, `PUT`, `DELETE` | Steuerklassen. |
| `/api/dashboard/users` | `GET`, `POST`, `PUT`, `DELETE` | Systembenutzer. |

### `/api/dashboard/users`

Verwaltet administrative Benutzer im System.

- **Methoden**: `GET`, `POST`, `PUT`, `DELETE`
- **Sicherheit**: Admin-Berechtigung erforderlich (`requireAdmin`)

#### `GET` (Benutzer auflisten)

Ruft eine paginierte Liste von Benutzern ab.

- **Query-Parameter**:
  - `page` (optional): Die Seitenzahl (Standard: `1`).
  - `limit` (optional): Anzahl der Benutzer pro Seite (Standard: `10`).
- **Antwort**: `200 OK`
  ```json
  {
    "data": {
      "users": [
        {
          "id": 1,
          "firstName": "Admin",
          "lastName": "User",
          "email": "admin@example.com",
          "role": "admin",
          "customer_id": null,
          "created_at": "...",
          "last_updated_at": "..."
        }
      ],
      "total": 1,
      "pagination": {
        "page": 1,
        "limit": 10,
        "total": 1,
        "totalPages": 1
      }
    },
    "message": "Users fetched successfully"
  }
  ```

#### `POST` (Benutzer erstellen)

Erstellt einen neuen Benutzer.

- **Body** (JSON):
  - `firstName` (string): Vorname.
  - `lastName` (string): Nachname.
  - `email` (string): E-Mail-Adresse.
  - `password` (string): Mindestens 6 Zeichen.
  - `role` (enum): `"user" | "admin"`.
- **Antwort**: `200 OK` mit dem erstellten Benutzerobjekt in `data`.

#### `PUT` (Benutzer aktualisieren)

Aktualisiert einen bestehenden Benutzer.

- **Body** (JSON):
  - `id` (number): Die Benutzer-ID (Erforderlich).
  - `firstName` (optional string): Neuer Vorname.
  - `lastName` (optional string): Neuer Nachname.
  - `email` (optional string): Neue E-Mail.
  - `password` (optional string): Neues Passwort.
  - `role` (optional enum): `"user" | "admin"`.
- **Antwort**: `200 OK` mit dem aktualisierten Benutzerobjekt in `data`.

#### `DELETE` (Benutzer löschen)

Löscht einen Benutzer.

- **Body** (JSON):
  - `id` (number): Die Benutzer-ID (Erforderlich).
- **Antwort**: `200 OK`
  ```json
  {
    "data": { "success": true },
    "message": "User deleted successfully"
  }
  ```

### `/api/dashboard/customers`

Verwaltet Kundendaten im System. Alle Anfragen erfordern Admin-Berechtigungen über `requireAdmin`.

#### `GET` (Kunden auflisten)

Ruft eine paginierte Liste von Kunden ab.

- **Query-Parameter**:
  - `page` (optional): Die Seitenzahl (Standard: `1`).
  - `limit` (optional): Anzahl der Datensätze pro Seite (Standard: `10`).
- **Antwort**: `200 OK`
  ```json
  {
    "data": {
      "customers": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Jane Doe",
          "email": "jane@example.com",
          "phone_number": "+49 123 456789",
          "address": "Musterstraße 1, 12345 Berlin",
          "created_at": "...",
          "last_updated_at": "..."
        }
      ],
      "total": 1,
      "pagination": {
        "page": 1,
        "limit": 10,
        "total": 1,
        "totalPages": 1
      }
    },
    "message": "Customers fetched successfully"
  }
  ```

#### `POST` (Kunde erstellen)

Erstellt einen neuen Kundendatensatz.

- **Body** (JSON):
  - `name` (string): Vollständiger Name des Kunden (erforderlich).
  - `email` (string): E-Mail-Adresse.
  - `phone_number` (string): Telefonnummer.
  - `address` (string): Anschrift.
- **Antwort**: `200 OK` mit dem erstellten `CustomerDTO` in `data`.

#### `PUT` (Kunde aktualisieren)

Aktualisiert einen bestehenden Kunden.

- **Body** (JSON):
  - `id` (string): Die UUID des Kunden (erforderlich).
  - `name` (optional string): Neuer Name.
  - `email` (optional string): Neue E-Mail.
  - `phone_number` (optional string): Neue Telefonnummer.
  - `address` (optional string): Neue Anschrift.
- **Antwort**: `200 OK` mit dem aktualisierten `CustomerDTO`.

#### `DELETE` (Kunde löschen)

Löscht einen Kundendatensatz.

- **Body** (JSON):
  - `id` (string): Die UUID des Kunden (erforderlich).
- **Antwort**: `200 OK`
  ```json
  {
    "data": { "success": true },
    "message": "Customer deleted successfully"
  }
  ```

#### Customer Flow Diagram

```mermaid
sequenceDiagram
    participant Admin as Admin Client
    participant API as /api/dashboard/customers
    participant Action as actions/customers.ts
    participant DB as PostgreSQL

    Admin->>API: POST /api/dashboard/customers
    API->>API: Validate with Zod
    API->>Action: createCustomer(data)
    Action->>DB: INSERT INTO customers
    DB-->>Action: raw_customer
    Action-->>API: result.data
    API->>API: Map to CustomerDTO
    API-->>Admin: 200 OK { data: CustomerDTO }
```

### `/api/dashboard/suppliers`

Verwaltet Produktlieferanten im System. Alle Anfragen erfordern Admin-Berechtigungen über `requireAdmin`.

#### `POST` (Lieferant erstellen)

Erstellt einen neuen Lieferanten.

- **Body** (JSON - Snake Case):
  - `company_name` (string): Firmenname (erforderlich).
  - `registration_name` (optional string): Offizieller Registrierungsname.
  - `address` (optional string): Anschrift.
  - `email` (string): E-Mail-Adresse.
  - `phone_number` (optional string): Telefonnummer.
  - `website` (optional string): URL der Webseite.
- **Antwort**: `200 OK` mit dem erstellten Lieferanten (`SupplierDTO` - Camel Case) in `data`.

#### `PUT` (Lieferant aktualisieren)

Aktualisiert einen bestehenden Lieferanten.

- **Body** (JSON - Snake Case):
  - `id` (number): Die ID des Lieferanten (erforderlich).
  - `company_name` (optional string): Neuer Firmenname.
  - `registration_name` (optional string): Neuer Registrierungsname.
  - `address` (optional string): Neue Anschrift.
  - `email` (optional string): Neue E-Mail.
  - `phone_number` (optional string): Neue Telefonnummer.
  - `website` (optional string): Neue Webseite.
- **Antwort**: `200 OK` mit dem aktualisierten `SupplierDTO`.

#### `DELETE` (Lieferant löschen)

Löscht einen Lieferanten. Eine Löschung ist nur möglich, wenn der Lieferant keinen Produkten zugeordnet ist.

- **Body** (JSON):
  - `id` (number): Die ID des Lieferanten (erforderlich).
- **Antwort**: `200 OK`
  ```json
  {
    "data": { "success": true },
    "message": "Supplier deleted successfully"
  }
  ```

#### Supplier Flow Diagram

```mermaid
sequenceDiagram
    participant Admin as Admin Client
    participant API as /api/dashboard/suppliers
    participant Action as actions/settings.ts
    participant DB as PostgreSQL

    Admin->>API: POST /api/dashboard/suppliers (snake_case)
    API->>API: Validate with Zod
    API->>Action: createSupplier(data)
    Action->>DB: Persist data
    DB-->>Action: Response
    Action-->>API: result.data
    API->>API: Map to SupplierDTO (camelCase)
    API-->>Admin: 200 OK { data: SupplierDTO }
```

### Dashboard API Flow

```mermaid
sequenceDiagram
    participant Admin as Admin Client
    participant API as /api/dashboard/*
    participant Auth as Auth Utils (requireAdmin)
    participant Action as Server Action
    participant DB as PostgreSQL

    Admin->>API: HTTP Request (JWT Cookie)
    API->>Auth: Check Authentication
    Auth-->>API: Session & Admin?
    alt Nicht Autorisiert
        API-->>Admin: 401/403 Redirect/Error
    else Autorisiert
        API->>Action: Geschäftslogik ausführen
        Action->>DB: Datenbankabfrage
        DB-->>Action: Ergebnis
        Action-->>API: Daten zurückgeben
        API-->>Admin: successResponse(data)
    end
```