Feiertagsverwaltung

Uebersicht

Das Feiertagsverwaltungssystem in TanStack Ship bietet eine umfassende Loesung zur Definition, Organisation und Nutzung von Feiertagen und besonderen Daten in Ihrer Marketing- und Preisinfrastruktur. Von wichtigen internationalen Feiertagen wie Weihnachten und Chinesischem Neujahr bis hin zu regionalspezifischen kulturellen Festen und benutzerdefinierten Geschaeftsdaten ermoeglicht das System automatisierte Werbeplanung und saisonale Preisanpassungen.

Als Teil der TanStack Ship Plattform integriert sich das Feiertagsmodul in das Kampagnen- und Angebotssystem fuer automatisierte Aktionen, die Preisberechnungsmaschine fuer feiertagsspezifische Tarife und das Inhaltsplanungssystem fuer zeitlich abgestimmte Marketing-Assets. Jeder Feiertag speichert lokalisierte Namen und Beschreibungen in allen unterstuetzten Sprachen und ermoeglicht so kulturell relevante Benutzererlebnisse fuer englische, chinesische und deutsche Zielgruppen.

Design-Ablauf

Das Feiertagsverwaltungssystem orchestriert den gesamten automatisierten saisonalen Aktionslebenszyklus von der Feiertagsdefinition bis zur Kampagnenaktivierung und Preisanpassung:

Kernfunktionen

Feiertagserstellung und -verwaltung

Feiertage koennen ueber das Admin-Dashboard unter /dashboard/admin/holidays erstellt und verwaltet werden:

• Mehrsprachige Benennung — Jeder Feiertag speichert Namen in allen unterstuetzten Sprachen (EN, ZH, DE) und ermoeglicht lokalisierte Anzeige und regionalspezifisches Kampagnen-Targeting
• Flexible Datumsbereiche — Unterstuetzung fuer eintaegige Feiertage (z. B. Neujahr), mehrtagige Veranstaltungen (z. B. Chinesische Neujahrswoche) und wiederkehrende jaehrliche Gedenktage
• Umfangreiche Metadaten — Optionale Beschreibungen in mehreren Sprachen, Aktivstatus-Umschalter und Laender-/Regionszuordnungsfelder
• Lebenszyklusverwaltung — Vollstaendige CRUD-Operationen zum Erstellen, Bearbeiten, Aktivieren/Deaktivieren und Loeschen von Feiertagen

Feiertagsgenerator

Der integrierte Feiertagsgenerator unter src/lib/holiday-generator.ts automatisiert die Befuellung haeufiger Feiertage:

• Internationale Feiertage — Weihnachten, Neujahr, Valentinstag, Halloween und andere weltweit anerkannte Daten
• Regionale Gedenktage — Chinesisches Neujahr, Mondfest, Qingming-Fest (China); Erntedankfest, Unabhaengigkeitstag (USA); Tag der Deutschen Einheit, Oktoberfest (Deutschland)
• Kulturelle Feste — Muttertag, Vatertag, Ostern und andere kulturell bedeutende Daten
• Benutzerdefinierte Geschaeftsdaten — Firmenjubilaeen, Produkteinfuehrungsdaten und interne Marketing-Meilensteine

Der Generator kann ueber die Admin-Oberflaeche ausgeloest werden, um Feiertage fuer alle unterstuetzten Regionen in einem einzigen Vorgang zu befuellen, mit Deduplizierungslogik zur Vermeidung doppelter Eintraege.

Kampagnen- und Preisintegration

Feiertage dienen als Ausloeser fuer automatisierte Marketing- und Preisaktionen:

• Automatisierter Kampagnenstart — Kampagnen koennen so konfiguriert werden, dass sie bei Beginn eines Feiertagsdatumsbereichs automatisch aktiviert werden. Zum Beispiel startet eine "Fruehlingsfest-Special"-Kampagne automatisch am ersten Tag des Chinesischen Neujahrs
• Feiertagsspezifische Rabatte — Die Preisberechnungsmaschine bewertet aktive Feiertage waehrend der Preisberechnung und ermoeglicht besondere Feiertagstarife ohne manuelles Eingreifen
• Saisonale Inhaltsplanung — Blogbeitraege, Landingpages und E-Mail-Kampagnen koennen zeitlich um wichtige Feiertage herum veroefentlicht werden, um die Marketingausrichtung auf kulturelle Ereignisse sicherzustellen

Design-Philosophie

Datengesteuerte Planung

Feiertage dienen als zentrale Planungsprimitiven fuer den gesamten Marketing-Automatisierungs-Stack. Anstatt saisonale Aktionen in die Geschaeftslogik hart zu codieren, behandelt das System Feiertage als deklarative Daten — Administratoren definieren einen Feiertag einmal mit seinem Datumsbereich und Sprachkuerzel, und alle nachgelagerten Systeme (Kampagnen-Engine, Preisberechnung, Inhaltsplaner) reagieren entsprechend. Dieser datengesteuerte Ansaatz beseitigt Redundanzen, stellt Konsistenz zwischen Modulen sicher und macht die saisonale Strategie auf einen Blick pruefbar. Im Gegensatz zur manuellen Verwaltung von Feiertagsaktionen ueber Tabellenkalkulationen oder Kalender-Tools — bei denen Daten abdriften, Kampagnen ihr Zeitfenster verpassen und Lokalisierung ein nachtraeglicher Gedanke ist — garantiert deklarative Feiertagsdaten, dass jedes Foerderungssystem am richtigen Datum mit dem richtigen Sprachkuerzel aktiviert wird, jedes Mal.

Lokalisierung als erstes Prinzip

Jeder Feiertag speichert seinen Namen und seine Beschreibung in allen unterstuetzten Sprachen (EN, ZH, DE) mit einem gracefen Rueckfall auf Englisch. Der Feiertagsaufloesungsdienst des Systems ermittelt zur Abfragezeit den passenden lokalisierten Wert basierend auf dem aktuellen Benutzer-Sprachkuerzel. Dadurch sieht ein chinesischer Benutzer "春节" waehrend ein deutscher Benutzer "Chinesisches Neujahr" fuer denselben Feiertag sieht — ohne die Feiertagsdefinition zu duplizieren oder separate Planungslogik pro Markt zu benoetigen.

Trennung von Zustaendigkeiten

Feiertagsdefinitionen sind klar von ihrer Nutzung getrennt: Das Feiertagsmodul besitzt die Daten (Erstellung, Speicherung, Aufloesung), waehrend die Kampagnen-Engine, der Preisberechner und der Inhaltsplaner das Verhalten besitzen. Diese Trennung bedeutet, dass das Hinzufuegen eines neuen Feiertags niemals Codeaenderungen erfordert — nur einen Datenbankeintrag — und jedes verbrauchende Modul unabhaengig entscheiden kann, wie es Feiertagsdaten interpretiert.

Best Practices

Regionale Feiertagsabdeckung

Pflegen Sie fuer SaaS-Plattformen, die globale Zielgruppen bedienen, einen umfassenden Feiertagskatalog, der alle Zielmaerkte abdeckt. Konzentrieren Sie sich auf Feiertage, die das Benutzerverhalten und Verkehrsmuster direkt beeinflussen — E-Commerce-Plattformen sollten Einkaufsereignisse priorisieren (Black Friday, Cyber Monday, Singles' Day), waehrend B2B-Plattformen geschaeftskulturelle Feiertage beachten sollten.

Vorzeitige Kampagnenplanung

Konfigurieren Sie Kampagnenzeitplaene so, dass sie vor den Feiertagsdaten aktiviert werden, nicht am Tag selbst. Starten Sie z. B. eine Weihnachtskampagne Anfang Dezember, nicht am 25. Dezember. Die Datumsbereichsunterstuetzung des Feiertagssystems ermoeglicht dies, indem Kampagnen auf Feiertagsstartdaten mit konfigurierbaren Vorlaufzeiten verweisen koennen.

Feiertagsgesteuerte Preisstrategie

Verwenden Sie feiertagsgesteuerte Preise sparsam und transparent. Wenden Sie Feiertagsrabatte durch sichtbare Gutscheincodes oder Werbebanner an, anstatt Preise stillschweigend anzupassen. Die Feiertagsbewertung der Preisberechnungsmaschine bietet diese Transparenz, indem jede feiertagsbedingte Preisanpassung im Transaktionsprotokoll aufgezeichnet wird.

Clientseitiges Feiertagsanzeige-Beispiel:

import { useQuery } from '@tanstack/react-query'

export function ActiveHolidayBanner() {
  const { data } = useQuery({
    queryKey: ['active-holidays'],
    queryFn: () =>
      fetch('/api/holidays/active').then((r) => r.json()) as Promise<
        Array<{ name: string; locale: string; discount: number }>
      >,
  })

  if (!data?.length) return null

  return (
    <div className="rounded-lg bg-gradient-to-r from-amber-50 to-orange-50 border border-amber-200 p-4 text-center">
      {data.map((holiday) => (
        <p key={holiday.locale} className="font-medium text-amber-800">
          🎉 {holiday.name} — {holiday.discount}% Rabatt
        </p>
      ))}
    </div>
  )
}

Mehrsprachige Konsistenz

Halten Sie konsistente Feiertagsbenennungskonventionen in allen Sprachen ein. Verwenden Sie den englischen Namen als Slug (z. B. chinese-new-year), um sprachuebergreifende referenzielle Integritaet zu gewaehrleisten, waehrend lokalisierte Anzeigenamen separat gespeichert werden. Dieser Ansatz haelt das System organisiert und liefert gleichzeitig kulturell angemessene Inhalte an jedes Publikum.

Haeufig gestellte Fragen

Wie erstelle ich einen neuen Feiertag? Navigieren Sie zu /dashboard/admin/holidays und klicken Sie auf "Feiertag hinzufuegen." Fuellen Sie den Namen in allen unterstuetzten Sprachen aus, legen Sie den Datumsbereich fest, fuegen Sie optional Beschreibungen hinzu und speichern Sie. Der Feiertag ist sofort fuer die Kampagnenplanung und Preisberechnungsmaschinenintegration verfuegbar.

Koennen Feiertage jaehrlich wiederkehren? Ja. Das System unterstuetzt jaehrliche Wiederkehr durch Datumsbereichskonfiguration. Beim Erstellen eines Feiertags koennen Sie angeben, ob es sich um ein einmaliges Ereignis oder eine jaehrliche Begehung handelt. Wiederkehrende Feiertage erscheinen automatisch jedes Jahr in aktiven Abfragen.

Wie funktioniert der Feiertagsgenerator? Der Generator unter src/lib/holiday-generator.ts enthaelt vordefinierte Listen internationaler und regionaler Feiertage. Wenn er ueber das Admin-Panel ausgeloest wird, erstellt er Datenbankdatensaetze fuer alle definierten Feiertage in den ausgewaehlten Regionen. Der Generator prueft auf vorhandene Eintraege, um Duplikate zu vermeiden, und kann erneut ausgefuehrt werden, um neue Feiertage hinzuzufuegen, wenn sie relevant werden.

Sind Feiertage laenderspezifisch? Ja. Jeder Feiertag kann einem oder mehreren Laendercodes zugeordnet werden. Wenn der Feiertagsaufloesungsdienst mit einem bestimmten Land abgefragt wird, werden nur Feiertage zurueckgegeben, die diesem Laendercode entsprechen, oder globale Feiertage (ohne Laenderbeschraenkung).

Kann ich Feiertage mit Namen nur in einigen Sprachen erstellen? Ja. Das Feiertagsnamensfeld ist ein JSON-Objekt mit Sprachschluesseln. Sie koennen Namen nur fuer die fuer Ihre Implementierung relevanten Sprachen eingeben. Das System faellt bei Bedarf auf den englischen Namen zurueck, wenn ein sprachspezifischer Name nicht verfuegbar ist.

Wie verwendet die Preisberechnungsmaschine Feiertagsdaten? Die Preisberechnungsmaschine ruft waehrend des Checkouts den Feiertagsaufloesungsdienst auf, um festzustellen, ob aktive Feiertage anwendbar sind. Wenn feiertagsspezifische Preise konfiguriert sind (z. B. 10% Rabatt waehrend Weihnachten), wendet die Maschine die Anpassung an, bevor der Gesamtbetrag festgelegt wird.

Welche Berichte sind fuer feiertagsgesteuerte Aktionen verfuegbar? Das Attributionsanalyse-Dashboard kann Konversionsdaten nach Feiertagszeitraeumen filtern, sodass Sie die Auswirkungen feiertagsspezifischer Kampagnen und Preisanpassungen auf den Gesamtumsatz und die Benutzerakquise messen koennen.

Konfiguration

Feiertage werden ueber die Admin-Oberflaeche unter /dashboard/admin/holidays verwaltet. Fuer die grundlegende Funktionalitaet sind keine zusaetzlichen Umgebungsvariablen erforderlich.

Fuer benutzerdefinierte Feiertagsdefinitionen aendern Sie src/lib/holiday-generator.ts, um Ihre eigenen Feiertagseintraege hinzuzufuegen. Der Generator liest aus vordefinierten Arrays und kann programmatisch erweitert werden.

Der Feiertagsaufloesungsdienst kann mit einem Cache-TTL in src/lib/holiday-service.ts konfiguriert werden, um Datenfrische mit Datenbanklast auszugleichen:

const CACHE_TTL_MS = 5 * 60 * 1000 // 5 Minuten

Integrationspunkte

Das Feiertagsverwaltungssystem integriert sich mit den folgenden TanStack Ship Plattformmodulen:

• Kampagnen & Angebote — Feiertage loesen automatisierte Kampagnenstarts und Angebotsaktivierungen basierend auf Datumsbereichsuebereinstimmungen aus
• Preisberechnungsmaschine — Feiertagsspezifische Rabattsaetze werden waehrend des Checkouts fuer saisonale Aktionspreise bewertet
• Inhaltsplanung — Blogbeitraege, Landingpages und E-Mail-Inhalte werden zeitlich um wichtige Feiertage herum fuer maximale Relevanz geplant
• Lokalisierung — Feiertagsnamen und -beschreibungen werden in allen unterstuetzten Sprachen fuer regionalspezifische Anzeige gespeichert
• Attributionsanalyse — Konversionsdaten koennen nach Feiertagszeitraeumen fuer die Leistungsmessung segmentiert werden