tickettracker/docs/confluence/02-projekte-budgets-teamspace.md

# Projekte, Budgets und Teamspace

Diese Seite beschreibt die aktuelle Projekt- und Teamspace-Logik in TicketTracker.

## Projekte

Projekte erweitern normale Tickets um Consulting-Projektinformationen.

Ein Projekt enthält unter anderem:

- Ticketnummer
- Titel und Organisation
- Teamspace-Projekt-Einträge
- Beschreibung und Ziele
- Zeitraum
- Projektstatus offen oder geschlossen
- ToDos
- Teamspace-Budgets und Verbrauchswerte
- Teamspace-Unterpositionen

Projekt-Tickets sind Consulting-Tickets. Wird ein Projekt gelöscht, bleiben Ticket, Sessions und ToDos erhalten. Gelöscht werden nur die Projektinformationen.

## Teamspace als Budgetquelle

Teamspace ist die fachliche Quelle für Projektbudgets.

Aktuelle Budgetregeln:

- Teamspace ist die Source of Truth für Projektbudgets.
- Zammad-Budgets werden nicht mehr als Budgetquelle verwendet.
- Das Gesamtbudget eines Projekts kommt aus Teamspace.
- Wenn mehrere Teamspace-Projekte an einem Ticket hängen, wird das Gesamtbudget aus diesen Teamspace-Projekten zusammengesetzt.
- Unterpositionen zeigen ihre eigenen Teamspace-Budgets und Teamspace-Istwerte.
- Stückpositionen werden nicht als Stundenbudget in die Stundenbetrachtung eingerechnet.

## Verbrauchslogik

Der Projektverbrauch hängt vom Profil-Schalter **Teamspace-Zeiten in TT erfassen** ab.

Wenn der Schalter aktiv ist:

- Projekt-Ist kommt aus Teamspace-Tageswerten, die in TicketTracker gepflegt werden.
- Zusätzlich können manuelle Projektstunden erfasst werden.
- Progress Bars, Reststunden und Budgetwarnungen verwenden diese Werte.

Wenn der Schalter deaktiviert ist:

- Projekt-Ist kommt aus Teamspace.
- Manuelle Projektstunden sind ausgeblendet und serverseitig gesperrt.
- Teamspace-Tageswerte können nicht in TicketTracker erfasst werden.
- Statistiken und Widgets zeigen keine TT/Teamspace-Differenzprüfung für diesen Benutzer.

## Mehrere Teamspace-Projekte pro Ticket

Ein Ticket kann mehrere Teamspace-Projekt-IDs haben. TicketTracker speichert dafür mehrere Teamspace-Einträge am Projekt.

Beispiel:

- `EP-2025-Comp-009`
- `EP-2025-Comp-025`

Einer der Einträge ist der Standard. Sessions können einem Teamspace-Projekt-Eintrag zugeordnet werden. Diese Zuordnung erfolgt auf Ebene des Teamspace-Projekts, nicht auf Ebene einzelner Unterpositionen.

## Gemeinsames Teamspace-Budget über mehrere Tickets

Mehrere unterschiedliche Ticketnummern können dieselbe Teamspace-Projekt-ID verwenden. TicketTracker behandelt diese Teamspace-Nummer dann als gemeinsame Budgetquelle.

Dabei gilt:

- Es gibt keine automatische Aufteilung auf die Ticketnummern.
- Teamspace-API-ID, Teamspace-API-URL, Budget, Unterpositionen und Teamspace-Monatswerte werden für dieselbe Teamspace-Nummer konsolidiert.
- Der Teamspace-Sync zieht gleiche Teamspace-Nummern nach jedem Lauf wieder auf denselben Datenstand.
- Die Migration konsolidiert bereits vorhandene doppelte Teamspace-Nummern beim Start.
- Ticket-spezifische Felder wie Standard-Eintrag, Reihenfolge, Session-Zuordnung und manuelle Projektstunden bleiben am jeweiligen Ticket.

## Teamspace-Projekt-ID-Sync

Der Sync auf der Zammad-Sync-Seite löst offene Consulting-Projekte gegen die Teamspace-API auf.

Gespeichert werden unter anderem:

- Teamspace-API-ID des Projekts
- Teamspace-API-URL
- Teamspace-Gesamtbudget
- Teamspace-Unterpositionen
- Teamspace-Budgets und Istwerte der Unterpositionen
- Stückpositionen und deren Erfüllungsstand
- echte Teamspace-Monatszeiten aus `/api/time` für den gewählten Monat

Die fachliche Teamspace-ID aus Zammad oder Projektinformationen, zum Beispiel `EP-2026-A-035`, ist nicht identisch mit der API-ID für Einzelabfragen. TicketTracker speichert deshalb die interne Teamspace-API-ID, sobald sie gefunden wurde.

## Teamspace-Monatsabgleich

Der Teamspace-Projekt-ID-Sync auf der Zammad-Sync-Seite enthält zusätzlich einen Monatsabgleich. Der Benutzer wählt einen Monat aus, TicketTracker ruft für diesen Zeitraum die Teamspace-Zeitbuchungen des angemeldeten Teamspace-Benutzers ab und speichert einen Snapshot pro Teamspace-Projekt-Eintrag.

Technische Grundlage:

- API-Endpoint: `/api/time`
- Filter: `worker={Teamspace User-ID}` und `date=YYYY-MM-01..YYYY-MM-letzterTag`
- gezählt werden Einträge mit `draftStatus.value = NORMAL`
- relevante Minuten sind `amountBillable`
- `amount` wird als Gesamtzeit mitgeführt, ist aber nicht die Vergleichsgröße

Die Monatswerte werden pro Benutzer, Teamspace-Projekt-Eintrag und Monat gespeichert. Dadurch bleiben drei Dinge getrennt:

- TT-Tageswerte, die in TicketTracker gepflegt werden
- echte Teamspace-Monatszeiten aus Teamspace
- Teamspace-Budget- und Unterpositionswerte aus dem Projektsync

Im Ergebnis des Syncs sieht man pro Teamspace-Projekt:

- TT-Monatswert
- TS-Monatswert
- Differenz
- Anzahl der gefundenen TS-Zeitbuchungen
- betroffene Haupt- oder Unterpositionen mit TS-Minuten

Wenn Teamspace-Zeiten auf Unterpositionen gebucht wurden, werden diese ebenfalls dem passenden Teamspace-Projekt-Eintrag zugeordnet. TicketTracker mappt dafür nicht nur die Hauptprojekt-API-ID, sondern auch die synchronisierten Unterpositions-API-IDs. Die Positionsaufschlüsselung wird im Monats-Snapshot gespeichert und kann dadurch später in der Monatsübersicht angezeigt werden.

## Unterpositionen

Unterpositionen werden aus Teamspace synchronisiert und im Projektdetail angezeigt. Sie dienen als Teamspace-Anzeige, um Budget, Verbrauch und freie Ressourcen pro Teamspace-Position sichtbar zu machen.

Wichtig:

- Zeiten werden nicht auf Unterpositionen in TicketTracker erfasst.
- Unterpositionen bekommen ihre Budgets und Istwerte aus Teamspace.
- Teamspace-Descriptions werden dekodiert und formatiert ausgegeben.
- Unterpositionen können einen Alias in TicketTracker bekommen.
- Akkordions der Unterpositionsgruppen merken sich den letzten offenen oder geschlossenen Zustand pro Benutzer und Projekt.
- Bei Teamspace-Strukturen mit Überpositionen werden nur echte bebuchbare Unterpositionen angezeigt, nicht reine Summenpositionen.
- Positionsnummern werden lesbar dargestellt, zum Beispiel `1` statt `0001` oder `1.1` statt `0001.0001`.

## Stückpositionen

Teamspace-Positionen mit `billingType = INVOICEABLE_FIX` sind Stück- oder Fixpositionen.

Für diese Positionen gelten andere Regeln:

- Stundenwerte werden nicht als Stundenbudget interpretiert.
- TicketTracker zeigt sie als Stückpositionen an.
- Der Erfüllungsstand wird über `plannedIncome` gegen `sumIncome` geprüft.
- Ist das Soll erreicht, wird die Position als abgerechnet beziehungsweise erfüllt markiert.
- Überschreitungen werden mit einem Hinweis-Icon angezeigt.

## Projektansichten

Die Projektliste zeigt Gesamtbudget, Verbrauch, Reststunden und Projektwarnungen. Bei mehreren Teamspace-Projekten können Detailbalken pro Teamspace-Projekt angezeigt oder ausgeblendet werden. Der Hauptbalken zeigt weiterhin das Gesamtbudget aller Teamspace-Projekte.

Im Projektdetail stehen Projektinformationen und ToDos getrennt von den Teamspace-Unterpositionen. Die Unterpositionen liegen in einer eigenen breiten Card unterhalb der Projekt-/ToDo-Informationen.