Webklar-Kundenbereich/docs/superpowers/plans/2026-10-01-website-analyse.md

Website-Analyse – Umsetzungsplan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Kunden mit Wartungs-Abo schalten im Portal eine Website-Analyse ein; Banner + Skript werden vom Runner eingesetzt, ein eigener Sammeldienst zählt datenschutzkonform, das Portal zeigt Zahlen und Heatmap.

Architecture: Neuer Dienst analytics/ (Node 24, node:sqlite, keine Abhängigkeiten) unter https://project.webklar.com/a/…; Client-Skripte w.js/h.js liefert er aus. Der Runner setzt das Skript beim Veröffentlichen ein. Das Portal verwaltet Freischaltung (portalFeatures), spricht den Sammeldienst per Admin-Token an und zeigt die Auswertung. WOMS bekommt einen Schalter.

Tech Stack: Node 24 (Sammeldienst), Node 20 (Portal/Runner), vanilla JS (Portal-UI, Client-Skript), React (WOMS), Playwright (Prüfung).

Spec: docs/superpowers/specs/2026-10-01-website-analyse-design.md

Worktrees: Portal/Runner/Analytics /home/webklar/apps/kundenbereich.webklar.com/dev-analyse (Branch feature/website-analyse). WOMS: git -C /home/webklar/apps/ticket.webklar.com/build worktree add -b feature/website-analyse ../dev-analyse origin/test, node_modules skip-worktree + eigenes npm install.

Global Constraints

• Nur Wartungs-Abo: productKey === 'wartung' und Status ∈ ACTIVE_STATUSES (stripeBilling.js). Hosting ausgeschlossen.
• Nur öffentliche Projekte (isPublic === true) mit Subdomain; Domains der Website = <subdomain>.project.webklar.com + liveDomain (falls gesetzt).
• Ereignisse exakt laut Spec-Tabelle (pv, bn, en, ck, ct) mit genau den dort genannten Feldern; bn ohne weitere Felder; en/ck/ct nur nach Annehmen.
• Keine IP, kein User-Agent gespeichert; keine Cookies; Banner-Wahl nur localStorage['wk-consent'] = {v:1,a,t}, 6 Monate gültig; GPC/DNT ⇒ wie Ablehnen ohne Banner.
• Besucher-Kennung HMAC-SHA256(tagesSalz, siteKey|ip|ua) → 16 Hex, Salz nur RAM, Wechsel 00:00 Europe/Berlin.
• Rohdaten/Klicks 30 Tage; Websites mit offSince > 60 Tage komplett löschen; Job täglich 02:30 Europe/Berlin.
• Limits: Body ≤ 4 KB, path ≤ 300, sel ≤ 200, sec 0–3600, scroll 0–100, x/y 0–1, 120 Ereignisse/Min je (site, IP).
• Banner: Leiste unten, „Ablehnen“ und „Annehmen“ gleich groß/gleich auffällig, Link „Datenschutz“ → /datenschutz-analyse.html; Akzentfarbe nur für „Annehmen“ (Kontrast ≥ 4,5:1, sonst Fallback #111111); Handy (< 768 px) kompakte Karte; Footer-Link „Cookie-Einstellungen“.
• siteKey ^[a-z0-9]{16,40}$, Farbe ^#[0-9a-f]{6}$.
• Heatmap-Link: HMAC-Token, 30 Minuten gültig, enthält siteKey, path, vp, exp.
• Schalter ANALYSE_ENABLED (Vorgabe off) ⇒ Kachel bleibt „Kommt bald“, Routen 409.
• Texte deutsch (Du-Form im Portal), kein confirm(). Nichts pushen/live schalten.

Review Focus

1. Ohne „Annehmen“ verlässt kein en/ck/ct den Browser (auch nicht nach Widerruf). → Task 6
2. Fremde Origin oder unbekannter siteKey ⇒ nichts gespeichert. → Task 2
3. Analyse aus / Abo weg ⇒ nach Neubau kein Skript und keine Zusatzseite mehr im Ordner. → Task 7, 10
4. Heatmap-Token einer Website liefert keine Punkte einer anderen Website. → Task 4
5. Kontakt-Klick speichert nie Telefonnummer/E-Mail-Adresse. → Task 6

---

Sammeldienst (analytics/)

Task 1: Gerüst, Datenbank, Website-Register

Files: analytics/package.json (type module, test node --test test/*.test.js), src/config.js, src/db.js, src/server.js, src/index.js, test/sites.test.js. Produces: loadConfig(env) ⇒ { port: 8090, dataDir: '/srv/webklar-analytics', adminToken, heatSecret, geoFile, baseHost: 'project.webklar.com' }; openDb(path) ⇒ db (Schema: sites(siteKey PK, projectId, domains JSON, active INT, offSince TEXT), events_raw(id, site, ts, type, path, vp, ref, country, device, visitor, sec, scroll, kind, host), clicks(id, site, ts, path, vp, x, y, sel), daily(site, day, dim, key, count, PK(site,day,dim,key))); Admin-Routen (Bearer adminToken, timingSafeEqual): PUT /a/admin/sites/:siteKey {projectId, domains[], active}, DELETE /a/admin/sites/:siteKey, GET /a/health.

• Tests: 401 ohne/mit falschem Token; PUT legt an/ändert; active=false setzt offSince einmalig; ungültiger siteKey 400; Domains nur Hostnamen.
• FAIL → implementieren → PASS → Commit „Analytics: Geruest, Datenbank, Website-Register“

Task 2: Annahme POST /a/e

Files: src/ingest.js, src/ua.js, src/salt.js, test/ingest.test.js. Produces: classifyUa(ua) ⇒ { bot:boolean, device:'m'|'t'|'d' } (kleine eigene Regeln, gängige Bots); createSalt({ now }) ⇒ { visitorId(site, ip, ua) } (Rotation 00:00 Berlin); Handler: Body ≤ 4 KB text/plain JSON; Website aktiv + Origin/Referer-Host ∈ domains, sonst 204 ohne Speichern; Felder streng nach Global Constraints validieren/kürzen; Land über geo.lookup(ip) (Task 3, injizierbar); Limit 120/Min je (site, ip); CORS-Header nur für passende Origin; Antwort 204; nie Set-Cookie.

• Tests: pv gespeichert ohne visitor; bn nur mit a; en/ck/ct mit visitor; fremde Origin ⇒ nichts; Bot ⇒ nichts; 121. Ereignis ⇒ verworfen; Query/Hash aus path entfernt; ref nur Host und nicht eigene Domain; kein IP/UA in der Datenbank (Tabelleninhalte prüfen); Salz wechselt um Mitternacht Berlin.
• FAIL → implementieren → PASS → Commit „Analytics: Ereignisse annehmen“

Task 3: Länder (DB-IP Lite)

Files: src/geo.js, scripts/geo-update.sh (lädt monatliche CSV dbip-country-lite-YYYY-MM.csv.gz nach dataDir/geo.csv), test/geo.test.js. Produces: loadGeo(file) ⇒ { lookup(ip) ⇒ 'DE'|…|'' } – IPv4 und IPv6 als BigInt-Bereiche, sortiert, Binärsuche; fehlende Datei ⇒ '' für alles.

• Tests mit kleiner Fixture-CSV (v4, v6, Grenzen, unbekannt). FAIL → implementieren → PASS → Commit „Analytics: Laenderzuordnung“

Task 4: Verdichtung, Löschung, Statistik, Heatmap-Daten

Files: src/jobs.js, src/stats.js, src/heat.js, test/stats.test.js. Produces: runNightly(db, { now }) (Rohdaten > 1 Tag in daily verdichten: dims pv_path, pv_ref, pv_country, pv_device, pv_total, visitors, en_sec_sum, en_count, scroll_sum, ct_kind, bn_shown|accept|reject; Rohdaten/Klicks > 30 Tage löschen; Websites offSince > 60 Tage: alle Zeilen löschen); GET /a/admin/stats/:siteKey?range=7|30|90 ⇒ { totals:{pv, visitors, contacts, consentRate}, series:[{day,pv}], pages, refs, countries, devices, contacts, banner } (heute aus Rohdaten + Vergangenheit aus daily); GET /a/heat?token= (Token HMAC heatSecret: siteKey|path|vp|exp, abgelaufen/falsch ⇒ 403) ⇒ { points:[{x,y}] } max 5000 neueste.

• Tests: Verdichtung + idempotent; 31 Tage alte Rohdaten weg; Website nach 61 Tagen weg; Stats-Form; consentRate = accept/(accept+reject); Token fremder Website/abgelaufen ⇒ 403.
• FAIL → implementieren → PASS → Commit „Analytics: Verdichtung, Statistik, Heatmap-Daten“

Task 5: Auslieferung der Client-Skripte

Files: src/assets.js, Route GET /a/w.js, GET /a/h.js (Cache-Control public, max-age=3600, Content-Type: text/javascript), Quellen in client/ (Task 6).

• Test: beide Dateien ausgeliefert, richtige Header, ETag. → Commit „Analytics: Skripte ausliefern“

Task 6: Client-Skript w.js und Overlay h.js

Files: analytics/client/w.js, analytics/client/h.js, analytics/client/core.js (reine Funktionen, auch von Tests importiert), test/client.test.js. Produces (core): vpClass(width), cleanPath(href), refHost(referrer, ownHost), cssPath(el) (≤ 200, ohne IDs mit Zahlen-Hashes), contactKind(a) ⇒ 'tel'|'mail'|'wa'|'out'|null (wa: wa.me / api.whatsapp.com), readConsent(storage, now), contrastOk(hex). w.js: liest data-site/data-color aus dem eigenen <script>; GPC/DNT ⇒ reject ohne Banner; sendet pv; Banner laut Global Constraints (zugänglich: Buttons, Fokus, role="dialog", aria-label); bn bei Anzeige/Klick; nach accept Listener für Klick (ck, ct), Verlassen (en via visibilitychange/pagehide); Footer-Link bzw. [data-webklar-consent] öffnet Banner erneut; Widerruf entfernt Listener sofort; ?__wk_heat= ⇒ lädt h.js, entfernt den Parameter per history.replaceState, sendet in diesem Modus nichts. h.js: holt Punkte, zeichnet Canvas-Overlay (radiale Verläufe, Deckkraft), Leiste oben mit Gerätewahl-Hinweis und „Schließen“.

• Tests (Node, core): alle reinen Funktionen inkl. Grenzfälle. Verhalten von w.js/h.js prüft Task 15 im Browser.
• Commit „Analytics: Banner-Skript und Heatmap-Overlay“

Runner

Task 7: Einsetzen beim Veröffentlichen

Files: runner/src/validate.js (Feld analytics streng prüfen: siteKey, color, privacy {company ≤ 200, address ≤ 300, email ≤ 200, kein Steuerzeichen}), runner/src/analytics-inject.js, Aufruf in jobs.js publish (auf dem .new-Ordner vor dem Tausch), runner/test/analytics-inject.test.js. Produces: injectAnalytics(dir, analytics, { baseUrl }): in jede *.html (rekursiv, ohne node_modules) vor </head> (sonst am Anfang von <body>, sonst Dateianfang) genau einmal <script src="https://project.webklar.com/a/w.js" data-site=".." data-color=".." defer></script>; erzeugt datenschutz-analyse.html aus Vorlage runner/src/templates/datenschutz-analyse.html (Platzhalter HTML-maskiert; Task 7 legt die Vorlage mit vorläufigem Text und allen Platzhaltern an, Task 13 schreibt den endgültigen Inhalt); ohne analytics nichts tun (ein früher eingesetztes Skript existiert im neuen Ordner ohnehin nicht, da aus der Quelle neu gebaut).

• Tests: Einsetzen in mehrere Dateien, kein Doppel, ohne head, Maskierung (<script> im Firmennamen), ohne analytics unverändert, Dev-Modus unberührt.
• Commit „Runner: Analyse-Skript und Datenschutz-Zusatzseite einsetzen“

Portal

Task 8: Schema, Konfiguration, Analytics-Client

Files: scripts/analyse-setup.mjs (portalFeatures: accentColor 7, avvVersion 20, avvAcceptedAt 40, avvAcceptedBy 100, activatedAt 40, offSince 40, privacyTicketId 40; limit 200), server/config.js (analyse: { enabled: ANALYSE_ENABLED==='on', url: ANALYTICS_URL||'http://webklar-analytics:8090', adminToken, heatSecret, avvVersion: '2026-10-01' }), server/services/analyticsClient.js (putSite, deleteSite, getStats, heatToken(siteKey,path,vp,now)), Tests.

• Commit „Analyse: Schema, Konfiguration, Client“

Task 9: Freischalt-Logik

Files: server/services/analyse.js, test/analyse.test.js. Produces: analyseEligibility(customerId, projectId) ⇒ { ok, reason } (Eigentum, Wartungs-Abo aktiv, isPublic, Subdomain); activateAnalyse({ customerId, projectId, accentColor, consent, by }) (siteKey aus portalFeatures-Dokument featureKey:'analyse' wiederverwenden/neu, Zustand active, AVV-Felder, putSite mit Domains, Neubau über runDeploy(..., { project }), Ticket über createFeatureTicket mit featureKey:'analyse' und Topic „Datenschutzerklärung von um Hinweis auf Analyse ergänzen“, Mail K18 „Deine Website-Analyse ist aktiv“); deactivateAnalyse(...) (off, offSince, putSite active false, Neubau); runAboCheck({ now }) (täglich: aktiv ohne Wartungs-Abo ⇒ deactivate + Mail K19 „Website-Analyse beendet“). Idempotent.

• Tests: ohne Abo/Hosting-Abo ⇒ abgelehnt; nicht öffentlich ⇒ abgelehnt; AVV fehlt ⇒ 400; doppelt aktivieren ⇒ ein Ticket; deaktivieren ⇒ offSince; Abo-Ende-Job.
• Commit „Analyse: Freischalten, Abschalten, Abo-Pruefung“

Task 10: Runner-Auftrag mit Analyse-Feld

Files: server/services/previewDeploy.js (runDeployViaRunner + registerDevRound unverändert für dev), Test. Im Build-Auftrag analytics setzen, wenn portalFeatures(analyse) active und Projekt öffentlich: { siteKey, color, privacy: { company: customer.companyName||customer.name, address: street + PLZ Ort, email: customer.email } }; sonst null.

• Tests: aktiv+öffentlich ⇒ Feld; aus ⇒ null; nicht öffentlich ⇒ null. Commit „Analyse: Runner-Auftrag“

Task 11: Routen

Files: server/routes/funktionen.js (GET liefert Analyse-Zustand je Projekt + eligibility; POST /analyse/activate, /analyse/deactivate, GET /analyse/stats?projectId&range, POST /analyse/heatmap-link {projectId,path,vp} ⇒ { url }), server/routes/admin/analyse.js (POST /api/admin/analyse/:projectId { on, avvConfirmedVerbally }), Schalter aus ⇒ 409; Tests.

• Commit „Analyse: Routen fuer Portal und WOMS“

Task 12: Portal-Oberfläche

Files: public/funktionen.js (+ CSS), neue Ansicht #view-analyse (Hash #analyse, App-Unterseite wie News). Kachel: Zustände (kein Abo / nicht öffentlich / aus / aktiv); Einschalt-Dialog (Erklärung, Farbwahl + Live-Vorschau des Banners, AVV-Haken mit Link zur AVV-Fassung, Knopf); Auswertung: Zeitraum, Kennzahl-Karten, SVG-Liniendiagramm, Listen (Seiten, Herkunft, Länder mit Flaggen-Emoji, Geräte, Kontakt-Klicks, Banner), Hinweis zu Einwilligung, Heatmap-Auswahl (Seite aus Top-Seiten, Gerät) + Knopf; DB-IP-Namensnennung klein unten; „Analyse ausschalten“ mit In-Seite-Bestätigung. 390 px tauglich.

• npm test grün; Commit „Analyse: Portal-Kachel und Auswertung“

Rechtstexte und WOMS

Task 13: Rechtstexte (Entwürfe)

Files: docs/rechtliches/avv-website-analyse.md, leistungsbeschreibung-website-analyse.md, abo-bedingungen-ergaenzung-analyse.md, Vorlage runner/src/templates/datenschutz-analyse.html (Inhalt laut Spec, Platzhalter {{company}}, {{address}}, {{email}}), Absatz in public/datenschutz.html (WEBklar als Auftragsverarbeiter für Kunden-Websites).

• Commit „Analyse: Rechtstexte (Entwuerfe, anwaltlich zu pruefen)“

Task 14: WOMS-Schalter und Services

Files (WOMS): src/lib/analyseApi.js, Zeile in src/components/AssignedProjectCard.jsx („Website-Analyse: an/aus“, Einschalten nur mit Haken „Kunde hat AVV bestätigt“), Services-Statuslabel für analyse aktiv.

• npm test + Build; Commit „Analyse: Schalter im WOMS“

Task 15: Browser-Prüfung (Playwright)

Testseite + Sammeldienst lokal (Testdaten-Verzeichnis), echtes w.js: ohne Annehmen nur pv+bn im Netzwerk; Annehmen ⇒ ck/ct/en; Ablehnen + Widerruf; GPC; Banner 390 px; Heatmap-Overlay mit Token; Portal-Ansichten mit Fixtures. Screenshots /root/reports/website-analyse-2026-10-01/.

Livegang (jeder Schritt mit OK des Nutzers)

• L1 /srv/webklar-analytics, .env (ANALYTICS_ADMIN_TOKEN, ANALYTICS_HEAT_SECRET), Compose-Dienst analytics (node:24-alpine, Code ro, webklar-network, Traefik-Router Host(project.webklar.com) && PathPrefix(/a/) Priorität > Portal, kein IP-Access-Log), geo-update.sh + monatlicher Cron, Schema-Skript, deploy.sh Neustart bei analytics/-Änderung.
• L2 Portal/Runner/Analytics pushen (ANALYSE_ENABLED=off).
• L3 Probe: öffentliche Wegwerf-Website, Analyse per Admin an, Banner/Ereignisse/Statistik/Heatmap prüfen, Abschalten ⇒ Skript weg, aufräumen.
• L4 WOMS pushen; Nutzer lädt Rechtstexte in „Rechtliches“; ANALYSE_ENABLED=on.
• L5 Live-Test des Nutzers mit einer echten Kunden-Website mit Wartungs-Abo.