《互联网产品的客户端架构·交易、增长与平台化》9.3 拉新活动页的降级

// file: src/growth/campaign.ts
// tier: L2
// verify: node --test --test-concurrency=1 test/growth/campaign.test.ts

export interface Clock {
  now(): number;
}

export class ManualClock implements Clock {
  #now: number;

  constructor(start: number) {
    if (!Number.isFinite(start)) throw new Error("起始时间非法");
    this.#now = start;
  }

  now(): number {
    return this.#now;
  }

  advance(ms: number): void {
    if (!Number.isFinite(ms) || ms < 0) throw new Error("推进时长非法");
    this.#now += ms;
  }

  set(ms: number): void {
    if (!Number.isFinite(ms)) throw new Error("设置时间非法");
    this.#now = ms;
  }
}

export type CampaignStatus = "active" | "paused" | "closed";

export interface CampaignConfig {
  id: string; version: number; status: CampaignStatus;
  startAt: number; endAt: number; quota: number; claimed: number;
  campaignPath: string; fallbackPath: string; channel: string; nearExhausted: number;
}

export type ConfigErrorKind = "network" | "timeout" | "server" | "not_found";

export class ConfigError extends Error {
  kind: ConfigErrorKind;

  constructor(kind: ConfigErrorKind, message: string) {
    super(message);
    this.kind = kind;
  }
}

export type ConfigLoader = (campaignId: string, at: number) => Promise<CampaignConfig>;

export interface ConfigCache { config: CampaignConfig | null; fetchedAt: number }

export interface CampaignOptions {
  staleMs: number; retryBaseMs: number; maxAttempts: number; defaultPath: string;
}

export type CampaignPhase = "upcoming" | "running" | "paused" | "ended" | "sold_out";

export type DegradeReason =
  | "config_unavailable"
  | "not_started"
  | "ended"
  | "paused"
  | "quota_exhausted";

export interface CampaignView {
  campaignId: string; phase: CampaignPhase | null;
  page: "campaign" | "fallback"; path: string;
  configSource: "network" | "cache" | "none"; staleMs: number | null;
  degraded: DegradeReason | null; shareParams: Record<string, string>;
  countdownMs: number | null;
  retry: { retryable: boolean; delayMs: number } | null;
  notices: string[];
}

function assertConfig(config: CampaignConfig): void {
  if (config.id.trim() === "") throw new Error("活动配置非法：缺少活动 id");
  if (!Number.isFinite(config.startAt) || !Number.isFinite(config.endAt)) {
    throw new Error("活动配置非法：时间窗口不是有限数字");
  }
  if (config.endAt <= config.startAt) throw new Error("活动配置非法：结束时间早于开始时间");
  if (!Number.isInteger(config.quota) || config.quota < 0) {
    throw new Error("活动配置非法：名额必须是非负整数");
  }
  if (!Number.isInteger(config.claimed) || config.claimed < 0) {
    throw new Error("活动配置非法：已领取数必须是非负整数");
  }
  if (!config.campaignPath.startsWith("/") || !config.fallbackPath.startsWith("/")) {
    throw new Error("活动配置非法：路径必须是站内绝对路径");
  }
}

// 阶段判定只看服务端配置与服务端时间，端上不自行推断活动是否开始。
export function evaluatePhase(config: CampaignConfig, now: number): CampaignPhase {
  assertConfig(config);
  if (config.status === "paused") return "paused";
  if (config.status === "closed" && now >= config.startAt) return "ended";
  if (now < config.startAt) return "upcoming";
  if (now >= config.endAt) return "ended";
  if (config.claimed >= config.quota) return "sold_out";
  return "running";
}

function degradeOf(phase: CampaignPhase): DegradeReason {
  if (phase === "upcoming") return "not_started";
  if (phase === "paused") return "paused";
  if (phase === "sold_out") return "quota_exhausted";
  return "ended";
}

function shareParamsFor(
  config: CampaignConfig | null,
  page: "campaign" | "fallback",
): Record<string, string> {
  if (config === null) return { ch: "direct" };
  return {
    ch: config.channel,
    cid: config.id,
    landing: page === "campaign" ? config.campaignPath : config.fallbackPath,
  };
}

// 拉取失败不等于降级：只要缓存还新鲜，就继续用缓存渲染，并同时给出重试建议。
export async function resolveCampaign(
  campaignId: string,
  loader: ConfigLoader,
  cache: ConfigCache,
  clock: Clock,
  options: CampaignOptions,
  attempt = 1,
): Promise<CampaignView> {
  const now = clock.now();
  const notices: string[] = [];
  let fetched: CampaignConfig | null = null;
  let failure: ConfigError | null = null;

  try {
    fetched = await loader(campaignId, now);
  } catch (error) {
    failure =
      error instanceof ConfigError
        ? error
        : new ConfigError("server", error instanceof Error ? error.message : "未知错误");
  }

  let config: CampaignConfig | null = null;
  let source: CampaignView["configSource"] = "none";
  let staleMs: number | null = null;

  const cacheUsable =
    cache.config !== null &&
    cache.config.id === campaignId &&
    now - cache.fetchedAt <= options.staleMs;

  if (fetched !== null) {
    if (cacheUsable && cache.config !== null && fetched.version < cache.config.version) {
      config = cache.config;
      source = "cache";
      staleMs = now - cache.fetchedAt;
      notices.push("服务端配置版本回退，继续使用缓存");
    } else {
      config = fetched;
      source = "network";
    }
  } else if (cacheUsable) {
    config = cache.config;
    source = "cache";
    staleMs = now - cache.fetchedAt;
    notices.push("活动配置拉取失败，使用缓存");
  }

  const retry = failure === null ? null : retryHint(failure.kind, attempt, options);

  if (config === null) {
    return {
      campaignId,
      phase: null,
      page: "fallback",
      path: options.defaultPath,
      configSource: "none",
      staleMs: null,
      degraded: "config_unavailable",
      shareParams: { ch: "direct" },
      countdownMs: null,
      retry,
      notices: [...notices, "没有可用配置，降级到默认页"],
    };
  }

  const phase = evaluatePhase(config, now);
  const page = phase === "running" ? "campaign" : "fallback";
  const degraded = page === "fallback" ? degradeOf(phase) : null;
  const remaining = config.quota - config.claimed;
  if (page === "campaign" && remaining <= config.nearExhausted) {
    notices.push("名额接近耗尽");
  }
  let countdownMs: number | null = null;
  if (phase === "running") countdownMs = config.endAt - now;
  if (phase === "upcoming") countdownMs = config.startAt - now;

  return {
    campaignId,
    phase,
    page,
    path: page === "campaign" ? config.campaignPath : config.fallbackPath,
    configSource: source,
    staleMs,
    degraded,
    shareParams: shareParamsFor(config, page),
    countdownMs,
    retry,
    notices,
  };
}

export function retryHint(
  kind: ConfigErrorKind,
  attempt: number,
  options: CampaignOptions,
): { retryable: boolean; delayMs: number } {
  if (!Number.isInteger(attempt) || attempt < 1) throw new Error("重试次数必须是正整数");
  if (kind === "not_found" || attempt >= options.maxAttempts) {
    return { retryable: false, delayMs: 0 };
  }
  const delayMs = Math.min(options.retryBaseMs * 2 ** (attempt - 1), 8_000);
  return { retryable: true, delayMs };
}

$ node --test --test-concurrency=1 test/growth/campaign.test.ts
✔ 进行中的活动从网络配置渲染活动页 (0.718541ms)
✔ 活动开始时刻即为进行中 (0.0775ms)
✔ 未开始的活动降级到常规页并给出开始倒计时 (0.081333ms)
✔ 到达结束时刻立即降级 (0.064ms)
✔ 运营暂停的活动不展示活动页 (0.087709ms)
✔ 名额恰好耗尽时判定售罄 (0.067333ms)
✔ 名额接近耗尽时保留活动页但给出提示 (0.087917ms)
✔ 假时钟推进后倒计时同步减少 (0.087125ms)
✔ 拉取失败但缓存新鲜时继续渲染并提示重试 (0.530959ms)
✔ 缓存超过容忍时长后不再使用 (0.133459ms)
✔ 没有缓存且拉取失败时降级到默认页 (0.082833ms)
✔ 活动不存在是终态错误，不重试 (0.069875ms)
✔ 服务端错误按指数退避，达到上限后停止 (0.064875ms)
✔ 服务端配置版本回退时保留较新的缓存 (0.070708ms)
✔ 降级页仍保留活动与渠道参数用于归因 (0.063416ms)
✔ 配置不可用时分享参数不携带未知活动 (0.075958ms)
✔ 其他活动的缓存不会被误用 (0.083584ms)
✔ 配置时间窗口倒挂时拒绝渲染 (0.193375ms)
✔ 名额不是整数时拒绝渲染 (0.052125ms)
✔ 非法重试次数被拒绝 (0.047292ms)
ℹ tests 20
ℹ suites 0
ℹ pass 20
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 135.090708