first commit

2026-06-24 14:31:42 +00:00
parent 77f946a553
commit 22b05a7a1b
10 changed files with 456 additions and 0 deletions
@@ -0,0 +1,124 @@
+# Monthly Report Kit
+
+Ein reproduzierbares Starterpaket fuer monatliche Kundenreports mit:
+
+- Claude Structured Outputs fuer valide, schemakonforme Inhalte
+- fester HTML/CSS-Vorlage statt KI-generiertem Layout
+- 28 austauschbaren Designs in 10 Layoutfamilien
+- Python/FastAPI-Render-Service
+- Gotenberg fuer die PDF-Erzeugung mit Chromium
+- JSON-Schema-Validierung vor jedem Rendern
+- n8n-Bausteinen und einem importierbaren Beispielworkflow
+- Beispielreport, Prompt-Vorlagen und PostgreSQL-Grundstruktur
+
+## Architektur
+
+```text
+PostgreSQL / andere Datenquelle
+        |
+        v
+n8n normalisiert Monatsdaten
+        |
+        v
+Claude Messages API + output_config.format
+        |
+        v
+validiertes Claude-JSON
+        |
+        v
+Report-Payload aus Kunde + Kennzahlen + Claude-Inhalt
+        |
+        v
+report-renderer -> HTML/Jinja2 -> Gotenberg -> PDF
+```
+
+Claude entscheidet nur, **was** im Report steht. Das Template entscheidet, **wie** es aussieht.
+
+## Schnellstart
+
+```bash
+cp .env.example .env
+docker compose up -d --build
+curl http://localhost:8080/health
+```
+
+Beispielreport erzeugen:
+
+```bash
+curl \
+  --request POST http://localhost:8080/render \
+  --header 'Content-Type: application/json' \
+  --data @examples/sample-report.json \
+  --output output/monatsreport-beispiel.pdf
+```
+
+HTML-Vorschau im Browser:
+
+```bash
+curl \
+  --request POST http://localhost:8080/preview/html \
+  --header 'Content-Type: application/json' \
+  --data @examples/sample-report.json \
+  --output output/preview.html
+```
+
+## Wichtigste Dateien
+
+| Datei | Zweck |
+|---|---|
+| `renderer/app/theme_catalog.py` | Katalog aller 28 Designs und Farbpaletten |
+| `renderer/app/templates/` | 10 wiederverwendbare Layoutfamilien |
+| `scripts/render-theme-gallery.py` | erzeugt Vorschauen und einen PDF-Designkatalog |
+| `renderer/app/schemas/claude-output-anthropic.schema.json` | API-kompatibles Structured-Output-Schema |
+| `renderer/app/schemas/claude-output.schema.json` | strenge Nachvalidierung mit Textlaengen und Grenzen |
+| `renderer/app/schemas/report-payload.schema.json` | kompletter Render-Payload |
+| `prompts/system-prompt.txt` | feste Claude-Rolle und Regeln |
+| `prompts/user-prompt-template.txt` | dynamischer Auftrag je Kunde/Monat |
+| `n8n/workflow-template.json` | importierbarer Workflow-Startpunkt |
+| `n8n/postgres-schema.sql` | Tabellen fuer Konfiguration und Reportlaeufe |
+
+## Design auswählen
+
+Alle verfügbaren Designs liefert der Renderer über `GET /themes`. Im Payload genügt die Theme-ID:
+
+```json
+{
+  "design": {
+    "theme": "executive-blue",
+    "palette_mode": "theme"
+  }
+}
+```
+
+`palette_mode: "theme"` verwendet die fest definierte Farbwelt des Designs. Mit `palette_mode: "custom"` bleiben Layout und Typografie erhalten, während die im Payload gelieferten Kundenfarben verwendet werden. Die flexiblen Varianten `modern` und `classic` verwenden standardmäßig Kundenfarben.
+
+### Enthaltene Layoutfamilien
+
+| Familie | Charakter | Designs |
+|---|---|---|
+| Modern | Karten, Verlaufskopf, weich | `modern`, `soft-lavender`, `midnight-gold` |
+| Classic | Serifenschrift, feine Linien | `classic` |
+| Minimal | viel Weißraum, ruhige Flächen | `nordic-light`, `nordic-night`, `alpine-sage` |
+| Dashboard | Management-orientierte KPI-Flächen | `executive-blue`, `executive-charcoal`, `executive-burgundy` |
+| Sidebar | markante Seitenleiste | `ocean-breeze`, `forest-lodge`, `sunset-coral` |
+| Editorial | magazinartige Serifengestaltung | `editorial-ivory`, `editorial-ink`, `editorial-rose` |
+| Magazine | große Typografie, asymmetrische Module | `magazine-cobalt`, `magazine-citrus`, `magazine-plum` |
+| Ledger | dicht, tabellarisch, zahlenorientiert | `ledger-green`, `ledger-blue`, `ledger-sepia` |
+| Split | geteilte Titel- und Inhaltsflächen | `split-teal`, `split-violet`, `split-terracotta` |
+| Poster | plakativ, sehr große Kennzahlen | `poster-red`, `poster-yellow`, `poster-mono` |
+
+Den vollständigen visuellen Katalog findest du nach dem Entpacken unter `output/theme-catalog/theme-gallery.pdf`. Neu erzeugen kannst du ihn mit:
+
+```bash
+python scripts/render-theme-gallery.py
+```
+
+## Produktionshinweise
+
+- API-Key niemals in Workflows exportieren oder im Repository speichern.
+- `report_version`, `prompt_version` und `template_version` je Report sichern.
+- Vor dem Versand immer Payload- und PDF-Pruefungen ausfuehren.
+- Wiederholungen ueber einen eindeutigen Schluessel aus `customer_id + period` verhindern.
+- Externe Bild-URLs vermeiden. Logos als Base64 Data URI uebergeben.
+
+Weitere Hinweise stehen unter `docs/`.