活动与优惠管理
TanStack Ship 活动管理系统，支持创建折扣优惠、优惠码、基于 UTM 的自动匹配和促销定价活动。
概述
TanStack Ship 的活动与优惠管理系统支持复杂的营销促销活动，推动转化和客户参与。该系统提供了一个完整的工具包，用于创建限时活动、定义多种类型的折扣优惠、生成优惠码并跟踪兑换效果——全部通过管理面板管理。
作为 TanStack Ship 平台的一部分，活动系统与 UTM 追踪模块（基于流量来源的自动优惠匹配）、定价引擎（结账时动态折扣应用）和账单系统（Stripe 集成优惠码处理）紧密集成。
活动生命周期
每个活动遵循从创建到到期的结构化生命周期：
设计理念
活动与优惠系统基于三个设计原则构建：
- 可组合折扣引擎 — 来自不同来源的折扣（百分比、固定金额、积分赠送）在定义的优先级链中评估。每个来源独立运作，实现复杂促销策略而无需修改核心定价逻辑。与 Voucherify 不同——它需要外部 API 调用和 Webhook 集成来进行折扣验证——我们内置的优惠引擎在您自己的数据库内服务端评估定价规则，消除了结账流程中的延迟和第三方依赖。
- UTM 优先自动匹配 — 在结账开始前，基于 UTM 参数自动为用户匹配优惠。这创造了零摩擦的折扣体验——用户无需查找或输入优惠码。
- 限时活动 — 每个活动都有明确的开始和结束日期。系统根据这些排期自动激活和停用优惠，确保促销定价永远不会意外持续运行。
核心能力
活动管理
活动是高级营销计划，将优惠、UTM 参数和定向规则组合在一起。每个活动包括：
- 名称与描述 — 管理员参考的内部名称和面向客户的促销描述
- 日期范围 — 用于自动激活和到期的开始和结束日期
- UTM 参数 — 用于归因追踪的来源、媒介和活动名称
- 启用状态 — 开关活动，无需删除配置
- 节假日关联 — 将活动链接到节假日排期以实现季节性促销
活动可以在激活前预览，以验证配置的优惠和 UTM 链接。
优惠类型
支持三种优惠类型，各有不同的使用场景：
| 类型 | 描述 | 最佳使用场景 |
|---|---|---|
| 百分比折扣 | 按基础价格的百分比折扣 | 季节性促销、首购优惠 |
| 固定金额 | 按计费货币的固定金额折扣 | 忠诚度奖励、购物车放弃恢复 |
| 积分赠送 | 向用户余额奖励额外积分 | 推荐奖励、互动激励 |
优惠可以叠加或单独应用，由定价引擎的优先级逻辑控制。
优惠码系统
每个优惠可以有一个或多个优惠码，支持精细配置：
- 自定义码 — 定义品牌相关的码（例如
LAUNCH2024、SUMMER20） - 自动生成码 — 系统生成唯一码用于单独分发
- 公开与私有 — 公开码在定价页面列出；私有码需要直接分享
- 指定套餐范围 — 将优惠限制到特定订阅套餐（月付、年付或两者）
- 使用限制 — 设置每个码的最大兑换次数
- 过期时间 — 独立于父级活动日期的码级别过期
客户端优惠码验证示例：
import { useMutation } from '@tanstack/react-query'
import { useState } from 'react'
export function CouponInput() {
const [code, setCode] = useState('')
const validate = useMutation({
mutationFn: async (couponCode: string) => {
const res = await fetch('/api/offers/validate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ code: couponCode }),
})
if (!res.ok) throw new Error('优惠码无效或已过期')
return res.json() as Promise<{
valid: boolean
discount: { type: string; value: number }
description: string
}>
},
})
return (
<div className="rounded-lg border p-4">
<label className="mb-2 block text-sm font-medium">优惠码</label>
<div className="flex gap-2">
<input
className="flex-1 rounded-md border px-3 py-2"
value={code}
onChange={(e) => setCode(e.target.value)}
placeholder="输入优惠码"
/>
<button
className="rounded-md bg-primary px-4 py-2 text-white"
onClick={() => validate.mutate(code)}
>
应用
</button>
</div>
{validate.isPending && <p className="mt-2 text-sm">验证中...</p>}
{validate.isError && (
<p className="mt-2 text-sm text-red-600">{validate.error.message}</p>
)}
{validate.isSuccess && (
<p className="mt-2 text-sm text-green-600">
{validate.data.description} — 优惠 {validate.data.discount.value}{validate.data.discount.type === 'percentage' ? '%' : '元'}
</p>
)}
</div>
)
}
基于 UTM 的自动匹配
当用户通过带有 UTM 标签的 URL 访问时，系统自动匹配适用的优惠。这支持复杂的营销策略：
- 广告活动定价 — 来自特定广告平台（Google Ads、Facebook、LinkedIn）用户的特殊定价
- 合作伙伴推荐 — 为每个合作伙伴设置自定义 UTM 码以追踪推荐优惠
- A/B 测试 — 为不同流量来源设置不同优惠以衡量转化效果
- 内容营销 — 通过独特的 UTM 链接为博客读者或邮件订阅者提供专属优惠
匹配逻辑会评估 UTM 来源、媒介和活动字段，与已配置的活动规则进行匹配。
节假日特定活动
活动可以链接到节假日管理系统以实现自动季节性激活：
- 创建在配置的节假日自动激活的活动
- 为不同节假日设置不同优惠（例如圣诞节 vs 黑五）
- 按市场区域本地化节假日活动（德国、中国、美国）
最佳实践
活动命名规范
使用一致的命名模式，例如 {类型}_{目标}_{年份}——WELCOME_NEWUSER_2024、SALE_SUMMER_2024。这使得管理面板中的筛选和报表更加便捷。
限时优惠
始终为活动设置明确的开始和结束日期。限时优惠营造紧迫感并提高转化率。系统会自动停用到期活动，无需手动清理。
测试 UTM 匹配
在启动活动之前，通过模拟使用已配置的 UTM 参数访问来测试 UTM 链接。验证结账时是否正确应用了优惠。
优惠叠加策略
确定优惠是否可以叠加（多个折扣同时应用）或互斥。定价引擎支持两种模式，但应限制叠加以防止利润率侵蚀。
常见问题
如何创建新活动？
导航到 /dashboard/admin/campaigns 并点击"新活动"。填写名称、描述、日期范围和可选的 UTM 参数，然后创建优惠并关联到活动。
一个活动中可以包含多个优惠吗？ 可以。一个活动可以包含多个不同类型的优惠。例如，夏季促销活动可能同时包含百分比折扣和积分赠送。
结账时优惠如何应用？ 定价引擎评估适用于用户和套餐的所有活跃优惠。如果检测到 UTM 匹配的活动，其优惠优先。否则，应用价值最高的通用优惠。
能否将优惠限制为仅限新用户？ 可以。通过配置资格规则，优惠可以限定新用户范围。系统在评估优惠适用性时会检查用户的注册日期和订阅历史。
如何追踪活动效果？ 管理面板提供活动分析视图，指标包括优惠兑换次数、转化率、收入影响和 UTM 归因数据。
活动到期后会怎样？ 到期活动会自动停用。活动中的优惠在结账时不再应用。历史兑换数据保留不变。
同一个优惠码可以在多个活动中使用吗？ 不可以。每个优惠码属于单个活动中的单个优惠，以避免归因追踪的歧义。
配置
活动和优惠完全从管理面板管理：
- 活动管理：
/dashboard/admin/campaigns - 优惠管理：
/dashboard/admin/offers - 优惠码：在每个优惠内创建
活动系统不需要特定的环境变量，使用现有的账单和 UTM 配置。
集成点
活动系统与以下 TanStack Ship 平台模块集成：