Communitygithub.com

AxelBeary/Inkglean

Architekturmuster für mehrfach genutzte Provisions- und Marktplatzplattformen – vorlagenbasierte Benutzerseiten, einbettbare Widgets und individuelles Seitenhosting. Beschreibt das dreischichtige Seitensystem für gehostete Vorlagen und externe Integration.

Was ist Inkglean?

Dieses Skill beschreibt eine dreischichtige Architektur für Provisionsplattformen (z.B. für Künstler, Creatorn oder Freelancer), die sowohl gehostete Vorlagen als auch externe Integrationen ermöglicht. Es unterstützt Entwicklerteams bei der Erstellung skalierbarer Multi-Tenant-Systeme mit individuellen Benutzerseiten – von einfachen Vorlagen (Layer 1) über einbettbare Widgets (Layer 2) bis hin zu vollständig eigenem Seitenhosting (Layer 3). Der Fokus liegt auf einer orthogonalen Aufteilung von Layouts und Farbpaletten, um die Anzahl der Vorlagen zu reduzieren und gleichzeitig viele visuelle Variationen zu ermöglichen. Das Skill enthält detaillierte Implementierungsmuster für Komponenten, Composables, Drag-and-Drop, Bestellformulare und CSS-Optimierungen, die in realen Projekten wie Inkglean erprobt sind. Es richtet sich an Entwickler, die flexible und wartbare Architekturen für Creator-Plattformen oder Marktplätze entwerfen.

Funktioniert mit~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/AxelBeary/Inkglean/tree/HEAD/docs/comms/archive/skills/software-development/commission-platform-architecture

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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:

AchseWer wähltBeispieleSteuert
Layout (Struktur)Künstlerclassic (zweispaltiges Studio) / gallery (Vollbildmuseum) / folio (einseitige Landingpage) / atelier (buchartiges, warmes Studio)Öffnungsbehandlung, Spaltenlogik, Galerieform, Navigation
Palette (Stimmung)Künstlerpaper / ink / dusk / moss – jede mit hellen UND dunklen Varianten definiertHintergrund-/Oberflächen-/Textfarben der Seite (--pal-* CSS-Variablen)
Akzent + ModusBesucher5-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ÖffnungBesonderheit
galleryKunstwerk im Vollbild, Name als kleine EckenplaketteRedaktionelle Groß-/Kleinalternierende Galerie, Hover-Zoom, Klick-Vorschau
classicSignaturwerk-Banner, Name über der Kunst platziertDesktop zweispaltig, klebrige Info-Karte mit stets sichtbarem Commission-CTA
folioGeteilter Bildschirm: Text links, gestapelte Kunstwerke rechtsScrollverfolgung mit Navigationshervorhebung, mobiler Hamburger + klebriger unterer CTA
atelierWarme 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-BoardR55 Stufen-Beispielbild
ÜberschreibbestätigungNein (altes Bild bleibt in der Bestellgalerie)Ja – ElMessageBox.confirm (altes Bild verloren)
GrundFokus ersetzen ≠ Bild löschenBeispiel ü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))) ersetzt el-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 CSS receipt-* Namensraum in templates.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 ruft submit() 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]

Verwandte Skills