节假日管理
TanStack Ship 节假日管理系统，用于定义季节性促销、基于日期的活动、本地化排期和自动化定价触发。
概述
TanStack Ship 的节假日管理系统提供了一个全面的解决方案，用于在您的营销和定价基础设施中定义、组织和利用节假日及特殊日期。从圣诞节和春节等主要国际节庆到特定地区的文化庆典和自定义商业日期，该系统实现了自动化促销排期和季节性定价调整。
作为 TanStack Ship 平台的一部分，节假日模块与活动和优惠系统（用于自动化促销）、定价引擎（用于节假日特定费率）以及内容排期系统（用于定时营销资产）深度集成。每个节假日存储所有支持语言的本地化名称和描述，为英文、中文和德文用户提供文化相关的用户体验。
设计流程
节假日管理系统从定义节假日到活动激活和定价调整，编排整个自动化季节性促销生命周期：
核心能力
节假日创建与管理
节假日可通过管理仪表板在 /dashboard/admin/holidays 创建和管理：
- 多语言命名 — 每个节假日存储所有支持语言（EN、ZH、DE）的名称，支持本地化显示和区域特定活动定位
- 灵活日期范围 — 支持单日节假日（如元旦）、多日活动（如春节周）和每年重复的纪念日
- 丰富元数据 — 可选的多语言描述、启用状态开关和国家/地区关联字段
- 生命周期管理 — 完整的 CRUD 操作，用于创建、编辑、启用/禁用和删除节假日
节假日生成器
内置的节假日生成器位于 src/lib/holiday-generator.ts，自动填充常见节假日：
- 国际节假日 — 圣诞节、新年、情人节、万圣节等全球公认日期
- 地区性纪念日 — 春节、中秋节、清明节（中国）；感恩节、独立日（美国）；德国统一日、慕尼黑啤酒节（德国）
- 文化庆典 — 母亲节、父亲节、复活节等文化重要日期
- 自定义商业日期 — 公司周年纪念、产品发布日、内部营销里程碑
生成器可从管理界面触发，一次性为所有支持地区填充节假日，并配有去重逻辑防止重复条目。
活动和定价集成
节假日作为自动化营销和定价操作的触发器：
- 自动活动启动 — 活动可配置为在节假日日期范围开始时自动激活。例如，"春节特惠"活动在春节第一天自动启动
- 节假日特定折扣 — 定价引擎在价格计算时评估活跃节假日，无需人工干预即可启用特殊假日费率
- 季节性内容排期 — 博客文章、落地页和邮件活动可定时在关键节假日发布，确保营销与文化活动的协调一致
设计理念
数据驱动排期
节假日作为整个营销自动化堆栈的核心排期原语。系统不将季节性促销硬编码到业务逻辑中，而是将节假日视为声明式数据——管理员只需定义一次节假日及其日期范围和语言，所有下游系统（活动引擎、定价计算器、内容调度器）都会相应响应。这种数据驱动的方法消除了重复，确保了模块间的一致性，并使季节性策略一目了然地可审计。与通过电子表格或日历工具手动管理节假日促销不同——日期会漂移、活动错过窗口期、本地化是事后考虑——声明式节假日数据保证每个促销系统在正确的日期以正确的语言激活，每次都是如此。
本地化优先设计
每个节假日以所有支持的语言（EN、ZH、DE）存储其名称和描述，并优雅回退到英文。系统的节假日解析服务在查询时根据当前用户语言环境解析适当的本地化值。这确保中国用户看到"春节"，而德国用户看到"Chinesisches Neujahr"——无需重复定义节假日或为每个市场维护单独的排期逻辑。
关注点分离
节假日定义与其使用方式清晰分离：节假日模块拥有数据（创建、存储、解析），而活动引擎、定价计算器和内容调度器拥有行为。这意味着添加新节假日永远不需要修改代码——只需一条数据库记录——每个消费模块可以独立决定如何解释节假日数据。
最佳实践
地区性节假日覆盖
对于服务全球受众的 SaaS 平台，维护覆盖所有目标市场的完整节假目录。专注于直接影响用户行为和流量模式的节假日——电商平台应优先考虑购物活动（黑色星期五、网络星期一、双十一），而 B2B 平台应关注商业文化节假日。
活动预排期
将活动排期配置为在节假日日期之前激活，而不是在当天激活。例如，在 12 月初启动圣诞活动，而不是 12 月 25 日。节假日的日期范围支持通过允许活动引用节假日开始日期并配置提前量偏移来实现这一点。
节假日驱动的定价策略
有节制且透明地使用节假日定价。通过可见的优惠券代码或促销横幅应用节假日折扣，而不是悄悄调整价格。定价引擎的节假日评估通过将每次节假日引起的价格调整记录在交易日志中来实现这种透明度。
客户端节假日展示示例：
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}% 折扣
</p>
))}
</div>
)
}
多语言一致性
在所有语言中维护一致的节假日命名约定。使用英文名称作为 slug（例如 chinese-new-year）以确保跨语言的引用完整性，同时分别存储本地化的显示名称。这种方法在向每个受众提供文化适当内容的同时保持系统有序。
常见问题
如何创建新的节假日？
导航到 /dashboard/admin/holidays 并点击"添加节假日"。填写所有支持语言的名称、设置日期范围、可选添加描述，然后保存。节假日立即可用于活动排期和定价引擎集成。
节假日能否每年重复？ 可以。系统通过日期范围配置支持每年重复。创建节假时，你可以指定是一次性事件还是年度纪念日。每逢重复节假自动出现在活跃查询中。
节假日生成器如何工作？
生成器位于 src/lib/holiday-generator.ts，包含预定义的国标和区域节日列表。从管理面板触发时，它为所选区域的所有已定义节假创建数据库记录。生成器检查现有条目以避免重复，并且可以重新运行以添加新的相关节假。
节假日是否区分国家？ 是的。每个节假可以关联一个或多个国家代码。当使用特定国家查询节假解析服务时，仅返回匹配该国家代码的节假或全局节假（无国家限制）。
能否仅用部分语言创建节假名称？ 可以。节假名称字段是一个包含语言键的 JSON 对象。你只需填充与实现相关的语言的名称。如果某个语言特定名称不可用，系统会自动回退到英文名称。
定价引擎如何使用节假数据？ 定价引擎在结账时调用节假解析服务，以确定是否有活跃的节假适用。如果配置了节假特定定价（例如圣诞节期间 10% 折扣），引擎会在最终确定总价之前应用调整。
节假日驱动的促销有哪些报告可用？ 归因分析仪表板可按节假期间筛选转化数据，使您能够衡量节假特定活动和定价调整对整体收入和用户获取的影响。
配置
节假日通过管理界面的 /dashboard/admin/holidays 管理。基本功能无需额外环境变量。
对于自定义节假日定义，修改 src/lib/holiday-generator.ts 添加自己的节假条目。生成器从预定义数组中读取，可编程扩展。
节假日解析服务的缓存 TTL 可在 src/lib/holiday-service.ts 中配置，以平衡数据新鲜度和数据库负载：
const CACHE_TTL_MS = 5 * 60 * 1000 // 5 分钟
集成点
节假日管理系统与以下 TanStack Ship 平台模块集成：