Architektur für Provisionsplattformen
Multi-Tenant-Provisionsplattformen, bei denen jeder Benutzer (Künstler, Creator, Freelancer) eine öffentlich zugängliche Seite mit Bestellmöglichkeiten hat. Dieses Skill beschreibt die Architekturentscheidungen, um sowohl gehostete Vorlagen als auch die Integration in eigene Websites von Creatorn zu ermöglichen.
Dreischichtiges Seitensystem
Das zentrale Architekturmuster: Unterstützung für Creator auf drei Ebenen technischer Fähigkeiten und Unabhängigkeit.
┌─────────────────────────────────────────────────┐
│ Layer 3: Individuelles Seitenhosting │
│ Eigenes HTML/CSS/JS hochladen → ausgeliefert │
│ unter /artist/alice (statische Dateien aus uploads/)│
├─────────────────────────────────────────────────┤
│ Layer 2: Einbettbares Widget │
│ Ein <script>-Tag auf der eigenen Website │
│ → "Commission bestellen"-Button + Bestellformular │
├─────────────────────────────────────────────────┤
│ Layer 1: Integrierte Vorlagen │
│ Layout-Variante wählen, kein Setup │
│ → Vollständige Seite unter /artist/alice │
└─────────────────────────────────────────────────┘
Layer 1: Integrierte Vorlagen
Für wen: Creator, die keine eigene Website haben oder keine pflegen möchten.
Umsetzung: Vue-Komponenten mit CSS-Variablen-Theming.
// Route: /artist/:subdomain
routes.get('/artist/:subdomain', async (req, reply) => {
const artist = await artistService.getBySubdomain(req.params.subdomain)
if (artist.page_type === 'default') {
// Integrierte Vue-SPA (oder SSR) rendern
// page_theme-Feld steuert die Vorlagenvariante
return reply.sendFile('index.html')
}
// ... Weiterleitung zu Layer 2-3, anderswo behandelt
})
Vorlage = Layout × Palette (orthogonale Achsen) – die entscheidende Modellierungsentscheidung. Wenn sich zwei „Vorlagen” hauptsächlich in der Farbe unterscheiden, sind es KEINE zwei Vorlagen – sie sind ein Layout in zwei Farbgebungen. Die Bündelung von Farbe in die Vorlagendimension lässt die Anzahl der Vorlagen mit doppeltem Strukturcode explodieren (Benutzer werden kritisieren: „das sieht aus wie dieselbe Seite in anderen Farben”). In unabhängige Achsen aufteilen, die der Künstler getrennt wählt:
| Achse | Wer wählt | Beispiele | Steuert |
|---|---|---|---|
| Layout (Struktur) | Künstler | classic (zweispaltiges Studio) / gallery (Vollbildmuseum) / folio (einseitige Landingpage) / atelier (buchartiges, warmes Studio) | Öffnungsbehandlung, Spaltenlogik, Galerieform, Navigation |
| Palette (Stimmung) | Künstler | paper / ink / dusk / moss – jede mit hellen UND dunklen Varianten definiert | Hintergrund-/Oberflächen-/Textfarben der Seite (--pal-* CSS-Variablen) |
| Akzent + Modus | Besucher | 5-Farben-Akzentwähler + Hell-/Dunkel-Präferenz | --color-primary, html.dark |
Wichtige Regeln:
- Eine Palette ist eine Stimmung mit hellen+dunklen Varianten, niemals „das dunkle Thema”. Der Künstler wählt
ink; Besucher im Hellmodus sehen blasses Grau, Besucher im Dunkelmodus sehen Anthrazit – die Stimmung bleibt konsistent, die Helligkeit folgt dem Besucher. - Die Akzentfarbe (Buttons/Links/Hervorhebungen) verwendet immer die Besuchervariablen (
--color-primary), niemals Palettenvariablen – die beiden Systeme bleiben orthogonal und funktionieren weiterhin. - 4 Layouts × 4 Paletten = 16 verschiedene Looks aus 8 Definitionen.
- Layouts müssen sich strukturell unterscheiden (anderer Seitenanfang, andere Spaltenlogik) oder sollten zu einem Layout zusammengeführt werden.
Bewährte Layout-Archetypen – jedes öffnet mit dem auffälligsten Asset des Künstlers (seiner Kunst), nicht mit einem generischen zentrierten Namen+Bio+Buttons-Hero:
| Layout | Öffnung | Besonderheit |
|---|---|---|
| gallery | Kunstwerk im Vollbild, Name als kleine Eckenplakette | Redaktionelle Groß-/Kleinalternierende Galerie, Hover-Zoom, Klick-Vorschau |
| classic | Signaturwerk-Banner, Name über der Kunst platziert | Desktop zweispaltig, klebrige Info-Karte mit stets sichtbarem Commission-CTA |
| folio | Geteilter Bildschirm: Text links, gestapelte Kunstwerke rechts | Scrollverfolgung mit Navigationshervorhebung, mobiler Hamburger + klebriger unterer CTA |
| atelier | Warme Buchoptik, Serifenschrift (Noto Serif SC) | Papierstruktur-Hintergrund, redaktionelle Ränder, großzügiger Weißraum, kunstorientiert mit literarischer Stimmung |
Bewährte Shared-Kit-Architektur: Vorlagen lesen niemals direkt Backend-Feldnamen – ein Adapter-Composable (useArtistData(props)) liefert imgUrl(), statusText() (i18n), socialLinks, heroArtwork; wiederverwendbare Tpl*-Komponenten nehmen Varianten über Props entgegen (TplHero variant="banner|fullscreen|split", TplGallery layout="grid|editorial|masonry") mit Slots als Erweiterungspunkten (#addons im Stufengitter). Siehe references/template-system.md für das vollständige Muster inklusive Async-Component-Timing-Fixes und Legacy-ID-Mapping.
Vom Künstler festgelegte Akzentfarb-Überschreibung (R49-Muster): Der Künstler kann eine dauerhafte Akzentfarbe setzen (5-Farben-Whitelist, gespeichert als artists.accent_color TEXT), die die Besucher-Wahl des ThemePickers auf seiner öffentlichen Seite überschreibt. Umsetzung in ArtistHome.vue:
const ACCENT_INDEX = { '#34dbcb': '1', '#34c2db': '2', '#3498db': '3', '#346edb': '4', '#3445db': '5' }
const accentOverride = computed(() => {
const raw = previewAccent.value || artist.value?.accentColor
return raw ? (ACCENT_INDEX[String(raw).toLowerCase()] || null) : null
})
// watch(immediate) + onUnmounted: speichern/wiederherstellen document.documentElement.dataset.accent
Wichtige Entscheidungen: (1) Globales data-accent-Attribut – KEINE pro-Vorlage CSS-Variablenänderungen nötig (theme.css hat bereits data-accent="1"~"5" Selektoren mit hellen+dunklen Varianten). Akzentunterstützung für alle 4 Vorlagen hinzuzufügen = null Vorlagendateiänderungen. (2) Der Akzent des Künstlers hat Vorrang vor dem ThemePicker des Besuchers auf dessen Seite; die Besucherwahl wird bei onUnmounted wiederhergestellt. (3) Das Backend validiert gegen eine 5-Farben-Whitelist + null (zurücksetzen); toLowerCase()-Normalisierung beim Schreiben. (4) Einstellungen-UI: runde Swatch-Buttons (32px) mit ✓-Haken bei aktiver Auswahl + "Standard"-Löschbutton. NICHT el-color-picker (freie Farbwahl würde die Whitelist brechen). (5) C61-Entscheidung: Der Akzent beeinflusst nur kundenseitige Seiten, NICHT das Künstler-Dashboard.
Vorschaumodus über URL-Parameter (R50-Muster): Der Button „Vorschau Startseite” in den Einstellungen öffnet /artist/:subdomain?_tpl=X&_pal=Y&_accent=Z in einem neuen Fenster. ArtistHome.vue liest route.query._tpl/_pal/_accent als Rendering-Überschreibungen (schreibt niemals in die Datenebene). Ein klebriger Warnbanner („Vorschaumodus — Änderungen nicht gespeichert”) erscheint, wenn ein Vorschau-Parameter vorhanden ist. Die Computed-Eigenschaften für Vorlage/Palette/Akzent fallen durch: previewParam || artist.field || default. Sicher für öffentlichen Zugriff – Vorschau-Parameter beeinflussen nur das Rendering, alle Daten kommen von der öffentlichen API.
Aktivitätszeitleiste ersetzt flache Notizliste (R40-Muster): Beim Zusammenführen von Statusänderungsdatensätzen (System-Notizen) und Künstlernotizen in einer einzigen chronologischen Ansicht wird el-timeline mit Typ/Hohl-Unterscheidung verwendet:
<el-timeline-item :type="note.created_by === 'system' ? 'info' : (note.image_path ? 'success' : 'primary')"
:hollow="note.created_by === 'system'" :timestamp="formatDate(note.created_at)" placement="top">
Typ-Anzeigen: 🔄 Statusänderung / 📝 Notiz / 🖼 Notiz mit Bild. System-Notizen erhalten die Klasse tl-item--system (gedämpfte Farbe, kleinere Schrift). Der Löschbutton (R46) wird nur für Nicht-System-Notizen angezeigt, mit Hover-Enthüllung und @media (hover: none) Touch-Fallback. Das Eingabefeld wird an den unteren Rand der Zeitleiste verschoben. Keine Backend-Änderungen – System-Notizen existieren bereits in order_notes mit created_by='system'. Die Aktionsleiste (weiter/zurücksetzen/abbrechen) bleibt AUSSERHALB der Zeitleistenkarte.
Drag-Replace mit kontextabhängigem Bestätigungsverhalten (R53 vs R55): Zwei Drag-to-Replace-Funktionen in derselben App haben UNTERSCHIEDLICHE Bestätigungsanforderungen – NICHT vereinheitlichen:
| R53 Fokusbild im Queue-Board | R55 Stufen-Beispielbild | |
|---|---|---|
| Überschreibbestätigung | Nein (altes Bild bleibt in der Bestellgalerie) | Ja – ElMessageBox.confirm (altes Bild verloren) |
| Grund | Fokus ersetzen ≠ Bild löschen | Beispiel überschreiben = altes Bild nicht wiederherstellbar |
Umsetzung: Gemeinsame Drag-Infrastruktur (dragover.prevent/dragleave mit contains(relatedTarget)-Anti-Flimmer/drop.prevent + versteckter Datei-Input), aber die Upload-Funktion prüft if (row.example_image) { await ElMessageBox.confirm(...) } nur für R55. Beide verwenden bestehende Upload-APIs. Die el-image preview-src-list muss aus dem R53-Fokusbild entfernt werden, um zu verhindern, dass es das Klickereignis verschluckt (gleiche Falle wie R18). |
Order-Form-Composable-Extraktion (R58-1-Muster): Wenn das Bestellformular über ~400 Zeilen wächst (Daten laden + Preise + Validierung + Upload + Senden + Entwurfswiederherstellung), extrahiere die GESAMTE Geschäftslogik in ein gemeinsames Composable (useOrderForm.js). Die Seitenkomponente wird zu reinem Layout (~300 Zeilen Template + Stil, Script nur const of = useOrderForm(subdomain, formRef) + Destrukturierung). Das Composable gibt ein flaches Objekt aus Refs/Reaktiven/Methoden zurück, gruppiert nach Anliegen: Daten laden (artist, tiers, rulesContent, loading), Formularstatus + Validierungsregeln, Sendestatus (submitting, showSuccess, resultNo, submit), Referenzbilder (refFileList, handleRefUpload, handleRefRemove), Preisgestaltung (addonSelections, pricePreview, pricingExpanded, selectedTier, onTierChange) und bereinigtes Rules-HTML. Warum dies für mehrere Vorlagen wichtig ist: Wenn die Bestellseite mehrere Layoutvorlagen unterstützt (Schritt-für-Schritt, Quittungsstil, Magazinstil), ist jede Vorlage eine dünne Layout-Hülle, die das GLEICHE Composable aufruft – null Logikduplizierung. Das Composable ist der „Kern”, Vorlagen sind „Skins”. Dies ist dasselbe Adaptermuster wie useArtistData für die Startseite, angewendet auf das Bestellformular. Wichtiges Implementierungsdetail: Das Composable nimmt formRef (die el-form-Ref aus dem Template) als Parameter entgegen, weil die Validierung (formRef.value.validate()) auf das Formularelement des Templates zugreifen muss – das Composable besitzt die Logik, aber NICHT das DOM.
Schritt-für-Schritt-Bestellformular-Layout (R58-2-Muster, bewährt): Das Standard-Bestelllayout ist ein dreistufiger geführter Ablauf, vollständig auf useOrderForm() aufgebaut (null Composable-Änderungen gegenüber R58-1 – bestätigt die Extraktion):
- Schritt-Anzeige: drei nummerierte Punkte + Verbindungslinien. Aktuell: vergrößert + primär. Erledigt: ✓ + primäre Füllung. Ausstehend: grau, hohl. Mobil (≤860px): nur Punkte.
- Schritt 1 – Stufe wählen: Responsives Kartenraster (
repeat(auto-fill, minmax(240px, 1fr))) ersetztel-select. Ausgewählt:--ease-bounceÜbergang + rotierender Stempel ✓ (@keyframes tier-stamp-in: Skala 0→1,2→1, Rotation -15°→0°). R14 progressive Offenlegung bleibt innerhalb von Schritt 1. - Schritt 2 – Beschreiben + hochladen: Textarea + Inspiration-Tags (R58-4: hartcodierte Standard-Chips, Klick fügt mit intelligentem Komma + 2000-Zeichen-Abkürzung hinzu) + Referenz-Upload (Datei + Einfügen unverändert).
- Schritt 3 – Kontakt: QQ + Name + Zustimmung zu den Regeln.
- Klebrige Zusammenfassungskarte: Breitbild-rechte Spalte (280px klebrig), Echtzeit-Stufe + Aufschlüsselung + Gesamtsumme + Raten. Mobil: unten im aktiven Schritt.
- Quittungsbestätigung (R58-3): Senden → validieren → Café-Quittung
el-dialog(an body übertragen, globales CSSreceipt-*Namensraum intemplates.css). Papier#fdfbf5, Courier-mono, gezackte Kanten (repeating-conic-gradient), gestrichelte Trennlinien, Barcode-Dekoration, Raten-Chips. Festes helles Thema (Papiermetapher). Abbrechen kehrt zu Schritt 3 zurück; Bestätigen ruftsubmit()auf. - Bestellinfo kopieren (R58-5): Erfolgsdialog „Bestellinfo kopieren” → mehrzeilige Zwischenablage (Bestellnr + Stufe + Addons + Gesamtsumme).
- Schrittnavigation: „Weiter” validiert den aktuellen Schritt vor dem Vorrücken; „Zurück” immer erlaubt; kein Überspringen.
Multi-Vorlagen-Bestellseite (R58-Architektur): Die Bestellseite unterstützt vom Künstler wählbare Layoutvorlagen, unabhängig von der Startseitenvorlage. Backend (bewährt, Migration v16): artists.order_template_id TEXT DEFAULT 'default' – Service-Layer-Whitelist-Validierung (ORDER_TEMPLATES = ['default'], Array erweitern bei Hinzufügen von Vorlagen). GET /api/artists/:subdomain gibt orderTemplateId: artist.order_template_id || 'default' zurück. PUT /api/artist/profile akzeptiert orderTemplateId (über keyMap auf order_template_id abgebildet). Ungültige Werte werfen INVALID_ORDER_TEMPLATE (409). Leerer String fällt auf 'default' zurück. Frontend: Die Künstler-Einstellungsseite zeigt einen kartenbasierten Vorlagenwähler (gleiches UI-Muster wie die Startseitenvorlagenauswahl). Client-seitiges Routing: OrderForm.vue liest artist.orderTemplateId und rendert die entsprechende Layout-Komponente über <component :is="..."> oder eine Vorlagen-Registry-Map. Alle Layout-Komponenten teilen useOrderForm() – sie unterscheiden sich NUR in der visuellen Anordnung (Schrittindikatoren, Kartenlayout, Bestätigungsdialogstil). Eine neue Bestellvorlage hinzufügen = eine neue .vue-Datei mit einer Layout-Hülle + ein Eintrag im Backend-Whitelist-Array, null Logikänderungen. Vorschau: Wiederverwendung des _tpl-URL-Parametermechanismus der Startseitenvorschau.
QQ-Kontaktmuster (R58-6): Zwei Möglichkeiten für QQ-Kontakt: „Zu QQ springen” (window.open('tencent://message/?uin=' + encodeURIComponent(qq), '_self')) + „QQ kopieren” (navigator.clipboard.writeText(qq) mit Toast). Zwischenablage-Fallback: bei Fehler (Berechtigung verweigert, nicht-HTTPS) ElMessage.warning(qq) anzeigen – die QQ-Nummer selbst als Warnmeldung, damit der Benutzer manuell aus dem Toast kopieren kann. Angewandt an zwei Stellen: clientseitiger Erfolgsdialog (Kontakt-QQ des Künstlers) und künstlerseitiges Bestelldetail (QQ des Kunden). i18n: separate Schlüssel pro Kontext (orderForm.jumpQq vs orderDetail.jumpQq), da die Toast-Nachricht unterschiedlich ist („QQ-Nummer kopiert” vs „Kunden-QQ kopiert”).
CSS-Handwerks-Upgrade-Muster (v0.16 batch1, bewährt):
- Globales Bounce-Easing:
--ease-bounce: cubic-bezier(.34, 1.56, .64, 1)in:root. Nur für Transform-/Box-Shadow-Übergänge verwenden (niemals Opacity – kann 1,0 nicht überschreiten). Fallback im konsumierenden Code:var(--ease-bounce, cubic-bezier(0.22, 1, 0.36, 1)). - Button-Drei-Zustands-Physik-Modell:
.el-button:hover:not(:disabled):not(.is-loading) { transform: translateY(-3px); box-shadow: tiefer }+:active { transform: translateY(-1px) scale(0.98) }. Die:not()-Ausschlüsse verhindern Animationen bei deaktivierten/loadenden Buttons. - **
clamp()-Flüssig
…
[Gekürzt für Übersetzung]