KANBAN
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 einerKanbanSourceProvider-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
- Kanban im Menü öffnen (
/kanban). Berechtigung:kanban.board.view. - Die aktiven Quellen erscheinen als Tabs (z. B. „Tickets", „Verträge");
die erste aktive Quelle ist standardmäßig aktiv. - Über die Layer-Leiste („Quellen") lassen sich Quellen ein-/ausblenden —
die Einstellung wird pro User gespeichert (Prefkanban.layer.<PLUGINKEY>,
z. B.kanban.layer.TICKET/kanban.layer.VERTRAG). Standard ist an. - 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(ParameterpluginKey,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 Berechtigungticket.tickets.editerforderlich;
ein unbekannter Zielstatus wird abgelehnt. - Verträge: Move = Kategorie-Zuweisung über die gemeinsame
VertragKanbanService— gleiche Semantik wie der Bestands-EndpointPOST /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)
- Öffnen Sie Admin → Kanban (
/settings/admin/kanban). - 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. - Anlegen: Namen eintragen, speichern
(POST /settings/admin/kanban). - Umbenennen: „Umbenennen" → Name eintragen → speichern
(POST /settings/admin/kanban/{id}/rename). - Reihenfolge: Pfeil hoch / runter
(POST /settings/admin/kanban/{id}/upbzw./down). - 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.
- „Anfragen"-Spalte: Hier landen automatisch neue Verträge aus dem
- 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-SPIapp.allesda.core.kanbanboard.KanbanSourceProvider (app-core). DieKanbanSourceRegistry (ebenfalls app-core, @Component) sammelt alleKanbanSourceProvider-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.viewvergeben (über ROLLEN)?
„Karten lassen sich nicht verschieben"
- Berechtigung
kanban.board.editvorhanden? - 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)
mitKanban-Quelle … konnte Karte … nicht verschiebenprü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=PLUGINKEYfür tiefe Links)POST /kanban/move– Karte verschieben (DnD; ParameterpluginKey,cardRef,zielSpalte; Berechtigungkanban.board.edit)POST /kanban/toggle-layer– Quelle ein-/ausblenden (Prefkanban.layer.<KEY>, nur aktive Provider)
Admin (/settings/admin/kanban):
GET /settings/admin/kanban– Kategorien-ÜbersichtPOST /settings/admin/kanban– Kategorie anlegenPOST /settings/admin/kanban/{id}/renamePOST /settings/admin/kanban/{id}/deletePOST /settings/admin/kanban/{id}/upPOST /settings/admin/kanban/{id}/downPOST /settings/admin/kanban/{id}/toggle-anfragenPOST /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-disabledum. - 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
detailUrldes
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);colorHexder 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).