《移动游戏产品的架构·商业化与发行工程》5.2 补单、掉单与用户申诉

// file: src/biz/order-recovery.ts
// tier: L1
// verify: node --test test/biz/order-recovery.test.ts

export type ChannelId = "apple-ios" | "google-play" | "android-channel" | "tap-tap";

export interface PendingOrder {
  readonly orderId: string;
  readonly channel: ChannelId;
  readonly amountCents: number;
  readonly createdAtMs: number;
  readonly attempts: number;
  readonly lastAttemptMs: number | null;
}

export interface RecoveryPolicy {
  readonly nowMs: number;
  readonly firstQueryAfterMs: number;
  readonly baseBackoffMs: number;
  readonly maxBackoffMs: number;
  readonly maxAttempts: number;
  readonly escalateAfterMs: number;
  readonly closeAfterMs: number;
}

export function backoffMs(attempts: number, policy: RecoveryPolicy): number {
  if (attempts <= 0) return 0;
  const raw = policy.baseBackoffMs * 2 ** (attempts - 1);
  return Math.min(raw, policy.maxBackoffMs);
}

export function nextQueryAt(order: PendingOrder, policy: RecoveryPolicy): number | null {
  const age = policy.nowMs - order.createdAtMs;
  if (age < 0) return null;
  if (age >= policy.closeAfterMs) return null;
  if (order.attempts >= policy.maxAttempts) return null;
  if (order.attempts === 0) return order.createdAtMs + policy.firstQueryAfterMs;
  const last = order.lastAttemptMs ?? order.createdAtMs;
  return last + backoffMs(order.attempts, policy);
}

export type QueryOutcome = "paid" | "pending" | "not-found" | "closed" | "error";

export type QueryAction = "deliver" | "retry" | "escalate" | "close";

export interface QueryDecision {
  readonly action: QueryAction;
  readonly reason: string;
}

export function decideQuery(
  order: PendingOrder,
  outcome: QueryOutcome,
  policy: RecoveryPolicy,
): QueryDecision {
  if (outcome === "paid") return { action: "deliver", reason: "channel confirms payment" };
  if (outcome === "closed") return { action: "close", reason: "channel closed the order" };
  const age = policy.nowMs - order.createdAtMs;
  if (age >= policy.closeAfterMs) return { action: "close", reason: "recovery window expired" };
  if (age >= policy.escalateAfterMs || order.attempts >= policy.maxAttempts) {
    return { action: "escalate", reason: "needs manual review" };
  }
  return { action: "retry", reason: outcome === "error" ? "query failed" : "not settled yet" };
}

export interface QueryTask {
  readonly orderId: string;
  readonly channel: ChannelId;
  readonly dueAtMs: number;
  readonly attempts: number;
}

export function planQueries(
  orders: readonly PendingOrder[],
  policy: RecoveryPolicy,
): readonly QueryTask[] {
  const tasks: QueryTask[] = [];
  for (const order of orders) {
    const dueAtMs = nextQueryAt(order, policy);
    if (dueAtMs === null || dueAtMs > policy.nowMs) continue;
    tasks.push({ orderId: order.orderId, channel: order.channel, dueAtMs, attempts: order.attempts });
  }
  return tasks.sort((a, b) => a.dueAtMs - b.dueAtMs || a.orderId.localeCompare(b.orderId));
}

export interface Appeal {
  readonly appealId: string;
  readonly orderId: string | null;
  readonly playerId: string;
  readonly amountCents: number;
  readonly createdAtMs: number;
  readonly hasReceipt: boolean;
}

export type AppealCode =
  | "auto-grant"
  | "manual-review"
  | "already-delivered"
  | "duplicate-appeal"
  | "need-proof"
  | "outside-window"
  | "refunded";

export interface AppealDecision {
  readonly code: AppealCode;
  readonly reason: string;
}

export interface AppealPolicy {
  readonly nowMs: number;
  readonly dedupeWindowMs: number;
  readonly autoGrantMaxCents: number;
  readonly appealWindowMs: number;
}

export interface OrderSnapshot {
  readonly state: "created" | "paid" | "delivering" | "delivered" | "refunding" | "refunded" | "closed";
}

export function triageAppeal(
  appeal: Appeal,
  order: OrderSnapshot | undefined,
  priorAppeals: readonly Appeal[],
  policy: AppealPolicy,
): AppealDecision {
  if (policy.nowMs - appeal.createdAtMs > policy.appealWindowMs) {
    return { code: "outside-window", reason: "appeal window expired" };
  }
  const duplicated = priorAppeals.some(
    (item) =>
      item.appealId !== appeal.appealId &&
      item.playerId === appeal.playerId &&
      item.orderId === appeal.orderId &&
      policy.nowMs - item.createdAtMs <= policy.dedupeWindowMs,
  );
  if (duplicated) return { code: "duplicate-appeal", reason: "same order appealed recently" };
  if (appeal.orderId === null) {
    return appeal.hasReceipt
      ? { code: "manual-review", reason: "receipt without order id" }
      : { code: "need-proof", reason: "order id and receipt are both missing" };
  }
  if (order === undefined) {
    return appeal.hasReceipt
      ? { code: "manual-review", reason: "order not found but receipt attached" }
      : { code: "need-proof", reason: "order not found and no receipt" };
  }
  if (order.state === "delivered") return { code: "already-delivered", reason: "order already delivered" };
  if (order.state === "refunded") return { code: "refunded", reason: "order already refunded" };
  if (order.state === "paid" || order.state === "delivering") {
    if (appeal.amountCents <= policy.autoGrantMaxCents) {
      return { code: "auto-grant", reason: "paid order within auto-grant threshold" };
    }
    return { code: "manual-review", reason: "paid order above auto-grant threshold" };
  }
  return { code: "manual-review", reason: `order is ${order.state}` };
}

export function formatTasks(tasks: readonly QueryTask[]): string {
  if (tasks.length === 0) return "no query due";
  return tasks.map((task) => `${task.orderId}@${task.channel}#${task.attempts}`).join(",");
}