diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6199bf7 --- /dev/null +++ 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. + diff --git a/README.md b/README.md index 4cd28c7..aa70665 100644 --- 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=` -2. Start: + - `QC_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` + diff --git a/docs/TARGET_STATE_AND_ROADMAP.md b/docs/TARGET_STATE_AND_ROADMAP.md new file mode 100644 index 0000000..3f1fad0 --- /dev/null +++ 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. +