tickte-system/docs/superpowers/specs/2026-09-30-unterstuetzung-design.md

Unterstützung bei Arbeitsblättern + 15-Minuten-Zeiten – Konzept

Stand 2026-09-30, freigegeben im Gespräch (Abschnitte 1–4).

Ziel

Wer bei einem Arbeitsblatt eines Kollegen mitgeholfen hat, wird als Unterstützung eingetragen: Person und Tätigkeit. Die Person, die das Arbeitsblatt angelegt hat, behält 100 % der Zeit; jede unterstützende Person bekommt zusätzlich 50 % der Arbeitszeit, aufgerundet auf volle 15 Minuten. Die Unterstützungszeit wird dem Kunden berechnet und im Kundenportal einzeln ausgewiesen.

Gleichzeitig werden Arbeitszeiten überall nur noch in 15-Minuten-Schritten erfasst. Das hebt die Entscheidung vom 2026-09-26 („ganze Minuten, keine 15er-Schritte“) auf.

Die Verträge (Abo-Bedingungen, AGB) halten Rundung und Unterstützung fest.

Nicht im Umfang: Auswertung der Stunden je Mitarbeiter, Umrechnung alter Arbeitsblätter, Rechnungserstellung.

Rechenregel

supportMinutes(totalTime) = ceil(totalTime / 2 / 15) * 15     // 0 bei totalTime <= 0
worksheetMinutes(ws)      = totalTime + Anzahl Unterstützer * supportMinutes(totalTime)

Beispiele: 15 → 15, 30 → 15, 45 → 30, 60 → 30, 75 → 45, 70 (alt) → 45. Kommentare und Git-Pushs ohne nachgetragene Zeit haben totalTime 0, also auch 0 Unterstützung.

Die Regel steht in beiden Systemen (WOMS und Portal) mit denselben Testfällen. Die Minuten der Unterstützung werden nie gespeichert, sondern immer aus totalTime berechnet. Ändert sich die Arbeitszeit, stimmt die Unterstützung automatisch.

Datenmodell

Appwrite woms-database, Collection worksheets, neues Attribut:

• supporters – String, nicht Pflicht, Größe 4000, JSON-Array: [{ "employeeId": "<Appwrite-User-ID>", "name": "Andrej Stevanovski", "task": "Farbkonzept" }]

Regeln: task ist Pflicht (1–200 Zeichen, getrimmt). Jede employeeId höchstens einmal. Die Person, die das Arbeitsblatt angelegt hat, darf nicht als Unterstützung stehen (bei Git-Pushs: der Mitarbeiter, dem der Push gehört, siehe isWorksheetCreator). name wird beim Eintragen gespeichert, damit die Zeile auch nach dem Löschen eines Mitarbeiters lesbar bleibt.

Das Attribut legt ein Skript scripts/setup-supporters.mjs an (idempotent). Der Nutzer führt es aus, weil Claude den Appwrite-Schlüssel nicht verwenden darf.

WOMS (Ticketsystem)

15-Minuten-Schritte

Betroffen: CreateWorksheetModal (neues Arbeitsblatt), WorksheetTimesModal („Zeiten bearbeiten“ und „Zeit nachtragen“ bei Git).

• Das Feld „Arbeitszeit“ wird eine Auswahl: 15 min, 30 min, 45 min, 1 h, 1 h 15 … bis 12 h (48 Werte). Kein freies Eintippen mehr.
• Beginn und Ende bleiben freie Uhrzeiten (bei Git ist das Ende die Uhrzeit des Pushs). Die automatisch berechnete Zeit (minutesBetween) wird auf den nächsten 15-Minuten-Schritt aufgerundet; danach kann ein anderer Wert gewählt werden. Dauer 0 → 15 min vorausgewählt.
• Hat ein altes Arbeitsblatt eine Zeit außerhalb des Rasters (z. B. 70), ist beim Bearbeiten der nächsthöhere Schritt (75) vorausgewählt.
• Beim Speichern wird geprüft, dass totalTime ein positives Vielfaches von 15 ist (außer bei „Nur Kommentar“, dort 0).
• useWorksheets.createWorksheet rechnet eine fehlende Zeit ebenfalls aufgerundet.

Unterstützung eintragen

Person, die das Arbeitsblatt angelegt hat (canEditWorksheetTimes): im Formular „Zeiten bearbeiten“ und beim neuen Arbeitsblatt der Haken „Unterstützung“. Darunter Zeilen mit Mitarbeiter (Auswahl aus employees, ohne sich selbst und ohne schon gewählte) und Wobei? (Pflichttext), „+ weitere Person“, Entfernen je Zeile. Haken aus = Liste leeren.

Alle anderen Mitarbeiter: bei fremden Arbeitsblättern mit Arbeitszeit der Knopf „Ich habe unterstützt“. Kleines Formular nur mit Wobei?. Ist man schon eingetragen, heißt der Knopf „Meine Unterstützung bearbeiten“ und man kann die Tätigkeit ändern oder den Eintrag entfernen. Andere Einträge und die Zeiten sind nicht änderbar.

Neue Hilfen in lib/ticketForm.js (oder lib/support.js): supportMinutes, worksheetMinutes, parseSupporters (fehlertolerant, kaputtes JSON → leere Liste), canAddOwnSupport(ws, user, employee) (nicht Ersteller, Arbeitsblatt hat Arbeitszeit), upsertOwnSupport, removeOwnSupport.

Unterstützung ist nur möglich bei Arbeitsblättern mit Arbeitszeit: nicht bei reinen Kommentaren, bei Git-Pushs erst nach „Zeit nachtragen“.

Speichern: updateWorksheet patcht { supporters }. „Ich habe unterstützt“ liest das Dokument vorher frisch und schreibt nur den eigenen Eintrag um, damit gleichzeitige Einträge anderer nicht überschrieben werden.

Berechtigungen: wie bisher nur in der Oberfläche durchgesetzt (die Collection erlaubt Update für Benutzer). Keine Änderung an den Appwrite-Rechten.

Anzeige

• WorksheetList: unter dem Arbeitsblatt je Unterstützung „↳ Unterstützung Andrej · Farbkonzept · 30 min“.
• WorksheetSummary „Arbeitszeit gesamt“ und useWorksheets Summen verwenden worksheetMinutes.
• Der Abo-Haken („+ Abo“, countsToPlan) gilt für das ganze Arbeitsblatt einschließlich Unterstützung.

Kundenportal

• Gleiche Rechenregel als server/services/worksheetMinutes.js (oder vorhandenes Modul) mit supportMinutes, worksheetMinutes, parseSupporters. Kaputtes JSON → Eintrag überspringen und loggen, nie Absturz.
• Stundenkonto (hourLedger.js): Verbrauch eines Abo-Arbeitsblatts = worksheetMinutes(ws) statt totalTime. Die Zeile im Verlauf bekommt den Zusatz „inkl. 30 min Unterstützung“.
• „Arbeiten am Projekt“ (customerProjectView.js, public/app.js): jeder Eintrag bekommt supports: [{ name, task, minutes }], dargestellt als eigene Zeilen unter dem Schritt: „↳ Unterstützung Andrej: Farbkonzept · 30 min“. Werden mehrere Git-Pushs eines Tages zu „Website aktualisiert“ zusammengefasst, hängen alle Unterstützungen unter diesem Eintrag.
• Gesamtzeit oben: im Kopf der Projektdetails (neben Auftragsnummer und Status) die Zeile „Arbeitszeit gesamt: 4 h 30 min“ = Summe aller Schritte inkl. Unterstützung. Ohne Auftrag steht sie oben im Abschnitt „Arbeiten am Projekt“. Bei 0 wird sie nicht gezeigt.
• customerActivity.js gibt supporters mit weiter, wo totalTime weitergegeben wird.
• Push-Zeitmail (Spec af7ecce, noch nicht gebaut): „andere Zeit“ nur in 15-Minuten-Schritten; wird in jener Spec nachgetragen.

Verträge

Stand heute: Abo-Bedingungen Version 4 (live seit 2026-09-30) § 4 enthält schon „aufgerundet auf volle 15 Minuten“ / „in Schritten von 15 Minuten“, aber nichts zur Unterstützung. AGB § 9 sagt nur „Die Vergütung ergibt sich aus dem Angebot“.

• Abo-Bedingungen Version 5, § 4 neuer Satz nach der Rundungsregel (Entwurf): „Wirkt an einem Arbeitsschritt eine weitere Person unterstützend mit, etwa bei Gestaltung, Abstimmung oder Prüfung, rechnen wir für sie die Hälfte der Arbeitszeit dieses Arbeitsschritts an, aufgerundet auf volle 15 Minuten; bei mehreren unterstützenden Personen gilt das für jede von ihnen. Im Kundenportal weisen wir jeden Arbeitsschritt mit seiner Arbeitszeit und jede Unterstützung mit Person, Tätigkeit und angerechneter Zeit einzeln aus.“
• AGB § 9 neuer Absatz 2, nur für Abrechnung nach Aufwand (Festpreis-Angebote unberührt), Regel vollständig ausgeschrieben (kein Verweis auf die Abo-Bedingungen): „Wird nach Aufwand abgerechnet, erfassen wir die Arbeitszeit je Arbeitsschritt in Schritten von 15 Minuten; angefangene 15 Minuten runden wir auf. Wirkt eine weitere Person unterstützend mit, rechnen wir für sie die Hälfte der Arbeitszeit des Arbeitsschritts an, aufgerundet auf volle 15 Minuten; bei mehreren unterstützenden Personen gilt das für jede. Jeder Arbeitsschritt und jede Unterstützung ist im Kundenportal einsehbar.“ Wird mit dem offenen § 11-Haftungsentwurf (webklar.com f40e889, fix/agb-haftung) zu einer neuen AGB-Version gebündelt.
• Alle Stellen, die die Texte wiederholen (PDF-Anhang der Vertragsmails, vertragsunterlagen/, Kalkulation, Portal-Texte), werden abgeglichen. Beide Texte kommen in WOMS „Rechtliches“ als neue Version.
• Laufende Abos bleiben auf ihrer Version. Einschätzung (keine Rechtsberatung): Version 4 rechnet die „tatsächlich aufgewendete Zeit“ ab; bei zwei Personen fällt mehr Zeit an, als mit 50 % berechnet wird, die Unterstützung ist also gedeckt.
• Die endgültigen Texte legt Claude dem Nutzer vor dem Livegang einzeln zur Freigabe vor.

Alte Daten und Fehlerfälle

• Alte Arbeitsblätter bleiben unverändert (keine Massen-Umrechnung); 70 Minuten bleiben 70 Minuten, bis jemand das Blatt bearbeitet.
• Ohne supporters = keine Unterstützung.
• Gelöschter Mitarbeiter: gespeicherter Name bleibt, Zeile wird weiter gezeigt und berechnet.
• Doppelte Person / Ersteller als Unterstützung: Oberfläche verhindert es; beim Lesen werden Duplikate ignoriert.
• Arbeitszeit 0 oder „Nur Kommentar“: Unterstützung zählt 0 (Einträge bleiben gespeichert).

Livegang (Reihenfolge)

1. Nutzer führt scripts/setup-supporters.mjs aus (Attribut supporters).
2. Kundenportal live (Push main), damit keine Unterstützung eingetragen werden kann, die der Kunde nicht sieht.
3. WOMS live (Push feature/unterstuetzung:test).
4. Verträge: Abo-Bedingungen v5 (Portal) und AGB (webklar.com) nach Freigabe der Texte; Versionen in „Rechtliches“ eintragen.

Nichts wird ohne das OK des Nutzers gepusht.

Tests

• Rechenregel in beiden Systemen mit denselben Fällen (15, 30, 45, 60, 75, 70, 0, Kommentar).
• WOMS: Unit-Tests (npm test) für Rechnung, parseSupporters, Berechtigungen (canAddOwnSupport, Ersteller/Nicht-Ersteller, Git-Push), eigener Eintrag ändern/entfernen. Playwright mit nachgebautem Appwrite: 15-Minuten-Auswahl und Aufrunden, Haken „Unterstützung“ mit zwei Personen, „Ich habe unterstützt“, Anzeige in Liste und Summe.
• Portal: Tests für customerWorkEntries (Unterstützungs-Zeilen, zusammengefasste Git-Tage), Gesamtzeit, Stundenkonto mit Unterstützung, kaputtes JSON.
• Vor dem Livegang: Build wie beim Deploy (docker run node:20-alpine), Blick auf echte Daten nur lesend im Chrome des Nutzers.