《移动游戏产品的架构·商业化与发行工程》8.3 风控规则引擎与人工复核

// file: src/biz/risk-engine.ts
// tier: L1
// verify: node --test test/biz/risk-engine.test.ts

export type RiskAction = "allow" | "review" | "block";
export type RiskEventKind = "purchase" | "refund" | "ad-reward" | "login";

export interface RiskEvent {
  readonly eventId: string;
  readonly accountId: string;
  readonly kind: RiskEventKind;
  readonly amountCents: number;
  readonly atMs: number;
  readonly signals: Readonly<Record<string, number>>;
}

export interface RiskRule {
  readonly id: string;
  readonly priority: number;
  readonly action: RiskAction;
  readonly weight: number;
  readonly reason: string;
  readonly when: (event: RiskEvent) => boolean;
}

export interface RuleHit {
  readonly id: string;
  readonly action: RiskAction;
  readonly weight: number;
  readonly reason: string;
}

export interface RiskDecision {
  readonly eventId: string;
  readonly accountId: string;
  readonly score: number;
  readonly action: RiskAction;
  readonly hits: readonly RuleHit[];
}

export interface ReviewCase {
  readonly caseId: string;
  readonly accountId: string;
  readonly score: number;
  readonly amountCents: number;
  readonly createdAtMs: number;
}

export interface ReviewPlan {
  readonly accepted: readonly ReviewCase[];
  readonly deferred: readonly ReviewCase[];
  readonly breached: readonly string[];
  readonly capacityUsed: number;
}

export interface ReviewLoad {
  readonly dailyCases: number;
  readonly minutesPerDay: number;
  readonly fte: number;
}

const ACTION_RANK: Readonly<Record<RiskAction, number>> = { allow: 0, review: 1, block: 2 };

function signal(event: RiskEvent, key: string): number {
  return event.signals[key] ?? 0;
}

export function buildDefaultRules(): readonly RiskRule[] {
  return [
    {
      id: "chargeback-seen",
      priority: 10,
      action: "block",
      weight: 40,
      reason: "a chargeback is already on record",
      when: (event) => signal(event, "chargebacks") >= 1,
    },
    {
      id: "device-farm",
      priority: 20,
      action: "block",
      weight: 35,
      reason: "too many accounts share one device",
      when: (event) => signal(event, "deviceAccounts") >= 5,
    },
    {
      id: "refund-burst",
      priority: 30,
      action: "review",
      weight: 30,
      reason: "three or more refunds in thirty days",
      when: (event) => signal(event, "refunds30d") >= 3,
    },
    {
      id: "ad-verification-gap",
      priority: 40,
      action: "review",
      weight: 25,
      reason: "reward claims outpace server-side ad verification",
      when: (event) => signal(event, "adGapRatio") >= 0.1,
    },
    {
      id: "purchase-velocity",
      priority: 50,
      action: "review",
      weight: 20,
      reason: "six or more orders within one hour",
      when: (event) => signal(event, "ordersLastHour") >= 6,
    },
    {
      id: "large-new-device",
      priority: 60,
      action: "review",
      weight: 20,
      reason: "top-tier purchase from a one-day-old device",
      when: (event) =>
        event.amountCents >= 64_800 &&
        event.signals.accountAgeDays !== undefined &&
        event.signals.accountAgeDays <= 1,
    },
  ];
}

export function evaluateRisk(event: RiskEvent, rules: readonly RiskRule[]): RiskDecision {
  const hits = rules
    .filter((rule) => rule.when(event))
    .slice()
    .sort((left, right) => left.priority - right.priority || left.id.localeCompare(right.id))
    .map<RuleHit>((rule) => ({
      id: rule.id,
      action: rule.action,
      weight: rule.weight,
      reason: rule.reason,
    }));
  const score = Math.min(100, hits.reduce((sum, hit) => sum + hit.weight, 0));
  const action = hits.reduce<RiskAction>(
    (current, hit) => (ACTION_RANK[hit.action] > ACTION_RANK[current] ? hit.action : current),
    "allow",
  );
  return { eventId: event.eventId, accountId: event.accountId, score, action, hits };
}

export function triageReviews(
  cases: readonly ReviewCase[],
  capacity: number,
  nowMs: number,
  slaMs: number,
): ReviewPlan {
  if (!Number.isInteger(capacity) || capacity < 0) {
    throw new RangeError(`capacity must be a non-negative integer, got ${capacity}`);
  }
  const overdue = (item: ReviewCase): boolean => nowMs - item.createdAtMs > slaMs;
  const sorted = cases.slice().sort((left, right) => {
    const leftOverdue = overdue(left) ? 1 : 0;
    const rightOverdue = overdue(right) ? 1 : 0;
    if (leftOverdue !== rightOverdue) {
      return rightOverdue - leftOverdue;
    }
    if (left.score !== right.score) {
      return right.score - left.score;
    }
    if (left.createdAtMs !== right.createdAtMs) {
      return left.createdAtMs - right.createdAtMs;
    }
    return left.caseId.localeCompare(right.caseId);
  });
  return {
    accepted: sorted.slice(0, capacity),
    deferred: sorted.slice(capacity),
    breached: sorted.filter(overdue).map((item) => item.caseId),
    capacityUsed: Math.min(capacity, sorted.length),
  };
}

export function estimateReviewLoad(
  monthlyCases: number,
  minutesPerCase: number,
  workingDays: number,
  minutesPerReviewerDay = 480,
): ReviewLoad {
  if (monthlyCases < 0 || minutesPerCase < 0 || workingDays <= 0 || minutesPerReviewerDay <= 0) {
    throw new RangeError("load inputs must be non-negative and use a positive working day");
  }
  const dailyCases = monthlyCases / workingDays;
  const minutesPerDay = dailyCases * minutesPerCase;
  return { dailyCases, minutesPerDay, fte: minutesPerDay / minutesPerReviewerDay };
}

export function formatDecision(decision: RiskDecision): string {
  const ids = decision.hits.map((hit) => hit.id).join(",") || "none";
  return `${decision.eventId} ${decision.action} score=${decision.score} hits=${ids}`;
}