Split the docs: README for users, DEVELOPMENT.md for developers

The README now explains setup, workflows, the mail options with Deck's
real menu names, and what happens when boards or stacks disappear -
without class names. Architecture, data model, tests, CI, release and
the time_sensitive troubleshooting move to DEVELOPMENT.md, fixing the
stale CI table, PHP version and Nextcloud version on the way.
DEVELOPMENT.md is excluded from the app package.

README.md

@@ -1,142 +1,82 @@
 # Deck Workflow-Automatisierung
 
-Nextcloud-App für **Nextcloud Hub Summer 26 (Server 35.x)**, die überfällige Karten der [Deck](https://github.com/nextcloud/deck)-App automatisch von einem Stapel in einen anderen verschiebt und optional eine E-Mail-Benachrichtigung verschickt.
+Nextcloud-App für **Nextcloud 35**, die überfällige Karten der [Deck](https://apps.nextcloud.com/apps/deck)-App automatisch von einem Stapel in einen anderen verschiebt und auf Wunsch per E-Mail darüber informiert.
 
-Ersetzt das früher genutzte eigenständige PHP-Cron-Skript durch eine vollwertige App mit Oberfläche in den **persönlichen Einstellungen** — jeder Nutzer kann dort seine eigenen Regeln ("Workflows") anlegen, ohne Admin-Rechte oder Server-Zugriff zu benötigen.
+Jeder Nutzer richtet seine Regeln („Workflows“) selbst in den **persönlichen Einstellungen** ein, ohne Admin-Rechte.
 
-## Funktionsumfang
+> Entwickler-Informationen (Aufbau, Tests, Build, Release) stehen in [DEVELOPMENT.md](DEVELOPMENT.md).
 
-Pro Workflow lässt sich konfigurieren:
+## Was die App macht
 
-- Quell-Board und Quell-Stapel
-- Ziel-Stapel, in den **alle** überfälligen Karten des Quell-Stapels verschoben werden
-- E-Mail-Benachrichtigung über verschobene Karten, in drei Stufen:
-  - **Keine E-Mail**
-  - **Nur an mich** – an den Board-Eigentümer, unabhängig von seinen Deck-Einstellungen
-  - **An Board-Mitglieder laut Deck-Einstellung** – an alle, die das Board sehen dürfen (Eigentümer, freigegebene Nutzer, Mitglieder freigegebener Gruppen und Teams), gefiltert nach deren eigener Deck-Einstellung *Benachrichtigungen* für dieses Board: *Alle Karten* → immer, *Zugewiesene Karten* (Deck-Standard) → nur wenn man der Karte direkt oder über eine Gruppe/ein Team zugewiesen ist, *Keine* → nie. Der Eigentümer eines nicht geteilten Boards bekommt wie in Deck jede Karte, außer er hat *Keine* gewählt.
+Ein Workflow besteht aus einem Board, einem **Quell-Stapel** und einem **Ziel-Stapel**. Bei jedem Durchlauf verschiebt die App **alle überfälligen Karten** des Quell-Stapels oben in den Ziel-Stapel.
 
-  Pro Lauf des Hintergrundjobs bekommt jeder Empfänger höchstens **eine** Sammelmail mit allen für ihn verschobenen Karten.
+Überfällig ist eine Karte, deren Fälligkeitsdatum samt Uhrzeit überschritten ist. Karten ohne Fälligkeitsdatum sowie erledigte, archivierte oder gelöschte Karten bleiben liegen. Es gibt keine weiteren Filter nach Labels oder Personen.
 
-Die App ist für den internen Einsatz gedacht und durchgehend **deutschsprachig** (Oberfläche, Fehlermeldungen, E-Mails). Es gibt keine Übersetzungsdateien.
+Beispiel: Ein Workflow „Waiting → ToDo“ holt jede Karte aus „Waiting / Blocked“ nach „Work in Progress / ToDo“, sobald ihr Fälligkeitsdatum erreicht ist.
 
-Workflows lassen sich nur für Boards anlegen, deren Eigentümer man ist. Ein Workflow gehört dem jeweiligen Board-Eigentümer, nicht dem, der ihn angelegt hat: Wird ein Board in Deck übertragen, sieht und verwaltet ab sofort der neue Eigentümer seine Workflows, und der Hintergrundjob läuft in dessen Namen. Ein Nutzer kann beliebig viele Workflows anlegen, bearbeiten, deaktivieren oder löschen.
+## Einrichtung (für Administratoren)
 
-## Architektur
+1. App nach `apps/workflow_deck_automation` auf den Server kopieren, zum Beispiel aus dem Release-Archiv `workflow_deck_automation.tar.gz`, und unter *Apps* aktivieren.
+2. Die [Deck-App](https://apps.nextcloud.com/apps/deck) muss installiert und für die Nutzer aktiviert sein.
+3. Die [Hintergrundjobs](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html) müssen auf *Cron* stehen.
+4. Für E-Mails muss in der Nextcloud-Administration ein Mailserver eingerichtet sein.
 
-- **Keine HTTP/OCS-Aufrufe gegen Deck.** Alles Lesen (Boards, Stapel, Karten) und das Verschieben von Karten läuft ausschließlich über Decks eigene interne PHP-Klassen (`OCA\Deck\Service\CardService`, `StackService`, `BoardService`, `OCA\Deck\Db\CardMapper`, …), aufgelöst per Dependency Injection direkt im selben PHP-Prozess. Sämtlicher Deck-Zugriff ist in [`lib/Service/DeckIntegrationService.php`](lib/Service/DeckIntegrationService.php) gebündelt.
-- **Hintergrundjob statt Seitenaufruf.** [`lib/BackgroundJob/RunWorkflowsJob.php`](lib/BackgroundJob/RunWorkflowsJob.php) ist ein einfacher `Job` ohne eigenes Intervall: Er läuft bei jedem Cron-Durchlauf von Nextcloud (üblicherweise alle 5 Minuten) und ruft [`lib/Service/WorkflowRunner.php`](lib/Service/WorkflowRunner.php) auf.
-- **Rechte-Kontext je Nutzer.** Ein Hintergrundjob hat standardmäßig keinen eingeloggten Nutzer, muss aber die Regeln mehrerer Nutzer in einem einzigen Lauf auswerten. Der `WorkflowRunner` "verkörpert" deshalb für die Dauer der jeweiligen Workflows kurzzeitig den entsprechenden Besitzer. Dazu gehört mehr als `IUserSession::setUser()`: Decks Berechtigungsprüfungen lesen die Session gar nicht, sondern eine Benutzer-ID, die beim Bau des Deck-Containers einmal pro Prozess eingefroren wird. `DeckIntegrationService::beginUserContext()` setzt diesen Wert für die Dauer der Verkörperung auf den Workflow-Besitzer und stellt ihn danach wieder her; schlägt das fehl, wird der Nutzer in diesem Lauf übersprungen, statt unter fremden Rechten zu arbeiten.
-- **E-Mail** läuft über Nextclouds eigenen `IMailer` (nutzt also den in der Nextcloud-Administration hinterlegten Mailserver) und geht an die im Profil der jeweiligen Empfänger hinterlegte Adresse. Die Empfänger und ihre Deck-Einstellungen ermittelt die App ebenfalls über Decks interne Klassen bzw. die Nutzereinstellung `deck` / `board:<id>:notify-due`.
+Die Workflows laufen bei **jedem** Cron-Durchlauf von Nextcloud, üblicherweise alle 5 Minuten. Ein eigenes Intervall gibt es nicht.
 
-### Wichtiger Hinweis zu Decks internen Klassen
+## Workflows anlegen
 
-`OCA\Deck\*` ist keine dokumentierte, stabile öffentliche API von Deck (keine `@since`-Markierungen, keine offizielle Zusicherung von Abwärtskompatibilität). Diese App verwendet sie trotzdem bewusst direkt, wie es die Vorgabe verlangt — jeder Zugriff läuft defensiv abgesichert über `DeckIntegrationService` (Prüfung, ob Deck aktiviert ist, `class_exists()`-Checks, try/catch mit Logging statt Absturz). Nach größeren Deck-Updates lohnt sich ein Blick ins Nextcloud-Log, falls Workflows plötzlich nicht mehr greifen.
+Die Einstellungen liegen unter **Persönliche Einstellungen → Deck Workflow-Automatisierung**. Dort legst du Workflows an und kannst sie bearbeiten, deaktivieren oder löschen.
 
-## Installation
+- **Board:** Zur Auswahl stehen nur Boards, deren **Eigentümer** du bist. Geteilte, archivierte und gelöschte Boards erscheinen nicht.
+- **Quell- und Ziel-Stapel:** Das müssen zwei verschiedene Stapel desselben Boards sein.
+- **E-Mail bei verschobenen Karten:** siehe unten.
+- **Workflow aktiv:** Deaktivierte Workflows bleiben gespeichert, verschieben aber nichts.
 
-1. App in `apps/workflow_deck_automation` des Nextcloud-Servers ablegen (oder über den Appstore-Build aus der CI, siehe unten).
-2. In der Nextcloud-Administration unter *Apps* aktivieren.
-3. Die [Deck-App](https://apps.nextcloud.com/apps/deck) muss installiert und für die jeweiligen Nutzer aktiviert sein.
-4. Sicherstellen, dass der [Hintergrundjob-Modus](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html) auf *Cron (empfohlen)* steht, damit `RunWorkflowsJob` regelmäßig läuft.
+Ein Workflow gehört immer dem Eigentümer des Boards. Überträgst du ein Board in Deck an jemand anderen, wandern seine Workflows mit: Der neue Eigentümer sieht und verwaltet sie ab sofort, und die Karten werden in seinem Namen verschoben.
 
-## Benutzung
+## E-Mail-Benachrichtigung
 
-Jeder Nutzer findet die Einstellungen unter **Persönliche Einstellungen → Deck Workflow-Automatisierung**. Dort können neue Workflows angelegt, bestehende bearbeitet oder gelöscht werden. Die Dropdowns für Board und Stapel werden live aus Deck geladen. Zur Auswahl stehen nur aktive Boards, deren Eigentümer man ist — geteilte, archivierte und im Papierkorb liegende Boards sowie gelöschte Stapel blendet die App aus.
+Pro Workflow gibt es drei Stufen:
 
-### Gelöschte Boards und Stapel
-
-Ein Workflow verweist per ID auf ein Board und zwei Stapel. Wird eines davon in Deck gelöscht, passiert Folgendes:
-
-- **Beim Speichern** werden Board und Stapel geprüft; ein Workflow auf nicht mehr existierende Ziele lässt sich gar nicht erst anlegen.
-- **In der Übersicht** wird ein betroffener Workflow rot markiert („Board nicht mehr vorhanden", „Quell-Stapel nicht mehr vorhanden" …).
-- **Im Hintergrundjob** wird der Workflow automatisch deaktiviert und der Besitzer einmalig per E-Mail informiert — unabhängig von der E-Mail-Einstellung des Workflows, denn hier geht es nicht um verschobene Karten, sondern darum, dass die Automatisierung nicht mehr läuft. Danach bleibt es still: Ein deaktivierter Workflow wird nicht erneut ausgewertet.
-
-Ist Deck vorübergehend nicht erreichbar, wird **nicht** deaktiviert — der Job überspringt den Workflow und versucht es beim nächsten Lauf erneut. Archivierte Boards lösen die Deaktivierung ebenfalls nicht aus, sie sind nur in den Auswahlfeldern ausgeblendet.
-
-## Ausführungstakt
-
-Der Hintergrundjob hat **kein eigenes Intervall** und ist auch nicht konfigurierbar: Er läuft bei **jedem** Cron-Durchlauf von Nextcloud. Der Takt ist damit exakt der des System-Crons — üblicherweise alle 5 Minuten, bei einem häufiger eingerichteten Cron entsprechend öfter.
-
-> Bis einschließlich v0.1.0 gab es dafür die `config.php`-Option `workflow_deck_automation.interval`. Sie ist entfallen und wird ignoriert; ein vorhandener Eintrag kann aus der `config.php` entfernt werden.
-
-### Der Job läuft nur nachts bzw. gar nicht
-
-Nextcloud merkt sich in der Spalte `time_sensitive` der Tabelle `oc_jobs`, ob ein Job zeitkritisch ist, und überspringt „unkritische" Jobs außerhalb des Wartungsfensters. `JobList::setLastRun()` setzt diese Spalte nur in eine Richtung — von „zeitkritisch" auf „unkritisch", nie zurück. Wer eine ältere Version dieser App installiert hatte (bis einschließlich v0.1.0 war der Job `TIME_INSENSITIVE`), hat diesen Stempel noch in der Datenbank. Er wird weder durch ein App-Update noch durch `app:enable` zurückgesetzt.
-
-Symptom: Ist in der `config.php` ein `maintenance_window_start` gesetzt, läuft der Job nur in diesem 4-Stunden-Fenster und den Rest des Tages gar nicht.
-
-Einmalig korrigieren:
-
-```sql
-UPDATE oc_jobs SET time_sensitive = 0
- WHERE class = 'OCA\\WorkflowDeckAutomation\\BackgroundJob\\RunWorkflowsJob';
-```
-
-Ohne Datenbankzugriff geht es auch über `occ`, indem der Job gelöscht und durch Aus-/Einschalten der App neu registriert wird:
-
-```bash
-php occ background-job:list --class 'OCA\WorkflowDeckAutomation\BackgroundJob\RunWorkflowsJob'
-php occ background-job:delete <id>
-php occ app:disable workflow_deck_automation
-php occ app:enable workflow_deck_automation
-```
-
-Neuinstallationen sind nicht betroffen.
-
-## Entwicklung
-
-Voraussetzungen: PHP 8.2+, Composer, Node.js 24+, npm 11+.
-
-```bash
-composer install
-npm install
-npm run build      # einmaliger Produktions-Build
-npm run watch       # Entwicklung mit automatischem Rebuild
-```
-
-### Tests & Linting
-
-```bash
-composer run lint       # php -l über lib/ und tests/
-composer run cs:check   # nextcloud/coding-standard (php-cs-fixer)
-composer run test:unit  # PHPUnit — reine Logik (Fälligkeitsprüfung), benötigt keine Deck-Installation
-```
-
-Ein echter End-to-End-Test (Karte anlegen, Workflow konfigurieren, Hintergrundjob auslösen, Verschiebung + Mail prüfen) lässt sich nur gegen eine echte Nextcloud-34-Instanz mit installierter Deck-App durchführen, z. B. per:
-
-```bash
-# Job-ID und letzten Lauf anzeigen
-php occ background-job:list --class 'OCA\WorkflowDeckAutomation\BackgroundJob\RunWorkflowsJob'
-
-# Sofort ausführen, ohne auf den nächsten Cron-Durchlauf zu warten
-php occ background-job:execute <id> --force-execute
-
-# Oder dauerhaft als Worker laufen lassen (Argument ist die Job-Klasse, keine App-ID)
-php occ background-job:worker 'OCA\WorkflowDeckAutomation\BackgroundJob\RunWorkflowsJob'
-```
-
-### Release-Paket bauen
-
-```bash
-make appstore
-```
-
-Erzeugt `build/artifacts/appstore/workflow_deck_automation.tar.gz`.
-
-## CI (Gitea Actions)
-
-In [`.gitea/workflows/`](.gitea/workflows/):
-
-| Workflow | Zweck |
+| Einstellung | Wer bekommt eine E-Mail? |
 | --- | --- |
-| `lint-php.yml` | `php -l` über eine PHP-8.2–8.4-Matrix |
-| `lint-info-xml.yml` | validiert `appinfo/info.xml` gegen das Appstore-XML-Schema |
-| `phpunit.yml` | führt die PHPUnit-Tests aus (SQLite/rein logisch, kein DB-Service nötig) |
-| `build-main.yml` | baut Frontend + Appstore-Archiv und veröffentlicht es als Release-Asset — bei Push auf `main` als rollendes Pre-Release `latest-main`, bei Push eines `v*`-Tags als reguläres Release |
+| **Keine E-Mail** | niemand |
+| **Nur an mich** | der Eigentümer des Boards, unabhängig von seinen Deck-Einstellungen |
+| **An Board-Mitglieder laut ihrer Deck-Einstellung** | alle, die das Board sehen dürfen, je nach ihrer eigenen Deck-Einstellung (siehe unten) |
 
-## Datenmodell
+Bei der dritten Stufe entscheidet jedes Board-Mitglied selbst. Dazu gehören der Eigentümer, Personen mit Freigabe sowie Mitglieder freigegebener Gruppen und Teams. Die Einstellung liegt in Deck im Menü **…** neben dem Board unter **Fälligkeitserinnerungen**:
 
-Workflows werden in der Tabelle `wfda_workflows` gespeichert (siehe [`lib/Migration/Version1000Date20260813120000.php`](lib/Migration/Version1000Date20260813120000.php)): eine Zeile pro Workflow, mit Board-/Stapel-IDs, `user_id` (der Board-Eigentümer, in dessen Namen der Job läuft — wird bei jedem Lauf aus Deck aktualisiert) sowie `enabled`/`notify_mode`/`last_run`. Die früheren Filter-Spalten `filter_user_ids`/`filter_label_ids` entfernt [`Version1001Date20260930120000`](lib/Migration/Version1001Date20260930120000.php). [`Version1002Date20261001120000`](lib/Migration/Version1002Date20261001120000.php) ersetzt das frühere Ja/Nein-Feld `notify_email` durch `notify_mode` (`off`/`owner`/`board`; gesetztes Häkchen → `owner`), [`Version1003Date20261001120100`](lib/Migration/Version1003Date20261001120100.php) entfernt die alte Spalte.
+- **Alle Karten:** eine E-Mail für jede verschobene Karte
+- **Zugewiesene Karten** (Deck-Standard): nur für Karten, denen man zugewiesen ist, direkt oder über eine Gruppe oder ein Team
+- **Keine Benachrichtigungen:** keine E-Mail
+
+Bei einem Board, das mit niemandem geteilt ist, bekommt der Eigentümer jede Karte gemeldet, außer er hat die Erinnerungen ausgeschaltet. So verhält sich auch Deck selbst.
+
+**Inhalt der E-Mail:** Jeder Empfänger bekommt pro Durchlauf höchstens **eine** E-Mail, auch wenn mehrere Karten verschoben wurden. Pro Karte steht darin ein Satz wie:
+
+> „Essensvorräte prüfen“ (Board „Persönlich“) ist überfällig und wurde von „Waiting / Blocked“ nach „Work in Progress / ToDo“ verschoben.
+
+Der Kartentitel ist ein Link direkt zur Karte in Deck. Die Kartenbeschreibung wird nicht mitgeschickt.
+
+**Keine E-Mail erhalten?**
+- Ist in deinem Nextcloud-Profil eine E-Mail-Adresse hinterlegt? Ohne Adresse wird die E-Mail übersprungen.
+- Welche Stufe ist im Workflow eingestellt?
+- Bei „An Board-Mitglieder“: Was steht in Deck unter *Fälligkeitserinnerungen* für dieses Board?
+
+Deck schickt zusätzlich seine eigene Erinnerung, wenn eine Karte fällig wird. Diese Glocken-Benachrichtigung kommt von Deck, nicht von dieser App.
+
+## Wenn Board oder Stapel gelöscht werden
+
+- **In der Übersicht** wird der Workflow rot markiert, zum Beispiel „Board nicht mehr vorhanden“ oder „Quell-Stapel nicht mehr vorhanden“.
+- **Beim nächsten Durchlauf** wird der Workflow automatisch deaktiviert. Der Eigentümer bekommt einmalig eine E-Mail, auch wenn für den Workflow „Keine E-Mail“ eingestellt ist. Danach kommt keine weitere Erinnerung.
+- **Archivierte Boards** deaktivieren den Workflow nicht. Sie lassen sich nur nicht mehr neu auswählen.
+- **Ist Deck vorübergehend nicht erreichbar**, passiert nichts: Der Workflow wird übersprungen und beim nächsten Durchlauf erneut versucht.
+
+Um einen deaktivierten Workflow wieder zu nutzen, stellst du ein vorhandenes Board und vorhandene Stapel ein und aktivierst ihn wieder.
+
+## Sprache
+
+Die App ist für den internen Einsatz gedacht und durchgehend **deutsch**: Oberfläche, Fehlermeldungen und E-Mails.
 
 ## Lizenz