upload

docs/CUSTOMIZATION.md

@@ -0,0 +1,83 @@
+# Anpassung des Designs
+
+## Designauswahl je Kunde
+
+Jeder Kunde erhält in seinem Render-Payload eine Theme-ID:
+
+```json
+{
+  "design": {
+    "theme": "forest-lodge",
+    "palette_mode": "theme"
+  }
+}
+```
+
+`GET /themes` liefert alle verfügbaren IDs inklusive Beschreibung, Layoutfamilie und Farbpalette.
+
+## Farbmodus
+
+- `theme`: verwendet die vorkonfigurierte Farbpalette des gewählten Designs.
+- `custom`: verwendet die Farben aus dem Kunden-Payload, behält aber Layout und Typografie des Designs.
+- Ohne Angabe: `modern` und `classic` verwenden Kundenfarben, alle benannten Varianten ihre Theme-Palette.
+
+Beispiel für kundenspezifische Farben:
+
+```json
+{
+  "design": {
+    "theme": "executive-blue",
+    "palette_mode": "custom",
+    "primary_color": "#173B67",
+    "secondary_color": "#2A6298",
+    "accent_color": "#37A6B8",
+    "text_color": "#182632",
+    "muted_color": "#6B7A86",
+    "surface_color": "#EEF3F7",
+    "font_family": "Arial"
+  }
+}
+```
+
+## Was je Kunde variieren darf
+
+- Logo
+- Theme-ID
+- optional Farbpalette
+- Kontaktzeile
+- Name und Objektbezeichnung
+
+Global möglichst unverändert lassen:
+
+- Seitenformat und Ränder
+- Abschnittsreihenfolge
+- KPI-Anzahl
+- maximale Anzahl Empfehlungen
+- Textlängen und Seitenumbrüche
+
+## Logo
+
+Am robustesten ist ein PNG oder SVG als Base64 Data URI:
+
+```text
+data:image/png;base64,iVBORw0KGgo...
+```
+
+Damit benötigt Gotenberg keinen Zugriff auf externe URLs. Große Logos vorher verkleinern.
+
+## Eine neue Farbvariante anlegen
+
+Für eine reine Farbvariante ist kein neues HTML nötig. In `renderer/app/theme_catalog.py` einen weiteren Eintrag mit vorhandener `layout`-Familie ergänzen und die Theme-ID im Enum von `renderer/app/schemas/report-payload.schema.json` eintragen.
+
+## Eine neue Layoutfamilie anlegen
+
+1. Ordner `renderer/app/templates/<layout>` erstellen.
+2. `report.html.j2` anlegen; optional ein eigenes `footer.html.j2`.
+3. In `renderer/app/theme_catalog.py` ein Theme mit dieser `layout`-ID registrieren.
+4. Theme-ID im Report-Schema ergänzen.
+5. `pytest -q` ausführen.
+6. Mit `python scripts/render-theme-gallery.py` visuell prüfen.
+
+## Textlängen
+
+Die maximalen Textlängen werden im Claude-Schema begrenzt. Inhalte sollten gekürzt werden, statt Schriftgrößen immer weiter zu reduzieren.

docs/DATA_MODEL.md

@@ -0,0 +1,27 @@
+# Datenmodell
+
+Der komplette Render-Payload besteht aus sieben Bereichen:
+
+- `report`: Zeitraum, Erzeugungszeit und Versionsnummern
+- `customer`: feste Kundendaten und Logo
+- `design`: Theme und Branding-Tokens
+- `metrics`: aktuelle Kennzahlen und Monatsvergleich
+- `trends`: zwei bis zwoelf historische Monatswerte
+- `content`: ausschliesslich der von Claude erzeugte redaktionelle Inhalt
+- `legal_note`: fester Hinweistext
+
+## Warum drei Schemas?
+
+`claude-output-anthropic.schema.json` enthaelt die von der rohen Messages API unterstuetzten Strukturregeln. Nicht direkt unterstuetzte Laengen- und Wertebeschraenkungen stehen dort als Beschreibungen.
+
+`claude-output.schema.json` prueft Claudes Ergebnis danach noch einmal streng, inklusive Textlaengen, Arraygroessen und Wertebereichen.
+
+`report-payload.schema.json` validiert das fertige Gesamtobjekt direkt vor dem Rendern. Dadurch kann Claude weder Farben noch Zahlenformate oder Layoutbereiche veraendern.
+
+## Versionsstrategie
+
+- `report_version`: fachliche Gesamtversion des Reportformats
+- `prompt_version`: Version der Claude-Anweisungen
+- `template_version`: Version des HTML/CSS-Layouts
+
+Eine Layoutaenderung erhoeht nur `template_version`. Eine veraenderte Bewertungslogik erhoeht `prompt_version`.

docs/PRODUCTION_CHECKLIST.md

@@ -0,0 +1,30 @@
+# Produktions-Checkliste
+
+## Vor dem ersten Einsatz
+
+- [ ] API-Key als Secret/Credential hinterlegt
+- [ ] Renderer und Gotenberg nicht ungeschuetzt aus dem Internet erreichbar
+- [ ] Kundendaten und Logos validiert
+- [ ] Alle Kennzahlen auf korrekte Einheiten geprueft
+- [ ] Testreports mit sehr kurzen und maximal langen Texten erzeugt
+- [ ] PDF auf A4, Seitenumbrueche und Umlaute kontrolliert
+- [ ] Dateinamen und Speicherpfade festgelegt
+- [ ] Eindeutigkeit pro Kunde, Monat und Reportversion in der DB aktiviert
+
+## Bei jedem Reportlauf
+
+- [ ] Eingabedaten vollstaendig
+- [ ] Claude-Response erfolgreich
+- [ ] JSON-Parsing und Schema-Validierung erfolgreich
+- [ ] Renderer liefert HTTP 200 und `application/pdf`
+- [ ] PDF ist groesser als 10 KB
+- [ ] Reportlauf mit Modell-, Prompt- und Templateversion protokolliert
+- [ ] Versand erst nach erfolgreicher Speicherung
+
+## Nach Designaenderungen
+
+- [ ] Beispielreport beider Themes rendern
+- [ ] PDF visuell auf jeder Seite pruefen
+- [ ] keine abgeschnittenen Karten oder Tabellenzeilen
+- [ ] Footer hat ausreichend Abstand
+- [ ] lange Kundennamen und lange Empfehlungen getestet