thunderbird2docuware/README.md

# DocuWare Ablage – Thunderbird-Extension

Legt eine markierte E-Mail aus Thunderbird in DocuWare ab. Nach Klick auf den Button
erscheint ein **Ablage-Dialog**: Aktenschrank wählen, Indexfelder ausfüllen (aus der
Mail vorbefüllt), ablegen. Hochgeladen werden – je nach Auswahl – die Mail als `.eml`,
die Mail als PDF und die Anhänge als separate Dokumente.

## Funktionsweise

- **Direkte Anbindung** an die DocuWare **Platform REST-API** (kein eigener Server).
  Auth v1 per **Cookie-Logon** (`/Account/Logon`).
- **Dynamische Felder**: Die Eingabemaske wird aus dem *Store-Dialog* des gewählten
  Schranks erzeugt (Felder, Pflichtfelder, Auswahllisten).
- **Vorbefüllung** der `EML_*`-Felder aus der Mail (Absender, Empfänger, Betreff,
  Datum, Richtung, Größe, Body …).

## Projektstruktur

```
manifest.json          MailExtension-Manifest (Manifest v2)
background/background.js  Button + Kontextmenü, öffnet den Dialog
dialog/                Ablage-Dialog (HTML/CSS/JS)
options/               Einstellungen (Server, Login, Defaults)
lib/
  store.js             Einstellungen (browser.storage.local)
  auth.js              Cookie-Logon (Auth-Abstraktion)
  docuware.js          Platform-REST-Client (Schränke, Dialoge, Felder, Upload)
  mail.js              Mail-Extraktion (eml, Metadaten, Anhänge)
  pdf.js               abhängigkeitsfreier Text-PDF-Generator
icons/
```

## Installation (Entwicklung)

1. Thunderbird → Menü → **Add-ons und Themes** → Zahnrad → **Add-on aus Datei
   installieren …** *oder* zum Testen:
2. Adresszeile: `about:debugging` → **Dieses Thunderbird** → **Temporäres Add-on
   laden …** → `manifest.json` in diesem Ordner wählen.

> Hinweis: Bei einem Self-Signed-Zertifikat des DocuWare-Servers muss dieses einmalig
> in Thunderbird akzeptiert werden, sonst schlagen die `fetch`-Aufrufe fehl.

## Einrichtung

Add-on-Einstellungen öffnen und ausfüllen:

- **Server-URL** – Basis ohne `/DocuWare/Platform`, z.B. `https://docuware.firma.de`
- **Organisation**, **Benutzername**, **Passwort**
- **Verbindung testen** → lädt die Aktenschränke (Bestätigung, dass Login & URL passen)
- optional **Standard-Aktenschrank** und Default-Optionen (eml/pdf/Anhänge)

> 🔒 **Das Passwort wird nicht gespeichert.** Es wird beim ersten Ablegen pro
> Thunderbird-Sitzung einmal abgefragt, daraus ein OAuth-Token geholt und sofort
> verworfen. Nur der Token bleibt im Speicher des Hintergrundskripts (überlebt keinen
> Neustart). In `storage.local` liegen ausschließlich Server, Organisation, Benutzer
> und Standardwerte – keine Zugangsdaten. Auch der Einstellungs-Export enthält **kein**
> Passwort.

## Benutzung

1. E-Mail öffnen → Button **„In DocuWare ablegen"** (oder Rechtsklick in der
   Nachrichtenliste → *In DocuWare ablegen*).
2. Aktenschrank wählen → Felder prüfen/ergänzen (Pflichtfelder mit `*`).
3. Auswählen, was abgelegt wird (eml / PDF / Anhänge).
4. **Ablegen**. Bei Erfolg wird die Mail optional mit dem Tag *DocuWare* markiert.

## Verifikation (End-to-End)

Gegen den **Test-Schrank `LL_TEST_BELEGE`** ablegen, dann per DocuWare-MCP gegenprüfen:

- `docuware_search` (file_cabinet_name `LL_TEST_BELEGE`, query = Betreff) → Treffer?
- `docuware_get_document` → Indexfelder (`EML_SENDER`, `EML_SUBJECT`, …) korrekt?
- `docuware_download_document` → `.eml`/PDF herunterladen & prüfen
- Anhänge erscheinen als eigene Dokumente
- Aufräumen: `docuware_delete_document` (nur im Test-Schrank!)

## Verteilung & automatische Updates (eigenes Gitea)

Das Add-on wird **nicht** auf addons.thunderbird.net gelistet, sondern als **unsigniertes
XPI** über dein eigenes Gitea verteilt + aktualisiert.

> **Kein Signieren nötig.** Thunderbird verlangt für self-distributed Add-ons keine
> Mozilla-Signatur, und addons.thunderbird.net (ATN) zeichnet Thunderbird-Add-ons ohnehin
> nicht gegen (jede hochgeladene Version bleibt `signed=false`, `web-ext sign` schlägt mit
> „no signed files were found" fehl). Wir bauen das XPI also lokal und verteilen es direkt.

> Im XPI und in `updates.json` stehen **keine** Zugangsdaten. Das DocuWare-Passwort
> wird ohnehin nirgends gespeichert (nur Sitzungs-Token im Speicher) und nie mitverteilt.

**Einmalige Einrichtung:**

1. In `manifest.json` → `applications.gecko.update_url` die Domain `GITEA.EXAMPLE.DE`
   durch deine (HTTPS-)Gitea-Adresse ersetzen. **HTTPS ist Pflicht** (TB lehnt HTTP ab).
2. `updates.json` ebenfalls auf deine Gitea-URLs anpassen und in dein Repo committen.
3. ⚠️ **`update_url` und Release-Assets müssen ANONYM (ohne Login) erreichbar sein** —
   sonst bekommt Thunderbird beim Update-Check nur die Login-Seite und aktualisiert nie.
   Bei Gitea: Repo öffentlich **und** instanzweit `REQUIRE_SIGNIN_VIEW = false` (in
   `app.ini`, Abschnitt `[service]`).

**Bei jedem neuen Release** – am einfachsten mit `scripts/release.sh` (baut sauberes XPI,
patcht `updates.json`, committet/pusht, legt Gitea-Release an + lädt das Asset hoch):

```bash
scripts/release.sh 0.10.2     # Version setzen + alles erledigen
```

Manuell wären das die Schritte: `version` in `manifest.json` erhöhen → sauberes XPI bauen
(`manifest.json` im Archiv-Wurzelverzeichnis; `scripts/`, `docs/`, `.env` **nicht** mit
einpacken) → XPI als Release-Anhang in Gitea hochladen → Eintrag (`version` + `update_link`)
in `updates.json` ergänzen, committen/pushen.

Thunderbird prüft die `update_url` periodisch und aktualisiert automatisch auf die
neueste dort gelistete Version.

**Nach dem Release verifizieren** (anonym, genau wie Thunderbird):

```bash
curl -L .../raw/branch/main/updates.json            # muss JSON liefern, nicht die Login-Seite
curl -sI -L .../releases/download/vX/...xpi          # Content-Type: application/octet-stream
```

## Bekannte Grenzen / nächste Schritte

- **PDF** ist v1 ein einfaches Text-PDF (Kopf + Klartext-Body) ohne HTML-Layout/Bilder.
- **Auth**: primär DocuWare Identity Service (OAuth, ROPC mit öffentlichem Client),
  Fallback Cookie-Logon für alte On-Prem-Server. Passwort wird nicht gespeichert
  (Token nur im RAM, 1× Abfrage pro Sitzung).
- **Upload-Multipart-Format** ggf. je nach DocuWare-Version anpassen
  (`docuware.js → uploadDocument`).
- Mehrfachauswahl von Mails: aktuell wird die erste markierte Mail abgelegt.