Plugin-Plattform v1.7: Sub-Add-Ins ueber stabile Ingest-API + Capability-Manifest

[MadGapun]

Kontext

Mehrere zurueckgestellte Features (#478 Thunderbird-Integration, #480 Outlook-Integration, #481 iCal-Sync) haben ein gemeinsames Muster: Sie holen Daten aus externen Desktop-/Mail-Systemen in PBP rein. Statt jedes davon monolithisch in den Core zu bauen, sollte PBP eine stabile Plugin-Schnittstelle bereitstellen, und jede Integration wird ein eigenstaendiges Sub-Repo, das Nutzer bei Bedarf installieren.

Ausloeser der Diskussion: Release-Retro nach v1.6.0-beta.8 — der Core wird zu schnell zu gross, wenn jede Plattform direkt integriert wird. Ausserdem hat jede Plattform eigene Release-Zyklen (Thunderbird-Versionen, Office-JS-Updates, macOS-Calendar-APIs).

Ziele

1. Core schlank halten — PBP bleibt die zentrale Bewerbungsverwaltung. Integrationen sind opt-in.
2. Jedes Add-in eigenstaendig — eigene Repos, eigene Releases, eigene Plattform-Tests.
3. Stabile Vertraege — Add-ins brechen nicht, wenn PBP-Interna sich aendern.
4. Community-fahig — Dritte koennen Adapter schreiben (Gmail, Apple Mail, Signal-Notifications, ...), ohne einen Core-PR zu brauchen.

Vorschlag: Architektur

Core-seitige Ingest-API (stabil versioniert)

Alle Endpoints unter `/api/v1/plugin/...`, Auth via API-Key (Settings -> Integrationen -> "Token generieren"):

```
POST /api/v1/plugin/inbox/message
Body: { sender, subject, body, received_at, headers, attachments[] }
-> { ingested_id, matched_application_id?, suggested_action? }

POST /api/v1/plugin/calendar/event
Body: { title, start, end, location, attendees[], ical_uid?, source }
-> { ingested_id, matched_application_id?, meeting_id? }

POST /api/v1/plugin/document
Body: multipart — file + metadata
-> { document_id, extracted_text? }

POST /api/v1/plugin/note
Body: { application_id?, text, source, external_ref? }
-> { note_id, matched_application_id? }

GET /api/v1/plugin/capabilities
-> { core_version, supported_endpoints[], schema_versions{} }

GET /api/v1/plugin/applications?state=active
-> Liste aktiver Bewerbungen fuer Matching-Hints in Add-ins
```

Capability-Manifest (Add-in-seitig)

Jedes Add-in liefert bei Registrierung ein Manifest:

```json
{
"name": "pbp-thunderbird-addon",
"version": "0.1.0",
"provides": ["inbox.email", "calendar.ical"],
"requires_core": ">=1.7.0",
"update_url": "https://github.com/MadGapun/pbp-thunderbird-addon/releases/latest"
}
```

Sub-Repos (v1.7+)

• pbp-thunderbird-addon — WebExtension (MailExtension API), Referenz-Implementierung fuer Feature: Thunderbird-Add-On "An PBP senden" mit Thread-Upload (+ Alternativen: Watch-Folder, IMAP, BCC) #478
• pbp-outlook-addin — Office-JS Manifest, fuer Feature: Outlook-Integration (Office-Add-In) "An PBP senden" mit Thread-Upload #480
• pbp-ical-sync — kleiner Python-Watcher fuer .ics-Feeds, fuer Feature: Termine an Thunderbird/Outlook-Kalender senden (iCalendar-Export und optional CalDAV/Graph-Sync) #481
• pbp-plugin-sdk (evtl.) — gemeinsame TypeScript/Python-Types + Helpers

Querverbindung: PTrans

PTrans (Windows-Desktop-Recorder + Whisper-Transkription) ist ein natuerlicher Plugin-Kandidat:

• Use-Case: Telefon-Interview / Kennenlerngespraech aufzeichnen -> lokal transkribieren -> Transkript landet automatisch als Notiz an der passenden Bewerbung.
• Endpoint: koennte `POST /api/v1/plugin/note` nutzen (Body: application_id?, text, source="ptrans", external_ref=audio-datei).
• Matching-Hinweis: PTrans ruft `GET /api/v1/plugin/applications?state=active` ab und bietet dem User beim Stop eine Dropdown-Auswahl an, zu welcher Bewerbung die Aufnahme gehoert.
• Voraussetzung: PTrans braucht eigene Config fuer PBP-API-URL + Token. Das koennte in PTrans v0.3.x rein, nachdem v0.2.0 (Audio-Uplift, Issue [v0.10.0] WP-3c: Monster Playwright #5) durch ist.

Das zeigt gut, warum die Plugin-API nicht Mail-spezifisch sein darf — sie muss generisch genug sein, um auch Transkripte, Termine, Dokumente etc. aufzunehmen.

Abgrenzung / Nicht-Ziele (v1.7)

• Kein Plugin-Store im UI — Installation bleibt manuell (Anleitung pro Repo).
• Keine Zwei-Wege-Sync — Add-ins schicken Daten nach PBP rein, lesen nur fuer Matching. Schreiben zurueck (z.B. PBP setzt Mail-Tag in Thunderbird) ist v1.8+.
• Keine Sandbox / kein Permission-Model — Add-ins haben Vollzugriff via Token, Token kann widerrufen werden. Granulare Permissions sind v2.x.

Umsetzungsschritte

• v1.6.0-final: `docs/PLUGIN_API.md` als Platzhalter + Verweis auf dieses Issue.
• v1.7.0-alpha: API-Schema festzurren, Endpoints `/api/v1/plugin/*` implementieren, Token-Management in Settings.
• v1.7.0-beta: Referenz-Implementierung `pbp-thunderbird-addon` als eigenes Repo, als End-to-End-Test der Schnittstelle.
• v1.7.0-final: Outlook + iCal-Sync als weitere Sub-Repos.
• v1.7.x: PTrans-Integration (braucht PTrans >= 0.3).

Related / Blocks

• Bloeckt: Feature: Thunderbird-Add-On "An PBP senden" mit Thread-Upload (+ Alternativen: Watch-Folder, IMAP, BCC) #478, Feature: Outlook-Integration (Office-Add-In) "An PBP senden" mit Thread-Upload #480, Feature: Termine an Thunderbird/Outlook-Kalender senden (iCalendar-Export und optional CalDAV/Graph-Sync) #481 (werden Sub-Repos)
• Related: [Epic] Bewerbung ↔ Kalender Lifecycle-Management: zentrales Event-System für Status-Propagation #497 (Event-System — Plugin-API ist die externe Seite davon)
• Related: PTrans v0.3 (externes Repo)

[MadGapun]

Korrekt-gelabelt: nicht in v1.7 umgesetzt. Plugin-Plattform ist eigener Sprint, fruehestens v1.8. Marker entsprechend.