《移动游戏产品的架构·网络、资源与热更新》11.2 灰度发布：分组、比例与观测

// file: src/hotfix/rollout.ts
// tier: L1
// verify: node --test test/hotfix/rollout.test.ts

import { createHash } from "node:crypto";

export type Channel = "android-store" | "taptap" | "ios";
export type DeviceTier = "low" | "mid" | "high";

export interface RolloutContext {
  readonly channel: Channel;
  readonly deviceTier: DeviceTier;
  readonly now: string;
}

export interface RolloutStage {
  readonly name: string;
  readonly percent: number;
  readonly channels: readonly Channel[];
  readonly tiers: readonly DeviceTier[];
  readonly startAt: string;
}

export interface RolloutPolicy {
  readonly experiment: string;
  readonly salt: string;
  readonly stages: readonly RolloutStage[];
  readonly exclusions?: readonly string[];
}

export type DecisionReason =
  | "enrolled"
  | "below-threshold"
  | "excluded"
  | "filtered"
  | "not-started";

export interface RolloutDecision {
  readonly accountId: string;
  readonly experiment: string;
  readonly enrolled: boolean;
  readonly stage: string | null;
  readonly bucket: number;
  readonly reason: DecisionReason;
}

export interface RolloutSummary {
  readonly experiment: string;
  readonly total: number;
  readonly enrolled: number;
  readonly byStage: Readonly<Record<string, number>>;
  readonly reasons: Readonly<Record<string, number>>;
}

export const BUCKETS = 10_000;

export function bucketOf(accountId: string, salt: string): number {
  if (accountId.trim() === "") {
    throw new Error("accountId is empty");
  }
  if (salt.trim() === "") {
    throw new Error("salt is empty");
  }
  const digest = createHash("sha256").update(`${salt}:${accountId}`, "utf8").digest();
  return digest.readUInt32BE(0) % BUCKETS;
}

function thresholdOf(stage: RolloutStage): number {
  return Math.round((stage.percent / 100) * BUCKETS);
}

function validatePolicy(policy: RolloutPolicy): void {
  if (policy.experiment.trim() === "") {
    throw new Error("experiment is empty");
  }
  if (policy.salt.trim() === "") {
    throw new Error("salt is empty");
  }
  if (policy.stages.length === 0) {
    throw new Error("policy has no stages");
  }

  const names = new Set<string>();
  let previousStart = Number.NEGATIVE_INFINITY;

  for (const stage of policy.stages) {
    if (stage.name.trim() === "") {
      throw new Error("stage name is empty");
    }
    if (names.has(stage.name)) {
      throw new Error(`duplicate stage: ${stage.name}`);
    }
    names.add(stage.name);
    if (!Number.isInteger(stage.percent) || stage.percent < 0 || stage.percent > 100) {
      throw new Error(`invalid percent for ${stage.name}: ${stage.percent}`);
    }
    if (stage.channels.length === 0) {
      throw new Error(`stage ${stage.name} has no channels`);
    }
    if (stage.tiers.length === 0) {
      throw new Error(`stage ${stage.name} has no tiers`);
    }
    const start = Date.parse(stage.startAt);
    if (Number.isNaN(start)) {
      throw new Error(`invalid startAt for ${stage.name}: ${stage.startAt}`);
    }
    if (start <= previousStart) {
      throw new Error(`stages must be strictly ascending at ${stage.name}`);
    }
    previousStart = start;
  }
}

export function evaluateRollout(
  accountId: string,
  context: RolloutContext,
  policy: RolloutPolicy,
): RolloutDecision {
  validatePolicy(policy);
  const now = Date.parse(context.now);
  if (Number.isNaN(now)) {
    throw new Error(`invalid now: ${context.now}`);
  }
  const bucket = bucketOf(accountId, policy.salt);
  const base = { accountId, experiment: policy.experiment, bucket };

  const excluded = new Set(policy.exclusions ?? []);
  if (excluded.has(accountId)) {
    return { ...base, enrolled: false, stage: null, reason: "excluded" };
  }

  let lastActive: RolloutStage | null = null;
  let lastAdmitting: RolloutStage | null = null;
  let enrolledStage: RolloutStage | null = null;

  for (const stage of policy.stages) {
    if (Date.parse(stage.startAt) > now) break;
    lastActive = stage;
    if (
      !stage.channels.includes(context.channel) ||
      !stage.tiers.includes(context.deviceTier)
    ) {
      continue;
    }
    lastAdmitting = stage;
    if (enrolledStage === null && bucket < thresholdOf(stage)) enrolledStage = stage;
  }

  if (enrolledStage !== null) {
    return { ...base, enrolled: true, stage: enrolledStage.name, reason: "enrolled" };
  }
  if (lastAdmitting !== null) {
    return {
      ...base,
      enrolled: false,
      stage: lastAdmitting.name,
      reason: "below-threshold",
    };
  }
  return {
    ...base,
    enrolled: false,
    stage: lastActive === null ? null : lastActive.name,
    reason: lastActive === null ? "not-started" : "filtered",
  };
}

export function summarizeRollout(
  decisions: readonly RolloutDecision[],
): RolloutSummary {
  const byStage: Record<string, number> = {};
  const reasons: Record<string, number> = {};
  let enrolled = 0;
  let experiment = "";
  for (const decision of decisions) {
    if (experiment === "") experiment = decision.experiment;
    if (decision.experiment !== experiment) {
      throw new Error("cannot summarize decisions from different experiments");
    }
    if (decision.enrolled) enrolled += 1;
    const stageKey = decision.stage ?? "none";
    byStage[stageKey] = (byStage[stageKey] ?? 0) + 1;
    reasons[decision.reason] = (reasons[decision.reason] ?? 0) + 1;
  }
  return { experiment, total: decisions.length, enrolled, byStage, reasons };
}

export function formatRolloutSummary(summary: RolloutSummary): string {
  const share =
    summary.total === 0 ? "0.0" : ((summary.enrolled / summary.total) * 100).toFixed(1);
  const stages = Object.keys(summary.byStage)
    .sort()
    .map((key) => `${key}=${summary.byStage[key]}`)
    .join(" ");
  const reasons = Object.keys(summary.reasons)
    .sort()
    .map((key) => `${key}=${summary.reasons[key]}`)
    .join(" ");
  return [
    `experiment ${summary.experiment}`,
    `enrolled ${summary.enrolled}/${summary.total} (${share}%)`,
    `stages ${stages}`,
    `reasons ${reasons}`,
  ].join("\n");
}

experiment battle-values-2026-11
enrolled 13/60 (21.7%)
stages android-5pct=48 internal=12
reasons below-threshold=35 enrolled=13 filtered=12