# 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.
- LLM-first 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; Rule-based bleibt als letzter Fallback/Testpfad aktiv.
- Provider-aware Suggestion-Runtime ist aktiv: Settings (`llm_active_provider`, `llm_active_model`, `llm_temperature`, `llm_max_tokens`, provider-spezifischer API-Key, `llm_base_url` fuer Ollama/kompatible Endpoints) steuern den primaeren Laufzeitpfad; der bestehende QC-Pfad bleibt als Kompatibilitaetsfallback erhalten.
- Composite-Suggestion-Merge nutzt Coverage-basierte Fallback-Logik: Fallback wird nur fuer fehlende Ziel-Feldpfade angefragt, und Primaer-Vorschlaege behalten im Merge immer Prioritaet vor Fallback-Werten.
- OpenAI-kompatible Requests nutzen intern modellabhaengig den passenden Token-Limit-Parameter (`max_completion_tokens` fuer OpenAI GPT-5-Modelle, ansonsten `max_tokens`), auch im Settings-Validate-Pfad.
- OpenAI-kompatible Runtime-Response-Extraktion ist fuer neuere GPT-5/OpenAI-kompatible Shapes robuster (String-/Part-Content in `choices[].message.content` sowie `output_text`/`output[].content`) und liefert bei leerem Inhalt sichere, priorisierte Shape-Diagnostik (u. a. `choices`/`message`, `message.content`-Typ/Laenge, `finish_reason` falls vorhanden) ohne Content-Dumps.
- Settings enthalten einen leichtgewichtigen Validate-Action fuer die aktive Provider-Konfiguration (kurzer Runtime-Check), ohne den Draft-/Review-Flow zu umgehen.
- Modellauswahl ist provider-aware statisch umgesetzt und so strukturiert, dass spaeter dynamische Model-Listen/Refresh anschliessbar sind.
- Technische Felddetails (z. B. Feldpfade/Slots/Suggestion-Metadaten) sind im UI per Debug-Toggle optional einblendbar.
- Strukturierte Debug-Logs fuer den Autofill-/LLM-Pfad sind aktiv (provider-aware Request/Parse, QC-Fallback, Rule-based-Fallback, Validate-Action; ohne Prompt-/Secret-Dumps).
- Fokus-Debugging im provider-aware Runtime-Pfad wurde vertieft und per Log-Level gestaffelt: operative Zusammenfassungen laufen auf INFO, tiefe Request-/Prompt-/Payload-, Raw-Response-, Shape-, Extract-/Parse-Samples sowie Feld-Transition-Details auf DEBUG; API-Key-/Authorization-Daten bleiben redigiert.
- Eine kleine interne Log-API (`GET /api/logs`) stellt aktuelle strukturierte Logeintraege aus einem In-Memory-Ring-Buffer bereit.
- 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
- [x] Go-App mit HTTP-UI + API-Endpunkten fuer Templates, Drafts und Builds.
- [x] 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
- [x] AI-Template-Sync vorhanden.
- [x] Onboarding/Discovery erzeugt flatten Manifest-Felder.
- [x] Template-Felder sind editierbar (Enable/Required/Label/Order/WebsiteSection/Notes).
- [-] Feldqualitaetsregeln sind grundlegend vorhanden, aber ohne erweiterte Governance-Checks.

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

### D) Leadharvester-Integration
- [x] Definierter Intake-Adapter von Leadharvester in `POST /api/drafts/intake`.
- [x] Mapping-Contract fuer Stammdaten + optionale Website-Zusammenfassung.
- [ ] Monitoring/Fehlerbild fuer Intake-Qualitaet und Nachbearbeitungsquote.

### E) LLM-Assistenz
- [x] Feldvorschlaege im Draft als expliziter Preview-/Apply-/Regenerate-Workflow (LLM-first ueber provider-aware Runtime; Rule-based nur Fallback/Test).
- [x] Draft-Autofill mit nachvollziehbarer Herkunft je Feld (provider-label wie `openai`/`anthropic`/`google`/`xai`/`ollama`, `qc-llm` als Kompatibilitaetsfallback, `fallback-rule-based` als letzter Fallback).
- [-] Stilprofil-Logik unter Beruecksichtigung von `businessType` + Tonalitaet (Kontext wird in den LLM-Pfad uebergeben; Qualitaets-/Governance-Feinschliff offen).
- [-] Prompt-/Systemsteuerung (Master-Prompt + Prompt-Bloecke) in Settings in den LLM-Suggestionspfad eingebunden; Build-Flow ohne prominente Prompt-Interna.
- [x] Semantische Slot-Mappings zwischen Template-Feldern und Zielrollen als Bruecke fuer LLM-Autofill aktiv genutzt (inkl. verbesserter Trennung in Repeated-Bereichen).
- [x] Phase A/B Provider-/Modell-Settings-Fundament inkl. produktiver Runtime-Umschaltung umgesetzt (Provider-/Modellwahl + provider-spezifische Keys + Base URL fuer Ollama/kompatible Endpoints steuern Suggestions direkt).
- [x] Phase C Komfort/Qualitaet umgesetzt: Temperature/Max Tokens in Settings + Runtime, Settings-Validate-Action, robustere Provider-Response-/Fehlerbehandlung und statisch provider-aware Modell-UX mit spaeterem Ausbaupfad.
- [x] Fokus-Debugging fuer Autofill/LLM: strukturierte Ablauf-Logs + interner Recent-Log-API-Endpunkt fuer schnelle Ursachenanalyse.

### 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.

