> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architektur und Ressourcenmodell

> Verstehen Sie Systemgrenzen, Ressourceneigentum, Beziehungen und die Verantwortlichkeiten der beteiligten Integrationskomponenten.

Die JobHandy Public API ist eine synchrone REST-Schnittstelle. Kundensysteme initiieren jede öffentliche Anfrage; der aktuelle öffentliche v1-Vertrag definiert keine Webhook-Endpoints oder Event-Subscriptions.

## Systemgrenze

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    subgraph Customer[Kundenumgebung]
        HRIS[HRIS / HCM]
        PAY[Payroll-System]
        INT[Integrationsdienst]
        SEC[Secret Manager]
        LOG[Logs und Monitoring]
        HRIS --> INT
        PAY --> INT
        SEC --> INT
        INT --> LOG
    end

    subgraph JobHandy[JobHandy]
        API[Public API v1]
        PORTAL[Administrationsportal]
        DATA[Autorisierte Tenant-Daten]
        FILES[Autorisierte Dokumente]
        PORTAL --> DATA
        API --> DATA
        API --> FILES
    end

    INT -->|HTTPS + X-API-Key| API
    ADMIN[Autorisierter Administrator] --> PORTAL
```

## Verantwortungsaufteilung

| Verantwortung                                          | Kundenintegration |                                 JobHandy API |
| ------------------------------------------------------ | ----------------: | -------------------------------------------: |
| API-Key sicher speichern                               |                Ja |                                         Nein |
| Polling und Synchronisation planen                     |                Ja |                                         Nein |
| Quellfelder auf API-Felder abbilden                    |                Ja |                                         Nein |
| `X-Request-ID` erzeugen und protokollieren             |         Empfohlen |             Gibt sie zurück oder erzeugt sie |
| API-Key-Scope erzwingen                                |              Nein |                                           Ja |
| Request-Schema und fachlichen Zustand validieren       |              Nein |                                           Ja |
| Mehrdeutige Ergebnisse von Schreibvorgängen abgleichen |                Ja | Stellt den aktuellen Ressourcenstatus bereit |
| Heruntergeladene Dateien nach dem Abruf schützen       |                Ja |       Schützt API-Zugriff und Download-Scope |

## Ressourceneigentum

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    KEY[Scope des API-Keys] --> TEN[Tenant]
    TEN --> DIV[Divisionshierarchie]
    TEN --> EMP[Mitarbeiter]
    TEN --> EXP[Payroll-Exportdokumente]
    EMP --> ORD[Bestellungen]
    EMP --> INC[Vorfälle]
    ORD --> OA[Bestellanhänge]
    INC --> IA[Vorfallsanhänge]
```

| Ressource              | Eigentumsgrenze                         | Öffentliche Schreibmöglichkeiten                                           |
| ---------------------- | --------------------------------------- | -------------------------------------------------------------------------- |
| Tenant                 | API-Key-Scope                           | Keine Operation zum Erstellen, Aktualisieren oder Löschen von Tenants      |
| Division               | Genau ein Tenant                        | Erstellen und aktualisieren                                                |
| Mitarbeiter            | Kein oder ein Tenant; Division optional | Erstellen und unterstützte Felder aktualisieren                            |
| Bestellung             | Genau ein Tenant und ein Mitarbeiter    | Lesen und einmalige HR-Entscheidung aus dem dokumentierten Status erfassen |
| Vorfall                | Mitarbeiter im autorisierten Scope      | Erstellen, unterstützte Felder aktualisieren, zulässige Anhänge hochladen  |
| Payroll-Exportdokument | Genau ein Tenant                        | Metadaten lesen und verfügbare Datei herunterladen                         |

## Side Effects von Schreiboperationen

| Operation                 | Persistente Wirkung                                    | Zusätzlicher Side Effect                                | Verhalten im Dry Run                            |
| ------------------------- | ------------------------------------------------------ | ------------------------------------------------------- | ----------------------------------------------- |
| Mitarbeiter erstellen     | Erstellt ein Konto                                     | Sendet eine E-Mail zur Passwortvergabe                  | Kein Konto und keine E-Mail                     |
| Mitarbeiter aktualisieren | Ändert unterstützte Felder                             | Im Vertrag ist kein zusätzlicher Side Effect angegeben  | Keine Speicherung                               |
| Bestellung entscheiden    | Speichert die endgültige HR-Entscheidung               | Sendet die zugehörigen Benachrichtigungen               | Keine Entscheidung und keine Benachrichtigungen |
| Vorfall erstellen         | Erstellt den Vorfall                                   | Setzt Melder- und Lifecycle-Metadaten                   | Keine Speicherung                               |
| Vorfall aktualisieren     | Ändert unterstützte Vorfallsfelder                     | Serverseitige Lifecycle-Regeln können angewendet werden | Keine Speicherung                               |
| Vorfallsanhänge hochladen | Speichert zulässige Dateien                            | Im Vertrag ist kein zusätzlicher Side Effect angegeben  | Validiert ohne Speicherung                      |
| Division erstellen        | Erstellt einen Hierarchieknoten                        | Im Vertrag ist kein zusätzlicher Side Effect angegeben  | Keine Speicherung                               |
| Division aktualisieren    | Ändert Hierarchie, Name, Reihenfolge oder Kostenstelle | Im Vertrag ist kein zusätzlicher Side Effect angegeben  | Keine Speicherung                               |

Der OpenAPI-Vertrag ist maßgeblich. Gehen Sie nicht von zusätzlichen E-Mails, Benachrichtigungen oder Folgeaktionen aus, die nicht dokumentiert sind.

## Beziehungen zwischen Identifikatoren

Ressourcen-IDs sind undurchsichtige Anwendungsidentifikatoren. Leiten Sie aus Zeichenfolge oder Reihenfolge keine fachliche Bedeutung ab.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Tenant-ID
  -> wird für X-Tenant-ID und Tenant-Felder verwendet
Divisions-ID
  -> wird für parentId und employee.divisionId verwendet
Mitarbeiter-ID
  -> wird von Bestellungen und Vorfällen referenziert
Bestellanhang-ID
  -> wird ausschließlich beim Download-Endpoint für Bestellanhänge verwendet
Payroll-Exportdokument-ID
  -> wird für Metadatenabruf und Download verwendet
```

## Integrationsmodell

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Source as Kunden-Quellsystem
    participant Integration as Integrationsdienst
    participant API as JobHandy Public API
    participant Target as Kunden-Zielsystem

    Source->>Integration: Änderung, Zeitplan oder Benutzerentscheidung
    Integration->>API: HTTPS-Anfrage + Zugangsdaten + Request-ID
    API->>API: Authentifizieren, Scope prüfen, validieren, dokumentierte Regeln anwenden
    API-->>Integration: Ressource oder Fehler + X-Request-ID
    Integration->>Integration: Checkpoint speichern und Ergebnis abgleichen
    Integration->>Target: Nachgelagerte Änderung oder Dateiimport ausführen
```

<Note>
  Der öffentliche Vertrag definiert Request- und Response-Verhalten. Kundenspezifische fachliche Verantwortlichkeiten, Zeitpläne, Feldmappings und nachgelagerte Aufbewahrung bleiben Bestandteil des Integrationsdesigns.
</Note>