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