Zum Inhalt

Reports Modul

Zweck

Das Reports Modul bietet umfangreiche Berichte und Analytics für Zeiterfassung, Schichten, Projekte und Mitarbeiter. Es unterstützt Export-Funktionen (CSV, PDF), Zeitraum-Filter, benutzerdefinierte Report-Typen und statistische Auswertungen.

Verantwortlichkeiten

Was gehört zum Modul

  • Berichte erstellen: Verschiedene Report-Typen generieren
  • Analytics: Statistische Auswertungen
  • Export-Funktionen: CSV, PDF Export
  • Zeitraum-Filter: Berichte für bestimmte Zeiträume
  • Benutzerdefinierte Reports: Custom Report-Konfigurationen

Was gehört nicht zum Modul

  • Daten-Erstellung: Daten werden von anderen Modulen bereitgestellt
  • Detaillierte Ansichten: Siehe jeweilige Modul-Seiten

Implementierung

Backend- und Frontend-API sind modular aufgebaut; Details siehe interne Entwickler-Dokumentation.

Konfiguration

Entitlement

Das Modul erfordert das Entitlement module.reports. Dieses wird pro Tenant aktiviert/deaktiviert.

Entitlement-Key: module.reports

Environment Variables

Keine modulspezifischen ENV-Variablen erforderlich.

Defaults

  • Standard-Format: CSV
  • Standard-Zeitraum: Aktueller Monat

Abhängigkeiten

Optionale Abhängigkeiten

  • time-tracking: Für Zeiterfassungs-Berichte
  • shift-pool: Für Schicht-Berichte
  • projects: Für Projekt-Berichte

Core-Abhängigkeiten

  • members: Für Mitarbeiter-Berichte

API-Endpoints

Authentifizierung

Alle Endpoints erfordern Authentifizierung. Zwei Methoden werden unterstützt:

  1. Firebase ID Token (Standard für Web-App)
  2. API-Token (für externe Nutzung)

Header: Authorization: Bearer <token>

Dashboard-Widget-Daten abrufen

GET /api/reports/dashboard

Lädt Dashboard-Widget-Daten für Berichte.

Response: 

{
  "success": true,
  "data": {
    "timeTracking": {
      "todayMinutes": 240,
      "weekHours": 35.5
    },
    "shifts": {
      "upcoming": 5
    }
  }
}

Zeit-Zusammenfassungs-Report

GET /api/reports/time-summary?period=this_week&format=json&startDate=2024-01-01&endDate=2024-01-31

Generiert einen Zeit-Zusammenfassungs-Report.

Query-Parameter: - period (optional): Zeitraum (today, yesterday, this_week, last_week, this_month, last_month, custom, Standard: this_week) - startDate (optional): Start-Datum (ISO 8601, erforderlich wenn period=custom) - endDate (optional): End-Datum (ISO 8601, erforderlich wenn period=custom) - format (optional): Format (json oder pdf, Standard: json)

Response (JSON): 

{
  "success": true,
  "report": {
    "type": "time_summary",
    "period": "this_week",
    "startDate": "2024-01-15",
    "endDate": "2024-01-21",
    "totalHours": 40.0,
    "totalMinutes": 2400,
    "entriesCount": 5,
    "members": [
      {
        "uid": "user123",
        "hours": 40.0,
        "minutes": 2400,
        "entriesCount": 5
      }
    ]
  }
}

Response (PDF): PDF-Datei wird direkt heruntergeladen.

Fehler: - 400 INVALID_PERIOD: Ungültiger Zeitraum - 400 MISSING_DATES: Start- und Enddatum erforderlich für benutzerdefinierten Zeitraum

Schicht-Übersichts-Report

GET /api/reports/shift-overview?period=this_week&format=json&startDate=2024-01-01&endDate=2024-01-31

Generiert einen Schicht-Übersichts-Report.

Query-Parameter: - period (optional): Zeitraum (Standard: this_week) - startDate (optional): Start-Datum (erforderlich wenn period=custom) - endDate (optional): End-Datum (erforderlich wenn period=custom) - format (optional): Format (json oder pdf, Standard: json)

Response (JSON): 

{
  "success": true,
  "report": {
    "type": "shift_overview",
    "period": "this_week",
    "startDate": "2024-01-15",
    "endDate": "2024-01-21",
    "totalShifts": 10,
    "publishedShifts": 8,
    "completedShifts": 5,
    "shifts": [
      {
        "id": "shift123",
        "title": "Schicht-Titel",
        "status": "PUBLISHED",
        "startsAt": "2024-01-15T08:00:00Z",
        "endsAt": "2024-01-15T17:00:00Z"
      }
    ]
  }
}

Response (PDF): PDF-Datei wird direkt heruntergeladen.

Fehler: - 400 INVALID_PERIOD: Ungültiger Zeitraum - 400 MISSING_DATES: Start- und Enddatum erforderlich für benutzerdefinierten Zeitraum

Mitarbeiter-Aktivitäts-Report

GET /api/reports/member-activity?period=this_week&format=json&startDate=2024-01-01&endDate=2024-01-31

Generiert einen Mitarbeiter-Aktivitäts-Report (nur Admin/Manager).

Query-Parameter: - period (optional): Zeitraum (Standard: this_week) - startDate (optional): Start-Datum (erforderlich wenn period=custom) - endDate (optional): End-Datum (erforderlich wenn period=custom) - format (optional): Format (json oder pdf, Standard: json)

Response (JSON): 

{
  "success": true,
  "report": {
    "type": "member_activity",
    "period": "this_week",
    "startDate": "2024-01-15",
    "endDate": "2024-01-21",
    "members": [
      {
        "uid": "user123",
        "displayName": "Max Mustermann",
        "totalHours": 40.0,
        "shiftsCount": 5,
        "timeEntriesCount": 10
      }
    ]
  }
}

Response (PDF): PDF-Datei wird direkt heruntergeladen.

Fehler: - 400 INVALID_PERIOD: Ungültiger Zeitraum - 400 MISSING_DATES: Start- und Enddatum erforderlich für benutzerdefinierten Zeitraum - 403 FORBIDDEN: Nur Admin oder Manager können Mitarbeiter-Reports sehen

Bericht generieren

POST /api/reports/generate

Generiert einen Bericht basierend auf Typ und Parametern.

Request Body: 

{
  "type": "time_summary",
  "period": "this_week",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "format": "json"
}

Request Body (Custom Period): 

{
  "type": "shift_overview",
  "period": "custom",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "format": "pdf"
}

Mögliche Report-Typen: - time_summary: Zeit-Zusammenfassungs-Report - shift_overview: Schicht-Übersichts-Report - member_activity: Mitarbeiter-Aktivitäts-Report (nur Admin/Manager)

Mögliche Zeiträume: - today: Heute - yesterday: Gestern - this_week: Diese Woche - last_week: Letzte Woche - this_month: Dieser Monat - last_month: Letzter Monat - custom: Benutzerdefiniert (erfordert startDate und endDate)

Mögliche Formate: - json: JSON-Response - pdf: PDF-Datei (wird direkt heruntergeladen)

Response (JSON): 

{
  "success": true,
  "report": {
    "type": "time_summary",
    "period": "this_week",
    "startDate": "2024-01-15",
    "endDate": "2024-01-21",
    "totalHours": 40.0
  }
}

Response (PDF): PDF-Datei wird direkt heruntergeladen.

Fehler: - 400 INVALID_TYPE: Ungültiger Report-Typ - 400 INVALID_PERIOD: Ungültiger Zeitraum - 400 MISSING_DATES: Start- und Enddatum erforderlich für benutzerdefinierten Zeitraum - 400 UNKNOWN_TYPE: Unbekannter Report-Typ

Firestore Collections

Das Reports Modul verwendet keine eigenen Collections. Es aggregiert Daten aus anderen Modulen für Berichte.

Wird dokumentiert: Detaillierte Datenbank-Struktur folgt.

Fehlerfälle

HTTP-Status-Codes

  • 200 OK: Erfolgreich
  • 400 Bad Request: Validierungsfehler
  • 401 Unauthorized: Nicht authentifiziert
  • 403 Forbidden: Keine Berechtigung
  • 500 Internal Server Error: Server-Fehler

Fehlercodes

Die folgenden Fehlercodes werden von den API-Endpunkten zurückgegeben:

  • INVALID_TYPE: Ungültiger Report-Typ
  • INVALID_PERIOD: Ungültiger Zeitraum
  • MISSING_DATES: Start- und Enddatum erforderlich für benutzerdefinierten Zeitraum
  • UNKNOWN_TYPE: Unbekannter Report-Typ
  • FORBIDDEN: Keine Berechtigung (z.B. für member_activity Report)

FAQ / Troubleshooting

Wird dokumentiert: Häufige Fragen und Lösungen folgen.