diff --git a/docs/LEADHARVESTER_INTEGRATION.md b/docs/LEADHARVESTER_INTEGRATION.md new file mode 100644 index 0000000..0a8a759 --- /dev/null +++ b/docs/LEADHARVESTER_INTEGRATION.md @@ -0,0 +1,319 @@ +# Leadharvester-Integration mit QC Text Builder + +Dieses Dokument beschreibt den minimalen, aber vollstaendigen Integrations-Workflow zwischen **Leadharvester** und **QC Text Builder**. + +Ziel: +- Leadharvester holt zuerst die verfuegbaren Templates aus QC Text Builder. +- Leadharvester zeigt Template-Name, Thumbnail und Vollansicht/Preview an. +- Danach waehlt der User oder Upstream-Prozess ein Template. +- Anschliessend uebergibt Leadharvester die gesammelten Stammdaten und Kontextdaten per Intake an QC Text Builder. +- QC Text Builder erzeugt oder aktualisiert daraus einen Draft. + +--- + +## 1) Basisdaten + +- QC Text Builder Base URL lokal: `http://localhost:8080` +- Template-Liste: `GET /api/templates` +- Template-Detail: `GET /api/templates/{id}` +- Draft-Intake: `POST /api/drafts/intake` + +--- + +## 2) Gesamt-Workflow + +### Schritt 1: Templates aus QC Text Builder abrufen + +Leadharvester ruft zuerst die verfuegbaren Templates ab: + +**Request** + +```http +GET /api/templates +``` + +**Beispiel lokal** + +```text +http://localhost:8080/api/templates +``` + +**Response-Struktur** + +```json +{ + "count": 1, + "templates": [ + { + "id": 1408367, + "name": "Mono QC 1- DE", + "description": "", + "locale": "DE", + "thumbnailUrl": "https://rai.monosolutions.com//thumbnails/01408367/1408367.jpeg", + "templatePreviewUrl": "https://u1408367.tool-apdialog.at", + "type": "ai", + "paletteReady": true, + "rawTemplateJson": {}, + "isAiTemplate": true, + "isOnboarded": true, + "manifestStatus": "reviewed", + "lastDiscoveredAt": "2026-03-27T10:00:00Z" + } + ] +} +``` + +### Felder, die Leadharvester mindestens verwenden sollte + +- `id` +- `name` +- `thumbnailUrl` +- `templatePreviewUrl` + +### Bedeutung + +- `thumbnailUrl`: kleine Vorschau fuer Template-Karten +- `templatePreviewUrl`: Vollansicht / Live-Preview des Templates +- `id`: wird spaeter als `templateId` an den Draft-Intake uebergeben + +--- + +## 3) Templates in Leadharvester anzeigen + +Leadharvester sollte die Template-Auswahl mindestens so darstellen: + +```json +{ + "templateId": 1408367, + "label": "Mono QC 1- DE", + "thumbnail": "https://rai.monosolutions.com//thumbnails/01408367/1408367.jpeg", + "previewUrl": "https://u1408367.tool-apdialog.at" +} +``` + +Nach der Auswahl muss Leadharvester mindestens diese Werte intern weitertragen: + +```json +{ + "selectedTemplateId": 1408367, + "selectedTemplateName": "Mono QC 1- DE" +} +``` + +--- + +## 4) Stammdaten und Kontext in Leadharvester sammeln + +Leadharvester sammelt anschliessend die Nutzdaten fuer den Draft. + +### Empfohlene Stammdaten (`globalData`) + +```json +{ + "companyName": "Dönerbude", + "username": "jansvabenik", + "email": "jan.svabenik@apdialog.com", + "phone": "+41 79 123 45 67", + "businessType": "Imbiss", + "descriptionShort": "Frische Döner und schnelle Mittagsgerichte.", + "descriptionLong": "Dönerbude bietet frisch zubereitete Spezialitäten, schnelle Bedienung und unkomplizierten Genuss für den Alltag.", + "mission": "Frisches, gutes Essen schnell und unkompliziert anbieten.", + "addressLine1": "Bahnhofstrasse 12", + "addressCity": "Zürich", + "addressZIP": "8001", + "addressCountry": "Schweiz" +} +``` + +### Empfohlener Kontext fuer Textvorschlaege + +```json +{ + "websiteUrl": "https://example.com", + "websiteSummary": "Frische Döner und schnelle Mittagsgerichte für Kundschaft in der Schweiz.", + "businessType": "Imbiss", + "localeStyle": "de-CH", + "marketStyle": "Schweiz", + "addressMode": "du", + "contentTone": "locker", + "promptInstructions": "Kurz, appetitlich und glaubwürdig formulieren." +} +``` + +--- + +## 5) Rueckuebergabe von Leadharvester an QC Text Builder + +Wenn Template + Stammdaten + Kontext feststehen, gibt Leadharvester die Daten per Intake zurueck an QC Text Builder. + +### Endpoint + +```http +POST /api/drafts/intake +Content-Type: application/json +``` + +### Exakter Intake-Contract + +```json +{ + "draftId": "string, optional", + "source": "string, required", + "requestName": "string, required", + "templateId": 0, + "globalData": {}, + "notes": "string, optional", + "websiteUrl": "string, optional", + "websiteSummary": "string, optional", + "businessType": "string, optional", + "localeStyle": "string, optional", + "marketStyle": "string, optional", + "addressMode": "string, optional", + "contentTone": "string, optional", + "promptInstructions": "string, optional", + "styleProfile": { + "localeStyle": "string, optional", + "marketStyle": "string, optional", + "addressMode": "string, optional", + "contentTone": "string, optional", + "promptInstructions": "string, optional" + } +} +``` + +### Empfohlenes Request-Beispiel + +```json +{ + "source": "leadharvester", + "requestName": "Dönerbude Intake 2026-03-27", + "templateId": 1408367, + "globalData": { + "companyName": "Dönerbude", + "username": "jansvabenik", + "email": "jan.svabenik@apdialog.com", + "phone": "+41 79 123 45 67", + "businessType": "Imbiss", + "descriptionShort": "Frische Döner und schnelle Mittagsgerichte.", + "descriptionLong": "Dönerbude bietet frisch zubereitete Spezialitäten, schnelle Bedienung und unkomplizierten Genuss für den Alltag.", + "mission": "Frisches, gutes Essen schnell und unkompliziert anbieten.", + "addressLine1": "Bahnhofstrasse 12", + "addressCity": "Zürich", + "addressZIP": "8001", + "addressCountry": "Schweiz" + }, + "notes": "Import aus Leadharvester", + "websiteUrl": "https://example.com", + "websiteSummary": "Frische Döner und schnelle Mittagsgerichte für Kundschaft in der Schweiz.", + "businessType": "Imbiss", + "localeStyle": "de-CH", + "marketStyle": "Schweiz", + "addressMode": "du", + "contentTone": "locker", + "promptInstructions": "Kurz, appetitlich und glaubwürdig formulieren.", + "styleProfile": { + "localeStyle": "de-CH", + "marketStyle": "Schweiz", + "addressMode": "du", + "contentTone": "locker", + "promptInstructions": "Kurz, appetitlich und glaubwürdig formulieren." + } +} +``` + +--- + +## 6) Backend-Verhalten beim Intake + +QC Text Builder macht beim Intake aktuell Folgendes: + +- Wenn `draftId` fehlt oder leer ist, wird ein **neuer Draft** erzeugt. +- Wenn `draftId` gesetzt ist, wird ein bestehender Draft **aktualisiert**. +- Der Draft wird mit Status **`draft`** gespeichert. +- `fieldValues` werden beim Intake leer initialisiert. +- Wenn `globalData` fehlt, wird automatisch `{}` verwendet. +- Wenn top-level `businessType` gesetzt ist und `globalData.businessType` leer ist, wird `businessType` in `globalData` gespiegelt. +- Wenn `styleProfile` gesetzt ist, wird dieses bevorzugt; fehlende Felder darin werden aus den flachen Stilfeldern ergaenzt. + +--- + +## 7) Rueckgabe aus QC Text Builder an Leadharvester + +Der Draft-Intake liefert den gespeicherten Draft zurueck. + +### Erwartung + +- **201 Created**, wenn ein neuer Draft erstellt wurde +- **200 OK**, wenn ein bestehender Draft aktualisiert wurde + +### Wichtige Rueckgabefelder + +```json +{ + "id": "1774540501012861000", + "templateId": 1408367, + "source": "leadharvester", + "requestName": "Dönerbude Intake 2026-03-27", + "status": "draft", + "createdAt": "2026-03-27T12:00:00Z", + "updatedAt": "2026-03-27T12:00:00Z" +} +``` + +### Was Leadharvester speichern sollte + +Mindestens: + +```json +{ + "qcDraftId": "1774540501012861000", + "qcTemplateId": 1408367, + "qcDraftStatus": "draft" +} +``` + +Diese `qcDraftId` ist wichtig, damit Leadharvester denselben Draft spaeter erneut aktualisieren oder weiterverfolgen kann. + +--- + +## 8) Minimaler Integrationsablauf fuer Coder + +```json +{ + "steps": [ + "GET /api/templates", + "Template in Leadharvester anzeigen (name + thumbnailUrl + templatePreviewUrl)", + "templateId aus der Auswahl merken", + "Lead-/Stammdaten in Leadharvester sammeln", + "POST /api/drafts/intake mit templateId + globalData + Kontext", + "draft id aus der Response speichern" + ] +} +``` + +--- + +## 9) Wichtige Regeln + +- Leadharvester muss **vor** dem Intake die Templates abrufen. +- Leadharvester sollte die `templateId` immer aus der aktuellen Template-Liste verwenden. +- `thumbnailUrl` ist fuer kleine Vorschauen gedacht. +- `templatePreviewUrl` ist fuer die Vollansicht / Preview gedacht. +- Leadharvester sollte die vom Intake zurueckgegebene `draftId` speichern. +- Diese `draftId` sollte bei spaeteren Updates wiederverwendet werden. + +--- + +## 10) Kurzfassung + +**Templates holen** +- `GET /api/templates` + +**Draft anlegen/aktualisieren** +- `POST /api/drafts/intake` + +**Pflicht fuer Leadharvester** +- Template waehlen +- `templateId` speichern +- Stammdaten/Kontext senden +- `draftId` aus Response speichern