From 4dbd6c930f95d73361a595b26c79c59ca25e32bd Mon Sep 17 00:00:00 2001 From: Michael Kaufmann Date: Tue, 17 Feb 2026 18:06:57 +0100 Subject: [PATCH] feat: Expand and refine the system's purpose, scope, and functional/non-functional requirements, adding new categories like smart highlights and update management. --- REQUIREMENTS.md | 103 +++++++++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 41 deletions(-) diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 23faf8d..86e95ee 100755 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -2,55 +2,76 @@ ## 1. Einleitung ### 1.1 Zweck des Systems -Das System dient als Wrapper und Erweiterung für das Bessa Web-Shop-Portal der Knapp-Kantine (https://web.bessa.app/knapp-kantine). Es ermöglicht den Benutzern, Menüpläne einzusehen, Buchungen automatisiert vorzunehmen und Menüdaten persistent für den öffentlichen Zugriff bereitzustellen, ohne dass jeder Betrachter eigene Zugangsdaten benötigt. +Das System dient als Erweiterung für das Bessa Web-Shop-Portal der Knapp-Kantine (https://web.bessa.app/knapp-kantine). Es verbessert die Benutzererfahrung durch eine übersichtliche Wochenansicht, vereinfachte Bestellvorgänge, Kostentransparenz und proaktive Benachrichtigungen. ### 1.2 High-Level-Scope -Das System umfasst einen automatisierten Scraper, eine API zur Datenbereitstellung, einen persistenten Dateispeicher für erfasste Menüs und ein Frontend-Dashboard zur Visualisierung der Kantinen-Wochenpläne. +Das System umfasst die Darstellung von Menüplänen in einer Wochenübersicht, die Verwaltung von Bestellungen und Stornierungen, ein Benachrichtigungssystem für Verfügbarkeitsänderungen, personalisierte Menü-Highlights sowie ein automatisches Update-Management. ## 2. Funktionale Anforderungen -| ID | Anforderung (Satzschablone nach Chris Rupp) | Priorität | -|:---|:---|:---| -| **Auth & Sessions** | | | -| FR-001 | Das System muss dem Benutzer die Möglichkeit bieten, sich mit Mitarbeiternummer und Passwort am Bessa-Backend anzumelden. | Hoch | -| FR-002 | Sobald ein Benutzer erfolgreich angemeldet ist, muss das System eine Session-ID erzeugen und die resultierenden Cookies verschlüsselt für 2 Stunden vorhalten. | Hoch | -| FR-003 | Das System muss die Zugangsdaten (Mitarbeiternummer/Passwort) unmittelbar nach der Verwendung durch den Scraper verwerfen und darf diese nicht dauerhaft speichern. | Hoch | -| **Scraper & Datenextraktion** | | | -| FR-004 | Das System muss in der Lage sein, den wöchentlichen Menüplan (Montag bis Freitag) automatisiert von der Bessa-Webseite zu extrahieren. | Hoch | -| FR-005 | Wenn ein Tag bereits eine Buchung enthält, muss das System den Navigationspfad so anpassen, dass dennoch alle verfügbaren Menüoptionen (M1F, M2F, etc.) extrahiert werden können. | Mittel | -| FR-006 | Das System muss für jedes extrahierte Gericht den Namen, die Beschreibung, den Preis und den Status (verfügbar/nicht verfügbar/ bestellt) erfassen. | Hoch | -| **Datenhaltung & Zugriff** | | | -| FR-007 | Das System muss erfolgreich gescrapte Menüpläne in einer persistenten JSON-Datei (`data/menus.json`) speichern. | Hoch | -| FR-008 | Das System muss unauthentifizierten Benutzern den Zugriff auf bereits im Speicher befindliche Menüdaten ermöglichen (Public Access). | Mittel | -| FR-009 | Falls keine Daten im persistenten Speicher vorhanden sind, muss das System einen nicht authentifizierten Benutzer die Möglichkeit bieten sich anzumelden, um den Speicher zu initialisieren. | Hoch | -| **Dashboard & UI** | | | -| FR-010 | Das System muss dem Benutzer eine intuitive Wochenansicht des Menüplans im Browser darstellen. | Mittel | -| FR-011 | Wenn ein Scraper-Vorgang aktiv ist, muss das System den Status (Fortschritt, aktuelle Aktion) in Echtzeit visualisieren. | Niedrig | -| **Buchungsfunktion** | | | -| FR-012 | Wenn der Benutzer authentifiziert ist, soll das System eine Bestellung für ein Menü ermöglichen. | Mittel | -| FR-013 | Wenn der Benutzer authentifiziert ist, soll das System ein bereits bestelltes Menü zu stornieren. | Mittel | -| **Menu Flagging & Notifications** | | | -| FR-014 | Das System muss authentifizierten Benutzern ermöglichen, nicht bestellbare Menüs (deren Cutoff noch nicht erreicht ist) zu markieren ("flaggen"). | Mittel | -| FR-015 | Das System soll die Statusprüfung für geflaggte Menüs auf verbundene Clients verteilen (Distributed Polling), um die Last zu minimieren. Der Server orchestriert, welcher Client wann welche Menüs prüft. | Mittel | -| FR-016 | Bei Statusänderung auf "verfügbar" muss das System den Benutzer benachrichtigen (Systembenachrichtigung). | Mittel | -| FR-017 | Geflaggte und ausverkaufte Menüs müssen im UI mit einem gelben Glow hervorgehoben werden. | Mittel | -| FR-018 | Geflaggte und verfügbare Menüs müssen im UI mit einem grünen Glow hervorgehoben werden. | Mittel | -| FR-019 | Wenn die Bestell-Cutoff-Zeit erreicht ist, muss das System das Flag automatisch entfernen. | Mittel | +| ID | Anforderung (Satzschablone nach Chris Rupp) | Priorität | Status | +|:---|:---|:---|:---| +| **Authentifizierung** | | | | +| FR-001 | Das System muss dem Benutzer die Möglichkeit bieten, sich mit Mitarbeiternummer und Passwort anzumelden. | Hoch | ✅ | +| FR-002 | Das System muss eine bestehende Bessa-Session erkennen und automatisch wiederverwenden, um eine erneute Anmeldung zu vermeiden. | Hoch | ✅ | +| FR-003 | Das System darf keine Zugangsdaten dauerhaft speichern. Die Authentifizierung muss sitzungsbasiert sein. | Hoch | ✅ | +| FR-004 | Dem Benutzer muss angezeigt werden, ob und als wer er angemeldet ist (Name oder ID). | Mittel | ✅ | +| **Menüanzeige** | | | | +| FR-010 | Das System muss dem Benutzer alle verfügbaren Tagesmenüs einer Woche gleichzeitig in einer Übersicht darstellen. | Hoch | ✅ | +| FR-011 | Das System muss dem Benutzer die Navigation zwischen der aktuellen und der kommenden Woche ermöglichen. | Mittel | ✅ | +| FR-012 | Für jedes Gericht müssen Name, Beschreibung, Preis und Verfügbarkeitsstatus angezeigt werden. | Hoch | ✅ | +| FR-013 | Bereits bestellte Menüs müssen visuell von nicht bestellten unterscheidbar sein (farbliche Markierung, Badge). | Mittel | ✅ | +| FR-014 | Die Tageskarten-Header müssen den Bestellstatus des Tages farblich signalisieren (bestellt / bestellbar / nicht bestellbar). | Niedrig | ✅ | +| FR-015 | Wenn neue Menüdaten geladen werden, muss der Fortschritt dem Benutzer in Echtzeit angezeigt werden. | Niedrig | ✅ | +| FR-016 | Das System muss bereits geladene Menüdaten zwischenspeichern (Caching), um bei erneutem Aufruf sofort eine Übersicht anzeigen zu können. | Mittel | ✅ | +| **Bestellfunktion** | | | | +| FR-020 | Authentifizierte Benutzer müssen ein verfügbares Menü direkt aus der Übersicht bestellen können. | Hoch | ✅ | +| FR-021 | Authentifizierte Benutzer müssen eine bestehende Bestellung direkt aus der Übersicht stornieren können. | Hoch | ✅ | +| FR-022 | Nach Bestellschluss (Cutoff-Zeit) dürfen keine neuen Bestellungen oder Stornierungen für diesen Tag möglich sein. | Hoch | ✅ | +| FR-023 | Es muss möglich sein, dasselbe Menü mehrfach zu bestellen. | Niedrig | ✅ | +| **Kostentransparenz** | | | | +| FR-030 | Das System muss die Gesamtkosten aller Bestellungen einer Woche automatisch berechnen und anzeigen. | Mittel | ✅ | +| **Bestell-Countdown** | | | | +| FR-040 | Das System muss eine Stunde vor Bestellschluss einen visuellen Countdown anzeigen. | Mittel | ✅ | +| **Menü-Flagging & Benachrichtigungen** | | | | +| FR-050 | Authentifizierte Benutzer müssen ausverkaufte Menüs zur Beobachtung markieren können ("flaggen"). | Mittel | ✅ | +| FR-051 | Das System muss geflaggte Menüs periodisch auf Verfügbarkeitsänderungen prüfen. | Mittel | ✅ | +| FR-052 | Bei Statusänderung eines geflaggten Menüs auf „verfügbar" muss der Benutzer benachrichtigt werden (In-App Toast + Systembenachrichtigung). | Mittel | ✅ | +| FR-053 | Geflaggte Menüs müssen im UI visuell hervorgehoben werden (gelber Glow bei ausverkauft, grüner Glow bei verfügbar). | Mittel | ✅ | +| FR-054 | Wenn die Bestell-Cutoff-Zeit erreicht ist, muss das System ein Flag automatisch entfernen. | Mittel | ✅ | +| **Personalisierung: Smart Highlights** | | | | +| FR-060 | Benutzer müssen Schlagwörter (Tags) definieren können, nach denen Menüs automatisch visuell hervorgehoben werden. | Mittel | ✅ | +| FR-061 | Die Hervorhebung muss anhand von Menüname und Beschreibung erfolgen (Substring-Matching, case-insensitive). | Niedrig | ✅ | +| FR-062 | Hervorgehobene Menüs müssen ein Tag-Badge mit dem matchenden Schlagwort anzeigen. | Niedrig | ✅ | +| FR-063 | Die nächste-Woche-Navigation muss die Anzahl der dort gefundenen Highlights als Badge anzeigen. | Niedrig | ✅ | +| **Darstellung & Theming** | | | | +| FR-070 | Das System muss einen hellen und einen dunklen Darstellungsmodus (Light/Dark Theme) unterstützen. | Niedrig | ✅ | +| FR-071 | Die Theme-Präferenz des Benutzers muss persistent gespeichert werden. | Niedrig | ✅ | +| FR-072 | Das System muss beim erstmaligen Laden die System-Präferenz (`prefers-color-scheme`) berücksichtigen. | Niedrig | ✅ | +| **Update-Management** | | | | +| FR-080 | Das System muss periodisch prüfen, ob eine neuere Version verfügbar ist. | Niedrig | ✅ | +| FR-081 | Bei Verfügbarkeit einer neueren Version muss ein diskreter Indikator im Header angezeigt werden. | Niedrig | ✅ | +| FR-082 | Benutzer müssen eine Versionsliste mit Installationslinks einsehen können (Versionsmenü). | Niedrig | ✅ | +| FR-083 | Es muss möglich sein, zu einer älteren Version zurückzukehren (Downgrade). | Niedrig | ✅ | +| FR-084 | Ein Dev-Mode muss es ermöglichen, zwischen stabilen Releases und Entwicklungs-Tags umzuschalten. | Niedrig | ✅ | + ## 3. Nicht-funktionale Anforderungen | Kategorie (ISO 25010) | ID | Anforderung | Zielwert/Metrik | |:---|:---|:---|:---| -| **Performance** | NFR-001 | Antwortzeit der API für gecachte Daten | < 200 ms (95. Perzentil) | -| **Performance** | NFR-007 | Polling-Effizienz & Token-Nutzung | Kein System-Token verfügbar. Polling muss über authentifizierte User-Clients erfolgen. Der Server muss die Anfragen so verteilen, dass redundante Abfragen vermieden werden. | -| **Performance** | NFR-002 | Dauer eines vollständigen Scrape-Vorgangs (exkl. Navigation) | < 30 Sekunden pro Woche | -| **Sicherheit** | NFR-003 | Speicherung von Zugangsdaten | 0 (keine dauerhafte Speicherung von Passwörtern) | -| **Sicherheit** | NFR-004 | Session-Sicherheit | HttpOnly Cookies für die Kommunikation zwischen Frontend und Backend | -| **Wartbarkeit** | NFR-005 | Testabdeckung der Scraper-Logik | Alle Kern-Selektoren müssen durch Debug-HTML-Dumps verifizierbar sein | -| **Benutzbarkeit** | NFR-006 | Mobile Responsiveness | Dashboard muss auf Viewports ab 320px Breite fehlerfrei nutzbar sein | +| **Performance** | NFR-001 | Die Darstellung bereits gecachter Daten muss ohne spürbare Verzögerung erfolgen. | < 200 ms (UI-Rendering) | +| **Performance** | NFR-002 | Das Polling für geflaggte Menüs darf die reguläre Nutzung nicht beeinträchtigen. | Intervall ≥ 5 Minuten | +| **Sicherheit** | NFR-003 | Es dürfen keine Zugangsdaten dauerhaft gespeichert werden. | 0 (keine persistente Speicherung von Passwörtern) | +| **Sicherheit** | NFR-004 | Auth-Tokens müssen sitzungsbasiert gespeichert werden und bei Schließen des Browsers verfallen. | sessionStorage | +| **Benutzbarkeit** | NFR-005 | Die Oberfläche muss auf mobilen Geräten fehlerfrei nutzbar sein. | Viewports ab 320px Breite | +| **Benutzbarkeit** | NFR-006 | Alle interaktiven Elemente müssen Tooltips oder Hilfetexte bieten. | 100% Coverage | +| **Benutzbarkeit** | NFR-007 | Die Benutzeroberfläche muss vollständig in deutscher Sprache sein. | Vollständige Lokalisierung | +| **Wartbarkeit** | NFR-008 | Die Build-Artefakte müssen durch automatisierte Tests validiert werden. | Build-Tests vorhanden | ## 4. Technische Randbedingungen -* **Architektur**: Node.js Backend mit Express (API + Static Serving) und Vanilla JS Frontend. -* **Engine**: Direkte API-Integration (Reverse Engineering der Bessa API) für maximale Performance und Zuverlässigkeit. -* **Datenspeicher**: Dateibasierter JSON-Store für persistente Daten + In-Memory Caching. -* **Schnittstellen**: REST API (`/api/bookings`, `/api/status`, `/api/order`). -* **Runtime**: Node.js Umgebung, Docker-ready. +* **Deployment**: Das System wird als Bookmarklet ausgeliefert, das auf der Bessa-Webseite ausgeführt wird. +* **Datenquelle**: Direkte Integration mit der Bessa REST-API (`api.bessa.app/v1`). +* **Datenhaltung**: Clientseitig via `localStorage` (Menü-Cache, Flags, Highlights, Theme) und `sessionStorage` (Auth-Token). +* **Build**: Bash-basiertes Build-Script, das Bookmarklet-URL, Standalone-HTML und Installer-Seite generiert. +* **Versionierung**: SemVer, verwaltet über GitHub Releases/Tags. +* **Tests**: Python-basierte Build-Tests + Node.js-basierte Logik-Tests.