1.1.0-rc1

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

@@ -0,0 +1,150 @@
+# 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.