cleanup

2026-02-07 09:23:49 +00:00
parent 96eabe3db6
commit 36552903e7
85 changed files with 9820870 additions and 1767 deletions
--- a/bitbylaw/docs/CONFIGURATION.md
+++ b/bitbylaw/docs/CONFIGURATION.md
@@ -0,0 +1,509 @@
+# Configuration Guide
+
+## Environment Variables
+
+Alle Konfiguration erfolgt über Environment Variables. Diese können gesetzt werden:
+1. In `.env` Datei (lokale Entwicklung)
+2. In systemd service file (production)
+3. Export in shell
+
+## Advoware API Configuration
+
+### Required Variables
+
+```bash
+# Advoware API Base URL
+ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
+
+# Product ID (typischerweise 64)
+ADVOWARE_PRODUCT_ID=64
+
+# Application ID (von Advoware bereitgestellt)
+ADVOWARE_APP_ID=your_app_id_here
+
+# API Key (Base64-encoded für HMAC-512 Signatur)
+ADVOWARE_API_KEY=your_base64_encoded_key_here
+
+# Kanzlei-Kennung
+ADVOWARE_KANZLEI=your_kanzlei_name
+
+# Database Name
+ADVOWARE_DATABASE=your_database_name
+
+# User für API-Zugriff
+ADVOWARE_USER=api_user
+
+# User Role (typischerweise 2)
+ADVOWARE_ROLE=2
+
+# User Password
+ADVOWARE_PASSWORD=secure_password_here
+
+# Token Lifetime in Minuten (Standard: 55)
+ADVOWARE_TOKEN_LIFETIME_MINUTES=55
+
+# API Timeout in Sekunden (Standard: 30)
+ADVOWARE_API_TIMEOUT_SECONDS=30
+
+# Write Protection (true = keine Schreibzugriffe auf Advoware)
+ADVOWARE_WRITE_PROTECTION=true
+```
+
+### Advoware API Key
+
+Der API Key muss Base64-encoded sein für HMAC-512 Signatur:
+
+```bash
+# Wenn Sie einen Raw Key haben, encodieren Sie ihn:
+echo -n "your_raw_key" | base64
+```
+
+## Redis Configuration
+
+```bash
+# Redis Host (Standard: localhost)
+REDIS_HOST=localhost
+
+# Redis Port (Standard: 6379)
+REDIS_PORT=6379
+
+# Redis Database für Advoware Cache (Standard: 1)
+REDIS_DB_ADVOWARE_CACHE=1
+
+# Redis Database für Calendar Sync (Standard: 2)
+REDIS_DB_CALENDAR_SYNC=2
+
+# Redis Timeout in Sekunden (Standard: 5)
+REDIS_TIMEOUT_SECONDS=5
+```
+
+### Redis Database Layout
+
+- **DB 0**: Motia Framework (nicht konfigurierbar)
+- **DB 1**: Advoware Cache & Locks (`REDIS_DB_ADVOWARE_CACHE`)
+  - Token Cache
+  - Employee Locks
+  - Webhook Deduplication
+- **DB 2**: Calendar Sync Rate Limiting (`REDIS_DB_CALENDAR_SYNC`)
+
+---
+
+## KONG API Gateway Configuration
+
+```bash
+# KONG Admin API URL (für Konfiguration)
+KONG_ADMIN_URL=http://localhost:8001
+
+# KONG Proxy URL (öffentlich erreichbar)
+KONG_PROXY_URL=https://api.bitbylaw.com
+```
+
+**Hinweis**: KONG-Konfiguration erfolgt typischerweise über Admin API oder Declarative Config (kong.yml).
+
+---
+
+## 3CX Telefonie Configuration
+
+```bash
+# 3CX API Base URL
+THREECX_API_URL=https://ralup.my3cx.de/api/v1
+
+# 3CX API Key für Authentifizierung
+THREECX_API_KEY=your_3cx_api_key_here
+
+# 3CX Webhook Secret (optional, für Signatur-Validierung)
+THREECX_WEBHOOK_SECRET=your_webhook_secret_here
+```
+
+### 3CX Setup
+
+1. Erstellen Sie API Key in 3CX Management Console
+2. Konfigurieren Sie Webhook URLs in 3CX:
+   - Call Started: `https://api.bitbylaw.com/telephony/3cx/webhook`
+   - Call Ended: `https://api.bitbylaw.com/telephony/3cx/webhook`
+3. Aktivieren Sie Call Recording (optional)
+
+---
+
+## Vermieterhelden Integration Configuration
+
+```bash
+# Vermieterhelden Webhook Secret (für Signatur-Validierung)
+VH_WEBHOOK_SECRET=your_vermieterhelden_webhook_secret
+
+# Lead Routing Target (wohin werden Leads geschickt)
+VH_LEAD_TARGET=espocrm  # Options: espocrm, advoware, both
+
+# Lead Auto-Assignment (optional)
+VH_AUTO_ASSIGN_LEADS=true
+VH_DEFAULT_ASSIGNEE=user_id_123
+```
+
+### Vermieterhelden Setup
+
+1. Konfigurieren Sie Webhook URL im WordPress:
+   - URL: `https://api.bitbylaw.com/leads/vermieterhelden`
+2. Generieren Sie Shared Secret
+3. Aktivieren Sie Webhook-Events für Lead-Erstellung
+
+---
+
+## Google Calendar Configuration
+
+```bash
+# Pfad zur Service Account JSON Datei
+GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/opt/motia-app/service-account.json
+
+# Google Calendar Scopes (Standard: calendar)
+# GOOGLE_CALENDAR_SCOPES wird im Code gesetzt, keine ENV Variable nötig
+```
+
+### Service Account Setup
+
+1. Erstellen Sie einen Service Account in Google Cloud Console
+2. Laden Sie die JSON-Schlüsseldatei herunter
+3. Speichern Sie sie als `service-account.json`
+4. Setzen Sie sichere Berechtigungen:
+
+```bash
+chmod 600 /opt/motia-app/service-account.json
+chown www-data:www-data /opt/motia-app/service-account.json
+```
+
+Siehe auch: [GOOGLE_SETUP_README.md](../GOOGLE_SETUP_README.md)
+
+## PostgreSQL Configuration
+
+**Status**: Aktuell nicht verwendet (zukünftige Erweiterung)
+
+```bash
+# PostgreSQL Host
+POSTGRES_HOST=localhost
+
+# PostgreSQL User
+POSTGRES_USER=calendar_sync_user
+
+# PostgreSQL Password
+POSTGRES_PASSWORD=secure_password
+
+# PostgreSQL Database Name
+POSTGRES_DB_NAME=calendar_sync_db
+```
+
+## Calendar Sync Configuration
+
+```bash
+# Anonymisierung von Google Events (true/false)
+CALENDAR_SYNC_ANONYMIZE_GOOGLE_EVENTS=true
+
+# Debug: Nur bestimmte Mitarbeiter synchronisieren (Komma-separiert)
+# Leer = alle Mitarbeiter
+CALENDAR_SYNC_DEBUG_KUERZEL=SB,AI,RO,OK,BI,ST,UR,PB,VB
+```
+
+### Anonymisierung
+
+Wenn `CALENDAR_SYNC_ANONYMIZE_GOOGLE_EVENTS=true`:
+- Titel: "Blocked"
+- Beschreibung: Leer
+- Ort: Leer
+
+Wenn `false`:
+- Volle Details aus Advoware werden synchronisiert
+
+### Debug-Modus
+
+Für Development/Testing nur bestimmte Mitarbeiter synchronisieren:
+
+```bash
+# Nur diese Kürzel
+CALENDAR_SYNC_DEBUG_KUERZEL=SB,AI
+
+# Alle (Standard)
+CALENDAR_SYNC_DEBUG_KUERZEL=
+```
+
+## EspoCRM Configuration
+
+```bash
+# API Key für Webhook-Validierung (optional)
+ESPOCRM_MARVIN_API_KEY=your_webhook_secret_here
+```
+
+**Hinweis**: Aktuell wird der API Key nicht für Validierung verwendet. Zukünftige Implementierung kann HMAC-Signatur-Validierung hinzufügen.
+
+## Motia Framework Configuration
+
+```bash
+# Node Environment (development|production)
+NODE_ENV=production
+
+# Node Memory Limit (in MB)
+# NODE_OPTIONS wird in systemd gesetzt
+NODE_OPTIONS=--max-old-space-size=8192 --inspect --heapsnapshot-signal=SIGUSR2
+
+# Host Binding (0.0.0.0 = alle Interfaces)
+HOST=0.0.0.0
+
+# Port (Standard: 3000)
+# PORT=3000
+
+# Log Level (debug|info|warning|error)
+MOTIA_LOG_LEVEL=debug
+
+# npm Cache (für systemd user www-data)
+NPM_CONFIG_CACHE=/opt/motia-app/.npm-cache
+```
+
+## Configuration Loading
+
+### config.py
+
+Zentrale Konfiguration wird in `config.py` geladen:
+
+```python
+from dotenv import load_dotenv
+import os
+
+# Load .env file if exists
+load_dotenv()
+
+class Config:
+    # Alle Variablen mit Defaults
+    REDIS_HOST = os.getenv('REDIS_HOST', 'localhost')
+    REDIS_PORT = int(os.getenv('REDIS_PORT', '6379'))
+    # ...
+```
+
+### Usage in Steps
+
+```python
+from config import Config
+
+# Access configuration
+redis_host = Config.REDIS_HOST
+api_key = Config.ADVOWARE_API_KEY
+```
+
+### Usage in Services
+
+```python
+from config import Config
+
+class AdvowareAPI:
+    def __init__(self):
+        self.api_key = Config.ADVOWARE_API_KEY
+        self.base_url = Config.ADVOWARE_API_BASE_URL
+```
+
+## Environment-Specific Configuration
+
+### Development (.env)
+
+Erstellen Sie eine `.env` Datei im Root:
+
+```bash
+# .env (nicht in Git committen!)
+ADVOWARE_API_BASE_URL=https://staging.advo-net.net:90/
+ADVOWARE_API_KEY=dev_key_here
+REDIS_HOST=localhost
+MOTIA_LOG_LEVEL=debug
+ADVOWARE_WRITE_PROTECTION=true
+```
+
+**Wichtig**: `.env` zu `.gitignore` hinzufügen!
+
+### Production (systemd)
+
+In `/etc/systemd/system/motia.service`:
+
+```ini
+[Service]
+Environment=NODE_ENV=production
+Environment=ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
+Environment=ADVOWARE_API_KEY=production_key_here
+Environment=ADVOWARE_PASSWORD=production_password_here
+Environment=REDIS_HOST=localhost
+Environment=MOTIA_LOG_LEVEL=info
+Environment=ADVOWARE_WRITE_PROTECTION=false
+```
+
+Nach Änderungen:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart motia.service
+```
+
+### Staging
+
+Eigene Service-Datei oder separate Environment-Datei.
+
+## Validation
+
+### Check Configuration
+
+Script zum Validieren der Konfiguration:
+
+```python
+# scripts/check_config.py
+from config import Config
+import sys
+
+required_vars = [
+    'ADVOWARE_API_BASE_URL',
+    'ADVOWARE_APP_ID',
+    'ADVOWARE_API_KEY',
+    'REDIS_HOST',
+]
+
+missing = []
+for var in required_vars:
+    if not getattr(Config, var, None):
+        missing.append(var)
+
+if missing:
+    print(f"ERROR: Missing configuration: {', '.join(missing)}")
+    sys.exit(1)
+
+print("✓ Configuration valid")
+```
+
+Run:
+```bash
+python scripts/check_config.py
+```
+
+## Secrets Management
+
+### DO NOT
+
+❌ Commit secrets to Git
+❌ Hardcode passwords in code
+❌ Share `.env` files
+❌ Log sensitive data
+
+### DO
+
+✅ Use environment variables
+✅ Use `.gitignore` for `.env`
+✅ Use systemd for production secrets
+✅ Rotate keys regularly
+✅ Use `chmod 600` for sensitive files
+
+### Rotation
+
+Wenn API Keys rotiert werden:
+
+```bash
+# 1. Update environment variable
+sudo nano /etc/systemd/system/motia.service
+
+# 2. Reload systemd
+sudo systemctl daemon-reload
+
+# 3. Clear Redis cache
+redis-cli -n 1 DEL advoware_access_token advoware_token_timestamp
+
+# 4. Restart service
+sudo systemctl restart motia.service
+
+# 5. Verify
+sudo journalctl -u motia.service -f
+```
+
+## Configuration Reference
+
+### Complete Example
+
+```bash
+# Advoware API
+ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
+ADVOWARE_PRODUCT_ID=64
+ADVOWARE_APP_ID=your_app_id
+ADVOWARE_API_KEY=your_base64_key
+ADVOWARE_KANZLEI=your_kanzlei
+ADVOWARE_DATABASE=your_db
+ADVOWARE_USER=api_user
+ADVOWARE_ROLE=2
+ADVOWARE_PASSWORD=your_password
+ADVOWARE_TOKEN_LIFETIME_MINUTES=55
+ADVOWARE_API_TIMEOUT_SECONDS=30
+ADVOWARE_WRITE_PROTECTION=true
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB_ADVOWARE_CACHE=1
+REDIS_DB_CALENDAR_SYNC=2
+REDIS_TIMEOUT_SECONDS=5
+
+# Google Calendar
+GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/opt/motia-app/service-account.json
+
+# Calendar Sync
+CALENDAR_SYNC_ANONYMIZE_GOOGLE_EVENTS=true
+CALENDAR_SYNC_DEBUG_KUERZEL=
+
+# PostgreSQL (optional)
+POSTGRES_HOST=localhost
+POSTGRES_USER=calendar_sync_user
+POSTGRES_PASSWORD=your_pg_password
+POSTGRES_DB_NAME=calendar_sync_db
+
+# EspoCRM
+ESPOCRM_MARVIN_API_KEY=your_webhook_key
+
+# Motia
+NODE_ENV=production
+HOST=0.0.0.0
+MOTIA_LOG_LEVEL=info
+```
+
+## Troubleshooting
+
+### "Configuration not found"
+
+```bash
+# Check if .env exists
+ls -la .env
+
+# Check environment variables
+env | grep ADVOWARE
+
+# Check systemd environment
+systemctl show motia.service -p Environment
+```
+
+### "Redis connection failed"
+
+```bash
+# Check Redis is running
+sudo systemctl status redis-server
+
+# Test connection
+redis-cli -h $REDIS_HOST -p $REDIS_PORT ping
+
+# Check config
+echo "REDIS_HOST: $REDIS_HOST"
+echo "REDIS_PORT: $REDIS_PORT"
+```
+
+### "API authentication failed"
+
+```bash
+# Check if API key is valid Base64
+echo $ADVOWARE_API_KEY | base64 -d
+
+# Clear token cache
+redis-cli -n 1 DEL advoware_access_token
+
+# Check logs
+sudo journalctl -u motia.service | grep -i "token\|auth"
+```
+
+## Related Documentation
+
+- [Development Guide](DEVELOPMENT.md)
+- [Deployment Guide](DEPLOYMENT.md)
+- [Troubleshooting](TROUBLESHOOTING.md)
+- [Google Setup](../GOOGLE_SETUP_README.md)