《移动游戏产品的架构·商业化与发行工程》12.2 未成年人保护与防沉迷

// file: src/biz/minor-protection.ts
// tier: L1
// verify: node --test test/biz/minor-protection.test.ts

export const SHANGHAI_OFFSET_MS = 8 * 60 * 60 * 1000;
export const FACE_CHECK_RATIO = 0.8;

export interface PlayCalendar {
  readonly holidays: readonly string[];
  readonly makeupWorkdays: readonly string[];
}

export type PlayReason = "within-window" | "outside-window" | "not-play-day" | "invalid-time";

export interface PlayDecision {
  readonly allowed: boolean;
  readonly reason: PlayReason;
  readonly localDate: string;
  readonly localTime: string;
  readonly minutesRemaining: number;
}

export type AgeBand = "under-8" | "8-16" | "16-18" | "adult";

export interface SpendLimits {
  readonly singleCents: number;
  readonly monthlyCents: number;
}

export type TopUpReason =
  | "allowed"
  | "adult"
  | "no-payment-band"
  | "single-limit"
  | "monthly-limit"
  | "invalid-amount";

export interface TopUpInput {
  readonly ageYears: number;
  readonly amountCents: number;
  readonly monthlySpentCents: number;
  readonly faceCheckEnabled: boolean;
}

export interface TopUpDecision {
  readonly allowed: boolean;
  readonly reason: TopUpReason;
  readonly band: AgeBand;
  readonly remainingMonthlyCents: number;
  readonly faceCheckRequired: boolean;
}

function shifted(nowMs: number): Date {
  return new Date(nowMs + SHANGHAI_OFFSET_MS);
}

export function shanghaiDayKey(nowMs: number): string {
  const local = shifted(nowMs);
  const year = local.getUTCFullYear();
  const month = String(local.getUTCMonth() + 1).padStart(2, "0");
  const day = String(local.getUTCDate()).padStart(2, "0");
  return `${year}-${month}-${day}`;
}

export function isPlayDay(nowMs: number, calendar: PlayCalendar): boolean {
  const key = shanghaiDayKey(nowMs);
  if (calendar.holidays.includes(key)) {
    return true;
  }
  if (calendar.makeupWorkdays.includes(key)) {
    return false;
  }
  const weekday = shifted(nowMs).getUTCDay();
  return weekday === 5 || weekday === 6 || weekday === 0;
}

export function evaluatePlayTime(nowMs: number, calendar: PlayCalendar): PlayDecision {
  if (!Number.isFinite(nowMs)) {
    return {
      allowed: false,
      reason: "invalid-time",
      localDate: "",
      localTime: "",
      minutesRemaining: 0,
    };
  }
  const local = shifted(nowMs);
  const localDate = shanghaiDayKey(nowMs);
  const hour = local.getUTCHours();
  const minute = local.getUTCMinutes();
  const localTime = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
  const minutesOfDay = hour * 60 + minute;
  const windowStart = 20 * 60;
  const windowEnd = 21 * 60;

  if (!isPlayDay(nowMs, calendar)) {
    return { allowed: false, reason: "not-play-day", localDate, localTime, minutesRemaining: 0 };
  }
  if (minutesOfDay < windowStart || minutesOfDay >= windowEnd) {
    return { allowed: false, reason: "outside-window", localDate, localTime, minutesRemaining: 0 };
  }
  return {
    allowed: true,
    reason: "within-window",
    localDate,
    localTime,
    minutesRemaining: windowEnd - minutesOfDay,
  };
}

export function ageBand(ageYears: number): AgeBand {
  if (!Number.isFinite(ageYears) || ageYears < 8) {
    return "under-8";
  }
  if (ageYears < 16) {
    return "8-16";
  }
  if (ageYears < 18) {
    return "16-18";
  }
  return "adult";
}

export function spendLimits(band: AgeBand): SpendLimits | null {
  switch (band) {
    case "under-8":
      return { singleCents: 0, monthlyCents: 0 };
    case "8-16":
      return { singleCents: 5_000, monthlyCents: 20_000 };
    case "16-18":
      return { singleCents: 10_000, monthlyCents: 40_000 };
    case "adult":
      return null;
  }
}

export function checkTopUp(input: TopUpInput): TopUpDecision {
  const band = ageBand(input.ageYears);
  const validAmount = Number.isFinite(input.amountCents) && input.amountCents > 0;
  const validSpent = Number.isFinite(input.monthlySpentCents) && input.monthlySpentCents >= 0;
  if (!validAmount || !validSpent) {
    return {
      allowed: false,
      reason: "invalid-amount",
      band,
      remainingMonthlyCents: 0,
      faceCheckRequired: false,
    };
  }
  const limits = spendLimits(band);
  if (limits === null) {
    return {
      allowed: true,
      reason: "adult",
      band,
      remainingMonthlyCents: 0,
      faceCheckRequired: false,
    };
  }
  const remaining = Math.max(0, limits.monthlyCents - input.monthlySpentCents);
  if (limits.singleCents === 0) {
    return {
      allowed: false,
      reason: "no-payment-band",
      band,
      remainingMonthlyCents: remaining,
      faceCheckRequired: false,
    };
  }
  if (input.amountCents > limits.singleCents) {
    return {
      allowed: false,
      reason: "single-limit",
      band,
      remainingMonthlyCents: remaining,
      faceCheckRequired: false,
    };
  }
  if (input.amountCents > remaining) {
    return {
      allowed: false,
      reason: "monthly-limit",
      band,
      remainingMonthlyCents: remaining,
      faceCheckRequired: false,
    };
  }
  const nextMonthlySpent = input.monthlySpentCents + input.amountCents;
  return {
    allowed: true,
    reason: "allowed",
    band,
    remainingMonthlyCents: remaining - input.amountCents,
    faceCheckRequired:
      input.faceCheckEnabled && nextMonthlySpent >= limits.monthlyCents * FACE_CHECK_RATIO,
  };
}

export function formatMinorDecision(
  accountId: string,
  play: PlayDecision,
  topUp: TopUpDecision,
): string {
  const playState = play.allowed ? "allow" : play.reason;
  const topUpState = topUp.allowed ? "allow" : topUp.reason;
  return `${accountId} date=${play.localDate} time=${play.localTime} play=${playState} minutes=${play.minutesRemaining} topup=${topUpState} band=${topUp.band} face=${topUp.faceCheckRequired ? "yes" : "no"}`;
}