Pickup-Config/README.md

pickup-config

Foodsharing pickup-config ist eine kombinierte React/Express-Anwendung, mit der Teams ihre Pickup-Slots konfigurieren, Benachrichtigungen pflegen und das Store-Watch-Monitoring (Team-Status) steuern können. Die App synchronisiert regelmäßig Betriebe, unterstützt Admin-spezifische Einstellungen und speichert benutzerbezogene Präferenzen (z. B. Geokoordinaten) lokal im config/-Verzeichnis.

---

Inhalt

1. Architekturüberblick
2. Voraussetzungen
3. Installation & Entwicklung
4. Konfiguration & Umgebungsvariablen
5. Wichtige npm-Skripte
6. Testing
7. Verzeichnisstruktur
8. Produktions-Build & Deployment
9. Häufige Workflows

---

Architekturüberblick

Bereich	Beschreibung
Client (React)	Lives unter src/ (CRA). Ansicht „Slots buchen“ verwaltet Pickup-Konfigurationen, „Betriebs-Monitoring“ bündelt Store-Watch. Komponenten sind funktionsorientiert, Hooks kapseln API-Logik.
Server (Express)	server.js liefert Produktions-Builds, proxied API-Aufrufe zur Foodsharing-API, persistiert Configs on-disk (config/) und betreibt den Scheduler (services/).
Scheduler / Services	services/ enthält Cron-Jobs (Pickup & Store-Watch), Notification-Integrationen sowie Stores für Config, Watcher, Preferences, etc.
Datenablage	config/ (lokal verbleibend, gitignored) speichert Laufzeitdaten wie pickup-config.json, Admin-Settings, Store-Watch-Status u. a.
Deployment	Dockerfile + docker-compose.yml ermöglichen containerisierte Builds.

---

Voraussetzungen

• Node.js v24.11.0 (siehe .nvmrc für nvm use)
• npm ≥ 11 (im Node-Release enthalten)

Für konsistente Builds immer mit exakt dieser Version arbeiten.

---

Installation & Entwicklung

1. Abhängigkeiten installieren

   npm ci
   

2. Lokale Entwicklung (React-Devserver)

   npm start
   

   • Läuft auf Port 3000 (CRA Defaults).
   • Nutzt Live-Reloading & Proxy-Konfiguration zu den Express-APIs.
3. Express-Server (Produktion, lokal)

   npm run build
   node server.js
   

   • Baut das Frontend (nach build/) und startet den Express-Server (Port PORT oder 3000).
   • Server lädt beim Start bestehende Sessions, Scheduler, Configs.

⚠️ Die Foodsharing-APIs erfordern gültige Credentials. Hinterlege sie per UI (Login) oder config/.

---

Konfiguration & Umgebungsvariablen

Variable	Beschreibung
PORT	Port für node server.js. Default: 3000.
ADMIN_EMAIL	E-Mail-Adresse, die Admin-Rechte erhält (Vergleich in server.js).

Weitere Laufzeitdaten:

• config/ – persistente JSON-Dateien (nicht ins Repo einchecken).
• data/ – ggf. Seeds (defaultConfig.js).
• .env / .env.example – ggf. ergänzen, wenn neue Variablen eingeführt werden.

---

Wichtige npm-Skripte

Script	Zweck
npm start	CRA-Devserver inkl. Live-Reload.
npm run build	Produktionsbundle (CRA).
npm test	Jest/RTL-Tests (Watch-Mode). Für CI CI=true npm test.
npm run check:foodsharing-api	Prüft die genutzten Foodsharing-Endpunkte gegen https://foodsharing.de/api/doc.
node server.js	Express-Server (liefert build/, API & Scheduler).

Docker:

docker-compose up --build

---

Testing

Standardtests laufen mit:

CI=true npm test

• Nutzt React Testing Library.
• Ergänzende Tests pro Komponente (Datei *.test.js neben den Komponenten).
• Für Scheduler/Services sind Integrationstests sinnvoll (derzeit nicht vorhanden).

---

Verzeichnisstruktur

Pfad	Inhalt
src/	React-Quellcode (Komponenten, Hooks, Utils).
public/	CRA-Statics.
services/	Node-Services (Scheduler, Notification, Stores, AdminConfig).
config/	Laufzeitdaten (JSON). Gitignored – niemals commiten.
build/	Output von npm run build. Niemals manuell anpassen.
docker-compose.yml, Dockerfile, rebuildContainer.sh	Deployment-Artefakte.

---

Produktions-Build & Deployment

1. Frontend bauen

   npm run build
   

2. Server starten

   node server.js
   

3. Container (optional)

   docker-compose up --build
   

   • Container läuft mit dem gebauten Bundle & Express-Server.
   • Nach relevanten Änderungen an server.js, services/, src/, Dockerfile oder docker-compose.yml den Container immer neu bauen und neu starten:

     docker compose up -d --build
     

     oder alternativ:

     ./rebuildContainer.sh
     

Abschluss-Checkliste nach relevanten Änderungen

Bei Änderungen an server.js, services/, src/, Dockerfile, docker-compose.yml oder der Foodsharing-API-Integration immer vollständig ausführen:

1. Tests:

   CI=true npm test -- --watch=false
   

2. Produktions-Build:

   npm run build
   

3. Falls Foodsharing-Endpunkte oder Payloads betroffen sind:

   npm run check:foodsharing-api
   

4. Container neu bauen und starten:

   docker compose up -d --build
   

5. Laufenden Dienst prüfen:

   curl http://localhost:3005/api/health
   

   Erwartet wird ein JSON mit \"status\":\"ok\".

Beachte: config/ muss beschreibbar sein, da dort u. a. Session- und Watcher-Infos landen.

---

Häufige Workflows

Slots buchen (Dashboard, „Slots buchen“ Tab)

• Login -> Slots konfigurieren (Aktivieren/Deaktivieren, Wochentage, Datumsspannen).
• Änderungen via „Konfiguration speichern“ persistieren.
• Standort ermitteln für Entfernungssortierung (wird in userPreferences abgelegt und durch /api/location/nearest-store ergänzt).

Store-Watch

• Tab „Betriebs-Monitoring“.
• Regionen laden, Team-Status verfolgen, Watchlist pflegen.
• Admin-Buttons („Regionen neu laden“ etc.) erscheinen nur für Admins.

Notifications

• Zahnrad-Button öffnet das Notification-Panel (auf beiden Tabs).
• Erlaubt ntfy- und Telegram-Einstellungen, Standortverwaltung sowie Testversand.

Admin-Settings

• Tab „Admin“ (nur Admin-E-Mail).
• Globale Cron-/Delay-Einstellungen, Notifications für alle, Ignored Slots.
• „Zu Slots buchen“-Button führt zurück zum Hauptdashboard.

---

Hilfe / Troubleshooting

• Node-Version mismatch → nvm use (siehe .nvmrc).
• Leere Daten / keine Betriebe → npm run build && node server.js oder in der UI „Betriebe aktualisieren“ (Admin), ggf. Logs prüfen.
• Standortbestimmung → Browser muss Geolocation erlauben; Backend nutzt /api/location/nearest-store, benötigt entsprechende Store-Daten (Regionen).

Bei neuen Features:

• Update .env.example falls Variablen hinzugefügt werden.
• config/ nicht committen.
• README + Tests aktualisieren.