《移动游戏产品的架构·商业化与发行工程》9.2 邮件、补偿与库存发放

<活动 id>:<玩家 id>:<发放原因>

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

export type GrantKind = "mail" | "compensation" | "inventory";
export type GrantStatus = "granted" | "duplicate" | "expired" | "out-of-stock";
export type CompensationState = "pending" | "met" | "breached";

export interface InventorySnapshot {
  readonly itemId: string;
  readonly total: number;
  readonly reserved: number;
}

export interface GrantRequest {
  readonly requestId: string;
  readonly playerId: string;
  readonly kind: GrantKind;
  readonly itemId: string;
  readonly quantity: number;
  readonly expiresAt: string;
  readonly idempotencyKey: string;
}

export interface GrantResult {
  readonly requestId: string;
  readonly idempotencyKey: string;
  readonly status: GrantStatus;
  readonly granted: number;
  readonly inventory: InventorySnapshot;
  readonly reason: string;
}

export interface CompensationAssessment {
  readonly incidentId: string;
  readonly state: CompensationState;
  readonly elapsedHours: number;
  readonly targetHours: number;
}

const HOUR_MS = 3_600_000;

function assertNonEmpty(name: string, value: string): void {
  if (value.trim() === "") {
    throw new RangeError(`${name} must not be empty`);
  }
}

function validateInventory(inventory: InventorySnapshot): void {
  assertNonEmpty("inventory.itemId", inventory.itemId);
  if (!Number.isInteger(inventory.total) || inventory.total < 0) {
    throw new RangeError(`inventory.total must be a non-negative integer, got ${inventory.total}`);
  }
  if (!Number.isInteger(inventory.reserved) || inventory.reserved < 0) {
    throw new RangeError(
      `inventory.reserved must be a non-negative integer, got ${inventory.reserved}`,
    );
  }
  if (inventory.reserved > inventory.total) {
    throw new RangeError("inventory.reserved cannot exceed inventory.total");
  }
}

function validateRequest(request: GrantRequest): void {
  assertNonEmpty("requestId", request.requestId);
  assertNonEmpty("playerId", request.playerId);
  assertNonEmpty("itemId", request.itemId);
  assertNonEmpty("idempotencyKey", request.idempotencyKey);
  if (!Number.isInteger(request.quantity) || request.quantity <= 0) {
    throw new RangeError(`quantity must be a positive integer, got ${request.quantity}`);
  }
  if (!Number.isFinite(Date.parse(request.expiresAt))) {
    throw new RangeError(`expiresAt is not a valid timestamp: ${request.expiresAt}`);
  }
}

export function applyGrant(
  request: GrantRequest,
  inventory: InventorySnapshot,
  seenKeys: ReadonlySet<string>,
  nowMs: number,
): GrantResult {
  validateRequest(request);
  validateInventory(inventory);
  if (!Number.isFinite(nowMs)) {
    throw new RangeError(`nowMs must be finite, got ${nowMs}`);
  }
  if (request.itemId !== inventory.itemId) {
    throw new RangeError(
      `request item ${request.itemId} does not match inventory ${inventory.itemId}`,
    );
  }

  const base = {
    requestId: request.requestId,
    idempotencyKey: request.idempotencyKey,
    inventory,
  };

  if (seenKeys.has(request.idempotencyKey)) {
    return { ...base, status: "duplicate", granted: 0, reason: "idempotency key already applied" };
  }
  if (Date.parse(request.expiresAt) <= nowMs) {
    return { ...base, status: "expired", granted: 0, reason: "grant expired before delivery" };
  }

  const remaining = inventory.total - inventory.reserved;
  if (request.quantity > remaining) {
    return {
      ...base,
      status: "out-of-stock",
      granted: 0,
      reason: `need ${request.quantity}, only ${remaining} left`,
    };
  }

  return {
    ...base,
    status: "granted",
    granted: request.quantity,
    inventory: { ...inventory, reserved: inventory.reserved + request.quantity },
    reason: "reserved and written to the grant ledger",
  };
}

export function assessCompensation(
  incidentId: string,
  raisedAt: string,
  sentAt: string | null,
  targetHours: number,
  nowMs: number,
): CompensationAssessment {
  assertNonEmpty("incidentId", incidentId);
  if (!Number.isFinite(targetHours) || targetHours <= 0) {
    throw new RangeError(`targetHours must be positive, got ${targetHours}`);
  }
  const raised = Date.parse(raisedAt);
  if (!Number.isFinite(raised)) {
    throw new RangeError(`raisedAt is not a valid timestamp: ${raisedAt}`);
  }
  if (!Number.isFinite(nowMs) || nowMs < raised) {
    throw new RangeError("nowMs must be finite and not earlier than raisedAt");
  }

  if (sentAt === null) {
    const elapsedHours = (nowMs - raised) / HOUR_MS;
    return {
      incidentId,
      state: elapsedHours <= targetHours ? "pending" : "breached",
      elapsedHours,
      targetHours,
    };
  }

  const sent = Date.parse(sentAt);
  if (!Number.isFinite(sent) || sent < raised) {
    throw new RangeError("sentAt must be a valid timestamp not earlier than raisedAt");
  }
  const elapsedHours = (sent - raised) / HOUR_MS;
  return {
    incidentId,
    state: elapsedHours <= targetHours ? "met" : "breached",
    elapsedHours,
    targetHours,
  };
}

export function formatGrantResult(result: GrantResult): string {
  const remaining = result.inventory.total - result.inventory.reserved;
  return `${result.requestId} ${result.status} granted=${result.granted} item=${result.inventory.itemId} remaining=${remaining} reason=${result.reason}`;
}