ADR-0062: Dateiablage über StorageBackend, Nextcloud (WebDAV) als Projektarchiv

• Status: proposed — teilweise abgelöst durch ADR-0063 (Linetra ist Index und Quelle der Wahrheit, Nextcloud wird einseitiger Spiegel; Volltextsuche liegt in Linetra). SharePoint und Google Drive werden in ADR-0064 (geplant; opt-in je Mandant als zusätzlicher Auftragsverarbeiter) neu bewertet. Der Inhalt unten bleibt als Ausgangslage stehen.
• Datum: 2026-10-02
• Phase: Prozessmanagement
• Bezug: ADR-0005, ADR-0059, ADR-0060

Kontext

Fotos und Dokumente aus dem Feld sollen zur Aufgabe im Tracker und in eine nachvollziehbare Ordnerstruktur in der Cloud. Heute liegen Uploads (entity_files) auf dem Compose-Volume FILE_STORAGE_DIR; Jira-Anhänge sind in Jira gefangen (Kunde ohne Jira-Account sieht sie nicht, Export ist mühsam). Die Betreiberfirma nutzt Nextcloud.

Entscheidung

1. StorageBackend-Protocol in storage/ (put(path, bytes, content_type), exists, delete, share_link optional). Adapter: LocalVolumeBackend (heutiges Verhalten) und WebDavBackend (Nextcloud, App-Passwort). S3/MinIO später, kein Umbau.
2. Volume bleibt Primärablage für entity_files (Download-Endpunkt, Idempotenz, Thumbnails). Nextcloud ist das Projektarchiv, Tracker-Anhang die Zweitkopie am Issue. Reihenfolge: Volume (sofort beim Eingang) → Freigabe durch das Backoffice (ADR-0061, Aktion attach) → Tracker → Nextcloud; jeder Schritt idempotent über media_sha256. Vor der Freigabe liegt die Datei nur auf dem Volume und ist in der Freigabe-Queue sichtbar; der Reviewer kann Issue und Dateiname ändern oder die Datei abweisen.
3. Ordner-Policy (konfigurierbar, Default):

{root}/{kunde}/{projekt}/{issue_key}/{yyyymmdd}_{hhmm}_{absender}_{originalname}
{root}/{kunde}/{projekt}/_unzugeordnet/{yyyymmdd}_{hhmm}_{absender}_{originalname}

kunde = Organisation des Projekts, projekt = Projektname (slugifiziert). _unzugeordnet nutzt nur der Reviewer, wenn er eine Datei bewusst ohne Issue freigibt (Projektdokument); abgewiesene Dateien werden nicht archiviert und fallen unter die Löschfrist aus ADR-0060. 4. Metadaten stehen in message_attachments.storage_path und tracker_attachment_id; Nextcloud selbst ist kein Index. Volltextsuche über Dateien ist nicht Teil dieser Entscheidung. 5. Zugangsdaten in integration_connections(provider='nextcloud'): base_url, config.root_path, App-Passwort verschlüsselt. Ein technischer Nextcloud-Benutzer, Freigaben an Kunden erfolgen in Nextcloud, nicht aus Linetra. 6. Fehlerverhalten: Nextcloud nicht erreichbar → Celery-Retry mit Backoff (max. 24 h), Datei bleibt auf dem Volume und am Issue; Status in der Inbox sichtbar. Kein Verlust, keine stille Lücke.

Begründung

Das Volume ist bereits die verlässliche Ablage mit Download-Endpunkt und Rechteprüfung; es zu ersetzen hätte keinen Nutzen. Nextcloud löst das eigentliche Problem: Kunden und Buchhaltung finden Fotos nach Projekt und Aufgabe, ohne Jira zu öffnen. WebDAV ist in Nextcloud Standard, braucht keine App-Installation und läuft auf der vorhandenen NAS. Die Abstraktion ist eine Datei und verhindert, dass webdav in der Pipeline hart verdrahtet wird.

Verworfene Alternativen

Folgen

• Bestehende entity_files-Uploads bleiben unverändert; nur Nachrichten-Anhänge laufen zusätzlich nach Nextcloud.
• Celery-Task storage.archive_attachment(attachment_id, tenant_id), idempotent, Retry.
• Settings-Route /settings/integrations zeigt Nextcloud-Verbindung mit Test („Ordner anlegen/löschen“).
• Löschfrist aus ADR-0060 betrifft Volume und Nachrichtentext; das Nextcloud-Archiv und die Tracker-Anhänge bleiben (Projektdokumentation).