Zum Inhalt

Freelancer Pool Modul

Zweck

Das Freelancer Pool Modul bietet einen öffentlichen Freelancer-Pool für Sicherheitsfirmen. Es ermöglicht Schichten öffentlich auszuschreiben, Freelancer-Bewerbungen zu verwalten, Verifizierungsprozess, Profil-Ansicht und Matching-System für passende Freelancer.

Verantwortlichkeiten

Was gehört zum Modul

  • Öffentlicher Pool: Öffentliche Schichten ausschreiben
  • Freelancer-Bewerbungen: Bewerbungen verwalten
  • Verifizierungsprozess: Verifizierung von Freelancern
  • Profil-Ansicht: Freelancer-Profile anzeigen
  • Matching-System: Matching für passende Freelancer

Was gehört nicht zum 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

  • Öffentlicher Zugriff: Öffentliche Schichten sind ohne Auth sichtbar

Abhängigkeiten

Optionale Abhängigkeiten

Keine.

Core-Abhängigkeiten

  • shift-pool: Für Schicht-Daten

API-Endpoints

Authentifizierung

Öffentliche Endpoints erfordern keine Authentifizierung. Admin-Endpoints erfordern Auth.

Header: Authorization: Bearer <token> (nur für Admin-Endpoints)

Sicherheit öffentlicher Endpoints

Alle öffentlichen Endpoints (Pool-Liste, Apply, Register) unterliegen verbindlichen Schutzmaßnahmen:

  • Rate Limiting / Throttling auf allen öffentlichen Endpoints
  • Anti-Abuse (Bot-Protection / CAPTCHA oder vergleichbar) speziell für Register und Apply
  • Keine User-Enumeration: generische Fehlermeldungen (z. B. bei DUPLICATE)
  • Secret-Hygiene: Passwörter und Tokens werden niemals geloggt; Token-/Passwort-Redaction
  • Least Privilege: Hochprivilegierte Endpoints (z. B. SuperAdmin) werden nicht öffentlich dokumentiert

Öffentliche Pool-Liste

GET /api/freelancer/pool/public

Öffentliche Pool-Liste (alle Schichten mit isPublicPool: true). Kein Auth erforderlich.

Query-Parameter: - from (optional): Start-Datum - to (optional): End-Datum - location (optional): Standort-Filter - q (optional): Suchbegriff

Response: 

{
  "shifts": [
    {
      "id": "shift123",
      "title": "Schicht-Titel",
      "startsAt": "2024-01-15T08:00:00Z",
      "endsAt": "2024-01-15T17:00:00Z",
      "location": "Standort A",
      "isPublicPool": true
    }
  ],
  "count": 1
}

Auf öffentliche Schicht bewerben

POST /api/freelancer/pool/public/:shiftId/apply

Bewirbt sich auf eine öffentliche Schicht. Öffentliche Bewerbung ist möglich; der Zugriff wird serverseitig validiert (u. a. Berechtigung, Anti-Abuse, Throttling). Kein Auth erforderlich für den Einstieg in den Freelancer-Flow.

Request Body: 

{
  "note": "Optional: Nachricht"
}

Response: 

{
  "application": {
    "id": "app123",
    "shiftId": "shift456",
    "status": "PENDING",
    "appliedAt": "2024-01-15T10:00:00Z"
  },
  "message": "Application submitted successfully"
}

Fehler: - 404 NOT_FOUND: Schicht nicht gefunden oder nicht verfügbar - 422 VALIDATION_ERROR: Bewerbungsfrist abgelaufen oder bereits beworben - 403 FORBIDDEN: Zugriff nur für berechtigte Freelancer

Freelancer-Registrierung

Freelancer registrieren

POST /api/freelancer/register

Registriert einen neuen Freelancer. Öffentlich zugänglich (kein Auth erforderlich).

Sicherheit: Passwort wird ausschließlich über TLS übertragen und serverseitig gehasht gespeichert; wird niemals geloggt. Es gelten Rate Limiting, Anti-Abuse (z. B. CAPTCHA), Passwort-Policy, Brute-Force-Schutz und keine User-Enumeration (generische Fehlermeldungen).

Request Body: 

{
  "email": "freelancer@example.com",
  "password": "[password]",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phone": "+49 123 456789",
  "companyName": "Optional: Firmenname",
  "address": {
    "street": "Musterstraße 1",
    "zip": "12345",
    "city": "Berlin",
    "country": "Deutschland"
  }
}

Response: 

{
  "freelancer": {
    "uid": "user123",
    "email": "freelancer@example.com",
    "firstName": "Max",
    "lastName": "Mustermann",
    "status": "pending_verification"
  },
  "message": "Freelancer registered successfully"
}

Fehler: - 422 VALIDATION_ERROR: Ungültige Eingabedaten (z.B. E-Mail-Format, Passwort-Anforderungen) - 409 DUPLICATE: Konto existiert bereits (generische Meldung aus Sicherheitsgründen)

Registrierung abschließen

POST /api/freelancer/complete-registration

Schließt die Freelancer-Registrierung nach E-Mail-Verifizierung ab (Auth erforderlich).

Response: 

{
  "freelancer": {
    "uid": "user123",
    "email": "freelancer@example.com",
    "status": "active"
  },
  "message": "Freelancer registration completed successfully"
}

Fehler: - 400 EMAIL_NOT_VERIFIED: E-Mail ist noch nicht verifiziert - 404 NO_PENDING_REGISTRATION: Keine ausstehende Registrierung gefunden

Freelancer-Profil

Eigenes Profil abrufen

GET /api/freelancer/me

Lädt das eigene Freelancer-Profil.

Response: 

{
  "freelancer": {
    "uid": "user123",
    "email": "freelancer@example.com",
    "firstName": "Max",
    "lastName": "Mustermann",
    "displayName": "Max Mustermann",
    "phone": "+49 123 456789",
    "companyName": "Firmenname",
    "status": "active",
    "verificationStatus": "pending"
  }
}

Fehler: - 403 Forbidden: Nur Freelancer können auf diesen Endpunkt zugreifen

Profil aktualisieren

PATCH /api/freelancer/me

Aktualisiert das eigene Freelancer-Profil.

Request Body: 

{
  "displayName": "Max Mustermann",
  "firstName": "Max",
  "lastName": "Mustermann",
  "email": "newemail@example.com",
  "phone": "+49 123 456789",
  "address": {
    "street": "Neue Straße 2",
    "zip": "12345",
    "city": "Berlin"
  },
  "companyName": "Neuer Firmenname"
}

Response: 

{
  "freelancer": {
    "uid": "user123",
    "displayName": "Max Mustermann",
    "firstName": "Max",
    "lastName": "Mustermann"
  },
  "message": "Profile updated successfully"
}

Fehler: - 422 VALIDATION_ERROR: Ungültige Eingabedaten (z.B. E-Mail-Format) - 404 NOT_FOUND: Freelancer-Profil nicht gefunden - 403 Forbidden: Nur Freelancer können ihr Profil aktualisieren

Konto-Löschung beantragen

DELETE /api/freelancer/me

Erstellt einen Löschauftrag für das eigene Freelancer-Konto (DSGVO-konform). Das Konto wird nicht sofort gelöscht, sondern ein Antrag wird an das Support-Team gesendet.

Request Body: 

{
  "confirmation": "DELETE_MY_ACCOUNT",
  "reason": "Optional: Grund für Löschung"
}

Response: 

{
  "message": "Deletion request submitted successfully. Your account will be reviewed by our support team. Data will be retained for 30 days after approval before permanent deletion.",
  "requestId": "user123",
  "status": "pending"
}

Fehler: - 422 CONFIRMATION_REQUIRED: Bestätigung erforderlich (confirmation muss "DELETE_MY_ACCOUNT" sein) - 404 NOT_FOUND: Freelancer-Profil nicht gefunden - 409 DUPLICATE_REQUEST: Löschungsanfrage existiert bereits - 403 Forbidden: Nur Freelancer können eine Löschungsanfrage stellen

Freelancer-Entitlements

Entitlements abrufen

GET /api/freelancer/entitlements

Lädt alle Entitlements für den eingeloggten Freelancer.

Response: 

{
  "entitlements": {
    "module.shift_pool": true,
    "module.time_tracking": false
  }
}

Fehler: - 403 Forbidden: Nur Freelancer können auf diesen Endpunkt zugreifen

Verifizierung

Verifizierungsdokument hochladen

POST /api/freelancer/verification/upload

Lädt einen Gewerbeschein oder Ausweis hoch.

Request: Multipart Form-Data - file (required): Die Datei (max. 10MB)

Response: 

{
  "documentPath": "[storage-path]/[filename]",
  "message": "Verification document uploaded successfully"
}

Fehler: - 400 MISSING_FILE: Keine Datei hochgeladen - 404 NOT_FOUND: Freelancer nicht gefunden - 422 VALIDATION_ERROR: Ungültiger Dateityp oder Dateigröße überschreitet 10MB - 403 Forbidden: Nur Freelancer können Verifizierungsdokumente hochladen

Verifizierungsstatus abrufen

GET /api/freelancer/verification/status

Lädt den Verifizierungsstatus.

Response: 

{
  "verificationStatus": "pending",
  "verificationSubmittedAt": "2024-01-15T10:00:00Z",
  "verificationReviewedAt": null,
  "verificationRejectionReason": null
}

Fehler: - 403 Forbidden: Nur Freelancer können auf diesen Endpunkt zugreifen - 404 NOT_FOUND: Freelancer-Profil nicht gefunden

Verifizierungsdokument abrufen

GET /api/freelancer/verification/document

Lädt die Download-URL für das Verifizierungsdokument. Sicherheit: Kurzlebige signierte URL, kurze TTL, one-time/rotating; URL und Dokumente werden nicht geloggt; Content-Disposition und no-store wo anwendbar.

Response: 

{
  "url": "https://storage.googleapis.com/...",
  "expiresAt": "2024-01-15T11:00:00Z"
}

Fehler: - 404 NOT_FOUND: Freelancer oder Verifizierungsdokument nicht gefunden - 403 Forbidden: Nur Freelancer können Verifizierungsdokumente abrufen

Firestore Collections

Das Freelancer Pool Modul verwendet keine eigenen Collections. Es nutzt Daten aus dem shift-pool Modul.

Wird dokumentiert: Detaillierte Datenbank-Struktur folgt.

Fehlerfälle

HTTP-Status-Codes

  • 200 OK: Erfolgreich
  • 201 Created: Ressource erstellt
  • 400 Bad Request: Validierungsfehler
  • 401 Unauthorized: Nicht authentifiziert (nur für Admin-Endpoints)
  • 403 Forbidden: Keine Berechtigung
  • 404 Not Found: Ressource nicht gefunden
  • 500 Internal Server Error: Server-Fehler

Fehlercodes

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

  • NOT_FOUND: Ressource nicht gefunden
  • VALIDATION_ERROR: Validierungsfehler bei Eingabedaten
  • DUPLICATE: Konto existiert bereits
  • EMAIL_NOT_VERIFIED: E-Mail ist noch nicht verifiziert
  • NO_PENDING_REGISTRATION: Keine ausstehende Registrierung gefunden
  • CONFIRMATION_REQUIRED: Bestätigung erforderlich (für Konto-Löschung)
  • DUPLICATE_REQUEST: Löschungsanfrage existiert bereits
  • MISSING_FILE: Keine Datei hochgeladen
  • FORBIDDEN: Keine Berechtigung (z.B. nur Freelancer können auf Endpunkt zugreifen)

FAQ / Troubleshooting

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