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](#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`. |
| `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:

```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.
   - Nach relevanten Änderungen an `server.js`, `services/`, `src/`, `Dockerfile` oder `docker-compose.yml` den Container immer neu bauen und neu starten:
     ```bash
     docker compose up -d --build
     ```
     oder alternativ:
     ```bash
     ./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:
   ```bash
   CI=true npm test -- --watch=false
   ```
2. Produktions-Build:
   ```bash
   npm run build
   ```
3. Falls Foodsharing-Endpunkte oder Payloads betroffen sind:
   ```bash
   npm run check:foodsharing-api
   ```
4. Container neu bauen und starten:
   ```bash
   docker compose up -d --build
   ```
5. Laufenden Dienst prüfen:
   ```bash
   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.