《移动游戏产品的架构·商业化与发行工程》7.1 归因链路：点击、安装、激活与事件回传

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

export type ChannelId = "adnet-alpha" | "adnet-beta" | "adnet-gamma" | "organic";
export type Platform = "ios" | "android";
export type Currency = "CNY" | "USD";

export interface ClickRecord {
  readonly clickId: string;
  readonly channel: ChannelId;
  readonly campaignId: string;
  readonly creativeId: string;
  readonly clickedAtMs: number;
  readonly deviceKey: string;
  readonly landing: string;
}

export interface InstallRecord {
  readonly installId: string;
  readonly platform: Platform;
  readonly installedAtMs: number;
  readonly deviceKey: string;
  readonly referrer: string;
  readonly reinstall: boolean;
}

export type ParseCode =
  | "missing-click-id"
  | "unknown-channel"
  | "missing-campaign"
  | "missing-device-key"
  | "bad-timestamp";

export type ParseResult =
  | { readonly ok: true; readonly click: ClickRecord }
  | { readonly ok: false; readonly code: ParseCode; readonly detail: string };

const CHANNELS: readonly ChannelId[] = ["adnet-alpha", "adnet-beta", "adnet-gamma", "organic"];

function isChannel(value: string): value is ChannelId {
  return (CHANNELS as readonly string[]).includes(value);
}

export function parseClick(raw: Record<string, string | undefined>): ParseResult {
  const clickId = (raw.click_id ?? "").trim();
  if (clickId === "") {
    return { ok: false, code: "missing-click-id", detail: "click_id is required" };
  }

  const channelText = (raw.channel ?? "").trim().toLowerCase();
  if (!isChannel(channelText)) {
    return {
      ok: false,
      code: "unknown-channel",
      detail: `channel "${channelText}" is not in the allowed list`,
    };
  }

  const campaignId = (raw.campaign_id ?? "").trim();
  if (campaignId === "") {
    return { ok: false, code: "missing-campaign", detail: "campaign_id is required" };
  }

  const deviceKey = (raw.device_key ?? "").trim();
  if (deviceKey === "") {
    return { ok: false, code: "missing-device-key", detail: "device_key is required" };
  }

  const timestampText = (raw.ts ?? "").trim();
  const clickedAtMs = Number(timestampText);
  if (timestampText === "" || !Number.isInteger(clickedAtMs) || clickedAtMs <= 0) {
    return {
      ok: false,
      code: "bad-timestamp",
      detail: `ts "${timestampText}" must be a positive integer in milliseconds`,
    };
  }

  return {
    ok: true,
    click: {
      clickId,
      channel: channelText,
      campaignId,
      creativeId: (raw.creative_id ?? "").trim(),
      clickedAtMs,
      deviceKey,
      landing: (raw.landing ?? "").trim(),
    },
  };
}

export type AttributionStatus =
  | "matched"
  | "organic"
  | "reinstall"
  | "out-of-order"
  | "device-mismatch";

export interface Attribution {
  readonly status: AttributionStatus;
  readonly channel: ChannelId;
  readonly clickId: string | null;
  readonly installId: string;
  readonly detail: string;
}

export function attributeInstall(click: ClickRecord | null, install: InstallRecord): Attribution {
  if (install.reinstall) {
    return {
      status: "reinstall",
      channel: click?.channel ?? "organic",
      clickId: click?.clickId ?? null,
      installId: install.installId,
      detail: "reinstall does not create a new install attribution",
    };
  }
  if (click === null) {
    return {
      status: "organic",
      channel: "organic",
      clickId: null,
      installId: install.installId,
      detail: "no click record for this install",
    };
  }
  if (click.clickedAtMs > install.installedAtMs) {
    return {
      status: "out-of-order",
      channel: click.channel,
      clickId: click.clickId,
      installId: install.installId,
      detail: "click happened after the install",
    };
  }
  if (click.deviceKey !== install.deviceKey) {
    return {
      status: "device-mismatch",
      channel: click.channel,
      clickId: click.clickId,
      installId: install.installId,
      detail: "click and install device keys differ",
    };
  }
  return {
    status: "matched",
    channel: click.channel,
    clickId: click.clickId,
    installId: install.installId,
    detail: `matched via ${click.channel}/${click.campaignId}`,
  };
}

export type EventName = "install" | "activate" | "purchase";

export interface EventRecord {
  readonly eventId: string;
  readonly eventName: EventName;
  readonly valueCents: number;
  readonly currency: Currency;
  readonly occurredAtMs: number;
}

export interface Postback {
  readonly channel: ChannelId;
  readonly clickId: string;
  readonly installId: string;
  readonly eventName: EventName;
  readonly valueCents: number;
  readonly currency: Currency;
  readonly occurredAtMs: number;
  readonly dedupeKey: string;
}

export type PostbackCode = "not-attributed" | "missing-event-id" | "invalid-value";

export type PostbackResult =
  | { readonly ok: true; readonly postback: Postback }
  | { readonly ok: false; readonly code: PostbackCode; readonly detail: string };

export function buildPostback(attribution: Attribution, event: EventRecord): PostbackResult {
  if (attribution.status !== "matched" || attribution.clickId === null) {
    return {
      ok: false,
      code: "not-attributed",
      detail: `${attribution.status} installs have no partner click to post back to`,
    };
  }
  if (event.eventId.trim() === "") {
    return { ok: false, code: "missing-event-id", detail: "event_id is required for dedupe" };
  }
  if (event.valueCents < 0 || (event.eventName === "purchase" && event.valueCents === 0)) {
    return {
      ok: false,
      code: "invalid-value",
      detail: `value ${event.valueCents} is not valid for ${event.eventName}`,
    };
  }
  return {
    ok: true,
    postback: {
      channel: attribution.channel,
      clickId: attribution.clickId,
      installId: attribution.installId,
      eventName: event.eventName,
      valueCents: event.valueCents,
      currency: event.currency,
      occurredAtMs: event.occurredAtMs,
      dedupeKey: `${attribution.installId}:${event.eventId}`,
    },
  };
}

export function formatAttribution(attribution: Attribution): string {
  const click = attribution.clickId ?? "-";
  return `${attribution.status}:${attribution.channel} click=${click} install=${attribution.installId}`;
}