Campus Helpdesk Agent Skill

Was macht Campus Helpdesk Agent Skill?

Dieses Skill definiert die technischen Standards, Arbeitsabläufe und Best Practices für die Entwicklung, Verbesserung und Wartung der Campus Helpdesk-Webanwendung. Verwenden Sie diesen Leitfaden, wann immer Sie Funktionen hinzufügen, Komponenten umgestalten, Status-Workflows aktualisieren oder Datenmodelle in diesem Projekt ändern.

---

1. Saubere, wiederverwendbare React-Komponenten schreiben

Behalten Sie eine modulare, entkoppelte Komponentenarchitektur bei:

• Single-Responsibility-Prinzip: Jede Komponente sollte genau eine Sache gut können.
  • Formularlogik und Eingaben gehören in IssueForm.jsx.
  • Öffentliche Suche, Filterung und Ticketkarten-Anzeige gehören in TicketList.jsx.
  • Analytische Metriken, visuelle Fortschrittsbalken und administrative Tabellen gehören in AdminDashboard.jsx.
  • Modale Inspektionen und Historie-Timelines gehören in TicketModal.jsx.
  • Benachrichtigungen gehören in Toast.jsx.
• Props- und State-Design:
  • Halten Sie den State so lokal wie möglich. Heben Sie den State nur dann in App.jsx an, wenn er über mehrere Ansichten hinweg gemeinsam genutzt wird (z.B. globale tickets, activeTab, toasts).
  • Verwenden Sie nach Möglichkeit reine Präsentations-Kindkomponenten und geben Sie Callbacks (onSelectTicket, onUpdateStatus, onDeleteTicket) sauber nach unten weiter.
  • Vermeiden Sie doppelten State; berechnen Sie abgeleitete Werte (z.B. gefilterte Tickets, KPI-Statistiken) mit useMemo.
• Namenskonventionen & sauberer Code:
  • Komponentendateien verwenden PascalCase (AdminDashboard.jsx, IssueForm.jsx).
  • Utility- und Konstantendateien verwenden camelCase (storage.js, constants.js).
  • Ereignisbehandler sollten dem handle[Action]-Schema folgen (z.B. handleSubmit, handleStatusChange).
  • Bewahren Sie Kommentare und Docstrings. Schreiben Sie selbsterklärenden Code mit sauberen, beschreibenden Variablennamen.
• Keine schweren externen Abhängigkeiten:
  • Behalten Sie die schlanke Architektur bei: Verwenden Sie native React-Hooks, reine Inline-SVGs für Icons und bereichsbezogene CSS-Klassen, anstatt sperrige Drittanbieter-Komponentenbibliotheken einzubinden.

---

2. Responsive und barrierefreie UI erstellen

Das Campus Helpdesk-Portal muss ein reibungsloses Benutzererlebnis auf allen Geräten bieten (Mobiltelefone, Tablets, Laptops, große Monitore):

• Fluide Layouts & Breakpoints:
  • Entwerfen Sie Mobile-First oder Desktop-Down mit konsistenten Breakpoints:
    • Desktop: Maximale Containerbreite 1240px mit mehrspaltigen Rastern (5 Metrik-Karten, 2-spaltige Analysen, 2-spaltige Formulare).
    • Tablet (<= 1024px): Reduzieren Sie 5-spaltige Metrik-Raster auf 3 oder 2 Spalten; stapeln Sie Analyse-Diagramme in eine einzige Spalte.
    • Mobil (<= 768px): Stapeln Sie die Header-Navigation und Formulareingaben in 1 Spalte; aktivieren Sie horizontales Scrollen für Datentabellen.
    • Kleine Bildschirme (<= 480px): Volle Breite Metrik-Karten, gestapelte Aktionsbuttons und unten fixierte Toast-Benachrichtigungen.
• Barrierefreiheit (a11y):
  • Alle interaktiven Elemente müssen semantisch korrektes HTML aufweisen (<button>, <input>, <select>, <textarea>).
  • Formularsteuerelemente müssen über zugehörige <label htmlFor="...">-Elemente mit passenden id-Attributen verfügen.
  • Modale Dialoge müssen role="dialog", aria-modal="true" haben und das Schließen durch Klicks auf den Hintergrund sowie Escape-Tasten unterstützen.
  • Interaktive Icons oder Icon-Only-Buttons müssen beschreibende aria-label- oder title-Attribute enthalten.
  • Behalten Sie zugängliche Farbkontrastverhältnisse für Text auf Status-Badges und Prioritäts-Tags bei.
• Visuelles Feedback & Übergänge:
  • Interaktive Elemente müssen klare :hover-, :focus- und :active-Zustände anzeigen.
  • Fokussierte Formularfelder müssen einen kontrastreichen Fokusring anzeigen (var(--primary-ring)).
  • Verwenden Sie Mikro-Animationen (Toast-Einblendung, Modal-Vergrößerung, Button-Spinner), um den Benutzer über Hintergrundaktionen zu informieren, ohne Layoutverschiebungen zu verursachen.

---

3. Studentisches Problemformular validieren

Alle Problemeinreichungen über IssueForm.jsx müssen vor State-Mutation oder Speicherung strengen clientseitigen Validierungsregeln folgen:

Validierungsregel-Matrix

Feld	Regel	Fehlermeldung
Vollständiger Name	Erforderlich, getrimmt, nicht leer	"Bitte geben Sie Ihren vollständigen Namen an."
Campus-E-Mail	Erforderlich, gültiges Regex-Muster /^[^\s@]+@[^\s@]+\.[^\s@]+$/	"Bitte geben Sie eine gültige E-Mail-Adresse ein."
Standort / Raum	Erforderlich, getrimmt, nicht leer	"Geben Sie das Gebäude, die Halle oder den Campus-Standort an."
Kategorie	Erforderlich, muss mit CATEGORIES-Liste übereinstimmen	Automatisch vorausgewählt
Priorität	Erforderlich, muss mit PRIORITIES (Niedrig, Mittel, Hoch, Dringend) übereinstimmen	Standardmäßig 'Mittel'
Betreff / Titel	Erforderlich, getrimmt, Mindestlänge $\ge 5$ Zeichen	"Der Titel muss mindestens 5 Zeichen lang sein."
Detaillierte Beschreibung	Erforderlich, getrimmt, Mindestlänge $\ge 15$ Zeichen	"Die Beschreibung sollte mindestens 15 Zeichen lang sein."

Validierungs-Implementierungsschritte

1. Verwalten Sie ein errors-State-Objekt, das Feldnamen auf Fehlertexte abbildet.
2. Löschen Sie den Fehler des jeweiligen Feldes, wenn der Benutzer seine Eingabe ändert (handleChange).
3. Überprüfen Sie alle Regeln bei handleSubmit. Verhindern Sie die Einreichung und heben Sie ungültige Felder mit .input-error und .field-error hervor, falls Fehler vorhanden sind.
4. Bei Erfolg:
   • Generieren Sie eine eindeutige ID (z.B. TCK-XXXX).
   • Weisen Sie den Anfangsstatus Ausstehend zu.
   • Erfassen Sie den ersten Einreichungs-Zeitstempel und Historie-Knoten.
   • Setzen Sie Formularfelder und Fehlerstatus zurück.
   • Lösen Sie eine Erfolgs-Toast aus und navigieren Sie zur Ticket-Tracker-Ansicht.

---

4. Ausstehende, in Bearbeitung und gelöste Status verwalten

Der Campus Helpdesk folgt einem streng definierten 3-stufigen Lebenszyklus:

[ Ausstehend ]  ───►  [ In Bearbeitung ]  ───►  [ Gelöst ]
    ▲                      ▲                     │
    └──────────────────────┴─────────────────────┘ (Kann bei Bedarf wieder geöffnet werden)

Statusdefinitionen & visuelles Designsyste

1. Ausstehend:
   • Bedeutung: Neue Problemmeldung von Student/Personal, wartet auf Bearbeitung oder Zuweisung.
   • Farbthema: Amber (#d97706), Hintergrund #fef3c7, Rahmen #fde68a.
   • Fortschrittsstufe: Schritt 1 aktiv.
2. In Bearbeitung:
   • Bedeutung: Techniker oder Campus-Abteilung hat das Ticket übernommen und untersucht oder repariert aktiv.
   • Farbthema: Königsblau (#2563eb), Hintergrund #dbeafe, Rahmen #bfdbfe.
   • Fortschrittsstufe: Schritt 1 & 2 aktiv.
3. Gelöst:
   • Bedeutung: Der Fehler wurde behoben, das Gerät ausgetauscht oder der Dienst wiederhergestellt.
   • Farbthema: Smaragdgrün (#059669), Hintergrund #d1fae5, Rahmen #a7f3d0.
   • Fortschrittsstufe: Schritte 1, 2 und 3 aktiv.

Lebenszyklus-Regeln & Prüfprotokoll

• Jeder Statusübergang muss ein Ereignis im history-Array des Tickets hinzufügen:

  {
    status: newStatus,
    timestamp: new Date().toISOString(),
    note: `Status zu ${newStatus} aktualisiert`
  }
  

• Die Aktualisierung interner Personalnotizen muss adminNote und updatedAt aktualisieren, ohne das ursprüngliche createdAt des Tickets zurückzusetzen.
• Aktualisierungen müssen sofort mit localStorage (campus_helpdesk_tickets_v1) synchronisiert werden.

---

5. Dashboard-Statistiken auf dem neuesten Stand halten

Das Admin-Dashboard bietet Betriebstransparenz in Echtzeit. Alle KPI-Metriken und Diagrammberechnungen müssen dynamisch aus der maßgeblichen tickets-Datenquelle abgeleitet werden:

Metrikberechnungen

1. Gesamtzahl der Tickets: $$\text{Gesamt} = \text{tickets.length}$$
2. Anzahl Ausstehend: $$\text{Ausstehend} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
3. Anzahl In Bearbeitung: $$\text{In Bearbeitung} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
4. Anzahl Gelöst: $$\text{Gelöst} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
5. Auflösungsrate (%): $$\text{Auflösungsrate} = \begin{cases} \text{Math.round}\left(\frac{\text{Gelöst}}{\text{Gesamt}} \times 100\right), & \text{falls Gesamt} > 0 \ 0, & \text{sonst} \end{cases}$$
6. Warteschlange für hohe und dringende Prioritäten: $$\text{Dringend/Hoch} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === 'Dringend' \lor t.\text{priority} === 'Hoch').\text{length}$$
7. Verteilung nach Kategorie und Priorität:
   • Berechnen Sie die Anzahl für alle vordefinierten Kategorien und Prioritäten, auch wenn die Anzahl 0 beträgt, um UI-Flackern oder Divisionen durch Null zu vermeiden.
   • Stellen Sie sicher, dass die Breitenprozentsätze der Fortschrittsbalken immer $\le 100%$ ergeben.

Wickeln Sie alle statistischen Berechnungen in den useMemo-Hook von React mit [tickets] als Abhängigkeit ein, um die Leistung zu erhalten.

---

6. Änderungen testen und Build ausführen

Bevor Sie Codeänderungen einreichen oder eine Aufgabe als abgeschlossen markieren, verifizieren Sie die Anwendung sowohl durch statische Analyse als auch durch Produktions-Build-Schritte:

Verifikationsprotokoll

1. Navigieren Sie zum Projektverzeichnis:

   cd "campus-helpdesk"
   

2. Statischen Code-Lint ausführen:

   npm run lint
   

   • Muss mit Exit-Code 0 beendet werden.
   • Stellen Sie sicher, dass es keine ungenutzten Importe, Variablen oder nicht maskierte JSX-Entitäten gibt.

3. Produktions-Build ausführen:

   npm run build
   

   • Überprüfen Sie, ob Vite die Produktions-Asset-Bündelung ohne Fehler oder Warnungen abschließt.
   • Überprüfen Sie, ob dist/index.html, dist/assets/*.css und dist/assets/*.js erfolgreich erstellt wurden.

4. localStorage-Persistenz überprüfen:

   • Testen Sie, dass das Einreichen eines Tickets den Eintrag localStorage.getItem('campus_helpdesk_tickets_v1') aktualisiert.
   • Testen Sie, dass die Aktualisierung des Ticketstatus nach dem Aktualisieren der Seite erhalten bleibt.
   • Testen Sie die Funktionalität "Beispieldaten zurücksetzen" und "Alles löschen".

---

7. Fehler ehrlich melden

Integrität und Ehrlichkeit sind bei der Meldung von Systemstatus oder Fehlern unerlässlich:

• Fehler nicht verschleiern: Wenn ein Build-Fehler, Syntaxfehler oder Lint-Fehler auftritt, melden Sie die genaue Fehlermeldung, den Dateinamen und die Zeilennummer.
• Ursachenerklärung: Erklären Sie, warum der Fehler aufgetreten ist (z.B. fehlender Import, unbehandelter Null-Fall im Storage-Parser, defekter Prop-Vertrag).
• Nur verifizierte Fehlerbehebungen: Behaupen Sie nicht, dass ein Problem behoben ist, ohne den Verifikationsbefehl (npm run lint / npm run build) erneut ausgeführt und den Exit-Code 0 bestätigt zu haben.
• Transparenz gegenüber dem Benutzer: Wenn eine unerwartete Browserbeschränkung oder ein localStorage-Kontingent-Problem auftritt, erklären Sie die Einschränkung proaktiv und präsentieren Sie klare technische Optionen.