diff --git a/README.md b/README.md new file mode 100644 index 0000000..59a3f3b --- /dev/null +++ b/README.md @@ -0,0 +1,229 @@ +

+ MCM Logo +

+ +

MCM – MultiCustomerMessenger

+ +

+ Unified Messaging Gateway für Telegram, WhatsApp und SMS auf dem Raspberry Pi +

+ +--- + +## Überblick + +MCM ist ein selbst gehostetes Messaging-Gateway, das eingehende und ausgehende Nachrichten über mehrere Kanäle zentral verwaltet. Die Bedienung erfolgt über eine REST-API oder eine interaktive Terminal-Oberfläche (TUI), die auch im Browser läuft. + +**Unterstützte Kanäle** + +| Kanal | Backend | +|---|---| +| Telegram | python-telegram-bot (Bot, Long-Polling) | +| WhatsApp | Green API (green-api.com) | +| SMS | python-gsmmodem-new (USB-Modem) | + +--- + +## Features + +- REST-API (FastAPI) mit OpenAPI-Dokumentation (`/docs`) +- Terminal-UI (Textual) – im Browser via `textual serve` +- Multi-User-Authentifizierung mit JWT-Tokens +- Benutzerverwaltung (Admin-Rollen, Passwort ändern) +- Konversations- und Kontaktverwaltung in der Datenbank +- MariaDB als Produktions-Backend, SQLite für lokale Entwicklung +- SMS optional – läuft auch ohne angeschlossenes USB-Modem +- systemd-Dienst für den Dauerbetrieb + +--- + +## Voraussetzungen + +- Python 3.11+ +- MariaDB (optional, SQLite ist Standard) +- USB-GSM-Modem (optional, für SMS) +- Green API Account (optional, für WhatsApp) +- Telegram Bot Token (optional) + +--- + +## Installation + +```bash +# 1. Repository klonen +git clone https://gitea.it-drui.de/viewit/MCM.git +cd MCM + +# 2. Virtuelle Umgebung anlegen und Pakete installieren +python3 -m venv .venv +.venv/bin/pip install -r requirements.txt + +# 3. Konfiguration anlegen +cp .env.example .env +# .env mit den eigenen Werten befüllen (Tokens, DB-URL, Secret Key) +``` + +--- + +## Konfiguration (`.env`) + +```env +# API +API_KEY=mein-sicherer-api-key +HOST=0.0.0.0 +PORT=8000 + +# Datenbank +DATABASE_URL=sqlite:///./mcm.db +# Für MariaDB: +# DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/mcm + +# Telegram +TELEGRAM_TOKEN=123456:ABC-... + +# WhatsApp (Green API) +WHATSAPP_ID_INSTANCE=1234567890 +WHATSAPP_API_TOKEN=abcdef... + +# SMS (USB-Modem) +SMS_ENABLED=false +SMS_PORT=/dev/ttyUSB0 + +# Authentifizierung +SECRET_KEY=change-this-secret-key-min-32-chars!! +TOKEN_EXPIRE_HOURS=24 + +# Standard-Admin (wird beim ersten Start angelegt) +DEFAULT_ADMIN_USER=admin +DEFAULT_ADMIN_PASSWORD=admin +``` + +> **Wichtig:** `SECRET_KEY` sollte ein langer zufälliger String sein: +> ```bash +> openssl rand -hex 32 +> ``` + +--- + +## Starten + +### Mit Terminal-UI (lokal) + +```bash +.venv/bin/python main.py +``` + +### Nur API (kein Terminal) + +```bash +.venv/bin/python main.py --no-tui +# oder +.venv/bin/python main_api_only.py +``` + +### TUI im Browser + +```bash +# API separat starten (Terminal 1) +.venv/bin/python main_api_only.py + +# TUI als Browser-App (Terminal 2) +.venv/bin/python -m textual serve --host 0.0.0.0 --port 8001 tui_standalone.py +``` + +Dann im Browser öffnen: `http://:8001` + +--- + +## Benutzerverwaltung + +Beim ersten Start wird automatisch ein Admin-Benutzer angelegt (`admin` / `admin`). +Das Passwort sollte direkt danach geändert werden. + +### API-Endpoints + +| Methode | Pfad | Beschreibung | +|---|---|---| +| `POST` | `/api/v1/auth/login` | Anmeldung → JWT-Token | +| `GET` | `/api/v1/auth/me` | Aktueller Benutzer | +| `GET` | `/api/v1/users/` | Benutzerliste (Admin) | +| `POST` | `/api/v1/users/` | Benutzer anlegen (Admin) | +| `PUT` | `/api/v1/users/{id}` | Benutzer bearbeiten | +| `DELETE` | `/api/v1/users/{id}` | Benutzer löschen (Admin) | + +### Beispiel – Login per curl + +```bash +curl -X POST http://localhost:8000/api/v1/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username": "admin", "password": "admin"}' +``` + +--- + +## API-Übersicht + +Vollständige Dokumentation unter `http://localhost:8000/docs` + +| Methode | Pfad | Beschreibung | +|---|---|---| +| `POST` | `/api/v1/messages` | Nachricht senden | +| `GET` | `/api/v1/conversations/` | Konversationen auflisten | +| `GET` | `/api/v1/conversations/{id}/messages` | Nachrichten einer Konversation | +| `GET` | `/api/v1/contacts/` | Kontakte auflisten | +| `POST` | `/api/v1/contacts/` | Kontakt anlegen | +| `GET` | `/api/v1/channels/status` | Kanal-Status | +| `GET` | `/health` | Health-Check | + +--- + +## systemd-Dienst + +```bash +# Dienst installieren +sudo cp install/mcm.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable mcm +sudo systemctl start mcm + +# Status prüfen +sudo systemctl status mcm +journalctl -u mcm -f +``` + +Weitere Details: [install/README_install.md](install/README_install.md) + +--- + +## Projektstruktur + +``` +MCM/ +├── main.py # Einstiegspunkt (TUI + API) +├── main_api_only.py # Nur API (für systemd) +├── tui_standalone.py # Einstiegspunkt für textual serve +├── config.py # Einstellungen (pydantic-settings) +├── schemas.py # Pydantic-Modelle +├── api/ +│ ├── app.py # FastAPI-Anwendung +│ ├── auth.py # JWT + API-Key Authentifizierung +│ └── routes/ # REST-Routen +├── channels/ # Kanal-Implementierungen +├── services/ # Business-Logik +├── tasks/ # APScheduler (WhatsApp-Polling) +├── tui/ +│ ├── api_client.py # HTTP-Client für TUI → API +│ ├── app.py # Textual App +│ ├── screens/ # Login- und Hauptbildschirm +│ └── styles.tcss # TUI-Stylesheet +├── db/ +│ ├── models.py # SQLAlchemy-Modelle +│ └── database.py # Engine + Session +└── install/ # systemd-Dienst + Installationsanleitung +``` + +--- + +## Lizenz + +Privates Projekt – alle Rechte vorbehalten.