Aufteilung der README.md in modulare Dokumentation
- Haupt-README.md behält Übersicht und Links zu detaillierten READMEs - steps/advoware_proxy/README.md: Detaillierte Dokumentation der 4 Proxy-Steps - steps/vmh/README.md: Detaillierte Dokumentation der Webhook-Receiver und Sync-Steps - Verbesserte Navigation und modulare Dokumentationsstruktur
This commit is contained in:
root
184
bitbylaw/steps/advoware_proxy/README.md
Normal file
184
bitbylaw/steps/advoware_proxy/README.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Advoware API Proxy Steps
|
||||
|
||||
Dieser Ordner enthält die API-Proxy-Steps für die Advoware-Integration. Jeder Step implementiert eine HTTP-Methode als universellen Proxy zur Advoware-API.
|
||||
|
||||
## Übersicht
|
||||
|
||||
Die Proxy-Steps fungieren als transparente Schnittstelle zwischen Clients und der Advoware-API. Sie handhaben Authentifizierung, Fehlerbehandlung und Logging automatisch.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. GET Proxy (`advoware_api_proxy_get_step.py`)
|
||||
|
||||
**Zweck:** Universeller Proxy für GET-Requests an die Advoware-API.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** Advoware Proxy GET
|
||||
- **Path:** `/advoware/proxy`
|
||||
- **Method:** GET
|
||||
- **Flows:** advoware
|
||||
|
||||
**Funktionalität:**
|
||||
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
|
||||
- Übergibt alle anderen Query-Parameter als API-Parameter
|
||||
- Gibt das Ergebnis als JSON zurück
|
||||
|
||||
**Beispiel Request:**
|
||||
```
|
||||
GET /advoware/proxy?endpoint=employees&limit=10&offset=0
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"data": [...],
|
||||
"total": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. POST Proxy (`advoware_api_proxy_post_step.py`)
|
||||
|
||||
**Zweck:** Universeller Proxy für POST-Requests an die Advoware-API.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** Advoware Proxy POST
|
||||
- **Path:** `/advoware/proxy`
|
||||
- **Method:** POST
|
||||
- **Flows:** advoware
|
||||
|
||||
**Funktionalität:**
|
||||
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
|
||||
- Verwendet den Request-Body als JSON-Daten für die API
|
||||
- Erstellt neue Ressourcen in Advoware
|
||||
|
||||
**Beispiel Request:**
|
||||
```
|
||||
POST /advoware/proxy?endpoint=employees
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. PUT Proxy (`advoware_api_proxy_put_step.py`)
|
||||
|
||||
**Zweck:** Universeller Proxy für PUT-Requests an die Advoware-API.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** Advoware Proxy PUT
|
||||
- **Path:** `/advoware/proxy`
|
||||
- **Method:** PUT
|
||||
- **Flows:** advoware
|
||||
|
||||
**Funktionalität:**
|
||||
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
|
||||
- Verwendet den Request-Body als JSON-Daten für Updates
|
||||
- Aktualisiert bestehende Ressourcen in Advoware
|
||||
|
||||
**Beispiel Request:**
|
||||
```
|
||||
PUT /advoware/proxy?endpoint=employees/123
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "John Smith",
|
||||
"email": "johnsmith@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. DELETE Proxy (`advoware_api_proxy_delete_step.py`)
|
||||
|
||||
**Zweck:** Universeller Proxy für DELETE-Requests an die Advoware-API.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** Advoware Proxy DELETE
|
||||
- **Path:** `/advoware/proxy`
|
||||
- **Method:** DELETE
|
||||
- **Flows:** advoware
|
||||
|
||||
**Funktionalität:**
|
||||
- Extrahiert den Ziel-Endpoint aus Query-Parametern (`endpoint`)
|
||||
- Löscht Ressourcen in Advoware
|
||||
|
||||
**Beispiel Request:**
|
||||
```
|
||||
DELETE /advoware/proxy?endpoint=employees/123
|
||||
```
|
||||
|
||||
## Gemeinsame Features
|
||||
|
||||
### Authentifizierung
|
||||
Alle Steps verwenden den `AdvowareAPI` Service für automatische Token-Verwaltung und Authentifizierung.
|
||||
|
||||
### Fehlerbehandlung
|
||||
- **400 Bad Request:** Fehlender `endpoint` Parameter
|
||||
- **500 Internal Server Error:** API-Fehler oder Exceptions
|
||||
|
||||
### Logging
|
||||
Detaillierte Logs für:
|
||||
- Eingehende Requests
|
||||
- API-Calls an Advoware
|
||||
- Fehler und Exceptions
|
||||
|
||||
### Sicherheit
|
||||
- Keine direkte Weitergabe sensibler Daten
|
||||
- Authentifizierung über Service-Layer
|
||||
- Input-Validation für erforderliche Parameter
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
# Test GET Proxy
|
||||
curl -X GET "http://localhost:3000/advoware/proxy?endpoint=employees"
|
||||
|
||||
# Test POST Proxy
|
||||
curl -X POST "http://localhost:3000/advoware/proxy?endpoint=employees" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "Test Employee"}'
|
||||
|
||||
# Test PUT Proxy
|
||||
curl -X PUT "http://localhost:3000/advoware/proxy?endpoint=employees/1" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "Updated Employee"}'
|
||||
|
||||
# Test DELETE Proxy
|
||||
curl -X DELETE "http://localhost:3000/advoware/proxy?endpoint=employees/1"
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
Überprüfen Sie die Logs für korrekte API-Calls:
|
||||
```bash
|
||||
motia logs | grep "Proxying request to Advoware"
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Umgebungsvariablen
|
||||
Stellen Sie sicher, dass folgende Variablen gesetzt sind:
|
||||
- `ADVOWARE_BASE_URL`
|
||||
- `ADVOWARE_USERNAME`
|
||||
- `ADVOWARE_PASSWORD`
|
||||
|
||||
### Dependencies
|
||||
- `services/advoware.py` - Advoware API Client
|
||||
- `config.py` - Konfigurationsmanagement
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
### Geplante Features
|
||||
- Request/Response Caching
|
||||
- Rate Limiting
|
||||
- Request Validation Schemas
|
||||
- Batch-Operations Support
|
||||
|
||||
### Custom Endpoints
|
||||
Für spezifische Endpoints können zusätzliche Steps erstellt werden, die direkt auf bestimmte Ressourcen zugreifen.
|
||||
194
bitbylaw/steps/vmh/README.md
Normal file
194
bitbylaw/steps/vmh/README.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# VMH Webhook & Sync Steps
|
||||
|
||||
Dieser Ordner enthält die Webhook-Receiver für EspoCRM und den Event-basierten Synchronisations-Handler für Beteiligte-Entitäten.
|
||||
|
||||
## Übersicht
|
||||
|
||||
Die VMH-Steps implementieren eine vollständige Webhook-Pipeline:
|
||||
1. **Webhook Receiver** empfangen Events von EspoCRM
|
||||
2. **Redis Deduplication** verhindert Mehrfachverarbeitung
|
||||
3. **Event Emission** triggert die Synchronisation
|
||||
4. **Sync Handler** verarbeitet die Änderungen (aktuell Placeholder)
|
||||
|
||||
## Webhook Receiver Steps
|
||||
|
||||
### 1. Create Webhook (`webhook/beteiligte_create_api_step.py`)
|
||||
|
||||
**Zweck:** Empfängt Create-Webhooks von EspoCRM für neue Beteiligte-Entitäten.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** VMH Webhook Beteiligte Create
|
||||
- **Path:** `/vmh/webhook/beteiligte/create`
|
||||
- **Method:** POST
|
||||
- **Flows:** vmh
|
||||
- **Emits:** `vmh.beteiligte.create`
|
||||
|
||||
**Funktionalität:**
|
||||
- Verarbeitet Batch-Payloads von EspoCRM
|
||||
- Extrahiert Entity-IDs aus dem Payload
|
||||
- Redis-basierte Deduplikation mit `vmh:beteiligte:create_pending`
|
||||
- Emittiert Events für neue Entities
|
||||
|
||||
**Payload Format:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "entity-123",
|
||||
"name": "John Doe",
|
||||
"createdAt": "2025-01-20T10:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "received",
|
||||
"action": "create",
|
||||
"new_ids_count": 1,
|
||||
"total_ids_in_batch": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Update Webhook (`webhook/beteiligte_update_api_step.py`)
|
||||
|
||||
**Zweck:** Empfängt Update-Webhooks von EspoCRM für geänderte Beteiligte-Entitäten.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** VMH Webhook Beteiligte Update
|
||||
- **Path:** `/vmh/webhook/beteiligte/update`
|
||||
- **Method:** POST
|
||||
- **Flows:** vmh
|
||||
- **Emits:** `vmh.beteiligte.update`
|
||||
|
||||
**Funktionalität:**
|
||||
- Ähnlich zum Create-Webhook
|
||||
- Verwendet `vmh:beteiligte:update_pending` für Deduplikation
|
||||
- Emittiert `vmh.beteiligte.update` Events
|
||||
|
||||
### 3. Delete Webhook (`webhook/beteiligte_delete_api_step.py`)
|
||||
|
||||
**Zweck:** Empfängt Delete-Webhooks von EspoCRM für gelöschte Beteiligte-Entitäten.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** VMH Webhook Beteiligte Delete
|
||||
- **Path:** `/vmh/webhook/beteiligte/delete`
|
||||
- **Method:** POST
|
||||
- **Flows:** vmh
|
||||
- **Emits:** `vmh.beteiligte.delete`
|
||||
|
||||
**Funktionalität:**
|
||||
- Ähnlich zum Create-Webhook
|
||||
- Verwendet `vmh:beteiligte:delete_pending` für Deduplikation
|
||||
- Emittiert `vmh.beteiligte.delete` Events
|
||||
|
||||
## Sync Handler Step
|
||||
|
||||
### Event Sync Handler (`beteiligte_sync_event_step.py`)
|
||||
|
||||
**Zweck:** Zentraler Event-Handler für die Synchronisation von Beteiligte-Änderungen.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** event
|
||||
- **Name:** VMH Beteiligte Sync
|
||||
- **Subscribes:** `vmh.beteiligte.create`, `vmh.beteiligte.update`, `vmh.beteiligte.delete`
|
||||
- **Flows:** vmh
|
||||
- **Emits:** (none)
|
||||
|
||||
**Funktionalität:**
|
||||
- Empfängt Events von allen Webhook-Receivern
|
||||
- Aktuell Placeholder-Implementierung (nur Logging)
|
||||
- Entfernt verarbeitete IDs aus Redis-Pending-Queues
|
||||
- Bereit für Integration mit EspoCRM-API
|
||||
|
||||
**Event Data Format:**
|
||||
```json
|
||||
{
|
||||
"entity_id": "entity-123",
|
||||
"action": "create",
|
||||
"source": "webhook",
|
||||
"timestamp": "2025-01-20T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Redis Deduplication
|
||||
|
||||
### Queue-Struktur
|
||||
- `vmh:beteiligte:create_pending` - IDs warten auf Create-Sync
|
||||
- `vmh:beteiligte:update_pending` - IDs warten auf Update-Sync
|
||||
- `vmh:beteiligte:delete_pending` - IDs warten auf Delete-Sync
|
||||
|
||||
### Deduplication Logic
|
||||
1. Sammle alle Entity-IDs aus Webhook-Payload
|
||||
2. Prüfe gegen bestehende Pending-Queue
|
||||
3. Nur neue IDs werden zur Queue hinzugefügt und Events emittiert
|
||||
4. Sync-Handler entfernt erfolgreich verarbeitete IDs
|
||||
|
||||
## Testing
|
||||
|
||||
### Webhook Simulation
|
||||
```bash
|
||||
# Create Webhook
|
||||
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/create" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"id": "test-123", "name": "Test Entity"}]'
|
||||
|
||||
# Update Webhook
|
||||
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/update" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"id": "test-123", "name": "Updated Entity"}]'
|
||||
|
||||
# Delete Webhook
|
||||
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/delete" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"id": "test-123"}]'
|
||||
```
|
||||
|
||||
### Redis Monitoring
|
||||
```bash
|
||||
# Prüfe Pending-Queues
|
||||
redis-cli SMEMBERS vmh:beteiligte:create_pending
|
||||
redis-cli SMEMBERS vmh:beteiligte:update_pending
|
||||
redis-cli SMEMBERS vmh:beteiligte:delete_pending
|
||||
```
|
||||
|
||||
### Log Monitoring
|
||||
```bash
|
||||
motia logs | grep "VMH Webhook"
|
||||
motia logs | grep "PLATZHALTER"
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Umgebungsvariablen
|
||||
- `REDIS_HOST` - Redis Host
|
||||
- `REDIS_PORT` - Redis Port
|
||||
- `REDIS_DB_ADVOWARE_CACHE` - Redis Database für Caching
|
||||
- `ESPOCRM_WEBHOOK_SECRET` - Webhook Secret für Authentifizierung
|
||||
|
||||
### Dependencies
|
||||
- `config.py` - Konfigurationsmanagement
|
||||
- `services/advoware.py` - Advoware API Client (für zukünftige Integration)
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
### Geplante Features
|
||||
- Vollständige EspoCRM-API-Integration im Sync-Handler
|
||||
- Batch-Verarbeitung für große Datenmengen
|
||||
- Retry-Logic für fehlgeschlagene Syncs
|
||||
- Metriken und Monitoring
|
||||
- Webhook-Authentifizierung mit Secrets
|
||||
|
||||
### Error Handling
|
||||
- Detaillierte Fehlerlogs
|
||||
- Graceful Handling von Redis-Verbindungsfehlern
|
||||
- Payload-Validation
|
||||
- Dead-Letter-Queues für fehlgeschlagene Events
|
||||
|
||||
### Security
|
||||
- Webhook-Secret Validation
|
||||
- Input-Sanitization
|
||||
- Rate-Limiting für Webhook-Endpunkte
|
||||
Reference in New Issue
Block a user