From 87d2f14586c09e3b15ecf5b544a19c668d08e35c Mon Sep 17 00:00:00 2001 From: Meik Date: Mon, 10 Nov 2025 22:55:44 +0100 Subject: [PATCH] minor changes --- README.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 171 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2335b70..e9c172f 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,177 @@ -## Development Requirements +# pickup-config -- Node.js v24.11.0 (see `.nvmrc` for quick switching with nvm) -- npm 11+ (bundled with Node 24) +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. -After switching to the required Node version run: +--- + +## Inhalt + +1. [Architekturüberblick](#architekturüberblick) +2. [Voraussetzungen](#voraussetzungen) +3. [Installation & Entwicklung](#installation--entwicklung) +4. [Konfiguration & Umgebungsvariablen](#konfiguration--umgebungsvariablen) +5. [Wichtige npm-Skripte](#wichtige-npm-skripte) +6. [Testing](#testing) +7. [Verzeichnisstruktur](#verzeichnisstruktur) +8. [Produktions-Build & Deployment](#produktions-build--deployment) +9. [Häufige Workflows](#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** + ```bash + npm ci + ``` +2. **Lokale Entwicklung (React-Devserver)** + ```bash + npm start + ``` + - Läuft auf Port 3000 (CRA Defaults). + - Nutzt Live-Reloading & Proxy-Konfiguration zu den Express-APIs. +3. **Express-Server (Produktion, lokal)** + ```bash + 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`. | +| `node server.js` | Express-Server (liefert `build/`, API & Scheduler). | + +Docker: ```bash -npm ci +docker-compose up --build ``` -This installs dependencies in a clean state that matches the lock file used by the Docker build. +--- + +## Testing + +Standardtests laufen mit: + +```bash +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** + ```bash + npm run build + ``` +2. **Server starten** + ```bash + node server.js + ``` +3. **Container** (optional) + ```bash + docker-compose up --build + ``` + - Container läuft mit dem gebauten Bundle & Express-Server. + +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.