tickte-system/WORKSHEETS_COLLECTION_SETUP.md

Worksheets Collection Setup

📋 Was ist ein Worksheet (WSID)?

Ein Worksheet ist ein Arbeitsschritt-Eintrag für einen Work Order (Ticket). Jedes Mal, wenn ein Techniker an einem Ticket arbeitet, wird ein neues Worksheet erstellt.

Unterschied: WOID vs WSID

Konzept	Beschreibung	Beispiel
WOID (Work Order ID)	Das Haupt-Ticket	59203
WSID (Work Sheet ID)	Einzelner Arbeitsschritt	100001

Beziehung: Ein WOID kann viele WSIDs haben (1:n)

Beispiel aus der Praxis:

Ticket WOID 59203: "Router-Problem bei Kunde XYZ"

├── WSID 100001 (29.12.2025, 10:00-10:30, Max M.)
│   └── "Fernanalyse durchgeführt, Router neu gestartet"
│       Status: Open → Occupied
│
├── WSID 100002 (29.12.2025, 14:00-14:45, Max M.)
│   └── "Firmware Update durchgeführt"
│       Status: Occupied → Assigned
│
└── WSID 100003 (30.12.2025, 09:00-09:15, Lisa S.)
    └── "Vor-Ort-Check: Alles funktioniert"
        Status: Assigned → Closed

Gesamtarbeitszeit für WOID 59203: 30 + 45 + 15 = 90 Minuten

---

🔧 Appwrite Collection einrichten

Collection erstellen

1. Gehe zu Appwrite Dashboard → Databases → woms-database
2. Klicke auf Create Collection
3. Collection ID: worksheets
4. Name: Work Sheets

Attribute hinzufügen

Attribut Name	Typ	Größe	Required	Array	Default	Beschreibung
wsid	string	10	✓	-	-	Work Sheet ID (6-stellig, z.B. "100000")
woid	string	10	✓	-	-	Verknüpfter Work Order (z.B. "59203")
workorderId	string	50	✓	-	-	Appwrite Document ID des Work Orders
employeeId	string	50	✓	-	-	ID des Mitarbeiters (aus Auth)
employeeName	string	255	✓	-	-	Name des Mitarbeiters
employeeShort	string	10	-	-	-	Kürzel (z.B. "KNSO")
serviceType	string	50	✓	-	Remote	Remote/On Site/Off Site/COMMENT
oldStatus	string	50	✓	-	-	Status vorher
newStatus	string	50	✓	-	-	Status nachher
oldResponseLevel	string	50	-	-	-	Response Level vorher
newResponseLevel	string	50	-	-	-	Response Level nachher
totalTime	integer	-	✓	-	0	Arbeitszeit in Minuten
startDate	string	50	✓	-	-	Startdatum (dd.mm.yyyy)
startTime	string	10	-	-	-	Startzeit (hhmm)
endDate	string	50	✓	-	-	Enddatum (dd.mm.yyyy)
endTime	string	10	-	-	-	Endzeit (hhmm)
details	string	10000	✓	-	-	Beschreibung der Arbeit
isComment	boolean	-	-	-	false	Nur Kommentar (keine Arbeitszeit)
createdAt	datetime	-	-	-	-	Erstellungszeitpunkt

Permissions einrichten

1. Gehe zu Settings → Permissions
2. Setze folgende Berechtigungen:

Read Access:

• ✅ Users (Alle eingeloggten Benutzer können Worksheets lesen)

Create Access:

• ✅ Users (Alle eingeloggten Benutzer können Worksheets erstellen)

Update Access:

• ✅ Users (Eigene Worksheets können bearbeitet werden)

Delete Access:

• ❌ Keine (Worksheets sollten nicht gelöscht werden - Audit Trail!)

Indexes erstellen

Für bessere Performance:

1. Index 1: woid_index

   • Key: woid
   • Type: key
   • Order: DESC
   • → Schnelles Finden aller Worksheets für einen Work Order

2. Index 2: employee_index

   • Key: employeeId
   • Type: key
   • Order: DESC
   • → Schnelles Finden aller Worksheets eines Mitarbeiters

3. Index 3: date_index

   • Key: startDate
   • Type: key
   • Order: DESC
   • → Zeitbasierte Abfragen

---

🎯 WSID-Generierung

Regeln:

• 6-stellige Zahlen (100000, 100001, 100002, ...)
• Global eindeutig (über alle Work Orders hinweg)
• Sequentiell aufsteigend
• Nur Zahlen, keine Buchstaben

Algorithmus:

1. Finde höchste existierende WSID in der Datenbank
2. Addiere +1
3. Falls keine WSID existiert: Starte bei 100000

---

📊 Verbesserungen gegenüber dem Original

1. Automatische Zeitberechnung

• System berechnet totalTime aus startTime und endTime
• Manuelles Überschreiben möglich

2. Arbeitszeit-Aggregation

• Gesamtarbeitszeit pro WOID wird automatisch berechnet
• Anzeige: "Gesamt: 90 Minuten (3 Worksheets)"

3. Status-Historie

• Komplette Historie: Wer hat wann welchen Status gesetzt?
• Nachvollziehbarkeit

4. Kommentar-Funktion

• Worksheets mit isComment = true zählen keine Arbeitszeit
• Reine Notizen/Updates

5. Mitarbeiter-Zuordnung

• Jedes Worksheet ist einem Mitarbeiter zugeordnet
• Report: Wer hat wie viel Zeit investiert?

---

🔗 Integration in Work Orders

Beim Anzeigen eines Tickets:

// Work Order laden
const workorder = await getWorkorder(woid)

// Alle Worksheets zu diesem Work Order laden
const worksheets = await getWorksheets(woid)

// Gesamtarbeitszeit berechnen
const totalMinutes = worksheets.reduce((sum, ws) => sum + ws.totalTime, 0)

Beim Erstellen eines Worksheets:

1. Aktuellen Work Order Status holen
2. Worksheet-Formular anzeigen (mit aktuellem Status als "old status")
3. Worksheet speichern
4. Work Order Status aktualisieren (auf "new status")

---

📝 Workflow-Beispiel

Techniker Max öffnet Ticket 59203:

1. Klickt auf "Add Worksheet"
2. System füllt aus:
   • WOID: 59203
   • Old Status: "Open"
   • Employee: "Max Müller" (aus Login)
   • Datum: heute
3. Max trägt ein:
   • Service Type: "Remote"
   • New Status: "Occupied"
   • Start: 10:00, End: 10:30 (→ automatisch 30 min)
   • Details: "Router neu gestartet"
4. System generiert WSID: 100001
5. Work Order Status wird auf "Occupied" aktualisiert

---

✅ Checkliste

• Collection worksheets in Appwrite erstellt
• Alle Attribute hinzugefügt
• Permissions konfiguriert
• Indexes erstellt
• Collection ID in .env / appwrite.js eingetragen

---

🚀 Nächste Schritte

Nach dem Setup:

1. useWorksheets.js Hook implementieren
2. CreateWorksheetModal.jsx Komponente erstellen
3. Worksheet-Liste in Ticket-Details einbauen
4. Zeitaggregation implementieren