《互联网产品的客户端架构·交易、增长与平台化》9.1 分享卡片的参数与归因

// file: src/growth/share.ts
// tier: L1
// verify: node --test test/growth/share.test.ts

export type ShareIssueCode =
  | "channel_missing"
  | "channel_unknown"
  | "campaign_unknown"
  | "inviter_invalid"
  | "path_invalid"
  | "time_invalid"
  | "signature_missing"
  | "signature_mismatch";

export interface ShareIssue { code: ShareIssueCode; field: string; message: string }

export interface SharePolicy {
  channels: string[];
  campaignIds: string[];
  clickWindowMs: number;
  activateWindowMs: number;
}

export interface ShareCard {
  channel: string; campaignId: string | null; inviterId: string | null;
  path: string; skuId: string | null; issuedAt: number;
}

export type ShareBuild =
  | { ok: true; path: string; params: Record<string, string> }
  | { ok: false; issues: ShareIssue[] };

const CHANNEL_RE = /^[a-z][a-z0-9_]{2,15}$/;
const CAMPAIGN_RE = /^c_[a-z0-9]{4,12}$/;
const INVITER_RE = /^u_[0-9]{6,12}$/;
const SIGNED_KEYS = ["ch", "cid", "inv", "sku", "ts"];

// 端上校验只能挡住手误与脏参数，挡不住伪造；签名真伪最终必须由服务端裁决。
export function fnv1a(input: string): string {
  let hash = 0x811c9dc5;
  for (let i = 0; i < input.length; i += 1) {
    hash ^= input.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash.toString(16).padStart(8, "0");
}

// 只对归因参数签名；渠道方附加的 utm_* 等参数不参与，避免它们把签名改坏。
export function signParams(path: string, params: Record<string, string>): string {
  const canonical = SIGNED_KEYS.filter((key) => params[key] !== undefined)
    .map((key) => `${key}=${params[key]}`)
    .join("&");
  return fnv1a(`${path}?${canonical}`);
}

function pathProblem(path: string): boolean {
  return !path.startsWith("/") || path.startsWith("//") || path.length > 200 || /[?#\s]/.test(path);
}

export function buildShareLink(card: ShareCard, policy: SharePolicy): ShareBuild {
  const issues: ShareIssue[] = [];
  const add = (code: ShareIssueCode, field: string, message: string) =>
    issues.push({ code, field, message });
  if (!Number.isFinite(card.issuedAt)) add("time_invalid", "ts", "分享时间非法");
  if (!CHANNEL_RE.test(card.channel) || !policy.channels.includes(card.channel)) {
    add("channel_unknown", "ch", `渠道码不在白名单：${card.channel}`);
  }
  if (
    card.campaignId !== null &&
    (!CAMPAIGN_RE.test(card.campaignId) || !policy.campaignIds.includes(card.campaignId))
  ) {
    add("campaign_unknown", "cid", `活动不存在或未开放：${card.campaignId}`);
  }
  if (card.inviterId !== null && !INVITER_RE.test(card.inviterId)) {
    add("inviter_invalid", "inv", "邀请人编号格式非法");
  }
  if (pathProblem(card.path)) {
    add("path_invalid", "path", "落地路径必须是站内绝对路径且不带查询串");
  }
  if (issues.length > 0) return { ok: false, issues };

  const params: Record<string, string> = { ch: card.channel, ts: String(card.issuedAt) };
  if (card.campaignId !== null) params.cid = card.campaignId;
  if (card.inviterId !== null) params.inv = card.inviterId;
  if (card.skuId !== null) params.sku = card.skuId;
  params.sig = signParams(card.path, params);
  return { ok: true, path: card.path, params };
}

export type SignatureState = "valid" | "missing" | "invalid";

export interface Landing {
  channel: string; campaignId: string | null; inviterId: string | null;
  skuId: string | null; signature: SignatureState;
  attributable: boolean; fallback: boolean; issues: ShareIssue[];
}

export function parseLanding(
  raw: Record<string, string | undefined>,
  policy: SharePolicy,
): Landing {
  const issues: ShareIssue[] = [];
  const add = (code: ShareIssueCode, field: string, message: string) =>
    issues.push({ code, field, message });
  if (raw.path !== undefined && pathProblem(raw.path)) {
    add("path_invalid", "path", "落地路径非法");
  }

  let signature: SignatureState = "missing";
  if (raw.sig !== undefined) {
    const signed = signParams(raw.path ?? "", raw as Record<string, string>);
    signature = signed === raw.sig ? "valid" : "invalid";
  } else {
    add("signature_missing", "sig", "缺少签名，只能按弱归因处理");
  }
  if (signature === "invalid") add("signature_mismatch", "sig", "签名不匹配，参数可能被改写");

  let channel = raw.ch ?? "";
  let fallback = false;
  if (!CHANNEL_RE.test(channel) || !policy.channels.includes(channel)) {
    add(channel === "" ? "channel_missing" : "channel_unknown", "ch", `渠道码不可用：${channel || "空"}`);
    channel = "direct";
    fallback = true;
  }

  let campaignId = raw.cid ?? null;
  if (campaignId !== null && !policy.campaignIds.includes(campaignId)) {
    add("campaign_unknown", "cid", `活动不在开放列表：${campaignId}`);
    campaignId = null;
  }

  let inviterId = raw.inv ?? null;
  if (inviterId !== null && !INVITER_RE.test(inviterId)) {
    add("inviter_invalid", "inv", "邀请人编号格式非法");
    inviterId = null;
  }

  if (signature === "invalid") {
    campaignId = null;
    inviterId = null;
    fallback = true;
  }
  return {
    channel, campaignId, inviterId, skuId: raw.sku ?? null, signature,
    attributable: signature !== "invalid" && !fallback, fallback, issues,
  };
}

export type MismatchCode = "channel" | "campaign" | "campaign_lost" | "inviter" | "sku";

export interface Consistency {
  consistent: boolean; mismatches: MismatchCode[]; action: "accept" | "fallback";
}

// 分享卡片是用户看到的承诺，落地页是实际打开的事实；两者不一致时以落地页为准，
// 但邀请人与活动冲突必须放弃归因，不能在两个候选人里猜一个。
export function compareCard(card: ShareCard, landing: Landing): Consistency {
  const mismatches: MismatchCode[] = [];
  if (card.channel !== landing.channel) mismatches.push("channel");
  if (card.campaignId !== landing.campaignId) {
    mismatches.push(landing.campaignId === null ? "campaign_lost" : "campaign");
  }
  if (card.inviterId !== null && landing.inviterId !== null && card.inviterId !== landing.inviterId) {
    mismatches.push("inviter");
  }
  if (card.skuId !== null && landing.skuId !== null && card.skuId !== landing.skuId) {
    mismatches.push("sku");
  }
  const blocking =
    mismatches.includes("channel") ||
    mismatches.includes("campaign") ||
    mismatches.includes("inviter");
  return {
    consistent: mismatches.length === 0,
    mismatches,
    action: blocking ? "fallback" : "accept",
  };
}

export interface Touch {
  kind: "click" | "activate"; at: number; channel: string;
  campaignId: string | null; inviterId: string | null; shareId: string;
}

export type AttributionSource = "invite" | "activate" | "click" | "organic";
export type AttributionReason = "within_window" | "expired" | "no_touch" | "future_touch";

export interface Attribution {
  source: AttributionSource; channel: string; campaignId: string | null;
  inviterId: string | null; shareId: string | null;
  reason: AttributionReason; ageMs: number | null;
}

function tierOf(touch: Touch): number {
  if (touch.inviterId !== null) return 3;
  return touch.kind === "activate" ? 2 : 1;
}

// 归因窗口从触点算到支付成功，不看安装包内的本地时间；
// 同一优先级取最后一次触点，邀请人优先于激活、激活优先于点击。
export function attributeOrder(
  touches: Touch[],
  orderAt: number,
  policy: SharePolicy,
): Attribution {
  if (!Number.isFinite(orderAt)) throw new Error("下单时间非法");
  const past = touches.filter((touch) => Number.isFinite(touch.at) && touch.at <= orderAt);
  const fresh = past.filter((touch) => {
    const limit = touch.kind === "activate" ? policy.activateWindowMs : policy.clickWindowMs;
    return orderAt - touch.at <= limit;
  });
  fresh.sort((a, b) => tierOf(a) - tierOf(b) || a.at - b.at);
  const winner = fresh.length > 0 ? fresh[fresh.length - 1] : null;
  if (winner !== null) {
    return {
      source: winner.inviterId !== null ? "invite" : winner.kind,
      channel: winner.channel,
      campaignId: winner.campaignId,
      inviterId: winner.inviterId,
      shareId: winner.shareId,
      reason: "within_window",
      ageMs: orderAt - winner.at,
    };
  }
  const last = past.length > 0 ? past[past.length - 1] : null;
  return {
    source: "organic",
    channel: "direct",
    campaignId: null,
    inviterId: null,
    shareId: null,
    reason: last !== null ? "expired" : touches.length > 0 ? "future_touch" : "no_touch",
    ageMs: last === null ? null : orderAt - last.at,
  };
}

$ node --test test/growth/share.test.ts
✔ 合法卡片生成全部归因参数与签名 (1.050542ms)
✔ 没有邀请人与商品时只生成渠道参数 (0.145292ms)
✔ 渠道不在白名单时拒绝生成 (0.087333ms)
✔ 活动不在开放列表时拒绝生成 (0.091167ms)
✔ 落地路径带查询串或协议头时拒绝生成 (0.081333ms)
✔ 签名只覆盖归因参数，附加 utm 参数不影响校验 (0.136667ms)
✔ 签名被改写时丢弃邀请人与活动 (0.088875ms)
✔ 参数被渠道剥掉时回落到 direct 并记录原因 (0.066708ms)
✔ 未知活动只丢活动，不影响渠道与邀请人 (0.063334ms)
✔ 分享卡与落地页完全一致时接受 (0.142583ms)
✔ 落地页丢了活动时记为 campaign_lost 但仍接受页面 (0.072333ms)
✔ 邀请人被替换时放弃归因而不是二选一 (0.052834ms)
✔ 点击窗口内按最后一次点击归因 (0.13725ms)
✔ 超出点击窗口的触点不参与归因 (0.055584ms)
✔ 激活归因优先于点击归因 (0.0735ms)
✔ 带邀请人的触点优先级最高 (0.068084ms)
✔ 订单时间早于全部触点时不产生倒挂归因 (0.044875ms)
✔ 没有触点时返回自然流量 (0.062375ms)
✔ 非法下单时间被拒绝 (0.202459ms)
✔ 同一输入生成稳定签名 (0.048958ms)
ℹ tests 20
ℹ suites 0
ℹ pass 20
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 177.244458