Add project roadmap and agent guidance

преди 1 месец · 75fcaafe14
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,52 @@
 # AGENTS.md

 Dieses Dokument definiert projektlokale Leitplanken fuer Menschen und Agenten, die an diesem Repo arbeiten.

 ## 1) Architekturprinzipien

 - Trennung der Verantwortungen beibehalten:
  - `internal/*svc`: fachliche Logik (Template, Onboarding, Draft, Build, Mapping).
  - `internal/store/*`: Persistenz-Adapter.
  - `internal/httpserver/handlers`: Transport/UI-Glue, keine schwere Fachlogik duplizieren.
 - Draft-/Review-/Build-Flow ist der zentrale Kontrollpfad.
 - Persistenz ist Teil der Kernlogik, nicht optionales Nebenprodukt.
 - Kleine, nachvollziehbare Aenderungen statt grosser Umbauten ohne klaren Nutzen.

 ## 2) Aktueller Scope

 - AI-Template-Sync, Discovery/Onboarding und bearbeitbare Manifest-Felder.
 - Draft-Intake, Draft-Bearbeitung und Statuswechsel (`draft`, `reviewed`, `submitted`).
 - Build-Start aus geprueften Daten, Polling und Editor-URL-Abruf.
 - SQLite als Default-Datenhaltung fuer lokalen Betrieb.

 ## 3) Bewusst noch nicht machen

 - Keine direkte Leadharvester->Build-Abkuerzung in der QC App.
 - Kein unkontrolliertes Auto-Building ohne Draft-/Review-Schritt.
 - Keine grossen Security-Umbauten im Vorbeigehen; Security wird gezielt spaeter gehaertet.
 - Keine unnoetigen Architekturverschiebungen, die bestehende Build-/Draft-/Review-/Persistenzlogik verbiegen.

 ## 4) Leadharvester-Integration (Zielbild)

 - Leadharvester liefert Upstream-Daten (Stammdaten + optional Website-Zusammenfassung).
 - Uebergabe in die QC App erfolgt ueber Draft-Intake und anschliessende Review.
 - Die QC App bleibt verantwortliche Stelle fuer Mapping, Template-Logik, Review und finalen Build.

 ## 5) Spaetere LLM-Features

 - LLM-Unterstuetzung darf nur als Vorschlagssystem eingefuehrt werden (reviewbar/ueberschreibbar).
 - Vorschlaege muessen `businessType` und ein Stilprofil (Tone/Style) beruecksichtigen.
 - Kein LLM-Bypass des Review-Gates.

 ## 6) Doku-Pflegepflicht bei Aenderungen

 Bei jeder relevanten Verhaltensaenderung:
 - README kurz und aktuell halten (Ist-Stand, Start, Kernfluss).
 - `docs/TARGET_STATE_AND_ROADMAP.md` aktualisieren (Zielbild/Roadmap).
 - Roadmap-Status mit diesen Markern pflegen:
  - `[x]` erledigt
  - `[-]` teilweise offen
  - `[ ]` offen

 Wenn ein Feature nur geplant ist, darf es nicht als fertig dokumentiert werden.

--- a/README.md
+++ b/README.md
@@ -1,63 +1,47 @@
 # QC Text Builder (Go)

 Milestone 2 status:
 - bootstrap app/server/config
 - Quick Creator client contracts (Bearer token only)
 - AI template sync endpoint
 - onboarding/discovery endpoint with local manifest flattening
 - site build flow via `POST /sites` using local manifest + own text (`content.aiData`)
 - SQLite persistence (default) for settings, templates, manifests, fields, site builds, and build drafts
 - build polling (`POST /api/site-builds/{id}/poll`) and background polling supervisor
 - draft intake/review flow (`draft -> reviewed -> submitted`) before final build
 - strict MVP scope: no ACP login flow, no DCM/EFL, no image payload handling

 ## Run

 1. Set env vars:
 QC Text Builder ist eine Go-Anwendung fuer den kontrollierten QC-Textprozess von Template bis Site-Build.

 ## Aktueller Stand

 Die App kann heute:
 - AI-Templates aus QC synchronisieren und anzeigen.
 - Templates onboarden (Discovery/Manifest) und Felder fuer Mapping/Review bearbeiten.
 - Drafts anlegen, aktualisieren und im Status `draft` -> `reviewed` -> `submitted` fuehren.
 - Builds aus geprueften Daten starten sowie Job-Status pollen und Editor-URL nachladen.

 Wichtig:
 - Leadharvester-Intake und LLM-Autofill sind geplant, aber noch nicht fertig integriert.

 ## Lokaler Start

 1. Env setzen:
   - `HTTP_ADDR=:8080`
   - `DB_DRIVER=sqlite` (default)
   - `DB_URL=data/qctextbuilder.db` (default, local file)
   - `DB_DRIVER=sqlite` (Default)
   - `DB_URL=data/qctextbuilder.db` (Default)
   - `QC_BASE_URL=https://qc-api.yggdrasil.dev-mono.net/api/v1`
   - `QC_TOKEN=<your bearer token>`
 2. Start:
   - `QC_TOKEN=<bearer token>`
 2. Starten:
   - `go run ./cmd/qctextbuilder`

 ## API (Milestone 3)

 - `GET /healthz`
 - `POST /api/templates/sync`
 - `GET /api/templates`
 - `GET /api/templates/{id}`
 - `POST /api/templates/{id}/onboard`
 - `PUT /api/templates/{id}/fields`
 - `POST /api/drafts/intake` (external prefilled draft intake)
 - `GET /api/drafts`
 - `GET /api/drafts/{id}`
 - `PUT /api/drafts/{id}`
 - `POST /api/site-builds`
 - `GET /api/site-builds/{id}`
 - `POST /api/site-builds/{id}/poll`
 - `POST /api/site-builds/{id}/fetch-editor-url`

 Draft payload (`POST /api/drafts/intake` / `PUT /api/drafts/{id}`) supports:
 - `templateId`, optional `manifestId`
 - `source`, `requestName`
 - `globalData` (same documented QC fields as build flow)
 - `fieldValues` keyed by manifest path (`section.keyName`)
 - `status` (`draft|reviewed|submitted`), `notes`

 Build request payload (`POST /api/site-builds`) expects:
 - `templateId` (AI template only, onboarded/reviewed)
 - `requestName`
 - `globalData` (`companyName`, `email`, `username` required; all other documented fields optional)
 - `fieldValues` keyed by manifest paths (`section.keyName`)

 Documented `globalData` scope supported by UI/API mapping:
 - `companyName`, `businessType`, `username`, `email`, `phone`
 - `orgNumber`, `startDate`, `mission`, `descriptionShort`, `descriptionLong`, `siteLanguage`
 - `address.line1`, `address.line2`, `address.city`, `address.region`, `address.zip`, `address.country`

 UI note:
 - `/builds/new` now supports loading an existing draft, reviewing/editing values, saving draft, and only then starting the build.
 - Template fields in `/builds/new` are grouped block-first by extracted internal block IDs (for example `m1710`, `c7886`, `r4830`) with heuristic fallback for fields without block IDs.
 - Template field settings in `/templates/{id}` include a persistent `websiteSection` mapping (`hero`, `intro`, `services`, `service_item`, `about`, `team`, `testimonials`, `cta`, `contact`, `footer`, `gallery`, `other`) used by `/builds/new` grouping with fallback when not set.
 ## Persistenz

 Default ist SQLite.
 Gespeichert werden Settings, Templates, Manifeste/Felder, Drafts und Site-Builds.

 ## Draft-/Review-Flow

 Empfohlener Ablauf:
 1. Draft anlegen oder via Intake vorbefuellen.
 2. Inhalte im UI/API pruefen und anpassen.
 3. Draft auf `reviewed` setzen.
 4. Build starten; Draft wird auf `submitted` fortgeschrieben.

 ## Weiterfuehrende Projektdoku

 Zielbild, Roadmap und Ausbaustufen stehen hier:
 - `docs/TARGET_STATE_AND_ROADMAP.md`

 Projektlokale Agentenleitplanken stehen hier:
 - `AGENTS.md`

--- a/docs/TARGET_STATE_AND_ROADMAP.md
+++ b/docs/TARGET_STATE_AND_ROADMAP.md
@@ -0,0 +1,112 @@
 # 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.
 - 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
 - [ ] 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 fuer fehlende Inhalte im Draft.
 - [ ] Draft-Autofill mit nachvollziehbarer Herkunft je Feld.
 - [ ] Stilprofil-Logik unter Beruecksichtigung von `businessType` + Tonalitaet.

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