《移动游戏产品的架构·网络、资源与热更新》6.3 赛季结算与客户端展示口径

// file: src/net/season.ts
// tier: L1
// verify: node --test test/net/season.test.ts
/**
 * 赛季结算的客户端展示模型（mga-net-lab）。
 * 段位阈值、软重置比例与展示口径均为实验设定，不是案例事实。
 */

export interface Tier {
  readonly id: string;
  readonly minPoints: number;
}

export interface SeasonConfig {
  readonly seasonId: string;
  readonly tiers: readonly Tier[];
  readonly softResetRatio: number;
  readonly maxCarryPoints: number;
}

export type RewardSource = "rank" | "tier" | "participation";

export interface RewardLine {
  readonly itemId: string;
  readonly count: number;
  readonly source: RewardSource;
}

export interface SettlementPayload {
  readonly seasonId: string;
  readonly finalPoints: number;
  readonly peakPoints: number;
  readonly rank: number;
  readonly totalPlayers: number;
  readonly rewards: readonly RewardLine[];
}

export interface RewardView {
  readonly itemId: string;
  readonly count: number;
  readonly sources: readonly RewardSource[];
}

export interface SettlementView {
  readonly seasonId: string;
  readonly tierId: string;
  readonly tierIndex: number;
  readonly points: number;
  readonly nextTierId: string | null;
  readonly pointsToNext: number;
  readonly progressPermille: number;
  readonly percentilePermille: number;
  readonly rewards: readonly RewardView[];
  readonly carryPoints: number;
}

const SOURCE_ORDER: readonly RewardSource[] = [
  "rank",
  "tier",
  "participation",
];

function assertInteger(value: number, label: string, min: number): void {
  if (!Number.isInteger(value) || value < min) {
    throw new RangeError(`${label} 必须是不小于 ${min} 的整数，收到 ${value}`);
  }
}

function validateConfig(config: SeasonConfig): void {
  if (config.seasonId.trim() === "") {
    throw new Error("seasonId 不能为空");
  }
  if (config.tiers.length === 0) {
    throw new Error("段位表不能为空");
  }
  const ids = new Set<string>();
  let previous = -1;
  for (let index = 0; index < config.tiers.length; index += 1) {
    const tier = config.tiers[index];
    if (tier.id.trim() === "") {
      throw new Error(`tiers[${index}].id 不能为空`);
    }
    if (ids.has(tier.id)) {
      throw new Error(`段位 id 重复：${tier.id}`);
    }
    ids.add(tier.id);
    assertInteger(tier.minPoints, `tiers[${index}].minPoints`, 0);
    if (index === 0 && tier.minPoints !== 0) {
      throw new Error(`首个段位必须从 0 分开始，收到 ${tier.minPoints}`);
    }
    if (tier.minPoints <= previous) {
      throw new Error(
        `段位阈值必须严格递增：${previous} → ${tier.minPoints}`,
      );
    }
    previous = tier.minPoints;
  }
  if (!(config.softResetRatio >= 0 && config.softResetRatio <= 1)) {
    throw new RangeError(
      `softResetRatio 必须在 0..1 之间，收到 ${config.softResetRatio}`,
    );
  }
  assertInteger(config.maxCarryPoints, "maxCarryPoints", 0);
}

export function tierForPoints(
  config: SeasonConfig,
  points: number,
): { readonly index: number; readonly tier: Tier } {
  validateConfig(config);
  assertInteger(points, "points", 0);
  let index = 0;
  for (let cursor = 0; cursor < config.tiers.length; cursor += 1) {
    if (points >= config.tiers[cursor].minPoints) {
      index = cursor;
    } else {
      break;
    }
  }
  return { index, tier: config.tiers[index] };
}

export function softResetCarry(
  config: SeasonConfig,
  peakPoints: number,
): number {
  validateConfig(config);
  assertInteger(peakPoints, "peakPoints", 0);
  return Math.min(
    Math.floor(peakPoints * config.softResetRatio),
    config.maxCarryPoints,
  );
}

function mergeRewards(rewards: readonly RewardLine[]): readonly RewardView[] {
  const merged = new Map<
    string,
    { count: number; sources: Set<RewardSource> }
  >();
  for (const reward of rewards) {
    if (reward.itemId.trim() === "") {
      throw new Error("奖励 itemId 不能为空");
    }
    assertInteger(reward.count, `奖励 ${reward.itemId} 的数量`, 1);
    const entry = merged.get(reward.itemId);
    if (entry === undefined) {
      merged.set(reward.itemId, {
        count: reward.count,
        sources: new Set<RewardSource>([reward.source]),
      });
    } else {
      entry.count += reward.count;
      entry.sources.add(reward.source);
    }
  }
  return [...merged.entries()]
    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
    .map(([itemId, entry]) => ({
      itemId,
      count: entry.count,
      sources: SOURCE_ORDER.filter((source) => entry.sources.has(source)),
    }));
}

export function buildSettlementView(
  config: SeasonConfig,
  payload: SettlementPayload,
): SettlementView {
  validateConfig(config);
  if (payload.seasonId !== config.seasonId) {
    throw new Error(
      `结算赛季 ${payload.seasonId} 与当前配置 ${config.seasonId} 不一致`,
    );
  }
  assertInteger(payload.finalPoints, "finalPoints", 0);
  assertInteger(payload.peakPoints, "peakPoints", 0);
  assertInteger(payload.rank, "rank", 1);
  assertInteger(payload.totalPlayers, "totalPlayers", 1);
  if (payload.peakPoints < payload.finalPoints) {
    throw new Error(
      `峰值积分 ${payload.peakPoints} 低于最终积分 ${payload.finalPoints}`,
    );
  }
  if (payload.rank > payload.totalPlayers) {
    throw new Error(
      `名次 ${payload.rank} 超出总人数 ${payload.totalPlayers}`,
    );
  }

  const { index, tier } = tierForPoints(config, payload.finalPoints);
  const next =
    index + 1 < config.tiers.length ? config.tiers[index + 1] : null;
  const pointsToNext =
    next === null ? 0 : next.minPoints - payload.finalPoints;
  let progressPermille = 1_000;
  if (next !== null) {
    const span = next.minPoints - tier.minPoints;
    const current = payload.finalPoints - tier.minPoints;
    progressPermille = Math.max(
      0,
      Math.min(1_000, Math.round((current * 1_000) / span)),
    );
  }
  const percentilePermille = Math.floor(
    ((payload.totalPlayers - payload.rank) * 1_000) / payload.totalPlayers,
  );

  return {
    seasonId: config.seasonId,
    tierId: tier.id,
    tierIndex: index,
    points: payload.finalPoints,
    nextTierId: next === null ? null : next.id,
    pointsToNext,
    progressPermille,
    percentilePermille,
    rewards: mergeRewards(payload.rewards),
    carryPoints: softResetCarry(config, payload.peakPoints),
  };
}

function permilleText(value: number): string {
  return `${Math.floor(value / 10)}.${value % 10}%`;
}

export function describeSettlement(view: SettlementView): string {
  const tierLabel =
    view.nextTierId === null
      ? "已是最高段"
      : `距下一段 ${view.pointsToNext}`;
  return `赛季 ${view.seasonId} 结算：段位 ${view.tierId}（第 ${view.tierIndex + 1} 段），积分 ${view.points}，${tierLabel}，进度 ${permilleText(view.progressPermille)}，超过 ${permilleText(view.percentilePermille)} 的玩家，奖励 ${view.rewards.length} 类，下季保留 ${view.carryPoints} 分`;
}