Referenzen-Redesign: Analyse und Plan (2026-07-04)

Problemstellung (Nutzerfeedback)

1. Zwei Funktionalitäten sind im Referenzen-Bereich vermischt:
   • Bestandsreferenzen hochladen, damit die Referenz-Fit-Analyse sie nutzen kann.
   • Projektdokumentation hochladen und daraus mit einem Template eine neue Referenz erstellen.
2. Beide laufen über nahezu dieselbe UI. Nutzer glauben deshalb häufig, sie müssten ihre fertigen Referenzen als "Projektdokumente" hochladen und daraus erst eine neue Referenz erstellen, damit die Analyse sie kennt.
3. Vergabestellen stellen harte Layout-Anforderungen an Referenzblätter (meist max. 2 Seiten, mit Bildern, z. B. Seite 1: zwei Bilder nebeneinander + Kurzbeschreibung; Seite 2: Detailbeschreibung + Bilder groß oder im Raster). Das Tool kann solche Layouts nicht rendern; Kunden weichen auf Design-Tools aus.

Ist-Zustand (Code-Analyse)

Datenmodell

• reference (src/lib/server/db/reference-schema.ts): generierte/angelegte Referenzen; content (Markdown), status (draft|processing|completed|failed), lifecycleStatus, useInAnalysis-Toggle. Keine Unterscheidung der Herkunft.
• referenceProject + referenceProjectDocument + referenceProjectImage (reference-project-schema.ts): Projekt-Container mit Dokumenten (extrahierter Text + Binärdaten in DB, storageKey fuer Blob-Storage ungenutzt) und Bildern (KI-Beschreibung, Untertitel, Fokuspunkte focusX/Y).
• referenceTemplate (reference-template-schema.ts): Markdown mit Direktiven ::: text-prompt / ::: image-prompt; pdfSettings (JSON) nur fuer Header/Footer.
• referenceDocumentUsage: Junction Referenz ↔ verwendete Dokumente.

Flows

• Drei Erstellungswege in dieselbe Tabelle: Bulk-Upload (/api/v1/protected/references/bulk-upload, Projekt je Ordner + Referenz je Datei), KI-Generierung (Job REFERENCE_CREATION → template-reference-generator.ts), manuelle Erstellung.
• Analyse (Referenz-Fit): src/lib/server/jobs/tender/analysis-processor.ts liest ausschliesslich reference.content aller Referenzen mit useInAnalysis = true.
• PDF-Export: client-seitig via pdfmake (src/lib/components/markdown-editor/export-utils.ts) aus Markdown — keine festen Layouts moeglich.
• Mitarbeiterprofile (empProfile, Personal-Match-Analyse) werden ueber denselben UI-Bereich importiert.

Kernprobleme

• Herkunft der Referenz nicht unterscheidbar (uploaded vs. generiert vs. manuell) → UI kann die Flows nicht trennen.
• Bestandsreferenz-Upload erfordert den Umweg Projekt → Dokumente → "Referenz erstellen".
• Freies Markdown als einziges Inhaltsformat verhindert layouttreue Templates.
• pdfmake kann keine pixelgenauen 2-Seiten-Layouts mit Bildrastern.

Technologie-Entscheidung PDF (Recherche 2026)

Verglichen: Chromium (Playwright/Puppeteer) + CSS Paged Media, paged.js, Gotenberg, WeasyPrint, Typst, @react-pdf/renderer, pdfmake, pdf-lib, Satori, LaTeX, carbone/docxtemplater+LibreOffice.

Empfehlung: HTML/CSS-Templates mit festen A4-Seiten als Svelte-Komponenten, gedruckt von Chromium via Gotenberg-Sidecar (MIT, stateless HTTP, eigener Coolify-Service).

Begruendung:

• Nur Chromium rendert Vorschau UND PDF mit derselben Engine → echtes "Vorschau = PDF".
• Feste 2-Seiten-Layouts sind fuer Chromium der einfache Fall: zwei absolut dimensionierte A4-Container (210mm × 297mm, @page { size: A4; margin: 0 }, break-after: page, overflow: hidden) — Inhalt kann nicht auf Seite 3 laufen.
• Templates bleiben im Stack (Svelte 5 + Tailwind, PR-reviewbar, testbar); Org-Theming via CSS Custom Properties.
• Gotenberg haelt das App-Image schlank; PDF/A moeglich, horizontal skalierbar. Alternative im App-Container: Playwright (~1,5 GB Image).

Ueberlauf-Strategie (drei Ebenen): Design-Time (feste Slot-Hoehen, line-clamp), Preview-Time (scrollHeight > clientHeight → Indikator + KI-Kuerzung mit Zeichenbudget je Slot), Export-Time (Seitenzahl-Assertion via pdfjs-dist, Fehler statt 3-seitigem PDF).

Ops-Hinweise: Fonts als WOFF2 selbst hosten + document.fonts.ready abwarten; Masse in mm/pt; preferCssPageSize; print-color-adjust: exact; Bild-Mindestaufloesung je Slot (300 DPI: Slotbreite_mm / 25,4 × 300 px); JPEG fuer Fotos.

Fallback: Typst (winziger Footprint, Seitenzahl zur Compile-Zeit pruefbar, exakte Browser-Vorschau via typst.ts/WASM) — falls der Chromium-Sidecar operativ zu teuer wird.

Verworfen: WeasyPrint (andere Engine als Vorschau), @react-pdf/renderer (Bild-Bugs, React-fremd), pdfmake (kein Fixlayout), carbone CE (Lizenz verbietet Hosted-Doc-Generation), Canva/Figma-APIs (Enterprise-Zwang bzw. keine Datenbefuellung).

Markt: Wettbewerber (ERCAS, Tendermeister) werben bereits mit einheitlich gestalteten Referenzblaettern per Klick — das Feature ist im Segment Table Stakes.

Zielbild

• Referenz-Bibliothek (/references): alle analyse-relevanten Referenzen der Organisation (hochgeladen, generiert, manuell) mit Quelle-Badge, useInAnalysis-Toggle, Lifecycle. Primaer-CTA: "Referenzen hochladen" — je Datei sofort eine analysebereite Referenz, ohne Projekt.
• Referenz-Erstellung / Studio (eigener Bereich): Referenzprojekte (Dokumente + Bilder), Templates, KI-Generierung → strukturierte Inhalte → Layout-Vorschau → PDF-Export. Ergebnis erscheint in der Bibliothek.
• Layout-System: strukturiertes Inhaltsmodell (Felder + Bild-Slots), Svelte-Print-Templates mit festen A4-Seiten, Gotenberg-Rendering mit Seitenzahl-Garantie, Live-Vorschau mit Ueberlauf-Kontrolle.
• Mitarbeiterprofile ziehen in einen eigenen Bereich.

Plan (Epic references-redesign)

Phase 1 — Entflechtung:

1. Datenmodell: reference.source (uploaded|generated|manual), projectId nullable, Backfill.
2. Direkter Upload-Flow fuer Bestandsreferenzen (analysebereit ohne Umweg).
3. IA-Split: Bibliothek vs. Studio, Navigation, Redirects, Copy (de/en), Onboarding.
4. Mitarbeiterprofile herausloesen.

Phase 2 — Layout-PDF: 5. Strukturiertes Referenz-Inhaltsmodell (jsonb + Zod, Generator auf structured output, Analyse-Rendering aus Struktur). 6. Gotenberg-Sidecar + Server-Export-Endpoint mit Seitenzahl-Assertion. 7. Layout-Template-System (feste A4-Svelte-Templates, Start-Layouts, Theming, Fokuspunkte). 8. Editor: Live-Vorschau, Ueberlauf-Kontrolle, KI-Kuerzung, Export-Umstellung (pdfmake abloesen).

Offene Fragen (Question-Issues):

• Q1: Konkrete Layout-Varianten + Pflichtfelder — 2-3 echte Kunden-Referenzblaetter einsammeln.
• Q2: KI-Ueberfuehrung hochgeladener Bestandsreferenzen ins strukturierte Modell ("Veredelung")?

Beruehrungspunkte: #970 (MCP-Read-Tools fuer Referenzen), #942 (Analysis Evals — References-Extraktion).

Nachtrag (2026-07-04, Feedback Product Owner)

Korrektur zur Ist-Analyse: Ein direkter Referenz-Upload existiert bereits — der Bulk-Upload erzeugt automatisch Referenzprojekte und legt die Referenz dort als Plain Text ab. Die tatsaechlichen Probleme des Imports sind:

1. UX: Der Flow ist fuer Nutzer schwer verstaendlich (wo starten, was hochladen, was passiert danach).
2. Starre Ordner-Konvention: Der Import erwartet eine bestimmte Ordnerstruktur (Projekt je Ordner); reale Ablagen sind anders gewachsen.
3. Excel fehlt: Referenzlisten liegen oft als Excel vor (Referenz je Zeile, Angaben in Spalten) — dafuer gibt es keinen Importpfad.

Issue #978 wurde entsprechend umgeschrieben (gefuehrter Import-Wizard mit Review-Schritt, freie Ordnerstrukturen, Excel-Spalten-Mapping).

Weitere Beschluesse:

• Mockups fuer UX-Issues (#978 Import-Flow, #979 IA-Split, #984 Editor-Vorschau): statische HTML-Mockups + Screenshots via impeccable-Skill, abgelegt unter docs/requirements-and-tasks/mockups/2026-07-04-referenzen/, in den Issues verlinkt — Diskussionsgrundlage fuer das Team vor der Implementierung.
• Spikes fuer tech-lastige Teile (vor Phase 2): #988 (PDF-Pipeline: 2-Seiten-Template via Gotenberg — Paritaet, Seitenzahl-Garantie, Ueberlauf-Messung) und #989 (KI-Befuellung strukturierter Felder mit Zeichenbudgets).

Nachtrag 2 (2026-07-04, Mockup-Review mit PO)

• Navigation (#979): EIN Top-Level-Punkt „Referenzen"; die Aufteilung Bibliothek/Studio erfolgt als Tabs auf der Seite selbst (nicht zwei Eintraege in der Hauptnavigation).
• Referenz-Editor (#984): WYSIWYG statt Formular-plus-Vorschau — Bearbeitung direkt in der A4-Ansicht (contenteditable auf den Print-Komponenten). AI-first: Agent-Chat-Sidebar rechts nach bestehendem App-Muster, Agent-Tools bearbeiten das strukturierte Inhaltsmodell.
• Templates (#983): Start mit wenigen kuratierten Templates; Architektur datengetrieben halten, damit Nutzer spaeter Templates komponieren koennen. Dokument-Chrome als Template-Feature: Firmenlogo auf jeder Seite, Seitenzahl, laufender Titel ab Seite 2, Bildnachweis-Zeilen.
• Reales Beispiel eingegangen (Loupz-Referenzblatt, intern — nicht im Repo): S. 1 Logo + Hero-Bild mit Bildnachweis + Kategorie-Tag + Titel + dreispaltiger Eckdaten-Block (Leistungsbilder nach AHO-Stufen, KG 200-600, BGF, BRI, Honorar, Besonderheiten); S. 2 laufender Titel + zwei Bilder + PROJEKTBESCHREIBUNG/AUFGABENSTELLUNG. Feldliste in #981 entsprechend geschaerft; Auswertung als Kommentar in #985.
• Import (#978): Machbarkeits-Abgleich ergaenzt — Schritte 1-2 client-seitig (doc-loader-Extraktion laeuft bereits im Browser, webkitRelativePath, Excel-Parsing im Client), EIN finaler POST, keine neuen Jobs oder Zwischenzustaende. Einfachheit als Designprinzip fuer UX und Implementierung.