Barplanner Hilfe & Dokumentation

Das Dashboard: Ihre zentrale Anlaufstelle

Nach dem Einloggen gelangen Sie direkt auf Ihr persönliches Dashboard. Es bietet Ihnen auf einen Blick alle wichtigen Informationen:

• Aktueller Standort: Falls Ihr Betrieb mehrere Standorte hat, wird hier der aktuell ausgewählte Standort angezeigt.
• Wichtige Nachrichten: Ungelesene Rundnachrichten vom Management werden hier prominent angezeigt. Klicken Sie auf die Karte, um die Nachricht zu lesen.
• Inventarübersicht: Falls das Inventarfeature aktiv ist, wird ein schnellzugriff auf das Inventarfeature angezeigt, mit der zusätzlichen Information, ob und wie viele Artikel unter dem Sollbestand sind.
• Planung: Wenn die Manager festgelegt haben, dass die Angestellten zugriff auf die Planungsübersicht haben, wird hier ein Schnellzugriff angezeigt. Diese Ansicht dient für Angestellte nur zur Ansicht.
• Deine Monatsarbeitszeit: Diese Karte zeigt eine Zusammenfassung Ihrer geleisteten und geplanten Stunden für den aktuellen Monat sowie die Differenz.
• Unbesetzte Schichten: Hier sehen Sie alle Schichten, die noch keinem Mitarbeiter zugewiesen sind. Wenn Sie eine dieser Schichten übernehmen möchten, klicken Sie einfach darauf.
• Anstehende Schichten: Eine Liste Ihrer bevorstehenden Schichten. Ein Klick auf eine Schicht zeigt Details wie Kommentare zur Schicht oder zum ganzen Tag. Mit dem Export-Button () können Sie alle Ihre anstehenden Schichten als .ics-Datei herunterladen und in Ihren persönlichen Kalender (z.B. Google Calendar, Apple Kalender) importieren.
• Fehlende Ist-Zeiten: Erscheint, wenn Sie vergessen haben, Ihre Arbeitszeiten für eine vergangene Schicht einzutragen. Ein Klick auf die Schicht öffnet ein Fenster, in dem Sie die Zeiten nachtragen können. Dieses Feld ist nur sichtbar, wenn das Management die Ist-Zeiten über barplanner verwaltet.

Schichten übernehmen

In der Karte "Unbesetzte Schichten" können Sie verfügbare Schichten sehen.

1. Klicken Sie auf eine Schicht, die Sie interessiert.
2. Ein Fenster öffnet sich und zeigt die genauen Zeiten und ggf. die Position (z.B. "Theke").
3. Wenn ein Kommentar zur Schicht hinterlegt ist, wird dieser ebenfalls angezeigt.
4. Klicken Sie auf den grünen Haken (), um die Schicht zu übernehmen. Sie wird dann in Ihre "Anstehenden Schichten" verschoben.

Schicht abgeben und übernehmen

Mitarbeiter können anstehende Schichten zur Übernahme durch Kollegen anbieten, falls sie verhindert sind.

• Schicht abgeben: Klicken Sie im Dashboard auf eine anstehende Schicht. Dort finden Sie einen "Schicht abgeben"-Button. Geben Sie einen Grund an, um die Schicht für andere freizugeben, anschließend werden die Manager als auch ihre Kollegen über E-Mail oder Push Benachrichtigung informiert. Die Schicht bleibt Ihnen zugewiesen, bis ein Kollege sie übernimmt.
• Angebotene Schichten: Eine zur Abgabe markierte Schicht erscheint in Ihren anstehenden Schichten mit einem Warnsymbol. Gleichzeitig wird sie für alle anderen Mitarbeiter in der Liste der "Unbesetzten Schichten" sichtbar.
• Schicht übernehmen: Kollegen können eine zur Abgabe stehende Schicht aus der Liste der unbesetzten Schichten wie gewohnt übernehmen. Der ursprüngliche Mitarbeiter, der neue Mitarbeiter und die Manager werden über die erfolgreiche Übernahme benachrichtigt.

Profil und Verfügbarkeiten verwalten

Über das Menü oben rechts (Ihr Benutzersymbol) gelangen Sie zu den Einstellungen. Hier haben Sie zwei wichtige Bereiche:

a) Profil:

Hier können Sie Ihre persönlichen Daten einsehen und bearbeiten. Dazu gehören:

• Name, Geburtstag, Kontaktdaten (Telefon, E-Mail)
• Adresse, Steuer-ID, IBAN (Diese können gefüllt werden, funktionalität hierzu kommt aber erst in kommenden Updates.)
• Sprachauswahl: Hier kannst du deine Sprache wählen. Egal auf welchem Endgerät du dich anmeldest, die Anwendung wird in der gewählten Sprache angezeigt.
• Sie können hier auch Ihr Passwort ändern.
• Account löschen: Sie haben die Möglichkeit, Ihren Account endgültig zu löschen. Achtung: Diese Aktion kann nicht rückgängig gemacht werden. Damit werden alle Daten gelöscht. Das beeinhaltet die gearbeiteten, als auch die anstehenden Schichten, Zeiten etc.

b) Verfügbarkeiten:

In diesem Tab können Sie dem Management mitteilen, wann Sie arbeiten können und wann nicht. Eine sorgfältig gepflegte Verfügbarkeit ist die Grundlage für eine faire und funktionierende Schichtplanung. Die Seite ist in drei Reiter unterteilt, die aufeinander aufbauen:

• Mein Kalender: Dieser Kalender ist für die Ausnahmen von Ihrer wiederholenden Standardverfügbarkeit. Wenn Sie an einem Tag, an dem Sie normalerweise verfügbar sind, einen Termin haben, tragen Sie dies hier ein.
  • Funktionsweise: Eine Eingabe in "Mein Kalender" überschreibt für diesen speziellen Tag immer Ihre Einstellung aus dem "Wiederholend"-Tab.
  • Status setzen: Klicken Sie in die Zellen, um Ihren Status zu ändern:
    • Grün (Verfügbar): Sie können an diesem Tag arbeiten.
    • Orange (Teilweise): Sie können nur zu bestimmten Zeiten. Es erscheint ein Feld für einen Kommentar (z.B. "Verfügbar ab 18 Uhr", "Arzttermin bis 11 Uhr").
    • Rot (Nicht verfügbar): Sie können an diesem Tag nicht arbeiten.
  • Schichtsystem nutzen: Wenn der Manager das Schichtsystem (z.B. mit "Frühschicht", "Spätschicht") aktiviert hat, können Sie diese vordefinierten Blöcke auswählen, um Ihre Verfügbarkeit noch schneller und präziser anzugeben.
• Team-Kalender: Dieser Reiter bietet eine schreibgeschützte Übersicht der Verfügbarkeiten Ihres gesamten Teams. Er dient rein zur Information und hilft Ihnen, Ihre eigene Planung mit der Ihrer Kollegen abzustimmen, ohne dass Sie jemanden direkt fragen müssen.
• Wiederholend: Dies ist der letzte Reiter, um Ihre grundsätzliche Wochenverfügbarkeit einzutragen. Was Sie hier einstellen, gilt für alle Wochen, in dem angegeben Zeitraum
  • Beispiel: Wenn Sie jeden Montag und Dienstag frei haben, stellen Sie dies hier einmal ein. Sie müssen es dann nicht für jede Woche neu eintragen.
  • Tipp: Pflegen Sie hier Ihre Standardwoche. Das spart Ihnen am meisten Zeit.

Rundnachrichten (Broadcasts)

Manager können Nachrichten an alle oder ausgewählte Mitarbeiter senden.

• Ungelesene Nachrichten: Erscheinen als Benachrichtigungskarte auf dem Dashboard. Klicken Sie darauf, um die Nachricht zu lesen und als "gelesen" zu markieren.
• Verlauf: Über den Menüpunkt "Nachrichtenverlauf" in der Hauptnavigation können Sie alle vergangenen Nachrichten einsehen.

Erweitertes Dashboard

Ihr Dashboard enthält zusätzliche Karten für einen schnellen Überblick:

• Wichtige Hinweise: Diese Karte fasst kritische Informationen zusammen, z.B. die Anzahl unbesetzter Schichten, fehlende Ist-Zeiten im Team oder ob für die Zukunft keine Pläne mehr veröffentlicht sind.
• Nachricht an Mitarbeiter: Ein Schnellzugriff, um eine Rundnachricht (Broadcast) an die Mitarbeiter zu senden.
• Planung: Direkter Link zur Wochen- und Schichtplanung.
• Monatsabschluss: Link zur Übersicht der Monatsgehälter und Arbeitsstunden aller Mitarbeiter.

Rundnachrichten (Broadcasts) senden

Mit dieser Funktion können Sie gezielt Nachrichten an Ihre Mitarbeiter senden.

1. Klicken Sie auf dem Dashboard auf "Nachricht an Mitarbeiter" oder navigieren Sie über das Hauptmenü.
2. Es öffnet sich ein Fenster, in dem Sie Ihre Nachricht verfassen können.
3. Zielgruppe definieren:
   • An alle senden: Die Nachricht geht an alle Mitarbeiter an allen Standorten.
   • Gezielte Auswahl: Wenn "An alle senden" nicht ausgewählt ist, können Sie die Empfänger nach Standort, Positionsgruppe (Rolle) und/oder spezifischer Position filtern. So können Sie z.B. nur eine Nachricht an das Thekenpersonal eines bestimmten Standorts senden.
4. Gültigkeit (optional): Sie können ein Ablaufdatum für die Nachricht festlegen.
5. Klicken Sie auf Senden. Die Empfänger erhalten eine Push-Benachrichtigung (falls aktiviert) und sehen die Nachricht auf ihrem Dashboard.

Broadcast-Verlauf

Hier können alle Nachrichten, die innerhalb eines Markts versendet wurden eingesehen werden, mit den notwendigen Eckdaten um herauszufinden, ob Informationen verteilt wurden.

Schichtplanung: Der Wochenplan

Die Schichtplanung ist eine der zentralen Aufgaben für Manager. Sie finden sie über den Navigationspunkt "Planung".

1. Woche auswählen: Sie können mit den Pfeiltasten zwischen den Wochen navigieren oder eine spezifische Woche über die Datumsauswahl anspringen.
2. Schichten erstellen: Klicken Sie in eine leere Zelle eines Tages, um eine neue Schicht zu erstellen. Es öffnet sich ein Fenster, in dem Sie die Start- und Endzeit, die benötigte Position (falls aktiviert) und die Pausenminuten eintragen können. Sie können hier auch einen Kommentar nur für diese Schicht hinterlegen.
3. Mitarbeiter zuweisen: Im selben Fenster können Sie die Schicht einem Mitarbeiter zuweisen. Das System zeigt Ihnen an, welche Mitarbeiter verfügbar sind. Wenn Sie versuchen, einen nicht verfügbaren oder bereits verplanten Mitarbeiter zuzuweisen, erhalten Sie eine Warnung, können diese aber bei Bedarf überstimmen.
4. Schichten bearbeiten und löschen: Klicken Sie auf eine existierende Schicht, um sie zu bearbeiten oder über den Löschen-Button zu entfernen.
5. Tageskommentar hinzufügen: Am Anfang jeder Tages-Spalte gibt es ein Kommentarfeld. Ein hier eingetragener Kommentar wird allen Mitarbeitern angezeigt, die an diesem Tag arbeiten.
6. Schichtkommentar: Sie können einer spezifischen Schicht einen Kommentar hinzufügen, der dann dem zugewiesen Mitarbeiter angezeigt wird.
7. Woche veröffentlichen: Solange eine Woche nicht veröffentlicht ist, sind die Schichten nur für Manager und Admins sichtbar. Sobald der Plan fertig ist, klicken Sie auf den Button "Woche veröffentlichen". Alle eingeteilten Mitarbeiter erhalten daraufhin eine Benachrichtigung (falls aktiviert) und können ihre Schichten einsehen.

Einstellungen und Regeln: Das Herzstück der Verwaltung

Unter dem Menüpunkt Einstellungen können Sie fast jeden Aspekt der Anwendung für Ihren Standort konfigurieren.

a) Ladendaten

Hier verwalten Sie die Stammdaten Ihres Standorts, wie Name, Adresse und Inhaber. Diese Informationen sind optional, aber wenn gefüllt werden sie beispielsweise in Mails und auch exportierten Kalendereinträgen verwendet.

b) Rollenverwaltung

Diese funktion ist nur sichtbar, wenn in den Regeln "Schichtpositionen aktivieren" ausgewählt wurde. Sie können verschiedene "Rollen" (Positionsgruppen) anlegen, z.B. "Minijob", "Student", "Festangestellt". Für jede Rolle können Standardwerte wie Stundenlohn, Wochenstunden, Urlaubstage und ein maximales Monatsgehalt festgelegt werden. Diese Werte dienen als Vorlage, wenn Sie neue Benutzer anlegen.

c) Regeln

Dies ist die mächtigste Seite zur Konfiguration, zu finden unter Einstellungen -> Regeln. Hier legen Sie die grundlegenden Betriebsregeln fest, indem Sie die jeweiligen Schalter aktivieren oder deaktivieren.

• Pausenregel: Wenn aktiv, können Sie automatische Pausenabzüge basierend auf der Arbeitszeit definieren (z.B. 30 Minuten Pause nach 6 Stunden Arbeit). Diese Automatik kann im Einzelfall bei der Ist-Zeiten-Erfassung manuell korrigiert werden.
• Schichtsystem: Aktiviert ein System mit vordefinierten Schichten (z.B. "Früh", "Spät", "Nacht"). Mitarbeiter können diese Schichten dann bei ihrer Verfügbarkeitsplanung auswählen, was die Planung beschleunigt.
• Mindestruhezeit-Prüfung: Wenn aktiv, warnt das System bei der Planung, falls die gesetzliche Ruhezeit (z.B. 11 Stunden) zwischen zwei Schichten eines Mitarbeiters unterschritten wird. Die Stundenzahl ist hier ebenfalls konfigurierbar.
• Angestellte dürfen Schichtplan sehen: Steuert, ob normale Mitarbeiter den gesamten Schichtplan einsehen können oder nur ihre eigenen Schichten.
• Ist-Stunden-Erfassung aktivieren: Ein zentraler Schalter, der die gesamte Logik rund um die Erfassung von tatsächlichen Arbeitszeiten (Ist-Zeiten) aktiviert.
• Schichtpositionen aktivieren: Aktiviert die detaillierte Planung mit Positionen (z.B. "Theke 1", "Service A"). Wenn dies aktiv ist, erscheint der zusätzliche Reiter "Positionen" in den Einstellungen.
  • Zusatzregel: Sie können hier ebenfalls festlegen, dass Mitarbeiter nur auf den Positionen geplant werden können, die ihnen in der Benutzerverwaltung explizit zugewiesen wurden.
• Inventur-Feature aktivieren: Mit diesem Schalter wird das gesamte Inventur-Modul in der Anwendung sichtbar und nutzbar gemacht.
  • Zusatzregel: Hier können Sie auch die Berechtigung steuern, ob jeder Mitarbeiter den Ist-Bestand ändern darf oder nur Manager.
• Reservierungssystem aktivieren: Schaltet das gesamte Reservierungs-Modul frei.

d) Positionen

Dieser Reiter ist nur sichtbar, wenn die "Schichtpositionen" in den Regeln aktiviert sind. Hier können Sie die spezifischen Positionen anlegen (z.B. "Runner", "Barista"), ihnen eine Farbe für den Plan zuweisen und eine davon als Standard definieren.

e) Öffnungszeiten & Sperrtage

Hier verwalten Sie die regulären wöchentlichen Öffnungszeiten und können über einen Kalender einzelne Tage für Reservierungen sperren (z.B. für geschlossene Gesellschaften) oder Sonderöffnungstage (z.B. an Feiertagen) anlegen. Es steuert hierbei ausschließlich das Reservierungsfeature und die Möglichkeit über eine Webseite und unsere API Reservierungen anzufragen.

Weitere Verwaltungsfunktionen

• Benutzerverwaltung: Hier legen Sie neue Benutzer an, weisen ihnen eine Rolle, Gehalt und einen Standort zu und können bestehende Benutzer bearbeiten oder deaktivieren.

Monatsabschluss und Gehaltsübersicht

Diese Seite, erreichbar über den Navigationspunkt "Monatsabschluss", ist entscheidend für die Gehaltsabrechnung. Sie bietet eine detaillierte monatliche Zusammenfassung für alle Mitarbeiter.

• Monat auswählen: Sie können den gewünschten Monat und das Jahr auswählen, um auch vergangene Abrechnungen einzusehen.
• Detaillierte Ansicht: Pro Mitarbeiter sehen Sie eine Aufschlüsselung von:
  • Geplanten vs. tatsächlich geleisteten Arbeitsstunden.
  • Automatisch berechneten Pausenminuten.
  • Dem daraus resultierenden Brutto-Lohn, der auf dem im System hinterlegten Stundenlohn basiert.

Diese Übersicht dient als Grundlage für die Lohn- und Gehaltsabrechnung.

Infrastruktur und Aufbau

• Server-Umgebung: Die Anwendung läuft auf einem Apache-Server. Das Backend ist eine Node.js-Anwendung, die mit dem Express.js-Framework aufgebaut ist.
• Frontend-Serving: Das Frontend, bestehend aus statischen HTML-, CSS- und JavaScript-Dateien, wird für die Produktion mit Vite gebündelt und optimiert. Im Betrieb wird das Frontend direkt vom Node.js/Express-Backend ausgeliefert, um eine nahtlose Einheit zu bilden.
• Hintergrundprozesse (Cron Jobs): Das System nutzt automatisierte, zeitgesteuerte Skripte (Cron Jobs) für wiederkehrende Aufgaben. Dazu gehören das Senden von Erinnerungen für fehlende Ist-Zeiten oder das Aufräumen alter Daten (z.B. Löschnachrichten nach einem Jahr).

Datenbank und Multi-Tenancy-Architektur

Das Herzstück der Anwendung ist eine MariaDB-Datenbank, die auf einem Multi-Tenant-Modell basiert. Das bedeutet, die Anwendung kann mehrere Mandanten (z.B. verschiedene Bars oder Restaurantketten) komplett voneinander getrennt auf derselben Codebasis verwalten.

• Globale Datenbank (barplanner_master): Es gibt eine zentrale "Master"-Datenbank. Sie enthält die Liste aller Mandanten (Bar-Gruppen) und die globalen Benutzer-Logins. Ihre Hauptaufgabe ist es, den Benutzer zu authentifizieren und ihn dem richtigen Mandanten zuzuordwohnen.
• Mandanten-Datenbanken (barplanner_agent, etc.): Jeder Mandant besitzt seine eigene, separate Datenbank. In dieser Datenbank werden alle mandantenspezifischen Daten gespeichert: Schichten, Mitarbeiter des Standorts, Einstellungen, Regeln, Verfügbarkeiten etc.
• Dynamische Datenbankverbindung (dbMiddleware.js): Die Magie der Multi-Tenancy geschieht in einer speziellen Middleware. Nach dem Login wird die Kennung des Mandanten (activeBarGroupSlug) in der Session des Benutzers gespeichert. Bei jeder nachfolgenden Anfrage an das Backend:
  1. Die dbMiddleware liest die activeBarGroupSlug aus der Session.
  2. Sie nutzt einen "DB Resolver", um die passende Datenbankverbindung für genau diesen Mandanten aus einem Pool von Verbindungen auszuwählen.
  3. Diese spezifische Datenbankverbindung wird an das request-Objekt (req.db) angehängt.
  4. Alle nachfolgenden Controller und Datenbankabfragen für diese Anfrage verwenden automatisch die richtige, isolierte Datenbank des Mandanten.

Dieses Design stellt sicher, dass die Daten eines Mandanten niemals mit denen eines anderen in Berührung kommen, was für Datensicherheit und -integrität sorgt.

Sicherheit

• Authentifizierung & Sessions: Der Zugriff auf geschützte Bereiche wird durch ein Session-basiertes System (express-session) geregelt. Jede Anfrage an einen geschützten Endpunkt wird von der checkSession-Middleware geprüft. Ohne gültige Session wird der Zugriff verweigert.
• Passwort-Sicherheit: Passwörter werden nicht im Klartext gespeichert. Sie werden mit einem Algorithmus gehasht, bevor sie in der Datenbank abgelegt werden.
• Rollenbasiertes Berechtigungssystem (RBAC): Die Anwendung nutzt ein feingranulares Rechtesystem. Middleware prüft bei bestimmten Aktionen, ob der Benutzer die erforderliche Berechtigungsstufe hat.
• Schutz vor SQL-Injection: Alle Datenbankabfragen werden mit parametrisierten Abfragen (Prepared Statements) ausgeführt. Das bedeutet, dass Benutzereingaben strikt von der SQL-Logik getrennt werden, wodurch SQL-Injection-Angriffe verhindert werden.
• API-Sicherheit: Die meisten API-Endpunkte sind durch die checkSession-Middleware geschützt. Öffentliche Endpunkte (z.B. für eine Reservierungs-Website) erfordern einen API-Key zur Authentifizierung.

Technologie-Stack im Überblick

• Backend: Node.js, Express.js
• Datenbank: MariaDB
• Frontend: Pures (Vanilla) HTML, CSS und JavaScript. Es wird bewusst auf große Frontend-Frameworks wie React oder Angular verzichtet, und dann sind die Anforderungen zu groß geworden, sodass ich das nichtmehr umbauen wollte.
• Build-Tool: Vite (für das Bündeln und Optimieren des Frontends)
• Icons: FontAwesome
• Push-Benachrichtigungen: Firebase Cloud Messaging (FCM)