《移动游戏产品的架构·商业化与发行工程》2.3 账号迁移、合并与风控

// file: src/biz/account-merge.ts
// tier: L1
// verify: node --test test/biz/account-merge.test.ts

export type CurrencyStrategy = "sum" | "max" | "primary";
export type ItemStrategy = "sum" | "max";
export type RiskBand = "auto" | "review" | "reject";
export type MergeDecision = "auto_merge" | "manual_review" | "reject";

export interface MergeAccount {
  readonly playerId: string;
  readonly createdAt: number;
  readonly lastLoginAt: number;
  readonly verified: boolean;
  readonly totalPaidCents: number;
  readonly bindings: readonly string[];
  readonly currencies: Readonly<Record<string, number>>;
  readonly items: Readonly<Record<string, number>>;
}

export interface MergePolicy {
  readonly currency: Readonly<Record<string, CurrencyStrategy>>;
  readonly itemStrategy: ItemStrategy;
  readonly reviewScore: number;
  readonly rejectScore: number;
}

export interface RiskSignals {
  readonly sameDevice: boolean;
  readonly samePaymentInstrument: boolean;
  readonly recentCredentialChange: boolean;
  readonly geoJump: boolean;
  readonly appealCount30d: number;
  readonly accountAgeDays: number;
}

export interface MergePlan {
  readonly primaryId: string;
  readonly secondaryId: string;
  readonly bindings: readonly string[];
  readonly currencies: Readonly<Record<string, number>>;
  readonly items: Readonly<Record<string, number>>;
  readonly riskScore: number;
  readonly band: RiskBand;
  readonly reasons: readonly string[];
  readonly decision: MergeDecision;
}

export const DEFAULT_POLICY: MergePolicy = {
  currency: { paid_gem: "sum", free_gem: "max", coin: "sum" },
  itemStrategy: "max",
  reviewScore: 30,
  rejectScore: 70,
};

export class MergeError extends Error {
  readonly code: string;

  constructor(code: string, message: string) {
    super(message);
    this.name = "MergeError";
    this.code = code;
  }
}

function fail(code: string, message: string): never {
  throw new MergeError(code, message);
}

export function assertMergeAccount(account: MergeAccount): void {
  if (account.playerId.trim().length === 0) {
    fail("INVALID_ACCOUNT", "playerId must not be empty");
  }
  if (!Number.isFinite(account.totalPaidCents) || account.totalPaidCents < 0) {
    fail("INVALID_ACCOUNT", "totalPaidCents must be a non-negative finite number");
  }
  for (const [key, value] of Object.entries(account.currencies)) {
    if (!Number.isFinite(value) || value < 0) {
      fail("INVALID_ASSET", `currency ${key} must be a non-negative finite number`);
    }
  }
  for (const [key, value] of Object.entries(account.items)) {
    if (!Number.isFinite(value) || value < 0) {
      fail("INVALID_ASSET", `item ${key} must be a non-negative finite number`);
    }
  }
}

export function choosePrimary(first: MergeAccount, second: MergeAccount): [MergeAccount, MergeAccount] {
  if (first.playerId === second.playerId) {
    fail("SAME_ACCOUNT", "cannot merge an account with itself");
  }
  if (first.totalPaidCents !== second.totalPaidCents) {
    return second.totalPaidCents > first.totalPaidCents ? [second, first] : [first, second];
  }
  if (first.createdAt !== second.createdAt) {
    return first.createdAt < second.createdAt ? [first, second] : [second, first];
  }
  return first.playerId < second.playerId ? [first, second] : [second, first];
}

export function scoreRisk(signals: RiskSignals): { score: number; reasons: string[] } {
  let score = 0;
  const reasons: string[] = [];
  if (signals.sameDevice) {
    score += 15;
    reasons.push("same_device");
  }
  if (signals.samePaymentInstrument) {
    score += 20;
    reasons.push("same_payment_instrument");
  }
  if (signals.recentCredentialChange) {
    score += 20;
    reasons.push("recent_credential_change");
  }
  if (signals.geoJump) {
    score += 25;
    reasons.push("geo_jump");
  }
  const appeals = Math.max(0, Math.floor(signals.appealCount30d));
  const appealScore = Math.min(15, appeals * 5);
  if (appealScore > 0) {
    score += appealScore;
    reasons.push("appeal_frequency");
  }
  if (signals.accountAgeDays < 7) {
    score += 15;
    reasons.push("young_account");
  }
  return { score: Math.min(100, score), reasons };
}

function mergeNumberMaps(
  primary: Readonly<Record<string, number>>,
  secondary: Readonly<Record<string, number>>,
  strategyFor: (key: string) => CurrencyStrategy | ItemStrategy,
): Record<string, number> {
  const keys = new Set([...Object.keys(primary), ...Object.keys(secondary)]);
  const merged: Record<string, number> = {};
  for (const key of [...keys].sort()) {
    const primaryValue = primary[key] ?? 0;
    const secondaryValue = secondary[key] ?? 0;
    const strategy = strategyFor(key);
    if (strategy === "sum") {
      merged[key] = primaryValue + secondaryValue;
    } else if (strategy === "primary") {
      merged[key] = primaryValue;
    } else {
      merged[key] = Math.max(primaryValue, secondaryValue);
    }
  }
  return merged;
}

function mergeBindings(primary: readonly string[], secondary: readonly string[]): string[] {
  return [...new Set([...primary, ...secondary])];
}

export function planMerge(
  first: MergeAccount,
  second: MergeAccount,
  signals: RiskSignals,
  policy: MergePolicy = DEFAULT_POLICY,
): MergePlan {
  assertMergeAccount(first);
  assertMergeAccount(second);
  const [primary, secondary] = choosePrimary(first, second);
  const bindings = mergeBindings(primary.bindings, secondary.bindings);
  const currencies = mergeNumberMaps(
    primary.currencies,
    secondary.currencies,
    (key) => policy.currency[key] ?? "max",
  );
  const items = mergeNumberMaps(primary.items, secondary.items, () => policy.itemStrategy);

  const risk = scoreRisk(signals);
  const reasons = [...risk.reasons];
  const unverified = !primary.verified || !secondary.verified;
  let riskScore = risk.score;
  if (unverified) {
    riskScore = Math.min(100, riskScore + 20);
    reasons.push("unverified_account");
  }

  let band: RiskBand;
  let decision: MergeDecision;
  if (riskScore >= policy.rejectScore) {
    band = "reject";
    decision = "reject";
  } else if (unverified || riskScore >= policy.reviewScore) {
    band = "review";
    decision = "manual_review";
  } else {
    band = "auto";
    decision = "auto_merge";
  }

  return {
    primaryId: primary.playerId,
    secondaryId: secondary.playerId,
    bindings,
    currencies,
    items,
    riskScore,
    band,
    reasons,
    decision,
  };
}

export function formatMergePlan(plan: MergePlan): string {
  const currencies = Object.entries(plan.currencies)
    .map(([key, value]) => `${key}=${value}`)
    .join(",");
  const bindings = plan.bindings.join("|") || "none";
  return `${plan.primaryId}<-${plan.secondaryId} band=${plan.band} score=${plan.riskScore} decision=${plan.decision} bindings=${bindings} currencies=${currencies}`;
}