# TK Wiki Newsletter Admin

Produktionsnahes internes Tool zur Erstellung von Thomas-Krenn.AG Newslettern auf Basis der letzten Wiki-Änderungen.

## Funktionen

- Login und Benutzerverwaltung mit RBAC (`admin`, `editor`, `reader`)
- Verpflichtender CSRF-Schutz auf allen POST-Formularen
- Filter in der Web-UI:
  - Zeitraum in Tagen oder „Letzter Monat“
  - Artikel-Auswahl: alle, nur neue oder nur bearbeitete Artikel
  - Kategorie
- Redaktioneller Feinschliff pro Ausgabe:
  - **Redaktionsnotiz** – optionaler Hinweistext, der als eigene Box im Newsletter erscheint
  - **Top-Highlights** – bis zu 3 Artikel per Titel hervorheben (erscheinen oben als Highlight-Box)
- Datenquelle: MediaWiki API (`recentchanges` über `wikiDE/api.php`)
- E-Mail-Layout im Thomas-Krenn Corporate Design:
  - Hero-Header mit Logo, Artikel-Karten mit „Zum Beitrag“-Button, Kontakt- und Adress-Footer
  - Neu-/Bearbeitet-Trennung, Zusammenfassungs-Kacheln, Outlook-taugliche Kopiervorschau
- Export:
  - Plain Text (für Outlook)
  - Raw HTML
- Optionaler SMTP-Versand:
  - UI-konfigurierbar
  - Verteilerlisten
  - flexibler Zeitplan (täglich / wöchentlich an bestimmten Wochentagen / monatlich an einem Tag) über einen Hintergrund-Scheduler
  - eigene Inhalts-Vorgaben für den geplanten Versand (Zeitraum, Artikel-Auswahl, Kategorie)
  - manueller Versand nur per Button – „Generieren“ verschickt nie automatisch
  - Versandprotokoll
- Docker/Compose Betrieb, inkl. automatischem Image-Build & Push in die Gitea Container Registry (per Versions-Tag)

## Start mit Docker

1. Konfiguration anlegen:

   ```bash
   cp .env.example .env
   ```

2. Wichtige Werte in `.env` setzen:
   - `HOST_PORT` (z. B. `8080`, falls `8000` bereits belegt ist)
   - `SECRET_KEY`
   - `ADMIN_BOOTSTRAP_EMAIL`
   - `ADMIN_BOOTSTRAP_PASSWORD`

3. Start:

   ```bash
   docker compose up --build -d
   ```

4. Zugriff:
   - [http://localhost:8080/login](http://localhost:8080/login) (oder dein `HOST_PORT`)

## Container-Image (Gitea Packages)

Fertige Images werden automatisch in die Gitea Container Registry veröffentlicht:

```
git.hexahost.dev/smueller/tk-wiki-newsletter
```

Verfügbare Tags: `latest`, die Version (`X.Y.Z`, `X.Y`, `X`) sowie der kurze Commit-SHA.

Image ziehen und mit vorhandener `.env` starten:

```bash
docker login git.hexahost.dev
docker pull git.hexahost.dev/smueller/tk-wiki-newsletter:latest
docker run -d --name tk-newsletter-admin \
  --env-file .env \
  -p 8080:8000 \
  -v newsletter_data:/app/data \
  git.hexahost.dev/smueller/tk-wiki-newsletter:latest
```

Alternativ in `docker-compose.yml` statt `build: .` das Image referenzieren:

```yaml
services:
  newsletter-admin:
    image: git.hexahost.dev/smueller/tk-wiki-newsletter:latest
    # build: .   # <- nicht mehr nötig, wenn das fertige Image genutzt wird
```

### Automatischer Build (CI/CD)

Der Workflow `.gitea/workflows/docker-build.yml` baut und pusht das Image über Gitea Actions.

- **Auslöser**: nur beim Setzen eines Versions-Tags `v*` (kein Build bei normalen Pushes auf `dev`/`main`).
- **Release-Ablauf** (Build bei Merge `dev` → `main` mit Version):

  ```bash
  git checkout main
  git merge --no-ff dev
  git push origin main
  git tag v1.0.0
  git push origin v1.0.0   # <- startet Build & Push
  ```

- **Benötigte Repo-Secrets** (Settings → Actions → Secrets):
  - `REGISTRY_TOKEN`: Gitea Access-Token mit Scope **Package: Read and write**
  - `REGISTRY_USER` (optional): Registry-Benutzername, falls abweichend vom Repo-Owner
- **Optionale Repo-Variable**: `REGISTRY`, um den Registry-Host zu überschreiben (Default `git.hexahost.dev`).

## Admin-Login & Passwort zurücksetzen

- Das Login erfolgt über **E-Mail + Passwort** (kein separater Benutzername). Beim ersten Start wird der Admin aus `ADMIN_BOOTSTRAP_EMAIL` / `ADMIN_BOOTSTRAP_PASSWORD` angelegt.
- **Wichtig:** Existiert der Admin bereits (persistente DB im Volume `newsletter_data`), wird eine spätere Passwort-Änderung in der `.env` normalerweise **nicht** übernommen.
- Um Passwort/Rolle/Status auf die `.env`-Werte zurückzusetzen: `ADMIN_BOOTSTRAP_RESET=true` setzen und Container neu starten:

  ```bash
  docker compose up -d --force-recreate
  ```

  Nach erfolgreichem Login `ADMIN_BOOTSTRAP_RESET=false` setzen, damit UI-Passwortänderungen nicht bei jedem Neustart überschrieben werden.

## Sicherheits-Hinweise für Produktion

- Reverse Proxy (z. B. Nginx/Traefik) mit TLS vor den Container setzen.
- `SECRET_KEY` lang und zufällig setzen.
- Bootstrap-Admin-Passwort nach erstem Login ändern.
- Netzwerkzugriff auf interne IPs/Netze beschränken.
- Regelmäßige Backups des `data` Volumes.

## Rollenmodell

- `reader`: darf Ergebnisse sehen
- `editor`: darf Newsletter generieren und sofort versenden
- `admin`: zusätzlich Benutzerverwaltung und SMTP-Konfiguration