minor changes

2025-11-10 22:55:44 +01:00
parent 5bd0176e30
commit 87d2f14586
1 changed files with 171 additions and 6 deletions
--- 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.

-This installs dependencies in a clean state that matches the lock file used by the Docker build.
+> ⚠️ 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
+docker-compose up --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.