qc-text-builder/AGENTS.md

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).
• Externer Draft-Intake-Vertrag (POST /api/drafts/intake) fuer Stammdaten plus optionalen Website-/Stilkontext.
• 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.

7) Umgang mit data/qctextbuilder.db

• data/qctextbuilder.db ist versionierbar, aber kein normales Immer-mitcommitten-Artefakt.
• Standardregel: bei normalen Code-/Doku-Commits nicht automatisch mit aufnehmen, auch wenn sich die Datei geaendert hat.
• Wenn ein reproduzierbarer lokaler Zustand bewusst festgehalten werden soll, darf die DB gezielt als eigener Snapshot-Commit aufgenommen werden.
• Snapshots der DB bewusst separat von Code-Commits halten, damit Aenderungen an Laufzeitdaten klar von Codeaenderungen getrennt bleiben.