chore: add MVP planning backlog

PRD.md

@@ -0,0 +1,386 @@
+# Product Requirements Document: Lokaler Akquise-Agent für Webdesign
+
+## 1. Produktvision und Problemstellung
+
+Matthias Meister Webdesign benötigt ein internes Akquise-Werkzeug, das hochwertige lokale Leads findet, deren Online-Auftritt analysiert und daraus persönliche, konkrete Erstkontakte vorbereitet. Das Produkt soll zunächst Matthias' eigenen Freelance-Akquiseprozess unterstützen und mittelfristig als Grundlage für ein späteres SaaS-Angebot für andere Freelancer oder Agenturen dienen.
+
+Das Kernproblem: Lokale Unternehmen haben häufig keine Website, eine veraltete Website, schlechte mobile Nutzbarkeit, schwache lokale Sichtbarkeit oder unklare Kontaktführung. Gleichzeitig ist klassische Kaltakquise schnell generisch, rechtlich sensibel und für Empfänger unangenehm. Der Agent soll deshalb nicht massenhaft Mails verschicken, sondern wenige qualitativ hochwertige Leads vorbereiten, die mit nachvollziehbaren Mini-Audits, konkreten Vorschlägen und manueller Freigabe kontaktiert werden.
+
+## 2. Zielgruppe und User Personas
+
+### MVP-User: Matthias Meister
+
+Matthias ist Solo-Freelancer im Webdesign. Er möchte lokale Unternehmen in Deutschland gezielt ansprechen, ohne generische Massenmails zu versenden. Er braucht ein Dashboard, das Recherche, Audit, Freigabe, Versand und Follow-up kompakt zusammenführt.
+
+### Externe Empfänger: Lokale Unternehmen
+
+Lokale Unternehmen sollen eine persönliche, respektvolle Kontaktaufnahme erhalten. Sie sollen erkennen, dass ihre Website tatsächlich angesehen wurde. Der Ton ist sachlich, hilfreich und auf Augenhöhe, ohne Scores, Drohkulisse oder anklagende Sprache.
+
+### Spätere SaaS-Zielgruppe
+
+Langfristig können Webdesigner, kleine Agenturen oder lokale Marketingdienstleister ähnliche Workflows nutzen. Diese Zielgruppe ist für das MVP nicht handlungsleitend, wird aber architektonisch als Zukunftsoption berücksichtigt.
+
+## 3. MVP-Scope und Core User Stories
+
+### Kampagnen
+
+- Als Nutzer möchte ich eine Kampagne mit Kategorie, PLZ, Umkreis, Wiederholungsrhythmus und Limits anlegen.
+- Als Nutzer möchte ich Kategorien aus einem Dropdown wählen und bei "Anderes" einen eigenen Suchbegriff eingeben.
+- Als Nutzer möchte ich pro Kampagne maximale neue Leads und maximale neue Audits pro Lauf festlegen.
+- Als Nutzer möchte ich Kampagnen wiederholt per Cron ausführen lassen und sie manuell mit "Jetzt ausführen" starten können.
+
+### Lead-Recherche
+
+- Als Nutzer möchte ich lokale Businesses über Google Places finden.
+- Als Nutzer möchte ich PLZ und Umkreis angeben; das System geocodiert die PLZ für die Radius-Suche.
+- Als Nutzer möchte ich weniger, aber qualitativ hochwertigere Leads erhalten.
+- Als Nutzer möchte ich Leads ohne E-Mail nicht verlieren, sondern in einer Kategorie "Kontakt fehlt" sehen.
+
+### Lead-Qualifizierung
+
+- Als Nutzer möchte ich Leads nach Website-Potenzial priorisieren: keine Website, veraltete Website, schlechte mobile Darstellung, schwache Kontaktführung, lokale SEO-Chancen.
+- Als Nutzer möchte ich Unternehmen mit moderner/guter Website als niedrige Priorität speichern.
+- Als Nutzer möchte ich Google-Bewertungen intern für Priorisierung und Angebotsrichtung nutzen, aber nicht automatisch auf der Kundenseite zeigen.
+- Als Nutzer möchte ich Dubletten vermeiden und bereits kontaktierte Unternehmen schützen.
+
+### Website-Audit
+
+- Als Nutzer möchte ich Startseite und relevante Unterseiten analysieren lassen: Kontakt, Impressum, Leistungen, Über uns/Team.
+- Als Nutzer möchte ich Desktop- und Mobile-Screenshots speichern.
+- Als Nutzer möchte ich PageSpeed-Insights intern nutzen, aber extern keine Scores anzeigen.
+- Als Nutzer möchte ich multimodale LLMs nutzen, um Screenshots in die Analyse einzubeziehen.
+- Als Nutzer möchte ich lokale Design- und Marketing-Skills aus einer `skills.md`-Registry verwenden.
+
+### Audit-Seite
+
+- Als Nutzer möchte ich eine personalisierte Audit-Seite unter `audit.matthias-meister-webdesign.de/<firmenname-ort>` erzeugen.
+- Als Nutzer möchte ich Audit-Seiten manuell freigeben, bevor sie öffentlich Inhalte zeigen.
+- Als Nutzer möchte ich nicht freigegebene Audits mit "Dieser Audit ist noch nicht freigegeben" anzeigen.
+- Als Nutzer möchte ich Audit-Seiten cachen und bei Änderungen invalidieren.
+- Als Nutzer möchte ich Audit-Seiten mit `noindex` versehen und nicht in eine Sitemap aufnehmen.
+- Als Nutzer möchte ich Audits nach 30 Tagen im Dashboard zur Prüfung sehen und nach 60 Tagen automatisch deaktivieren lassen, mit manueller Reaktivierung.
+
+### Outreach
+
+- Als Nutzer möchte ich eine Kontaktstrategie pro Lead erhalten: erst anrufen, direkt E-Mail, zurückstellen oder nicht kontaktieren.
+- Als Nutzer möchte ich E-Mail-Entwurf, Betreff, Audit-Link und Telefon-Skript in einer Review-Ansicht bearbeiten.
+- Als Nutzer möchte ich nach Freigabe direkt über meinen Stalwart-Mailserver senden.
+- Als Nutzer möchte ich ein respektvolles Follow-up vorbereiten lassen, das erneut nur nach Freigabe gesendet wird.
+- Als Nutzer möchte ich eingehende Antworten im MVP manuell markieren.
+
+### Dashboard
+
+- Als Nutzer möchte ich einen Kanban/Funnel für Leads und Status sehen.
+- Als Nutzer möchte ich Kampagnenmetriken sehen: gefundene Leads, Audits, gesendete E-Mails, Antworten, Gespräche, Angebote und Aufträge.
+- Als Nutzer möchte ich Rybbit-Daten für generierte Audit-Seiten im Dashboard sehen, ohne die Rybbit-Instanz separat öffnen zu müssen.
+- Als Nutzer möchte ich eine manuelle Sperrliste für Domains, E-Mails, Telefonnummern, Firmennamen und Google Place IDs pflegen.
+
+## 4. Out of Scope für das MVP
+
+- SaaS-Mandantenfähigkeit
+- Mehrere Benutzer oder Rollen
+- Abrechnung, Pläne oder Kontingente
+- Automatische Inbox-Auswertung
+- Automatische Antworterkennung
+- Vollwertiges CRM
+- Automatischer Versand ohne manuelle Freigabe
+- Google-Maps-Scraping per Browser-Automation
+- Sentry oder externes Error-Monitoring
+- Internationale Suche außerhalb Deutschlands
+
+## 5. High-Level Architektur und Tech-Stack
+
+### Frontend und App
+
+- Next.js mit App Router
+- shadcn/ui und Tailwind CSS
+- React Hook Form und Zod für Formulare und Validierung
+- Dashboard mit Light/Dark Mode
+- Öffentliche Audit-Seiten mit festem, hellem und ruhigem Design
+
+### Backend und Daten
+
+- Convex Cloud für MVP
+- Convex Database für Kampagnen, Leads, Audits, Status, Rohdaten und Verlauf
+- Convex File Storage für Screenshots
+- Convex Cron Jobs und Actions für wiederkehrende Kampagnen, Audits und Lifecycle-Regeln
+- Später optional Self-hosted Convex für SaaS
+
+### Auth
+
+- Better Auth mit Convex-Integration
+- E-Mail/Passwort
+- Ein Admin-User im MVP
+- Öffentliche Audit-Seiten ohne Login
+
+### Agenten- und LLM-Schicht
+
+- Vercel AI SDK als Orchestrierungsschicht
+- OpenRouter als flexibler Modellzugang
+- Modellprofile für Lead-Klassifikation, Audit-Analyse, multimodale Analyse, Textgenerierung und Qualitätscheck
+- Strukturierte Outputs mit Zod-Schemas
+- Lokale Design- und Marketing-Skills werden im Projekt-Repository gespeichert
+- Eine `skills.md` dient als Skill-Registry mit Name, Zweck, Einsatzbereich, benötigtem Input und erwartetem Output
+- Das Dashboard zeigt pro Audit eine kompakte Übersicht der verwendeten Skills
+- Speicherung aller Prompts, Modellnamen, Rohantworten, Zwischenergebnisse und finalen Texte in Convex
+
+### Recherche und Analyse
+
+- Google Geocoding API für PLZ zu Koordinaten
+- Google Places API für lokale Businesses
+- PageSpeed Insights API für technische Performance-/SEO-/Accessibility-Signale
+- Playwright für Website-Aufruf, Screenshots, Unterseitenanalyse, Textauszüge und einfache technische Checks
+- RapidAPI nur als optionaler Fallback, wenn offizielle APIs relevante Daten nicht liefern
+
+### Mail und Analytics
+
+- Stalwart Mailserver via SMTP/SMTPS
+- Nodemailer für SMTP-Versand
+- Versand nur nach manueller Freigabe
+- Rybbit, selbst gehostet, nur auf öffentlichen Audit-Seiten
+- Rybbit-Daten werden im Dashboard per API abgerufen, nicht regelmäßig nach Convex synchronisiert
+
+### Deployment und Konfiguration
+
+- Deployment unter Coolify
+- App-Domain: `audit.matthias-meister-webdesign.de`
+- Secrets in `.env`, Coolify Environment Variables und Convex Secrets
+- Keine API-Keys oder SMTP-Credentials im Dashboard oder Repository
+
+## 6. Konzeptionelles Datenmodell
+
+### Campaign
+
+- Name
+- Kategorie oder Freitext-Nische
+- PLZ
+- Ort/Region
+- Koordinaten
+- Umkreis
+- Wiederholungsrhythmus
+- maximale neue Leads pro Lauf
+- maximale Audits pro Lauf
+- Status: aktiv, pausiert
+- letzter Lauf
+- nächster Lauf
+
+### Lead
+
+- Firmenname
+- Kategorie/Nische
+- Adresse/Ort
+- Google Place ID
+- Google-Maps-Quelle
+- Website-Domain
+- Telefonnummer
+- E-Mail-Adresse
+- E-Mail-Quelle
+- Ansprechpartner
+- Priorität: hoch, mittel, niedrig, zurückstellen
+- Kontaktstatus
+- Dublettenstatus
+- Sperrstatus
+- interne Notizen
+
+### Audit
+
+- Lead-Referenz
+- Status: Entwurf, freigegeben, veröffentlicht, deaktiviert
+- Slug
+- geprüfte Domain
+- geprüfte Unterseiten
+- Screenshots
+- PageSpeed-Rohdaten
+- Playwright-Ergebnisse
+- gefundene Textpassagen
+- verwendete Skills
+- Skill-Ausgaben
+- multimodale Analyse
+- finale Zusammenfassung
+- öffentlicher Audit-Text
+- CTA-Typ
+- Veröffentlichungsdatum
+- 30-Tage-Hinweisstatus
+- Deaktivierungsdatum
+
+### Outreach
+
+- Lead-Referenz
+- Audit-Referenz
+- Kontaktstrategie
+- Telefon-Skript
+- E-Mail-Betreff
+- E-Mail-Entwurf
+- Follow-up-Entwurf
+- Freigabestatus
+- Versandstatus
+- Versandzeitpunkt
+- Antwortstatus
+- Sales-Status: Follow-up geplant, Follow-up gesendet, Antwort erhalten, Kein Interesse, Später wieder melden, Gespräch vereinbart, Angebot angefragt, Angebot gesendet, Auftrag gewonnen, Auftrag verloren, Nicht weiter verfolgen
+
+### Blacklist
+
+- Typ: Domain, E-Mail, Telefonnummer, Firmenname, Google Place ID
+- Wert
+- Notiz
+- Erstellungsdatum
+
+## 7. UI/UX-Prinzipien und Accessibility
+
+Das Dashboard ist ein funktionales Arbeitswerkzeug. Es soll dicht, scanbar und effizient sein, ohne Marketing-Optik. Hauptansicht ist ein Kanban/Funnel. Detail- und Review-Ansichten bündeln Lead-Daten, Audit, E-Mail, Betreff, Telefon-Skript, Quellen und Freigabeaktionen.
+
+Die öffentliche Audit-Seite ist ruhiger als Matthias' bestehende Hauptseite. Sie wirkt persönlich, beratend und respektvoll. Sie verwendet keine Scores, Ampeln, Warnfarben oder anklagende Sprache. Screenshots werden ohne Annotationen im Kontext der Befunde gezeigt. Der Bericht nennt Firma, Domain und konkrete Beobachtungen. Das Angebot und der Link zur Hauptwebsite erscheinen am Ende.
+
+Alle zentralen Interaktionen müssen mit Tastatur bedienbar sein. Formulare brauchen klare Labels, Fehlermeldungen und valide Kontraste. Texte dürfen auf mobilen und Desktop-Viewports nicht überlaufen.
+
+## 8. Voice & Tone
+
+Alle generierten E-Mails und Audit-Texte werden in Ich-Form geschrieben, passend zu Matthias als Solo-Freelancer.
+
+Der Stil ist:
+
+- auf Augenhöhe
+- konkret
+- lokal und nahbar
+- respektvoll
+- nicht belehrend
+- frei von generischen KI-Floskeln
+- ohne übertriebene Dringlichkeit
+- ohne Preise in der Erstansprache
+
+Der Agent formuliert Sachverhalte und Vorschläge, keine Urteile. PageSpeed- und technische Befunde werden in Kundennutzen übersetzt, zum Beispiel weniger Absprünge, bessere mobile Kontaktaufnahme, mehr Vertrauen oder bessere lokale Auffindbarkeit.
+
+## 9. Security, Privacy und Compliance
+
+- Keine automatische Kontaktaufnahme ohne manuelle Freigabe
+- Keine erratenen E-Mail-Adressen
+- Personenbezogene E-Mail-Adressen nur, wenn sie explizit als geschäftliche Kontaktadresse veröffentlicht sind
+- Dokumentation der Quelle für Kontaktinformationen
+- Blacklist für manuelle Ausschlüsse
+- Dubletten- und Kontakt-Sperre gegen doppelte Ansprache
+- "Nicht erneut kontaktieren" blockiert für 12 Monate und wird danach nur zur Prüfung vorgeschlagen
+- Audit-Seiten mit `noindex`
+- Keine Sitemap für Audit-Seiten
+- Kein öffentliches Audit-Verzeichnis
+- Rybbit nur anonym und nur für generierte Audit-Seiten
+- Secrets nicht im Dashboard, nicht im Repo und nicht in Logs
+
+Die rechtliche Bewertung von Kaltakquise, UWG und DSGVO bleibt ein sensibler Bereich. Das Produkt reduziert Risiken durch manuelle Freigabe, Quellenhaltung, transparente Kontaktstrategie und zurückhaltende Sprache, ersetzt aber keine Rechtsberatung.
+
+## 10. Nicht-funktionale Anforderungen
+
+- Qualität vor Menge: kleine, hochwertige Lead-Limits pro Lauf
+- Nur ein aktiver Agentenlauf gleichzeitig im MVP
+- Kampagnenläufe müssen abbrechbar oder zumindest nachvollziehbar fehlschlagen
+- Fehlerstatus für Google, PageSpeed, OpenRouter, Rybbit, SMTP und Playwright sichtbar im Dashboard
+- Öffentliche Audit-Seiten sollen schnell laden und gecached werden
+- Cache-Invalidierung bei Audit-Änderungen
+- Audit-Rohdaten müssen intern nachvollziehbar gespeichert werden
+- Dashboard soll deutsche UI haben und für i18n vorbereitet sein
+- MVP ist auf Deutschland begrenzt
+
+## 11. Entwicklungsphasen und Meilensteine
+
+### Phase 1: Foundation
+
+- Next.js-App mit Dashboard-Grundstruktur
+- Convex Cloud Setup
+- Better Auth Login
+- Kampagnen- und Lead-Datenmodell
+- Grundlegender Kanban/Funnel
+
+### Phase 2: Recherche und Qualifizierung
+
+- Google Geocoding
+- Google Places Suche
+- Kategorien und "Anderes"-Freitext
+- Dublettenprüfung
+- Kontakt-fehlt-Kategorie
+- Blacklist
+
+### Phase 3: Audit-Pipeline
+
+- Playwright-Crawling für Startseite und Unterseiten
+- Screenshots in Convex
+- PageSpeed Insights
+- Skills-Registry `skills.md`
+- OpenRouter/Vercel-AI-SDK Analyse
+- interne Rohdatenhaltung
+
+### Phase 4: Audit-Seiten und Review
+
+- Öffentliche Audit-Seite
+- Manuelle Audit-Freigabe
+- noindex und Cache
+- 30-/60-Tage-Lifecycle
+- Review-Ansicht im Dashboard
+
+### Phase 5: Outreach und Follow-up
+
+- E-Mail-Entwurf mit Betreff
+- Telefon-Skript
+- SMTP-Versand über Stalwart/Nodemailer
+- Follow-up-Entwurf
+- manuelles Antwort- und Sales-Status-Tracking
+
+### Phase 6: Analytics und Feinschliff
+
+- Rybbit Tracking auf Audit-Seiten
+- Rybbit API im Dashboard
+- Kampagnenmetriken
+- Qualitätsregeln für Anti-KI-Slop
+- UI-Polish und Accessibility-Review
+
+## 12. Potenzielle technische Herausforderungen und Mitigation
+
+### API-Kosten und Limits
+
+Google, PageSpeed und OpenRouter können Kosten verursachen. Das MVP nutzt harte Limits pro Kampagne und nur einen aktiven Agentenlauf gleichzeitig.
+
+### Schlechte oder fehlende Kontaktdaten
+
+Leads ohne E-Mail werden nicht gelöscht, sondern in "Kontakt fehlt" gesammelt. Bei Telefonnummer erstellt der Agent ein kurzes Skript zur manuellen Klärung.
+
+### Generische KI-Texte
+
+Der Agent nutzt konkrete Website-Daten, Screenshots, Textpassagen, lokale Skills und Voice-Regeln. Die finale Review-Ansicht erlaubt manuelle Bearbeitung vor Freigabe.
+
+### Fehlerhafte visuelle Interpretation
+
+Multimodale Befunde werden mit DOM/Text/PageSpeed und sichtbaren Screenshots kombiniert. Extern werden nur vorsichtig formulierte Beobachtungen verwendet.
+
+### Rechtliche Sensibilität von Outreach
+
+Keine automatische Kontaktaufnahme, Quellenhaltung für E-Mails, manuelle Freigabe, zurückhaltende Sprache und Blacklist reduzieren Risiko.
+
+### Deployment mit Browser-Automation
+
+Playwright benötigt Browser-Abhängigkeiten im Coolify-Deployment. Dies wird als technischer Implementierungsaspekt in der späteren Planung berücksichtigt.
+
+## 13. Zukünftige Erweiterungen
+
+- SaaS-Mandantenfähigkeit
+- Self-hosted Convex
+- Teamrollen und Organisationen
+- Abrechnung und Nutzungspläne
+- automatische Inbox-/Thread-Zuordnung via JMAP
+- vollwertiges CRM
+- Call-Queue mit Gesprächsnotizen
+- bearbeitbare Kategorien im Dashboard
+- internationale Suche
+- zusätzliche Sprachen
+- automatisierte Re-Audits
+- erweiterte Rybbit-/Conversion-Auswertungen
+- alternative Mailprovider
+- zusätzliche Datenquellen über RapidAPI
+
+## 14. Erfolgskriterien für das MVP
+
+- Matthias kann wiederkehrende lokale Kampagnen anlegen und ausführen.
+- Der Agent findet qualitativ passende Leads mit nachvollziehbaren Quellen.
+- Der Agent erstellt brauchbare Mini-Audits mit Screenshots, PageSpeed-Kontext und konkreten Vorschlägen.
+- Die öffentlichen Audit-Seiten wirken persönlich, ruhig und nicht anklagend.
+- E-Mail, Betreff und Telefon-Skript sind editierbar und versandbereit.
+- Kein Versand erfolgt ohne manuelle Freigabe.
+- Follow-ups können vorbereitet und manuell freigegeben werden.
+- Kampagnenmetriken und Rybbit-Daten geben Matthias einen schnellen Überblick über Wirkung und Fortschritt.