feat: Add Excel, PDF export, and user generation modules
- Implemented `excel_export.py` for generating library item exports in Excel format. - Created `pdf_export.py` for generating audit reports compliant with DIN 5008 standards, including detailed event tables and signature blocks. - Developed `generate_user.py` for interactive user creation with validation for usernames and passwords. - Introduced `module_registry.py` for managing module states and path matching. - Added a basic `__init__.py` in the `terminplaner` module for initialization.
This commit is contained in:
@@ -0,0 +1,442 @@
|
||||
# Web Push Notifications für Inventarsystem
|
||||
|
||||
## Überblick
|
||||
|
||||
Web Push Notifications ermöglichen es, Benutzer über wichtige Ereignisse in Echtzeit zu benachrichtigen, auch wenn sie die Anwendung nicht aktiv nutzen. Diese Implementierung nutzt:
|
||||
|
||||
- **Service Workers** für Hintergrundprozesse und Offline-Unterstützung
|
||||
- **Web Push API** für Benachrichtigungen auf Desktop und Mobil
|
||||
- **MongoDB** zur Speicherung von Subscriptions
|
||||
- **VAPID-Authentifizierung** für sichere Push-Kommunikation
|
||||
|
||||
## Architektur
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Browser / Client-Side │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ • Service Worker (static/service-worker.js) │
|
||||
│ • Push Notification Manager (js/push-notifications) │
|
||||
│ • Web App Manifest (manifest.json) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
↕ (Push Subscriptions / Notifications)
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Server / Backend │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ • Flask API Endpoints (/api/push/*) │
|
||||
│ • Push Notification Manager (push_notifications.py)│
|
||||
│ • MongoDB Collections (push_subscriptions) │
|
||||
│ • VAPID Key Management │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
↕ (VAPID-signed push messages)
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Push Service (Firebase, Web Push Service) │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ • Stores subscriptions │
|
||||
│ • Delivers push messages to browsers │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Setup & Konfiguration
|
||||
|
||||
### 1. VAPID-Schlüssel generieren
|
||||
|
||||
VAPID-Schlüssel sind erforderlich für die Authentifizierung mit dem Push-Dienst:
|
||||
|
||||
```bash
|
||||
cd /path/to/Inventarsystem
|
||||
bash generate-vapid-keys.sh
|
||||
```
|
||||
|
||||
Dies erzeugt ein Schlüsselpaar. **Speichern Sie den Private Key sicher!**
|
||||
|
||||
Beispielausgabe:
|
||||
```
|
||||
PUBLIC KEY (share with browsers):
|
||||
BBxyz...xyz
|
||||
|
||||
PRIVATE KEY (keep secret!):
|
||||
AAabc...abc
|
||||
```
|
||||
|
||||
### 2. Umgebungsvariablen setzen
|
||||
|
||||
Speichern Sie die Schlüssel als Umgebungsvariablen:
|
||||
|
||||
```bash
|
||||
export VAPID_PUBLIC_KEY="BBxyz...xyz"
|
||||
export VAPID_PRIVATE_KEY="AAabc...abc"
|
||||
export VAPID_SUBJECT="mailto:admin@inventarsystem.local"
|
||||
```
|
||||
|
||||
Für Docker:
|
||||
```bash
|
||||
# In .env oder docker-compose.yml
|
||||
VAPID_PUBLIC_KEY=BBxyz...xyz
|
||||
VAPID_PRIVATE_KEY=AAabc...abc
|
||||
VAPID_SUBJECT=mailto:admin@inventarsystem.local
|
||||
```
|
||||
|
||||
### 3. Abhängigkeiten installieren
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
# oder
|
||||
pip install pywebpush
|
||||
```
|
||||
|
||||
### 4. MongoDB Collection initialisieren
|
||||
|
||||
Die `push_subscriptions` Collection wird automatisch erstellt beim ersten Speichern einer Subscription. Indizes werden automatisch erstellt durch:
|
||||
|
||||
```python
|
||||
from Web.push_notifications import ensure_push_subscriptions_collection
|
||||
ensure_push_subscriptions_collection()
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### `POST /api/push/subscribe`
|
||||
|
||||
Speichert eine Notification Subscription des Benutzers.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"subscription": {
|
||||
"endpoint": "https://fcm.googleapis.com/fcm/send/...",
|
||||
"keys": {
|
||||
"p256dh": "BCOA...",
|
||||
"auth": "kXA..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully subscribed to push notifications"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/push/unsubscribe`
|
||||
|
||||
Deaktiviert eine Notification Subscription.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"endpoint": "https://fcm.googleapis.com/fcm/send/..."
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully unsubscribed from push notifications"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/push/subscriptions`
|
||||
|
||||
Listet alle aktiven Subscriptions des aktuellen Benutzers auf.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"count": 2,
|
||||
"subscriptions": [
|
||||
{
|
||||
"id": "507f1f77bcf86cd799439011",
|
||||
"endpoint": "https://...",
|
||||
"created_at": "2026-04-10T14:30:00",
|
||||
"last_used": "2026-04-10T15:45:00",
|
||||
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/push/vapid-key`
|
||||
|
||||
Ruft den öffentlichen VAPID-Schlüssel ab (erforderlich für Browser).
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"vapid_key": "BBxyz...xyz"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/push/test` (Admin only)
|
||||
|
||||
Sendet eine Test-Benachrichtigung.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"target_user": "username" // optional, default: current user
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Test push sent to 2 subscription(s)"
|
||||
}
|
||||
```
|
||||
|
||||
## Frontend Integration
|
||||
|
||||
### Aktivierung in Settings
|
||||
|
||||
Fügen Sie einen Container in Ihre Einstellungsseite ein:
|
||||
|
||||
```html
|
||||
<div id="push-notification-settings"></div>
|
||||
|
||||
<script src="{{ url_for('static', filename='js/push-notifications.js') }}"></script>
|
||||
<script>
|
||||
document.addEventListener('DOMContentLoaded', function() {
|
||||
showPushNotificationSettings();
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
Dies zeigt einen Button und Subscription-Status an.
|
||||
|
||||
### Manuelle Steuerung
|
||||
|
||||
```javascript
|
||||
// Initialisieren
|
||||
await pushNotificationManager.init();
|
||||
|
||||
// Benachrichtigungen aktivieren
|
||||
await pushNotificationManager.subscribe();
|
||||
|
||||
// Benachrichtigungen deaktivieren
|
||||
await pushNotificationManager.unsubscribe();
|
||||
|
||||
// Status prüfen
|
||||
const isSubscribed = await pushNotificationManager.isSubscribed();
|
||||
|
||||
// Test-Benachrichtigung senden (Admin)
|
||||
await pushNotificationManager.sendTestNotification();
|
||||
```
|
||||
|
||||
## Backend Integration
|
||||
|
||||
### Benachrichtigungen versenden
|
||||
|
||||
```python
|
||||
from Web import push_notifications as pn
|
||||
|
||||
# Benachrichtigung an einen Benutzer
|
||||
pn.send_push_notification(
|
||||
'username',
|
||||
'Titel',
|
||||
'Nachricht',
|
||||
url='/my_borrowed_items',
|
||||
reference={'item_id': '123', 'type': 'borrowing'}
|
||||
)
|
||||
|
||||
# Benachrichtigung an alle Admins
|
||||
pn.send_push_to_all_admins(
|
||||
'Admin Alert',
|
||||
'Wichtiges Ereignis',
|
||||
url='/main_admin'
|
||||
)
|
||||
```
|
||||
|
||||
### Integration mit Notification-System
|
||||
|
||||
Benachrichtigungen werden automatisch über Push versendet, wenn erstellt:
|
||||
|
||||
```python
|
||||
# In app.py
|
||||
_create_notification(
|
||||
db,
|
||||
audience='user',
|
||||
notif_type='borrowing_activated',
|
||||
title='Ausleihung aktiviert',
|
||||
message='Ihre geplante Ausleihung ist jetzt aktiv',
|
||||
target_user='john_doe',
|
||||
reference={'url': '/my_borrowed_items', 'item_id': '123'}
|
||||
)
|
||||
# → Schreibt in DB + sendet Push-Benachrichtigung
|
||||
```
|
||||
|
||||
## MongoDB Schema
|
||||
|
||||
### Collection: `push_subscriptions`
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": ObjectId("..."),
|
||||
"Username": "john_doe",
|
||||
"Endpoint": "https://fcm.googleapis.com/fcm/send/...",
|
||||
"Keys": {
|
||||
"p256dh": "BCOA...",
|
||||
"auth": "kXA..."
|
||||
},
|
||||
"SubscriptionHash": "abc123def456...",
|
||||
"IsActive": true,
|
||||
"CreatedAt": ISODate("2026-04-10T14:30:00Z"),
|
||||
"LastUsed": ISODate("2026-04-10T15:45:00Z"),
|
||||
"UserAgent": "Mozilla/5.0..."
|
||||
}
|
||||
```
|
||||
|
||||
**Indizes:**
|
||||
- `Username` - Schnelle Abfrage nach Benutzer
|
||||
- `{Username: 1, IsActive: 1}` - Abfrage aktiver Subscriptions
|
||||
- `CreatedAt` - Zeitbasierte Bereinigung
|
||||
- `SubscriptionHash` - Eindeutigkeit, Duplikat-Verhinderung
|
||||
|
||||
## Service Worker
|
||||
|
||||
### Funktionen
|
||||
|
||||
Die Service Worker (`static/service-worker.js`) behandelt:
|
||||
|
||||
1. **Push Events** - Empfängt und zeigt Benachrichtigungen an
|
||||
2. **Click Handler** - Öffnet relevante URLs bei Benachrichtigungs-Klick
|
||||
3. **Offline Caching** - Speichert statische Assets offline
|
||||
4. **Background Sync** - Synchronisiert Daten im Hintergrund
|
||||
5. **Installation** - Installiert sich selbst und lädt Cache vor
|
||||
|
||||
### Push-Payload-Format
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Ausleihung aktiviert",
|
||||
"body": "Ihre geplante Ausleihung ist jetzt aktiv",
|
||||
"icon": "/static/img/logo-192x192.png",
|
||||
"badge": "/static/img/badge-72x72.png",
|
||||
"tag": "notification-borrowing_activated",
|
||||
"url": "/my_borrowed_items",
|
||||
"reference": {
|
||||
"item_id": "123",
|
||||
"type": "borrowing"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Benachrichtigungen werden nicht empfangen
|
||||
|
||||
1. **VAPID-Schlüssel nicht gesetzt**
|
||||
```bash
|
||||
# Überprüfen
|
||||
curl http://localhost:5000/api/push/vapid-key
|
||||
# Sollte VAPID_PUBLIC_KEY zurückgeben, nicht "nicht konfiguriert"
|
||||
```
|
||||
|
||||
2. **Service Worker nicht registriert**
|
||||
- Browser DevTools → Application → Service Workers
|
||||
- Sollte "activated and running" anzeigen
|
||||
- Überprüfen Sie Console auf Fehler
|
||||
|
||||
3. **Notification Permission verweigert**
|
||||
- Browser-Einstellungen überprüfen
|
||||
- Site-Benachrichtigungsberechtigungen zurücksetzen
|
||||
- `chrome://settings/content/notifications` (Chrome)
|
||||
|
||||
4. **No active subscriptions**
|
||||
```bash
|
||||
# MongoDB überprüfen
|
||||
db.push_subscriptions.find({Username: "username"})
|
||||
# Sollte aktive Subscriptions anzeigen
|
||||
```
|
||||
|
||||
### Debug-Befehle
|
||||
|
||||
```bash
|
||||
# Alle Subscriptions anzeigen
|
||||
docker exec inventarsystem-mongodb mongosh --eval \
|
||||
'db.push_subscriptions.find({}).pretty()' Inventarsystem
|
||||
|
||||
# Test-Push senden
|
||||
curl -X POST http://localhost:5000/api/push/test \
|
||||
-H "Content-Type: application/json" \
|
||||
-c cookies.txt -b cookies.txt
|
||||
|
||||
# Logs überprüfen
|
||||
docker logs inventarsystem-app | grep -i "push\|notification"
|
||||
```
|
||||
|
||||
## Browser-Unterstützung
|
||||
|
||||
| Browser | Desktop | Mobile | Service Worker | Push API |
|
||||
|---------|---------|--------|-----------------|----------|
|
||||
| Chrome | ✅ | ✅ | ✅ | ✅ |
|
||||
| Firefox | ✅ | ✅ | ✅ | ✅ |
|
||||
| Safari | ⚠️ | ✅ | ⚠️ | ⚠️ |
|
||||
| Edge | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
**Safari-Hinweis:** Verwendet Web Push über APNs mit Einschränkungen.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Notification Häufigkeit
|
||||
- Nicht mehr als 1 Benachrichtigung pro Minute pro Benutzer
|
||||
- Sammelns Sie verwandte Events
|
||||
|
||||
### 2. Payload-Größe
|
||||
- Halten Sie Nachrichten kurz (<100 Zeichen)
|
||||
- Verwenden Sie `reference` für Kontext, nicht `body`
|
||||
|
||||
### 3. Sicherheit
|
||||
- **Private Key**: Niemals in Code commiten!
|
||||
- **Secrets**: Nur als Umgebungsvariablen speichern
|
||||
- **Validate**: Server-seitig alle Subscription-Daten validieren
|
||||
|
||||
### 4. Datenschutz
|
||||
- Dokumentieren Sie Push-Sammlung (DSGVO)
|
||||
- Bieten Sie einfache Opt-out-Möglichkeit
|
||||
- Speichern Sie keine PII in Push-Nachrichten
|
||||
|
||||
### 5. Wartung
|
||||
|
||||
Stale Subscriptions automatisch bereinigen:
|
||||
|
||||
```python
|
||||
# In Scheduler oder Cron-Job
|
||||
from Web.push_notifications import cleanup_inactive_subscriptions
|
||||
cleanup_inactive_subscriptions() # Entfernt inaktive Subs älter als 30 Tage
|
||||
```
|
||||
|
||||
## Performance-Tipps
|
||||
|
||||
1. **Batch-Sends**: Senden Sie mehrere Pushes in einem Query
|
||||
2. **Async**: Verwenden Sie Background Tasks für Push-Sending
|
||||
3. **Redis**: Nutzen Sie Cache für häufig angeforderte VAPID-Keys
|
||||
4. **Indexes**: MongoDB-Indexes auf `Username`, `IsActive` sollten vorhanden sein
|
||||
|
||||
## Zukünftige Erweiterungen
|
||||
|
||||
- [ ] Action Buttons in Benachrichtigungen (Approve/Deny)
|
||||
- [ ] Benachrichtigungs-Kategorien und Gruppierung
|
||||
- [ ] Rich-Media-Unterstützung (Bilder, Video)
|
||||
- [ ] Scheduled Notifications
|
||||
- [ ] Analytics & Delivery Tracking
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0 (Inventarsystem v0.5+)
|
||||
**Letzte Aktualisierung:** April 2026
|
||||
Reference in New Issue
Block a user