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
@@ -81,6 +81,8 @@ Die Proxy-Endpunkte spiegeln die Advoware-API wider:
|
|||||||
curl -X GET "http://localhost:3000/api/advoware/employees"
|
curl -X GET "http://localhost:3000/api/advoware/employees"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Für detaillierte Informationen zu den Proxy-Steps siehe [steps/advoware_proxy/README.md](steps/advoware_proxy/README.md).
|
||||||
|
|
||||||
### EspoCRM Webhooks
|
### EspoCRM Webhooks
|
||||||
|
|
||||||
Webhooks werden automatisch von EspoCRM gesendet für Änderungen an Beteiligte-Entitäten:
|
Webhooks werden automatisch von EspoCRM gesendet für Änderungen an Beteiligte-Entitäten:
|
||||||
@@ -89,6 +91,8 @@ Webhooks werden automatisch von EspoCRM gesendet für Änderungen an Beteiligte-
|
|||||||
- **Update**: `/webhooks/vmh/beteiligte/update`
|
- **Update**: `/webhooks/vmh/beteiligte/update`
|
||||||
- **Delete**: `/webhooks/vmh/beteiligte/delete`
|
- **Delete**: `/webhooks/vmh/beteiligte/delete`
|
||||||
|
|
||||||
|
Für detaillierte Informationen zu den Webhook- und Sync-Steps siehe [steps/vmh/README.md](steps/vmh/README.md).
|
||||||
|
|
||||||
### Synchronisation
|
### Synchronisation
|
||||||
|
|
||||||
Die Synchronisation läuft event-driven ab:
|
Die Synchronisation läuft event-driven ab:
|
||||||
@@ -120,12 +124,12 @@ Die Flows sind in `motia-workbench.json` definiert:
|
|||||||
```
|
```
|
||||||
bitbylaw/
|
bitbylaw/
|
||||||
├── steps/
|
├── steps/
|
||||||
│ ├── advoware_proxy/ # API Proxy Steps
|
│ ├── advoware_proxy/ # API Proxy Steps - siehe [README](steps/advoware_proxy/README.md)
|
||||||
│ │ ├── advoware_api_proxy_get_step.py
|
│ │ ├── advoware_api_proxy_get_step.py
|
||||||
│ │ ├── advoware_api_proxy_post_step.py
|
│ │ ├── advoware_api_proxy_post_step.py
|
||||||
│ │ ├── advoware_api_proxy_put_step.py
|
│ │ ├── advoware_api_proxy_put_step.py
|
||||||
│ │ └── advoware_api_proxy_delete_step.py
|
│ │ └── advoware_api_proxy_delete_step.py
|
||||||
│ └── vmh/
|
│ └── vmh/ # VMH Webhook & Sync Steps - siehe [README](steps/vmh/README.md)
|
||||||
│ ├── webhook/ # Webhook Receiver Steps
|
│ ├── webhook/ # Webhook Receiver Steps
|
||||||
│ │ ├── beteiligte_create_api_step.py
|
│ │ ├── beteiligte_create_api_step.py
|
||||||
│ │ ├── beteiligte_update_api_step.py
|
│ │ ├── beteiligte_update_api_step.py
|
||||||
|
|||||||
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