《移动游戏产品的架构·商业化与发行工程》4.1 商品目录、定价档位与区域价格

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

export type ProductKind = "consumable" | "non-consumable" | "subscription";
export type Region = "cn-ios" | "cn-android" | "tap-tap" | "overseas";
export type Currency = "CNY" | "USD";

export interface PricePoint {
  readonly region: Region;
  readonly currency: Currency;
  readonly amountCents: number;
}

export interface Grant {
  readonly item: string;
  readonly quantity: number;
}

export interface Product {
  readonly sku: string;
  readonly kind: ProductKind;
  readonly tierCents: number;
  readonly grant: Grant;
  readonly prices: readonly PricePoint[];
}

export interface Catalog {
  readonly version: string;
  readonly products: readonly Product[];
}

export interface CatalogPolicy {
  readonly allowedTiers: readonly number[];
  readonly regions: readonly Region[];
}

export type IssueCode =
  | "duplicate-sku"
  | "tier-not-allowed"
  | "missing-region-price"
  | "currency-mismatch"
  | "tier-price-mismatch"
  | "invalid-grant"
  | "unit-price-inversion";

export interface CatalogIssue {
  readonly code: IssueCode;
  readonly sku: string;
  readonly detail: string;
}

export const REGION_CURRENCY: Record<Region, Currency> = {
  "cn-ios": "CNY",
  "cn-android": "CNY",
  "tap-tap": "CNY",
  overseas: "USD",
};

export function priceFor(product: Product, region: Region): PricePoint | undefined {
  return product.prices.find((price) => price.region === region);
}

export function unitPriceCents(product: Product): number | undefined {
  if (product.grant.quantity <= 0) {
    return undefined;
  }
  return product.tierCents / product.grant.quantity;
}

function checkProduct(product: Product, policy: CatalogPolicy): CatalogIssue[] {
  const issues: CatalogIssue[] = [];
  if (!policy.allowedTiers.includes(product.tierCents)) {
    issues.push({
      code: "tier-not-allowed",
      sku: product.sku,
      detail: `tier ${product.tierCents} not in ${policy.allowedTiers.join("/")}`,
    });
  }
  if (product.grant.item.trim() === "" || product.grant.quantity <= 0) {
    issues.push({
      code: "invalid-grant",
      sku: product.sku,
      detail: "grant item must be non-empty and quantity must be positive",
    });
  }
  for (const region of policy.regions) {
    const price = priceFor(product, region);
    if (price === undefined) {
      issues.push({
        code: "missing-region-price",
        sku: product.sku,
        detail: `region ${region} has no price`,
      });
      continue;
    }
    if (price.currency !== REGION_CURRENCY[region]) {
      issues.push({
        code: "currency-mismatch",
        sku: product.sku,
        detail: `${region} expects ${REGION_CURRENCY[region]}, got ${price.currency}`,
      });
      continue;
    }
    if (price.currency === "CNY" && price.amountCents !== product.tierCents) {
      issues.push({
        code: "tier-price-mismatch",
        sku: product.sku,
        detail: `tier ${product.tierCents} but ${region} price ${price.amountCents}`,
      });
    }
  }
  return issues;
}

function checkLadders(products: readonly Product[]): CatalogIssue[] {
  const issues: CatalogIssue[] = [];
  const groups = new Map<string, Product[]>();
  for (const product of products) {
    if (product.kind !== "consumable" || product.grant.quantity <= 0) {
      continue;
    }
    const group = groups.get(product.grant.item) ?? [];
    group.push(product);
    groups.set(product.grant.item, group);
  }
  for (const group of groups.values()) {
    const ladder = [...group].sort((a, b) => a.tierCents - b.tierCents);
    for (let i = 1; i < ladder.length; i += 1) {
      const small = ladder[i - 1];
      const large = ladder[i];
      const smallUnit = small.tierCents / small.grant.quantity;
      const largeUnit = large.tierCents / large.grant.quantity;
      if (largeUnit > smallUnit) {
        issues.push({
          code: "unit-price-inversion",
          sku: large.sku,
          detail: `${large.sku} unit ${largeUnit.toFixed(2)} > ${small.sku} unit ${smallUnit.toFixed(2)}`,
        });
      }
    }
  }
  return issues;
}

export function validateCatalog(catalog: Catalog, policy: CatalogPolicy): CatalogIssue[] {
  const issues: CatalogIssue[] = [];
  const seen = new Set<string>();
  for (const product of catalog.products) {
    if (seen.has(product.sku)) {
      issues.push({
        code: "duplicate-sku",
        sku: product.sku,
        detail: "sku appears more than once",
      });
    }
    seen.add(product.sku);
    issues.push(...checkProduct(product, policy));
  }
  issues.push(...checkLadders(catalog.products));
  return issues;
}

export function formatCatalog(catalog: Catalog): string {
  const lines = catalog.products.map((product) => {
    const regions = product.prices.map((price) => price.region).join(",");
    return `${product.sku}\tCNY ${(product.tierCents / 100).toFixed(2)}\t${product.grant.quantity} ${product.grant.item}\t${regions}`;
  });
  return [`catalog ${catalog.version} (${catalog.products.length} products)`, ...lines].join("\n");
}

large.tier / large.qty > small.tier / small.qty
<=> large.tier * small.qty > small.tier * large.qty