178 lines
6.2 KiB
Markdown
178 lines
6.2 KiB
Markdown
# 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](#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
|
||
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.
|