ClaudeDo/docs/superpowers/specs/2026-08-27-ticketsystem-integration-design.md

# Ticketsystem-Anbindung (Bandel TicketSystem)

Datum: 2026-08-27
Status: Design freigegeben, Umsetzung offen

## Ziel

Tickets aus dem hauseigenen Ticketsystem (`Bandel.APIs`) pro Projekt in eine ClaudeDo-Liste
importieren und den Ticket-Status automatisch nachziehen, während der Task durch die Queue läuft.

Das Feature ist **vollständig optional**: ohne konfigurierte Base-URL passiert nichts — kein
Netzwerkverkehr, kein Hook, kein sichtbarer Menüeintrag.

## Nicht-Ziele (bewusst weggelassen)

| Weggelassen | Wann nachrüsten |
|---|---|
| Polling / Hintergrund-Sync | Wenn der manuelle Import spürbar nervt |
| Zwei-Wege-Sync (Ticket-Änderung → Task) | Wenn Titel/Beschreibung real auseinanderlaufen |
| Jira-Provider + `ITicketProvider`-Interface | Wenn Jira tatsächlich kommt — Interface-Extract ist ein Rider-Refactor von 30 s |
| Update bereits importierter Tickets | Würde Task-Notizen überschreiben; erst mit klarer Merge-Regel |
| Kommentar ans Ticket beim Merge | Wenn die Rückverfolgbarkeit fehlt |

Der einzige Vorgriff auf Jira ist das Provider-Präfix in `TaskEntity.TicketRef` (`bandel:1234`).
Das kostet nichts und erspart später eine Migration.

## Externe API

Base-URL: `http://bandelapis.fb-tuning.local`
Auth: derselbe Personal Access Token (`tsp_…`), den auch der Ticket-MCP nutzt.
Die relevanten Endpunkte akzeptieren `[Authorize(AuthenticationSchemes = "Bearer,Pat")]`.

| Zweck | Endpoint | Scope |
|---|---|---|
| Token-Inhaber ermitteln | `GET /api/ticketsystem/pat/me` | — (keine Scope-Policy) |
| Projekte je Abteilung | `GET /api/Navigation/sidebar` | `pat:projects:read` |
| Board eines Projekts | `GET /api/Board/project/{projectId}` | `pat:board:read` |
| Status setzen | `PATCH /api/Ticket/{id}/status` | `pat:tickets:write` |

Antworten sind in `BandelApiResponse<T>` gewrappt (`{ Success, Data, Message, ErrorCode }`).
Das Board liefert `GetTicketSummaryDto` mit u. a. `Id`, `Title`, `Description`, `StatusId`,
`StatusName`, `AssigneeID`, `AssigneeName`.

Ticket-Status: `0 Keine`, `1 Offen`, `2 InBearbeitung`, `3 Fertig`, `4 Archiviert`.

> **Nicht verifiziert:** Die API läuft auf srv-04b, gegen den hier nicht geprobt wurde. Die
> Endpunkte und DTO-Felder stammen aus dem Quellcode von `Bandel.APIs`, nicht aus einem
> Live-Aufruf. Der erste manuelle Smoke-Test muss die tatsächlichen Response-Shapes bestätigen
> (siehe „Manuelle Verifikation").

## Konfiguration

### Global

- `AppSettingsEntity.TicketApiBaseUrl` (`string?`, Spalte `ticket_api_base_url`).
  Null/leer = Feature aus.
- PAT: DPAPI-verschlüsselt in `~/.claudeDo/ticket.pat`, **CurrentUser-Scope**.
  `OnlineTokenStore` macht das bereits exakt so — ihm fehlt nur ein Dateiname-Parameter im
  parameterlosen Ctor. Der wird zum optionalen Argument, die Klasse wandert nach
  `ClaudeDo.Worker/` (raus aus `Online/`) und wird von beiden Features genutzt.
  **Kein neuer Krypto-Code.**

Der Token landet nie in `worker.config.json` und nie in der DB.

### Pro Liste

- `ListConfigEntity.TicketProjectId` (`int?`, Spalte `ticket_project_id`).
  Null = Liste ist nicht mit einem Ticket-Projekt verknüpft.

> ⚠️ **Verbatim-Copy-Falle:** `ListRepository.SetConfigAsync` überschreibt jede Spalte mit dem
> übergebenen Entity. Jeder Writer (`set_list_config` MCP-Tool, Listen-Settings-Modal) muss
> `TicketProjectId` mitführen, sonst setzt der nächste fremde Schreibvorgang die Verknüpfung
> still zurück — derselbe Fehler, der `SessionSkills` schon einmal getroffen hat.

## Datenmodell

- `TaskEntity.TicketRef` (`string?`, Spalte `ticket_ref`) — Format `<provider>:<id>`, aktuell
  immer `bandel:<ticketId>`. Kein Index nötig; der Import filtert über die Liste, nicht global.
- `ListConfigEntity.TicketProjectId` (`int?`)
- `AppSettingsEntity.TicketApiBaseUrl` (`string?`)

Eine EF-Migration mit drei Spalten über drei Tabellen.

> ⚠️ **Migrations-Kollision:** Parallel entstandene Migrationen vom selben Elternknoten löschen
> sich bei einem SQLite-Table-Rebuild gegenseitig die Spalten weg, und die Tests laufen mit
> `EnsureCreated` und merken es nicht. Diese Migration entsteht als einzelne, nachdem alle
> parallelen Tasks gemergt sind — nicht in einem Nebenläufer.

## Import: „Update from Ticketsystem"

Einstieg: Kontextmenü der Liste in `ListsIslandView.axaml`, direkt über „Einstellungen".
Sichtbar nur, wenn Base-URL gesetzt **und** die Liste ein `TicketProjectId` hat.

Ablauf (Worker, über eine neue Hub-Methode `ImportTicketsAsync(listId)`):

1. `GET /api/ticketsystem/pat/me` → `UserName` des Token-Inhabers.
2. `GET /api/Board/project/{TicketProjectId}` → Board-Items.
3. Filtern auf `StatusId == 1` (Offen) **und** `AssigneeName == UserName`
   (Ordinal, case-insensitive). Alles andere wird ignoriert.
4. Bereits vorhandene `TicketRef`-Werte der Liste laden; Treffer überspringen.
5. Pro verbleibendem Ticket ein Task via `TaskRepository.AddAsync`:
   - `Status = Idle`, `ListId` = die Liste
   - `Title` = Ticket-Titel
   - `Description` = Ticket-Beschreibung + Leerzeile + `Ticket #<id>`
   - `TicketRef = "bandel:<id>"`
   - `CreatedBy = "ticketsystem"`
6. Ergebnis als Footer-Meldung: „12 Tickets geprüft, 3 neue Tasks."

Der Import erzeugt nur `Idle`-Tasks — er queued nichts. Ob und wann etwas läuft, bleibt eine
bewusste Nutzeraktion.

**Warum Board-Filter statt `GET /api/Board/global/{userId}`:** Das globale Board wählt Items über
Zuweisung *oder* Reporter *oder* PersonInCharge aus. Das ist breiter als „mir zugewiesen".
Der Namensvergleich ist bewusst gewählt (`/pat/me` liefert keine UserId, und Benutzernamen
ändern sich hier nicht).

## Write-back: Hook in `TaskStateService`

`TaskStateService` ist der einzige Ort im System, der `Status` schreibt. Ein Hook dort deckt
Queue-Picker, Merge/Approve, Cancel, Reset und beide MCP-Oberflächen gleichzeitig ab — jede
andere Stelle wäre ein Teilabdeckungs-Fix.

| Task-Status | Ticket-Status |
|---|---|
| `Running`, `WaitingForReview` | `2 InBearbeitung` |
| `Done` | `3 Fertig` |
| alles andere (`Idle`, `Queued`, `WaitingForChildren`, `Failed`, `Cancelled`) | **kein Schreiben** |

`1 Offen` wird nie geschrieben: das ist der Eingangszustand. Ein fehlgeschlagener oder
abgebrochener Task lässt das Ticket bewusst auf `InBearbeitung` stehen — die Arbeit ist
angefangen, nicht zurückgegeben.

Auslösebedingungen (alle müssen gelten, sonst passiert nichts):

- `task.TicketRef` ist gesetzt und beginnt mit `bandel:`
- `TicketApiBaseUrl` ist konfiguriert und ein PAT liegt vor
- der Zielstatus unterscheidet sich vom letzten geschriebenen (kein redundanter PATCH bei
  `Running → WaitingForReview`, beide mappen auf `2`)

Der Aufruf ist fire-and-forget mit `try/catch`: ein Fehler wird als Warnung geloggt (landet über
`BroadcastLogSink` im Footer-Log-Strip) und beendet den Statuswechsel **nie**. Das Ticketsystem
darf die Queue nicht anhalten können.

## UI

### Settings-Modal — neuer Tab „Ticketsystem"

Unter „Erweitert", wie der Online-Inbox-Tab (`SettingsModalView.axaml`, `ErweitertCategories`):

- Base-URL (Textfeld)
- Personal Access Token (maskiert; gespeichert = Anzeige „gesetzt", nicht der Wert)
- Button „Verbindung testen" → `GET /api/ticketsystem/pat/me`, zeigt Benutzername und die
  gewährten Scopes an. Fehlt `pat:board:read` oder `pat:tickets:write`, wird das als Hinweis
  ausgegeben — das ist der häufigste Konfigurationsfehler.

Neues `TicketSettingsTabViewModel` neben `OnlineInboxSettingsViewModel`, gleiches Muster
(`LoadAsync`, `IsBusy`, `StatusMessage`).

### Listen-Settings-Modal — Projektzuordnung

Ein Dropdown „Ticket-Projekt" mit den Projekten aus `GET /api/Navigation/sidebar`, gruppiert
nach Abteilung, plus „— keins —". Lädt beim Öffnen des Modals, nur wenn eine Base-URL
konfiguriert ist; sonst ist das Feld ausgeblendet.

### Lokalisierung

Alle neuen Strings in `locales/en.json` **und** `locales/de.json`. Die Parität wird von
`Localization.Tests` erzwungen — beide Dateien müssen zusätzlich einzeln als JSON parsebar
bleiben, ein kaputtes `de.json` wird sonst still verschluckt.

## Fehlerbehandlung

| Fall | Verhalten |
|---|---|
| Base-URL nicht gesetzt | Feature komplett inaktiv, Menüeintrag versteckt |
| PAT fehlt/ungültig (401) | Import bricht mit Footer-Fehler ab; Write-back loggt Warnung |
| Scope fehlt (403) | Wie 401, Meldung nennt den fehlenden Scope |
| API nicht erreichbar | Timeout 10 s, Footer-Fehler, kein Retry |
| Write-back schlägt fehl | Warnung im Log, Task-Statuswechsel geht durch |
| Ticket im Ticketsystem gelöscht | PATCH liefert 404 → Warnung, `TicketRef` bleibt stehen |

Kein `catch {}` ohne Meldung — Nutzeraktionen, die scheitern, erscheinen im Footer-Strip.

## Tests

Alle mit gefaktem `HttpMessageHandler`, kein echter Netzwerkaufruf, kein echtes `claude`:

- Status-Mapping: jeder `TaskStatus` → erwarteter Ticket-Status bzw. „kein Aufruf"
- Kein redundanter PATCH bei `Running → WaitingForReview`
- Kein Aufruf ohne `TicketRef`, ohne Base-URL, ohne PAT
- Write-back-Fehler (401/404/Timeout) lässt den Statuswechsel durchgehen
- Import: filtert korrekt auf Assignee + `StatusId == 1`
- Import: überspringt bereits importierte Tickets, legt keine Duplikate an
- `SetConfigAsync` erhält `TicketProjectId`, wenn ein anderer Writer die Config anfasst
- Locale-Parität en/de

## Manuelle Verifikation (nicht automatisierbar)

1. PAT in den Settings hinterlegen, „Verbindung testen" → korrekter Benutzername + Scopes.
2. Liste mit Projekt `393 Bandel.LagerApp` verknüpfen, „Update from Ticketsystem" → nur eigene,
   offene Tickets erscheinen als Tasks.
3. Einen Task laufen lassen → Ticket steht im Ticketsystem auf `InBearbeitung`.
4. Approve/Merge → Ticket steht auf `Fertig`.
5. Base-URL leeren → Menüeintrag verschwindet, keine Netzwerkaufrufe mehr.

Punkte 1–4 bestätigen zugleich die aus dem Quellcode abgeleiteten Response-Shapes.