Docs

KANBAN

Dokumentation

KANBAN

Das KANBAN-Plugin ist die zentrale Anlaufstelle für Kanban-Boards: unter
/kanban bündelt es die Boards aller aktiven Plugins in einem
Unified Kanban Board und stellt die gemeinsame Spalten-Pflege für
Kanban-Kategorien (Admin-Bereich) bereit.

Das Board ist quellenbasiert (Layer): Jede Quelle stammt von einer
KanbanSourceProvider-Implementierung des jeweiligen Plugins und zeigt deren
Karten:

  • Tickets (Plugin TICKET) — Spalten = Ticket-Statuses, Karten = aktive
    Tickets (Subtitle: Zuteilung, Farbe: Priorität)
  • Verträge (Plugin VERTRAG) — Spalten = Kanban-Kategorien, Karten =
    Verträge mit Kategorie (Subtitle: Mieter, Fallback-Titel „Vertrag #uuid")

Weitere Plugins können über dieselbe KanbanSourceProvider-Schnittstelle
eigene Kanban-Boards beisteuern (Details: Abschnitt
„Einen eigenen KanbanSourceProvider implementieren").

> Das Board braucht keine eigene Datenbank-Tabelle — die Karten kommen
> direkt aus den Quell-Plugins. Voraussetzung ist das KANBAN-Plugin plus
> mindestens ein Plugin mit Kanban-Quelle (z. B. TICKET oder VERTRAG).
> Die bisherige Kategorien-Pflege für Verträge bleibt unter
> Admin → Kanban (/settings/admin/kanban) erhalten.


  • Kanban-Board öffnen (/kanban)
  • Quellen (Layer) ein-/ausblenden
  • Karten per Drag & Drop zwischen Spalten verschieben
  • Karte anklicken → Detailseite des Quell-Plugins
  • Kanban-Kategorien verwalten (Admin → Kanban)

1) Kanban-Board öffnen

  1. Kanban im Menü öffnen (/kanban). Berechtigung: kanban.board.view.
  2. Die aktiven Quellen erscheinen als Tabs (z. B. „Tickets", „Verträge");
    die erste aktive Quelle ist standardmäßig aktiv.
  3. Über die Layer-Leiste („Quellen") lassen sich Quellen ein-/ausblenden —
    die Einstellung wird pro User gespeichert (Pref kanban.layer.<PLUGINKEY>,
    z. B. kanban.layer.TICKET / kanban.layer.VERTRAG). Standard ist an.
  4. Der aktive Tab steht in der URL (/kanban?tab=VERTRAG) — Links sind damit
    teilbar. Die Vertragsliste verweist über ihren Kanban-Tab ebenfalls auf
    /kanban?tab=VERTRAG.

> Ohne aktive Quelle erscheint ein Leerer-Zustand mit Link zum
> Kanban-Setup (/settings/admin/kanban). Sind alle Quellen per
> Layer-Toggle ausgeblendet, wird ein Hinweisbanner angezeigt.

2) Karten verschieben (Drag & Drop)

  • Karte mit Maus / Touch in eine andere Spalte ziehen.
  • Der Move wird per POST /kanban/move (Parameter pluginKey, cardRef,
    zielSpalte) an die passende Quelle delegiert. Berechtigung:
    kanban.board.edit.
  • Tickets: Move = Statuswechsel — wie der Einzel-Statuswechsel
    (POST /tickets/{id}/status), inkl. Audit-Entry und Mail-Notiz.
    Zusätzlich ist die Berechtigung ticket.tickets.edit erforderlich;
    ein unbekannter Zielstatus wird abgelehnt.
  • Verträge: Move = Kategorie-Zuweisung über die gemeinsame
    VertragKanbanService — gleiche Semantik wie der Bestands-Endpoint
    POST /dokumente/vertraege/kanban/move (Change-Log-Eintrag
    „KANBAN_MOVED", Mail-Event).
  • Schlägt der Move fehl (Rechte, Ziel existiert nicht, …), gibt das UI
    einen Toast („Verschieben fehlgeschlagen") aus und lädt die Seite neu,
    damit UI und Daten wieder synchron sind.
  • Erledigt-Spalten: Wird eine Karte in eine Spalte mit dem „Erledigt"-Badge gezogen,
    erscheint vor dem Move ein Bestätigungsdialog (M27.2-12). Abbrechen lädt das
    Board neu (Server-Zustand ist autoritativ).

3) Karte anklicken

  • Jede Karte ist ein Klick-Target und öffnet die Detailseite des
    Quell-Plugins (z. B. /tickets/{uuid}, /dokumente/vertraege/{uuid}).
  • In der Detailseite führt der „Zurück"-Button (M27.2-13) bei interner
    Herkunft (z. B. aus dem Board, inkl. Tab- und Filter-Query) per
    Referrer-Prüfung wieder zurück zum Board; ohne Referrer (oder bei externem
    Aufruf) gilt die Listenansicht des Quell-Plugins.

4) Kanban-Kategorien verwalten (Admin → Kanban)

  1. Öffnen Sie Admin → Kanban (/settings/admin/kanban).
  2. Sie sehen die Liste der konfigurierten Spalten („Kategorien") in aktueller
    Reihenfolge. Die Karten-Anzahl je Spalte liefert die jeweilige Kanban-
    Quelle über die Spalten-SPI (Issue #792); inaktive oder fehlerhafte
    Quellen zeigen einen Platzhalter statt einer Zahl.
  3. Anlegen: Namen eintragen, speichern
    (POST /settings/admin/kanban).
  4. Umbenennen: „Umbenennen" → Name eintragen → speichern
    (POST /settings/admin/kanban/{id}/rename).
  5. Reihenfolge: Pfeil hoch / runter
    (POST /settings/admin/kanban/{id}/up bzw. /down).
  6. Sonderfunktionen (pro Kategorie):
    • „Anfragen"-Spalte: Hier landen automatisch neue Verträge aus dem
      HOMEPAGE-Anfrageformular
      (POST /settings/admin/kanban/{id}/toggle-anfragen).
    • „Abgeschlossen"-Spalte: Verträge in dieser Spalte werden in Listen /
      Statistiken separat behandelt
      (POST /settings/admin/kanban/{id}/toggle-abgeschlossen).
      > Es kann jeweils sinnvoll nur eine „Anfragen"- und
      > eine „Abgeschlossen"-Spalte geben.
  7. Löschen: POST /settings/admin/kanban/{id}/delete — nur löschbar, wenn
    keine aktive Quelle Karten in der Spalte zählt (Karten-Zahlen liefert die
    jeweilige Quelle über die Spalten-SPI, Issue #792); Karten in anderen
    Spalten bleiben unangetastet. Liefert eine aktive Quelle ihre Zahlen nicht,
    ist Löschen gesperrt (sichtbarer Hinweis statt stillschweigender 0).

Plugins registrieren ihre Karten über das Plugin-SPI
app.allesda.core.kanbanboard.KanbanSourceProvider (app-core). Die
KanbanSourceRegistry (ebenfalls app-core, @Component) sammelt alle
KanbanSourceProvider-Beans automatisch — neue Quellen erscheinen im Board
ohne jede Core-Änderung
. Das Tenant-Filtering (nur aktive Plugins) macht
die Registry, nicht der Provider.

Interface: Methode für Methode

Methode Aufgabe
String pluginKey() Plugin-Key gemäß tenant.getEnabledPluginKeys() (z. B. "ERP"). Die Registry filtert danach — nur Provider aktiver Plugins liefern ein Layer.
String labelKey() i18n-Key für das Tab-/Layer-Label (z. B. "erp.kanban.layer"). Fehlt der Key (oder ist er leer), fällt das UI auf den Plugin-Key zurück.
KanbanBoardDto board(TenantInfo tenant, String username) Liefert das Board des Plugins: KanbanBoardDto(pluginKey, labelKey, columns) mit KanbanColumnDto(key, name, order, cards) und KanbanCardDto(ref, title, subtitle, colorHex, detailUrl, order). ref ist der plugin-interne Bezeichner der Karte; subtitle, colorHex und detailUrl sind optional (null erlaubt). Welche Karten sichtbar sind, entscheidet die Quelle selbst (keine Daten-Leaks über Plugins). null ist erlaubt (leeres Board).
void move(String cardRef, String zielSpalte, TenantInfo tenant, String username) Verschiebt eine Karte in eine andere Spalte — delegiert an die eigene Plugin-Logik (Statuswechsel, Kategorie-Zuweisung …). Eigenen Rechte-Check durchführen (z. B. ticket.tickets.edit) und bei Fehlern werfen (z. B. IllegalArgumentException mit i18n-Key).

> Issue #687 – Spalten- und Karten-Metadaten: KanbanColumnDto trägt
> optional die Flags newItems (Spalte, in die neue Einträge gelegt werden,
> z. B. Formular-Ziel) und done (Erledigt-/Terminal-Spalte); KanbanCardDto
> trägt optional fields (zusätzliche Info-Zeilen, z. B. Mieter/Priorität),
> startDate/endDate (ISO-Daten für die Client-Zeitfilterung) und
> searchText (vorberechneter Suchtext). Die bisherigen 4- bzw.
> 6-Argument-Konstruktoren bleiben per Kompatibilitäts-Overloads verfügbar.

Beispiel-Snippet (Plugin „ERP")

@Component
public class ErpKanbanSource implements KanbanSourceProvider {

    private final ErpService erpService;

    public ErpKanbanSource(ErpService erpService) {
        this.erpService = erpService;
    }

    @Override
    public String pluginKey() {
        return "ERP";
    }

    @Override
    public String labelKey() {
        return "erp.kanban.layer";
    }

    @Override
    public KanbanBoardDto board(TenantInfo tenant, String username) {
        List<KanbanColumnDto> columns = new ArrayList<>();
        for (ErpStatus status : erpService.statuses()) {
            List<KanbanCardDto> cards = erpService.aktiveAuftraege(status).stream()
                .map(a -> new KanbanCardDto(
                    a.getUuid().toString(),          // cardRef
                    a.getTitel(),
                    a.getMitarbeiter(),              // subtitle
                    null,                            // colorHex (UI-Fallback)
                    "/erp/auftraege/" + a.getUuid(), // detailUrl
                    0))
                .collect(Collectors.toList());
            columns.add(new KanbanColumnDto(status.getKey(), status.getLabel(),
                status.getSortOrder(), cards));
        }
        return new KanbanBoardDto(pluginKey(), labelKey(), columns);
    }

    @Override
    public void move(String cardRef, String zielSpalte, TenantInfo tenant, String username) {
        if (!permissionService.hasPermission(username, "erp.auftraege.edit")) {
            throw new IllegalArgumentException("erp.kanban.no_permission");
        }
        erpService.changeStatus(UUID.fromString(cardRef), zielSpalte);
    }
}

> Fehler-Isolation: Die KanbanSourceRegistry ruft jede Quelle in einem
> eigenen try/catch auf: Wirft board() oder liefert es null, wird das
> Problem geloggt und die Quelle übersprungen — die Boards der übrigen
> Quellen werden trotzdem ausgeliefert. Dasselbe gilt für move(): Ein Fehler
> in einer Quelle bricht den Aufruf nicht ab und macht das Board nicht
> unbrauchbar. Ein einzelner defekter Provider lässt das Kanban-Board also
> niemals komplett abbrechen.


„Ich sehe /kanban nicht"

  • KANBAN-Plugin für den Mandanten aktiviert? (Sonst: /plugin-disabled.)
  • Berechtigung kanban.board.view vergeben (über ROLLEN)?

„Karten lassen sich nicht verschieben"

  • Berechtigung kanban.board.edit vorhanden?
  • Plugin-spezifische Rechte: beim TICKET-Move zusätzlich
    ticket.tickets.edit; beim VERTRAG-Move die üblichen
    Vertragsrechte (Sperre-Check wird mit Force umgangen, da der
    Board-Route USER_ADMIN vorbehalten ist).
  • Schlägt der Move fehl, zeigt das UI einen Toast — Server-Log (Logging-Plugin)
    mit Kanban-Quelle … konnte Karte … nicht verschieben prüfen.

„Eine Quelle fehlt im Board"

  • Quell-Plugin im Tenant aktiviert? Nur aktive Plugins liefern Quellen.
  • Layer per Layer-Toggle ausgeblendet? Pref kanban.layer.<PLUGINKEY> des
    Users prüfen (Standard ist an).
  • Quelle wirft Fehler? Server-Log: Kanban-Quelle … hat Board nicht liefern können — die Registry isoliert und überspringt fehlerhafte Quellen.

„Karten aus einem Quell-Plugin stimmen nicht"

  • Sichtbare Karten entscheidet die Quelle (z. B. zeigt TICKET nur aktive
    Tickets, VERTRAG nur Verträge mit Kategorie). Korrigieren Sie die Daten an
    der Quelle (z. B. Status im Ticket-Plugin, Kategorie am Vertrag).

Nutzerbereich:

  • GET /kanban – Unified Kanban Board (optional ?tab=PLUGINKEY für tiefe Links)
  • POST /kanban/move – Karte verschieben (DnD; Parameter pluginKey, cardRef, zielSpalte; Berechtigung kanban.board.edit)
  • POST /kanban/toggle-layer – Quelle ein-/ausblenden (Pref kanban.layer.<KEY>, nur aktive Provider)

Admin (/settings/admin/kanban):

  • GET /settings/admin/kanban – Kategorien-Übersicht
  • POST /settings/admin/kanban – Kategorie anlegen
  • POST /settings/admin/kanban/{id}/rename
  • POST /settings/admin/kanban/{id}/delete
  • POST /settings/admin/kanban/{id}/up
  • POST /settings/admin/kanban/{id}/down
  • POST /settings/admin/kanban/{id}/toggle-anfragen
  • POST /settings/admin/kanban/{id}/toggle-abgeschlossen

Bestands-Endpunkte der Quell-Plugins:

  • POST /tickets/{id}/status – Ticket-Statuswechsel (TICKET)
  • POST /dokumente/vertraege/kanban/move – Vertrag in Kategorie verschieben (VERTRAG)

  • Alle /kanban-Routes sind KANBAN-gated: ist das Plugin im Tenant
    deaktiviert, leiten sie auf /plugin-disabled um.
  • Die Layer-Toggles sind pro User (Pref kanban.layer.<KEY>, Standard
    an) und betreffen nur die Darstellung — nicht die Daten der Quellen.
  • Karten sind Klick-Targets: der Klick öffnet die detailUrl des
    Quell-Plugins (nach einem Drag wird der Klick für kurze Zeit unterdrückt).
  • Farbkennzeichnung der Quellen wird deterministisch aus dem Plugin-Key
    abgeleitet (Hash); colorHex der Karte (z. B. Ticket-Priorität) übersteuert
    die Quellenfarbe auf Karten-Ebene.
  • Neue Quellen kommen von KanbanSourceProvider-Beans der jeweiligen Plugins
    — KANBAN selbst filtert nur nach Tenant und User-Prefs; die
    Sichtbarkeits-/Rechte-Logik bleibt im Quell-Plugin (Fehler-Isolation in der
    Registry).
  • Die Inline-Kanban-Ansicht in der Vertragsliste wurde entfernt (M27.2-04):
    der Kanban-Tab verweist jetzt auf das zentrale Board
    (/kanban?tab=VERTRAG).