Add third-party REST API (/api/v1) + Swagger UI and Jobangebote page

- REST API under /api/v1 with X-API-Key auth (API_TOKEN), documented with
  OpenAPI 3.0; Swagger UI at /swagger, spec at /swagger.json
- Endpoints: applications CRUD + timeline, attachments/emails download,
  generation trigger/status, settings, statistics, export, templates, joboffers
- Jobangebote page (/jobangebote) listing offers ingested via the REST API,
  with "Als Bewerbung übernehmen" and delete actions; header nav + badge
- jobangebote table with (quelle, external_id) upsert for third-party ingestion

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -207,6 +207,55 @@ Generierten Anhang (PDF) herunterladen
 ### GET /api/bewerbungen/filter
 Bewerbungen mit Filter abrufen
 
+## REST-API für Drittanbietersoftware (`/api/v1`)
+
+Zusätzlich zu den internen Endpunkten gibt es eine eigenständige, versionierte
+REST-API unter `/api/v1` für externe Software. Sie ist vollständig mit
+OpenAPI 3.0 dokumentiert; eine interaktive Swagger-UI läuft unter **`/swagger`**,
+das Rohdokument unter **`/swagger.json`**.
+
+### Authentifizierung
+
+Jeder Endpunkt (außer `GET /api/v1/health`) erfordert einen API-Key im Header
+`X-API-Key`. Der Schlüssel wird über die Umgebungsvariable `API_TOKEN` konfiguriert
+(z. B. in `.env`, siehe `.env.example`). Ist `API_TOKEN` nicht gesetzt, antwortet
+die API mit `503` – sie gibt nie ungeschützt Daten heraus. Swagger/UI sind
+auch ohne Token erreichbar (die Dokumentation enthält keine sensiblen Daten).
+
+```bash
+curl -H "X-API-Key: $API_TOKEN" http://localhost:3000/api/v1/applications
+```
+
+### Endpunkte
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| GET | `/api/v1/health` | Verfügbarkeit (ohne Auth) |
+| GET | `/api/v1/applications` | Bewerbungen auflisten (Filter: `month`, `year`, `status`, `art`, `search`, `limit`, `offset`) |
+| POST | `/api/v1/applications` | Bewerbung anlegen (Duplicate-Guard via `force`) |
+| GET | `/api/v1/applications/{id}` | Einzelne Bewerbung |
+| PUT | `/api/v1/applications/{id}` | Bewerbung aktualisieren |
+| DELETE | `/api/v1/applications/{id}` | Bewerbung löschen |
+| GET | `/api/v1/applications/{id}/timeline` | Statusverlauf |
+| POST | `/api/v1/applications/{id}/timeline` | Status-Eintrag hinzufügen |
+| DELETE | `/api/v1/applications/{id}/timeline/{eintragId}` | Status-Eintrag löschen |
+| GET | `/api/v1/applications/{id}/attachments` | Generierte Anhänge auflisten |
+| GET | `/api/v1/applications/{id}/attachments/{attachmentId}` | Anhang (PDF) herunterladen |
+| GET | `/api/v1/applications/{id}/emails` | E-Mail-Korrespondenz |
+| GET | `/api/v1/emails/{emailId}/attachments/{attachmentId}` | E-Mail-Anhang herunterladen |
+| POST | `/api/v1/applications/{id}/generate` | KI-Generierung anstoßen (async, `202`) |
+| GET | `/api/v1/applications/{id}/generation-status` | Generierungsstatus abfragen |
+| GET | `/api/v1/settings` | Einstellungen abrufen |
+| PUT | `/api/v1/settings` | Einstellungen speichern |
+| GET | `/api/v1/statistics` | Statistiken (Gesamt, nach Art/Status) |
+| GET | `/api/v1/export` | Bewerbungen exportieren (ohne interne Notizen) |
+| GET | `/api/v1/templates` | Basis-Unterlagen (Vorlagen) |
+
+Die vollständige, maschinenlesbare Dokumentation (Parameter, Schemas,
+Fehlerantworten) liegt unter `/swagger.json` und ist in der Swagger-UI unter
+`/swagger` interaktiv bedienbar (inkl. „Authorize“ zum Eintragen des API-Keys
+für Test-Requests).
+
 ## PDF-Export
 
 Der PDF-Export generiert ein professionelles Dokument mit: