Entwickler-Anleitung: Integration ohne iframes

1. Aktueller Stand und Zuständigkeiten

• Repository: qrisr/ronorp-html-page. Technik: TanStack Start, React, Vite, Server-Routen und Datenbankzugriff über HTTP.
• Aktuelle eigenständige Werkzeuge: /crowdifypotential und /crowdfunding-kampage-erstellen. Die bestehende Schreibweise des Generator-Pfads aus Kompatibilitätsgründen beibehalten.
• Die Oberflächen liegen in public/potential/index.html und public/generator/index.html. Die React-Hüllen verwenden derzeit iframes. Diese Hüllen nicht für die neue Integration verwenden.
• Die Crowdify-Entwickler sind für Seitentemplates, CMS-Unterstützung für Skripte, Reverse Proxy und CSP zuständig. Die Werkzeug-Entwickler übernehmen die Widget-Ausgliederung, API-Konfiguration und Regressionstests. Vor der Umsetzung eine verantwortliche Person für die Veröffentlichung und ein Ziel für die Lead-Übergabe vereinbaren.

In der früheren Besprechung wurden sowohl responsive iframes als auch Web Components erwogen. Die aktuelle Vorgabe ist eindeutig: kein iframe. Prüfen, ob das Crowdify-CMS Modulskripte und Custom Elements erlaubt. Falls nicht, den Einhängepunkt in einem kontrollierten Seitentemplate ergänzen; nicht stillschweigend auf ein iframe zurückfallen.

2. Zielintegration: Custom Elements mit Shadow DOM

Ein versioniertes JavaScript-Modul bauen, das <crowdify-potential> und <crowdify-campaign> registriert. Jedes Werkzeug in einem eigenen Shadow Root einhängen, damit das CSS der Website und die Formular-IDs nicht kollidieren. Beide Werkzeuge bleiben im normalen Dokumentfluss der Website: natürliche Höhe, ein Scrollbereich für die Seite und keine auf die Bildschirmhöhe fixierte Hülle.

Vorgeschlagene Einbindung – zur Veranschaulichung, noch kein funktionsfähiges Beispiel:

<!-- Proposed published assets on crowdify.net -->
<script type="module" src="/assets/crowdify-tools/v1/widgets.js"></script>

<!-- Calculator page -->
<crowdify-potential
  lang="de"
  api-base="/crowdify-tools-api">
</crowdify-potential>

<!-- Generator page -->
<crowdify-campaign
  lang="de"
  api-base="/crowdify-tools-api">
</crowdify-campaign>

• Für die Widgets einen eigenen Vite-Library-Build verwenden; den bestehenden TanStack-Server-Build beibehalten. Den Ablauf zur Veröffentlichung der Dateien vereinbaren und die erzeugten Dateien testen, bevor dieses Beispiel verwendet wird.
• Unveränderliche, versionierte Dateien ausliefern. Die vorherige Version für eine Rückkehr bereithalten. Die oben gezeigten Beispielpfade müssen von den Entwicklern angelegt werden.
• Falls Dateien stattdessen von einem anderen Origin ausgeliefert werden, CORS für Modulskripte und die CSP der Website ausdrücklich konfigurieren. Der oben vorgeschlagene Dateipfad unter demselben Origin vermeidet diese Abhängigkeit.

3. Bestehende Oberfläche umbauen; Verhalten erhalten

1. Die beiden bestehenden Formularansichten, Darstellungsfunktionen und die Berechnungslogik in einhängbare Module innerhalb dieses Repositorys ausgliedern. Keine zweite Implementierung der Formeln erstellen.
2. Globale Aufrufe von document.getElementById und document.querySelector durch Abfragen ersetzen, die auf den Wurzelknoten der Komponente begrenzt sind. Globale Stile für body/:root durch :host oder lokale Selektoren ersetzen.
3. Alle fest eingetragenen API-URLs durch einen konfigurierten API-Client pro Widget ersetzen. Sprache, Durchlauf-ID, Besucher-ID, Eingaben und Ereignisbehandlung auf die jeweilige Instanz begrenzen.
4. Ereignisbehandlung bereinigen und laufende Anfragen abbrechen, wenn die Komponente entfernt wird. Custom Elements nur einmal registrieren. Beide Werkzeuge gemeinsam auf einer Seite testen, um Probleme durch geteilten Zustand zu erkennen.
5. Alle sechs Zahlenfelder des Rechners sichtbar in einer Spalte belassen. DE/FR/IT, E-Mail-Freischaltung, erneutes Versuchen und alle acht Berichtsabschnitte erhalten. Einwilligungs- und Bestätigungsregeln nicht stillschweigend verändern.
6. Das SSE-Protokoll des Generators und die Wiederherstellung unvollständiger Abschnitte erhalten. Den Inhalt erhalten, nicht nur die Erfolgsmeldung.
7. Das originale Crowdify-Logo verwenden. Die Wortmarke nicht mit gestaltetem Text nachbauen.

Shadow DOM isoliert JavaScript nicht von der Website und ist keine Sicherheitsgrenze. Nutzer- und KI-Texte mit den bestehenden Escaping-Regeln darstellen; zurückgegebenes HTML oder Skripte nicht ausführen.

4. API-Aufrufe über Crowdify leiten

Bevorzugte Einrichtung: Einen Reverse Proxy unter demselben Origin von https://www.crowdify.net/crowdify-tools-api/* zu /api/public/* des veröffentlichten Werkzeug-Backends ergänzen. Den externen Backend-Origin mit der für die Veröffentlichung verantwortlichen Person vereinbaren; nicht raten und DNS nicht zur Behebung von Layoutproblemen ändern.

POST /crowdify-tools-api/request-code
POST /crowdify-tools-api/verify-code
POST /crowdify-tools-api/lead
POST /crowdify-tools-api/track
POST /crowdify-tools-api/generate-konzept
POST /crowdify-tools-api/potential-empfehlungen

• Das Präfix einmal zuordnen; JSON-Inhalte, Statuscodes und Antwort-Header erhalten. Keine API-Secrets im Widget oder im CMS hinterlegen.
• Bei der Generierung text/event-stream erhalten; Zwischenspeicherung und Pufferung im Proxy deaktivieren und ein Zeitlimit wählen, das die vollständige Antwort zulässt. Der Client verwendet Streaming-Fetch mit POST, keine EventSource-GET-Anfrage.
• Datenblöcke auch über Netzwerkgrenzen hinweg korrekt zusammensetzen. Bei Abbruch durch den Nutzer die Anfrage beenden; einen unvollständigen Abschnitt auch dann als unvollständig behandeln, wenn die HTTP-Antwort normal beendet wurde.
• Falls eine API mit anderem Origin unvermeidbar ist, OPTIONS und einheitliches, auf die erlaubten Origins begrenztes CORS an allen öffentlichen Endpunkten umsetzen. Die aktuellen Endpunkte verwenden noch nicht überall dieselbe CORS-Regel. Admin-Endpunkte nicht über den öffentlichen Proxy freigeben.

5. Backend in Lovable einrichten

Secrets über die Veröffentlichungsplattform setzen. Ihre Werte dürfen weder auf dieser Seite noch im Client-Code oder in den erzeugten Dateien erscheinen.

• LOVABLE_API_KEY: serverseitige KI-Generierung. Verfügbares Kontingent prüfen und ein vollständiges echtes Konzept testen.
• RESEND_API_KEY, MAIL_FROM: beim Mailanbieter bestätigter Absender; CODE_SECRET: Geheimnis für die Signierung der Codes. Zustellung, falsche und abgelaufene Codes sowie erneuten Versand testen.
• SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY: dauerhafte Speicherung über HTTP. sql/schema.sql vor einer Anwendung mit der bestehenden Datenbank abgleichen. Vorhandene Datensätze erhalten.
• LEAD_WEBHOOK_URL und bei Bedarf LEAD_WEBHOOK_SECRET: vereinbartes Empfangssystem von Crowdify. Eine bestätigte Zustellung prüfen, nicht nur eine Anfrage aus dem Browser.
• ADMIN_CODE: den vereinbarten Zugangscode ausdrücklich setzen. Ohne Konfiguration ist der Online-Zugang gesperrt. Der lokale Demo-Code konfiguriert den veröffentlichten Server nicht.

Keine Schlüssel aus einem anderen Projekt kopieren. Über den bestehenden Ablauf GitHub → Lovable veröffentlichen und danach die echte öffentliche URL sowie die veröffentlichte Dateiversion prüfen.

6. Speicherung, Einwilligung und Nutzungs-Auswertung

• Die bestehenden serverseitigen Datensätze in personen, laeufe und events beibehalten. Die Quellenwerte potential-kalkulator und kampagnen-generator erhalten.
• Eingegebene Adresse, bestätigter Code, Marketing-Einwilligung, Speicherung und Weiterleitung als getrennte Zustände führen. Einwilligung nicht vorauswählen; eine unbestätigte Adresse darf nicht als bestätigt gelten.
• Interne Durchläufe und Durchläufe mit Master-Code weiterhin von der externen Lead-Weiterleitung ausschliessen.
• Die tatsächlichen Rückmeldungen der Lead-Antwort prüfen (gespeichert, weitergeleitet). Wiederholungsversuche und Vermeidung von Duplikaten vereinbaren, bevor eine Zustellung als abgeschlossen gilt.
• Die bestehende Admin-Ansicht liegt unter /admin. Zugang, Personen, Durchlaufzahlen und Quellenfilter mit der Datenbank abgleichen. Ein abgewiesener Code ist kein Beleg für fehlende Daten.
• Beim Wechsel vom iframe-Origin zu crowdify.net ändert sich der Origin des Browser-Speichers. Bestehender localStorage wird weder automatisch übernommen noch ist er eine verlässliche historische Datenquelle. Serverdatensätze erhalten; eine allfällige Wiederherstellung reiner Browserdaten separat vereinbaren.

7. Mobile Bedienung und PDF-Export

• Mit 375 CSS-Pixeln im tatsächlichen Crowdify-Template sowie auf iPhone Safari und Android Chrome testen. Geöffnete Bildschirmtastatur und lange Ergebnisse einbeziehen.
• Kein seitliches Scrollen der Seite oder innerer Bereiche. Szenariotabellen auf kleinen Bildschirmen als beschriftete Karten anzeigen. Touch-Flächen mindestens 44 px und Eingabeschrift mindestens 16 px gross halten.
• Navigation und Scrollposition der Website vorhersehbar halten. Den Fokus bei Schrittwechseln bewusst setzen und Validierungsfehler bei der jeweiligen Eingabe anzeigen.
• Nicht voraussetzen, dass das bisherige Verhalten von window.print() im Shadow DOM erhalten bleibt. Aus denselben Berichtsdaten ein eigenes druckbares Dokument einschliesslich Komponentenstilen erzeugen und danach alle Abschnitte und Seitenumbrüche testen. Ein neues Druckfenster ist zulässig; ein iframe ist nicht nötig.
• DE/FR/IT, CHF-Formatierung und die ursprüngliche PDF-Struktur des Generators erhalten.

8. Abnahmetest: exaktes Rechner-Referenzbeispiel

Soziales Projekt; Familie 10; persönliches Netzwerk 20; Newsletter 20; Social Media 20; Communities 20; Influencer-/Medienkontakte 20.

Reach = 90. Project factor = 1.5. Influencer factor = 1.6.
Average contribution = CHF 120.

Low:  90 × 0.04 × 1.5 × 1.6 =  8.64 →  9 boosters; CHF 1'037
Mid:  90 × 0.06 × 1.5 × 1.6 = 12.96 → 13 boosters; CHF 1'555
Best: 90 × 0.09 × 1.5 × 1.6 = 19.44 → 19 boosters; CHF 2'333

Displayed scenario sum: 41 boosters; CHF 4'925.

Die Geldbeträge aus den ungerundeten Booster-Werten berechnen und erst die angezeigten Beträge runden. Die angezeigten Szenariowerte addieren. Den Hinweis beibehalten, dass die Szenarien Alternativen und keine kumulierte Finanzierung sind. Alle acht Analyseabschnitte, PDF-Ausgabe, leere optionale Felder, Nulleingaben und alle Influencer-Schwellenwerte prüfen.

9. Vor der Veröffentlichung einen echten Gesamtdurchlauf abschliessen

1. Die echte Crowdify-Seite öffnen und die veröffentlichte Widget-Version feststellen.
2. Beide Werkzeuge mit ausdrücklich freigegebenen Testdaten absenden. Tatsächliche Antworten und Ergebnisse festhalten.
3. Eine echte E-Mail empfangen, ihren Code eingeben und die Abweisung eines falschen oder abgelaufenen Codes prüfen.
4. Die vollständige Kampagne mit sechs Abschnitten erzeugen, auf abgeschnittene Inhalte prüfen, das PDF exportieren und kontrollieren.
5. Die richtige Person und beide nach Quelle gekennzeichneten Durchläufe im Speicher und in der Admin-Ansicht finden.
6. Den Empfang am vereinbarten Lead-Ziel prüfen. Auch nicht erteilte Einwilligung und interne Durchläufe testen.
7. API-, Mail- und Speicherfehler sowie unterbrochene Generierung und Wiederholungsversuche testen, ohne doppelte Leads oder verlorene Eingaben.
8. Den entscheidenden Ablauf auf echten mobilen Browsern im Seitentemplate wiederholen und danach die Freigabe zur Veröffentlichung einholen.

Die Veröffentlichung ist blockiert , wenn ein erforderlicher Dienst fehlt oder nur eine Erfolgsmeldung der Oberfläche als Beleg vorliegt. Die letzten funktionierenden eigenständigen Seiten und die vorherige Widget-Dateiversion für eine Rückkehr bereithalten; vorhandene Datenbankeinträge erhalten.

10. Referenzen zur Umsetzung

• MDN: Web Components, Custom Elements und Shadow DOM
• Vite: Library-Build-Modus
• MDN: Format des Server-Sent-Event-Datenstroms

Referenzen im Projekt: src/components/Vollbild.tsx, src/routes/api/public/, src/lib/mailcode.ts, src/lib/speicher.ts und sql/schema.sql.