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.