# 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)