《移动游戏产品的架构·商业化与发行工程》3.1 渠道矩阵：国内安卓、TapTap 与海外商店

加权分成 = Σ(份额 × 分成) / Σ份额

加权审核 = Σ(份额 × 时长，仅已知桶) / Σ(已知桶份额)

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

export type Platform = "android-cn" | "ios" | "taptap" | "overseas";

export interface ChannelGroup {
  readonly id: string;
  readonly platform: Platform;
  readonly channelCount: number;
  readonly packageCount: number;
  readonly sharePct: number;
  readonly commissionPct: number;
  readonly reviewHours: number | null;
}

export interface MatrixSummary {
  readonly groups: number;
  readonly channels: number;
  readonly packages: number;
  readonly coveragePct: number;
  readonly weightedCommissionPct: number;
  readonly weightedReviewHours: number | null;
  readonly reviewSamplesPct: number;
}

export interface TrimResult {
  readonly kept: readonly ChannelGroup[];
  readonly dropped: readonly ChannelGroup[];
  readonly coveragePct: number;
  readonly droppedChannels: number;
  readonly droppedPackages: number;
}

function round1(value: number): number {
  return Math.round(value * 10) / 10;
}

function assertGroup(group: ChannelGroup): void {
  if (typeof group.id !== "string" || group.id.length === 0) {
    throw new Error("group id is required");
  }
  if (!Number.isInteger(group.channelCount) || group.channelCount <= 0) {
    throw new RangeError(`channelCount must be a positive integer: ${group.channelCount}`);
  }
  if (!Number.isInteger(group.packageCount) || group.packageCount < group.channelCount) {
    throw new RangeError(`packageCount must be >= channelCount for ${group.id}`);
  }
  if (!Number.isFinite(group.sharePct) || group.sharePct < 0 || group.sharePct > 100) {
    throw new RangeError(`sharePct out of range for ${group.id}`);
  }
  if (!Number.isFinite(group.commissionPct) || group.commissionPct < 0 || group.commissionPct > 100) {
    throw new RangeError(`commissionPct out of range for ${group.id}`);
  }
  if (group.reviewHours !== null && (!Number.isFinite(group.reviewHours) || group.reviewHours < 0)) {
    throw new RangeError(`reviewHours invalid for ${group.id}`);
  }
}

export function summarizeMatrix(groups: readonly ChannelGroup[]): MatrixSummary {
  if (groups.length === 0) {
    throw new Error("summarizeMatrix needs at least one group");
  }
  const seen = new Set<string>();
  let channels = 0;
  let packages = 0;
  let coverage = 0;
  let commissionWeighted = 0;
  let reviewWeighted = 0;
  let reviewSamples = 0;

  for (const group of groups) {
    assertGroup(group);
    if (seen.has(group.id)) {
      throw new Error(`duplicate group id: ${group.id}`);
    }
    seen.add(group.id);
    channels += group.channelCount;
    packages += group.packageCount;
    coverage += group.sharePct;
    commissionWeighted += group.sharePct * group.commissionPct;
    if (group.reviewHours !== null) {
      reviewWeighted += group.sharePct * group.reviewHours;
      reviewSamples += group.sharePct;
    }
  }

  if (coverage > 100.0001) {
    throw new RangeError(`sharePct sum exceeds 100: ${coverage}`);
  }
  if (coverage <= 0) {
    throw new RangeError("sharePct sum must be positive");
  }

  return {
    groups: groups.length,
    channels,
    packages,
    coveragePct: round1(coverage),
    weightedCommissionPct: round1(commissionWeighted / coverage),
    weightedReviewHours: reviewSamples === 0 ? null : round1(reviewWeighted / reviewSamples),
    reviewSamplesPct: round1(reviewSamples),
  };
}

export function trimToCoverage(groups: readonly ChannelGroup[], targetPct: number): TrimResult {
  if (!Number.isFinite(targetPct) || targetPct <= 0 || targetPct > 100) {
    throw new RangeError(`targetPct must be in (0, 100], got ${targetPct}`);
  }
  const total = summarizeMatrix(groups).coveragePct;
  if (total + 0.0001 < targetPct) {
    throw new Error(`coverage ${total}% cannot reach target ${targetPct}%`);
  }
  const ranked = [...groups].sort((a, b) => b.sharePct - a.sharePct || a.id.localeCompare(b.id));
  const kept: ChannelGroup[] = [];
  let coverage = 0;
  for (const group of ranked) {
    if (coverage + 0.0001 >= targetPct) {
      break;
    }
    kept.push(group);
    coverage += group.sharePct;
  }
  const keptIds = new Set(kept.map((group) => group.id));
  const dropped = ranked.filter((group) => !keptIds.has(group.id));
  return {
    kept,
    dropped,
    coveragePct: round1(coverage),
    droppedChannels: dropped.reduce((sum, group) => sum + group.channelCount, 0),
    droppedPackages: dropped.reduce((sum, group) => sum + group.packageCount, 0),
  };
}

export function formatMatrix(summary: MatrixSummary): string {
  const review = summary.weightedReviewHours === null ? "n/a" : `${summary.weightedReviewHours}h`;
  return `groups=${summary.groups} channels=${summary.channels} packages=${summary.packages} coverage=${summary.coveragePct}% commission=${summary.weightedCommissionPct}% review=${review} reviewSamples=${summary.reviewSamplesPct}%`;
}

export function formatTrim(result: TrimResult): string {
  const kept = result.kept.map((group) => group.id).join(",");
  const dropped = result.dropped.map((group) => group.id).join(",") || "none";
  return `kept=${kept} dropped=${dropped} coverage=${result.coveragePct}% channels-removed=${result.droppedChannels} packages-removed=${result.droppedPackages}`;
}

groups=4 channels=9 packages=11 coverage=100% commission=34.3% review=70.6h reviewSamples=85%