qc-text-builder/docs/TARGET_STATE_AND_ROADMAP.md

Zielbild und Roadmap: QC Text Builder

Zielbild

Die QC App ist die kontrollierte Text-Build-Pipeline zwischen Vorbefuellung und finalem QC-Site-Build.

Geplantes Endbild:

• Leadharvester liefert Stammdaten (z. B. Firmenname, Kontakt, Adresse, Branche) und optional eine Website-Zusammenfassung als Input.
• QC App uebernimmt Template-Logik: Template-Sync, Discovery/Manifest, Feld-Mapping, Feldgruppierung, Draft-Review und Build-Ausfuehrung.
• Builds werden nicht direkt aus externer Intake ohne Review durchgedrueckt, sondern ueber den Draft-/Review-Flow gesteuert.
• Spaeter erzeugt eine LLM-Unterstuetzung Feldvorschlaege und Draft-Befuellung, weiterhin mit menschlicher Review vor Submit.

Rolle von Persistenz (SQLite)

SQLite ist aktuell die Standardpersistenz fuer den lokalen und Team-nahen Betrieb:

• Einstellungen (inkl. QC-Basisdaten)
• Templates
• Onboarding-Manifeste und Felder
• Drafts
• Site-Builds inkl. Polling-/Result-Status

Bedeutung:

• Nachvollziehbarkeit: Draft- und Build-Verlauf bleibt erhalten.
• Reproduzierbarkeit: Mapping-Stand und Feld-Entscheidungen sind persistent.
• Entkopplung: Intake, Review und Build koennen zeitlich getrennt stattfinden.

Hinweis: Eine produktive Postgres-Variante ist vorbereitet, aber noch nicht implementiert.

Draft-/Review-Flow

Soll-Logik:

1. Intake/Vorbefuellung erzeugt oder aktualisiert einen Draft.
2. Draft wird im UI/API geprueft und angepasst.
3. Status wird auf reviewed gesetzt.
4. Erst dann wird Build gestartet; bei Build-Start wird der Draft auf submitted gesetzt.

Aktueller Stand:

• Draft-Erfassung, Listing, Update und UI-Weiterbearbeitung sind vorhanden.
• Definierter externer Intake unter POST /api/drafts/intake ist vorhanden; templateId ist optional, Build wird dort nicht ausgeloest.
• Draft-Kontext fuer spaetere LLM-Unterstuetzung ist vorbereitet (Website-URL, Website-Summary, Stilprofil inkl. locale/market/address mode/tone/prompt instructions).
• Prompt-/Systemsteuerung liegt global in Settings; der normale Build-/Review-Flow bleibt auf Inhalte und Feldbearbeitung fokussiert.
• Semantische Zielslots (z. B. hero.title, service_items[n].description) werden intern auf konkrete Template-Felder gemappt als Vorbereitung fuer spaeteren LLM-Autofill.
• Repeated-Sektionen (u. a. Services/Team/Testimonials) werden in der Slot-Vorschau block- und rollentypisch pro Item getrennt statt in Sammel-Slots zusammenzufallen.
• Rule-based Suggestion-State fuer Draft-/Build-UI ist vorhanden: Vorschlaege werden separat von Feldwerten gespeichert und per Generate/Regenerate/Apply (global und per Feld) explizit gesteuert.
• Build-Start erfordert bereits einen Template-Manifest-Status reviewed/validated.
• Prozessuale Review-Gates (z. B. Freigabe-Policy, Rollen, Pflichtchecks pro Feld) sind noch nicht vollstaendig ausgebaut.

Geplante Leadharvester-Integration

Integrationsidee:

• Leadharvester ist Upstream fuer Stammdaten + optional Website-Zusammenfassung.
• Uebergabe erfolgt in die QC App als Draft-Intake (nicht als direkter Build-Trigger).
• QC App bleibt System of Control fuer:
  • Template-Auswahl und Manifest-Logik
  • Feld-Mapping/Transformation
  • Review und Freigabe
  • finalen Build-Call in QC

Geplante LLM-Unterstuetzung

Spaeterer Ausbau in der QC App:

• Vorschlaege fuer fehlende Felder aus vorhandenen Stammdaten + Website-Zusammenfassung.
• Vorbefuellung von Drafts mit transparenten, ueberschreibbaren Vorschlaegen.
• Beruecksichtigung von businessType plus Stilprofil (Tone/Style), damit Vorschlaege branchenspezifisch und konsistent sind.

Wichtig: LLM ist Assistenz, kein automatischer Bypass des Review-Schritts.

Security-Positionierung

Security-Haertung ist bewusst nachgelagert und noch nicht abgeschlossen.

• Aktuell liegt der Fokus auf funktionaler Pipeline (Template -> Draft/Review -> Build).
• Token-/Secret-Haertung und erweiterte Zugriffskontrollen werden in spaeteren Schritten priorisiert.

Roadmap (Statuspflege)

Statusmarker:

• [x] erledigt
• [-] teilweise offen
• [ ] offen

A) Fundament und laufender Betrieb

• Go-App mit HTTP-UI + API-Endpunkten fuer Templates, Drafts und Builds.
• SQLite als Default-Persistenz integriert (Templates, Manifeste/Felder, Drafts, Builds, Settings).
• [-] Alternative Persistenz (Postgres) nur als Stub vorbereitet, noch nicht umgesetzt.

B) Template- und Manifest-Logik

• AI-Template-Sync vorhanden.
• Onboarding/Discovery erzeugt flatten Manifest-Felder.
• Template-Felder sind editierbar (Enable/Required/Label/Order/WebsiteSection/Notes).
• [-] Feldqualitaetsregeln sind grundlegend vorhanden, aber ohne erweiterte Governance-Checks.

C) Draft-/Review-/Build-Flow

• Draft-Intake via API und Draft-Bearbeitung via UI/API.
• Draft-Statusmodell (draft, reviewed, submitted) vorhanden.
• Build aus Feldwerten + GlobalData inkl. QC-CreateSite-Aufruf.
• Build-Polling, Timeout-Handling und Editor-URL-Fetch vorhanden.
• [-] Review-Gate ist noch nicht als strikter, rollenbasierter Freigabeprozess umgesetzt.

D) Leadharvester-Integration

• Definierter Intake-Adapter von Leadharvester in POST /api/drafts/intake.
• Mapping-Contract fuer Stammdaten + optionale Website-Zusammenfassung.
• Monitoring/Fehlerbild fuer Intake-Qualitaet und Nachbearbeitungsquote.

E) LLM-Assistenz

• [-] Feldvorschlaege im Draft als expliziter Preview-/Apply-/Regenerate-Workflow (aktuell rule-based, ohne produktiven LLM-Runner).
• [-] Draft-Autofill mit nachvollziehbarer Herkunft je Feld (Suggestion-State mit Quelle/Status vorhanden, per-section Flow noch offen).
• [-] Stilprofil-Logik unter Beruecksichtigung von businessType + Tonalitaet (Kontextfelder + Auswahlfelder vorhanden, produktive Vorschlagslogik offen).
• [-] Prompt-/Systemsteuerung (Master-Prompt + Prompt-Bloecke) in Settings als Vorbereitung fuer spaeteren LLM-Runner; Build-Flow ohne prominente Prompt-Interna.
• [-] Semantische Slot-Mappings zwischen Template-Feldern und Zielrollen als Bruecke fuer spaeteren LLM-Autofill vorbereitet (inkl. verbesserter Trennung in Repeated-Bereichen).

F) Security und Betriebsreife

• Verbindliche Secret-Strategie (verschluesselte Speicherung statt einfacher Platzhalterlogik).
• AuthN/AuthZ fuer sensible Schreiboperationen.
• Auditierbare Freigaben fuer Review/Submit-Schritte.

Pflegehinweis

Dieses Dokument ist ein lebender Projektkompass. Bei Scope-Aenderungen oder abgeschlossenen Roadmap-Punkten muessen Status und Text in diesem Dokument und im README synchron aktualisiert werden.