Initial commit

2026-05-28 11:11:27 +02:00
commit d8a626f6c3
8 changed files with 514 additions and 0 deletions
@@ -0,0 +1,195 @@
+# 📲 WhatsApp Reminder
+
+Ein selbst gehosteter, dockerisierter Bot der automatisch personalisierte WhatsApp-Erinnerungen nach einem monatlichen Plan versendet — jeden Monat eine andere Person aus einer frei konfigurierbaren Rotation.
+
+Basiert auf [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js) und läuft vollständig auf deinem eigenen Server. Kein WhatsApp Business-Konto nötig, keine Cloud-Dienste, komplett kostenlos.
+
+---
+
+## Features
+
+- Schickt jeden Monat eine personalisierte Nachricht an den Kontakt der laut Plan dran ist
+- Überspringt Monate ohne zugewiesenen Kontakt (z.B. der eigene Monat)
+- Cron-basierte Planung mit Zeitzonenunterstützung
+- Session bleibt über Neustarts erhalten — QR-Code einmal scannen, fertig
+- Einfaches Web-Interface zur Übersicht und zum manuellen Auslösen
+- Docker Healthcheck inklusive
+
+---
+
+## Voraussetzungen
+
+- Docker + Docker Compose
+
+Das wars.
+
+---
+
+## Einrichtung
+
+**1. Repo klonen**
+
+```bash
+git clone ssh://git@gitea.aontech.ch:222/neyer/whatsapp-reminder.git
+cd whatsapp-reminder
+```
+
+**2. Kontakte konfigurieren**
+
+`config/contacts.json` aus der Vorlage erstellen:
+
+```bash
+cp config/contacts.example.json config/contacts.json
+```
+
+Dann anpassen:
+
+```json
+[
+  { "id": "alice",  "name": "Alice Müller",   "phone": "+41791234567" },
+  { "id": "bob",    "name": "Bob Schmidt",    "phone": "+41797654321" },
+  { "id": "carol",  "name": "Carol Weber",    "phone": "+41791112233" }
+]
+```
+
+> Telefonnummern im internationalen Format, Leerzeichen und Bindestriche werden automatisch entfernt.
+
+**3. Zeitplan und Nachricht konfigurieren**
+
+`config/settings.json` aus der Vorlage erstellen:
+
+```bash
+cp config/settings.example.json config/settings.json
+```
+
+Dann anpassen:
+
+```json
+{
+  "amount": 25,
+  "currency": "CHF",
+  "cron": "0 7 1 * *",
+  "timezone": "Europe/Zurich",
+  "message": "Hallo {vorname}, diesen Monat bist du wieder dran mit {amount} {currency} ;)\nDanke.",
+  "schedule": [
+    "alice",
+    "bob",
+    null,
+    "carol",
+    "alice",
+    "bob",
+    null,
+    "carol",
+    "alice",
+    "bob",
+    null,
+    "carol"
+  ]
+}
+```
+
+- `schedule` — Array mit 12 Einträgen (Januar → Dezember). Kontakt-`id` oder `null` zum Überspringen.
+- `cron` — Standard-Cron-Ausdruck. `"0 7 1 * *"` = jeden 1. des Monats um 07:00 Uhr.
+- Der Zeitplan wiederholt sich jedes Jahr automatisch — kein jährliches Anpassen nötig.
+
+**Verfügbare Platzhalter in `message`:**
+
+| Platzhalter | Beschreibung |
+|---|---|
+| `{vorname}` | Vorname des Kontakts |
+| `{name}` | Vollständiger Name |
+| `{amount}` | Betrag aus den Einstellungen |
+| `{currency}` | Währung aus den Einstellungen |
+| `{month}` | Name des aktuellen Monats |
+| `{year}` | Aktuelles Jahr |
+
+**4. Container starten**
+
+```bash
+docker compose up --build -d
+```
+
+**5. QR-Code scannen**
+
+Im Browser öffnen:
+
+```
+http://<server-ip>:3001/qr
+```
+
+In WhatsApp: **Verknüpfte Geräte → Gerät verknüpfen** → QR-Code scannen.
+
+Fertig. Die Session wird in `data/` gespeichert und bleibt auch nach Neustarts erhalten.
+
+---
+
+## Web-Interface
+
+| URL | Beschreibung |
+|---|---|
+| `http://<ip>:3001` | Übersicht mit Monatsplan |
+| `http://<ip>:3001/qr` | QR-Code zur Erstanmeldung |
+| `http://<ip>:3001/send-now` | Erinnerung für diesen Monat manuell senden |
+| `http://<ip>:3001/status` | JSON-Status (wird vom Healthcheck genutzt) |
+
+Einen bestimmten Monat manuell auslösen:
+
+```
+http://<ip>:3001/send-now?year=2026&month=5
+```
+
+---
+
+## Konfigurationsreferenz
+
+### `config/contacts.json`
+
+```json
+[
+  {
+    "id": "eindeutige-id",
+    "name": "Vollständiger Name",
+    "phone": "+41791234567"
+  }
+]
+```
+
+### `config/settings.json`
+
+```json
+{
+  "amount": 25,
+  "currency": "CHF",
+  "cron": "0 7 1 * *",
+  "timezone": "Europe/Zurich",
+  "message": "Hallo {vorname}, ...",
+  "schedule": ["id-oder-null", ...]
+}
+```
+
+Änderungen an beiden Dateien werden live übernommen — kein Neustart des Containers nötig.
+
+---
+
+## Port
+
+Das Web-Interface läuft standardmässig auf Port `3001`. Änderbar in `docker-compose.yml`:
+
+```yaml
+ports:
+  - "3001:3000"  # 3001 durch einen freien Port ersetzen
+```
+
+---
+
+## Sicherheit
+
+- Die WhatsApp-Session wird lokal in `data/` auf deinem eigenen Server gespeichert.
+- Das Web-Interface hat keine Authentifizierung — Port 3001 nicht ins öffentliche Internet exponieren.
+- Dieses Projekt nutzt WhatsApp Web intern. Es ist inoffiziell und steht in keiner Verbindung zu WhatsApp/Meta.
+
+---
+
+## Lizenz
+
+MIT