Zum Inhalt

Calendar Core Modul

Zweck

Das Calendar Core Modul ist das zentrale Kalendermodul von TimeAM. Es aggregiert Events aus verschiedenen Feature-Modulen (Zeiterfassung, Schichtplanung, Projekte) und stellt sie in einer einheitlichen Kalenderansicht dar. Das Modul nutzt FullCalendar (React) als Basis-Library.

Verantwortlichkeiten

Was gehört zum Modul

  • Event-Aggregation: Events aus verschiedenen Modulen sammeln und zusammenführen
  • Kalender-Ansichten: Monat, Woche, Tag, Liste
  • Event-Filterung: Nach Modulen, Datum, Status filtern
  • Event-Darstellung: Einheitliche Darstellung aller Events
  • Kalender-Integration: Integration mit FullCalendar (React)

Was gehört nicht zum Modul

  • Event-Erstellung: Events werden von anderen Modulen erstellt (time-tracking, shift-pool, etc.)
  • Event-Verwaltung: Bearbeitung von Events erfolgt in den jeweiligen Modulen
  • Benachrichtigungen: Siehe notifications Modul

Implementierung

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

Konfiguration

Entitlement

Das Modul ist ein Core-Modul und erfordert kein spezielles Entitlement. Es ist immer aktiv.

Entitlement-Key: Keiner (Core-Modul)

Environment Variables

Keine modulspezifischen ENV-Variablen erforderlich.

Defaults

  • Standard-Ansicht: Monat
  • Zeitzone: Lokale Zeitzone des Browsers
  • Sprache: Deutsch (de-DE)

Abhängigkeiten

Optionale Abhängigkeiten

  • time-tracking: Für Zeiterfassungs-Events im Kalender
  • shift-pool: Für Schicht-Events im Kalender
  • projects: Für Projekt-Events im Kalender

Core-Abhängigkeiten

Keine.

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>

Events abrufen

GET /api/calendar/events?from=2024-01-01&to=2024-01-31&includeModules=time-tracking,shift-pool

Lädt Kalender-Events aus allen aktivierten Modulen.

Query-Parameter: - from (required): Start-Datum (ISO 8601) - to (required): End-Datum (ISO 8601) - includeModules (optional): Komma-getrennte Liste von Modulen (z.B. time-tracking,shift-pool)

Response: 

{
  "events": [
    {
      "id": "time-tracking:entry123",
      "title": "Arbeitszeit",
      "startsAt": "2024-01-15T08:00:00Z",
      "endsAt": "2024-01-15T17:00:00Z",
      "sourceModule": "time-tracking",
      "ref": {
        "type": "timeEntry",
        "id": "entry123"
      },
      "status": "completed",
      "meta": {
        "durationMinutes": 540
      }
    },
    {
      "id": "shift-pool:shift456",
      "title": "Schicht: Sicherheitsdienst",
      "startsAt": "2024-01-16T20:00:00Z",
      "endsAt": "2024-01-17T06:00:00Z",
      "sourceModule": "shift-pool",
      "ref": {
        "type": "shift",
        "id": "shift456"
      },
      "status": "published",
      "meta": {
        "location": "Standort A"
      }
    }
  ],
  "count": 2,
  "range": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z"
  },
  "loadedModules": ["time-tracking", "shift-pool"]
}

Fehler: - 400 INVALID_FROM: Fehlender oder ungültiger "from" Parameter - 400 INVALID_TO: Fehlender oder ungültiger "to" Parameter - 400 INVALID_FROM_FORMAT: Ungültiges "from" Datumsformat - 400 INVALID_TO_FORMAT: Ungültiges "to" Datumsformat - 400 INVALID_RANGE: "from" muss vor "to" liegen - 400 RANGE_TOO_LARGE: Zeitraum zu groß (max. 93 Tage)

Beispiele:

Beispiel 1: Alle Events für einen Monat 

curl -X GET "https://api.example.com/api/calendar/events?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Beispiel 2: Nur Zeiterfassungs-Events 

curl -X GET "https://api.example.com/api/calendar/events?from=2024-01-01&to=2024-01-31&includeModules=time-tracking" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Beispiel 3: Zeiterfassung und Schichten 

curl -X GET "https://api.example.com/api/calendar/events?from=2024-01-01&to=2024-01-31&includeModules=time-tracking,shift-pool" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Firestore Collections

Das Calendar Core Modul verwendet keine eigenen Collections. Es aggregiert Daten aus anderen Modulen:

  • Time Entries: /tenants/{tenantId}/timeEntries/{entryId} (aus time-tracking)
  • Shifts: /tenants/{tenantId}/shifts/{shiftId} (aus shift-pool)

Wird dokumentiert: Detaillierte Datenbank-Struktur folgt.

Fehlerfälle

HTTP-Status-Codes

  • 200 OK: Erfolgreich
  • 400 Bad Request: Validierungsfehler (z.B. fehlende Datum-Parameter)
  • 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_FROM: Fehlender oder ungültiger "from" Parameter (ISO 8601 Datum erforderlich)
  • INVALID_TO: Fehlender oder ungültiger "to" Parameter (ISO 8601 Datum erforderlich)
  • INVALID_FROM_FORMAT: Ungültiges "from" Datumsformat
  • INVALID_TO_FORMAT: Ungültiges "to" Datumsformat
  • INVALID_RANGE: "from" muss vor "to" liegen
  • RANGE_TOO_LARGE: Zeitraum zu groß (maximal 93 Tage erlaubt)

FAQ / Troubleshooting

Warum werden keine Events angezeigt?

  1. Prüfen Sie, ob die entsprechenden Module aktiviert sind (time-tracking, shift-pool)
  2. Prüfen Sie, ob im angegebenen Zeitraum Events existieren
  3. Prüfen Sie die includeModules Parameter

Wie werden Events aus verschiedenen Modulen zusammengeführt?

Das Calendar Core Modul lädt Events parallel aus allen aktivierten Modulen und fügt sie zu einer Liste zusammen. Die Events werden nach Startzeit sortiert.

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