《移动游戏产品的架构·网络、资源与热更新》10.2 热更的内容边界与红线

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

export type Platform = "android" | "ios";
export type Surface = "config" | "asset" | "script" | "native";
export type Domain =
  | "activity"
  | "level"
  | "cosmetic"
  | "text"
  | "battle-numbers"
  | "season"
  | "ui"
  | "voice"
  | "payment"
  | "gacha-odds"
  | "core-rules"
  | "privacy";
export type Zone = "allow" | "review" | "blocked" | "store";

export interface BoundaryEntry {
  readonly id: string;
  readonly domain: Domain;
  readonly surface: Surface;
  readonly platform: Platform;
  readonly reviewer?: string;
  readonly hasRollbackPlan: boolean;
}

export interface BoundaryPolicy {
  readonly name: string;
  readonly scriptPlatforms: readonly Platform[];
  readonly defaultRollbackMinutes: number;
  readonly rollbackMinutes: Readonly<Record<string, number>>;
}

export interface ZoneDecision {
  readonly id: string;
  readonly zone: Zone;
  readonly rollbackMinutes: number;
  readonly reasons: readonly string[];
}

export interface BoundaryAudit {
  readonly policy: string;
  readonly decisions: readonly ZoneDecision[];
  readonly counts: Readonly<Record<Zone, number>>;
  readonly blockedIds: readonly string[];
  readonly releaseBlocked: boolean;
}

export const TIDE_MATCH3_BOUNDARY: BoundaryPolicy = {
  name: "潮汐消消",
  scriptPlatforms: [],
  defaultRollbackMinutes: 30,
  rollbackMinutes: { activity: 30, level: 30, cosmetic: 30, text: 30 },
};

export const TIDE_ARK_BOUNDARY: BoundaryPolicy = {
  name: "潮汐方舟",
  scriptPlatforms: ["android"],
  defaultRollbackMinutes: 15,
  rollbackMinutes: { "battle-numbers": 15, season: 15, ui: 15, voice: 15 },
};

const RED_DOMAINS: readonly Domain[] = [
  "payment",
  "gacha-odds",
  "core-rules",
  "privacy",
];

const REVIEW_DOMAINS: readonly Domain[] = ["battle-numbers", "season"];

const DOMAINS: readonly Domain[] = [
  "activity",
  "level",
  "cosmetic",
  "text",
  "battle-numbers",
  "season",
  "ui",
  "voice",
  "payment",
  "gacha-odds",
  "core-rules",
  "privacy",
];

const SURFACES: readonly Surface[] = ["config", "asset", "script", "native"];

function validateEntry(entry: BoundaryEntry): void {
  if (entry.id.trim() === "") throw new Error("entry id is required");
  if (!DOMAINS.includes(entry.domain)) {
    throw new Error(`unknown domain: ${String(entry.domain)}`);
  }
  if (!SURFACES.includes(entry.surface)) {
    throw new Error(`unknown surface: ${String(entry.surface)}`);
  }
  if (entry.platform !== "android" && entry.platform !== "ios") {
    throw new Error(`unknown platform: ${String(entry.platform)}`);
  }
}

export function classifyBoundary(
  entry: BoundaryEntry,
  policy: BoundaryPolicy,
): ZoneDecision {
  validateEntry(entry);

  if (RED_DOMAINS.includes(entry.domain)) {
    return {
      id: entry.id,
      zone: "blocked",
      rollbackMinutes: 0,
      reasons: [`红线内容：${entry.domain} 不得通过热更下发`],
    };
  }

  if (entry.surface === "native") {
    return {
      id: entry.id,
      zone: "store",
      rollbackMinutes: 0,
      reasons: ["原生代码与权限只能随商店整包发布"],
    };
  }

  if (entry.surface === "script" && !policy.scriptPlatforms.includes(entry.platform)) {
    return {
      id: entry.id,
      zone: "store",
      rollbackMinutes: 0,
      reasons: ["该平台只接受资源与配置热更"],
    };
  }

  const rollbackMinutes =
    policy.rollbackMinutes[entry.domain] ?? policy.defaultRollbackMinutes;
  const reasons: string[] = [];
  let needsReview = false;

  if (entry.surface === "script") {
    needsReview = true;
    reasons.push("代码热更需要复核");
  }
  if (REVIEW_DOMAINS.includes(entry.domain)) {
    needsReview = true;
    reasons.push("影响战斗或赛季数值，需要复核与回滚方案");
  }

  if (!needsReview) {
    return { id: entry.id, zone: "allow", rollbackMinutes, reasons };
  }

  if (entry.reviewer === undefined || entry.reviewer.trim() === "") {
    reasons.push("缺少复核人");
  }
  if (!entry.hasRollbackPlan) {
    reasons.push("缺少回滚方案");
  }

  const zone: Zone = reasons.some((line) => line.startsWith("缺少"))
    ? "blocked"
    : "review";

  return { id: entry.id, zone, rollbackMinutes, reasons };
}

export function auditBoundary(
  entries: readonly BoundaryEntry[],
  policy: BoundaryPolicy,
): BoundaryAudit {
  const seen = new Set<string>();
  const decisions: ZoneDecision[] = [];
  for (const entry of entries) {
    if (seen.has(entry.id)) throw new Error(`duplicate entry id: ${entry.id}`);
    seen.add(entry.id);
    decisions.push(classifyBoundary(entry, policy));
  }

  const counts: Record<Zone, number> = {
    allow: 0,
    review: 0,
    blocked: 0,
    store: 0,
  };
  for (const decision of decisions) counts[decision.zone] += 1;

  const blockedIds = decisions
    .filter((decision) => decision.zone === "blocked")
    .map((decision) => decision.id);

  return {
    policy: policy.name,
    decisions,
    counts,
    blockedIds,
    releaseBlocked: blockedIds.length > 0,
  };
}

export function formatBoundaryAudit(audit: BoundaryAudit): string {
  const lines = ["entry\tzone\trollback\treasons"];
  for (const decision of audit.decisions) {
    const reasons = decision.reasons.length > 0 ? decision.reasons.join("; ") : "-";
    lines.push(
      `${decision.id}\t${decision.zone}\t${decision.rollbackMinutes}min\t${reasons}`,
    );
  }
  lines.push(
    `summary\tallow=${audit.counts.allow}\treview=${audit.counts.review}\tblocked=${audit.counts.blocked}\tstore=${audit.counts.store}\trelease=${audit.releaseBlocked ? "blocked" : "ok"}`,
  );
  return lines.join("\n");
}

entry	zone	rollback	reasons
activity	allow	30min	-
level	allow	30min	-
battle-numbers	review	15min	影响战斗或赛季数值，需要复核与回滚方案
gacha	blocked	0min	红线内容：gacha-odds 不得通过热更下发
native-sdk	store	0min	原生代码与权限只能随商店整包发布
summary	allow=2	review=1	blocked=1	store=1	release=blocked