125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 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/`.
|