《移动游戏产品的架构·商业化与发行工程》11.2 深链路由与冷启动恢复

tide://activity/summer?campaign=recall_w1

https://link.tide.example/activity/summer?campaign=recall_w1

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

export type RouteKind = "activity" | "store" | "post" | "home";
export type LinkSource = "push" | "web" | "qr" | "inapp";
export type RouteStatus = "ready" | "login-required" | "upgrade-required" | "fallback";

export type RouteTarget =
  | { readonly kind: "activity"; readonly id: string }
  | { readonly kind: "store"; readonly sku: string }
  | { readonly kind: "post"; readonly id: string }
  | { readonly kind: "home" };

export interface LinkPolicy {
  readonly schemes: readonly string[];
  readonly hosts: readonly string[];
  readonly maxLength: number;
  readonly campaignMaxLength: number;
}

export interface DeepLink {
  readonly source: LinkSource;
  readonly campaign: string;
  readonly target: RouteTarget;
  readonly raw: string;
}

export interface AppContext {
  readonly loggedIn: boolean;
  readonly appVersion: number;
  readonly minVersion: number;
  readonly activityIds: readonly string[];
  readonly skuIds: readonly string[];
  readonly postIds: readonly string[];
}

export interface RouteDecision {
  readonly kind: RouteKind;
  readonly id: string | null;
  readonly campaign: string;
  readonly status: RouteStatus;
  readonly requiresLogin: boolean;
  readonly requiresUpgrade: boolean;
  readonly reason: string;
}

export interface PendingLink {
  readonly link: DeepLink;
  readonly receivedAtMs: number;
  readonly attempts: number;
}

export interface RecoveryPolicy {
  readonly ttlMs: number;
  readonly maxAttempts: number;
}

export interface RecoveryResult {
  readonly action: "resume" | "discard";
  readonly reason: string;
  readonly link: DeepLink | null;
  readonly attempts: number;
}

const MAX_TARGET_ID_LENGTH = 128;

function decodeTargetId(segment: string | null): string {
  if (segment === null) throw new RangeError("deep link target is missing an id");
  let id: string;
  try {
    id = decodeURIComponent(segment);
  } catch {
    throw new RangeError(`deep link target id is not valid percent-encoding: ${segment}`);
  }
  const trimmed = id.trim();
  if (trimmed === "") throw new RangeError("deep link target id must not be empty");
  if (trimmed.length > MAX_TARGET_ID_LENGTH) {
    throw new RangeError(`deep link target id is too long: ${trimmed.length}`);
  }
  if (/[\s/]/.test(trimmed)) {
    throw new RangeError(`deep link target id contains whitespace or a slash: ${trimmed}`);
  }
  return trimmed;
}

function sanitizeCampaign(value: string | null, maxLength: number): string {
  if (value === null) return "organic";
  const cleaned = value.trim().replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, maxLength);
  return cleaned === "" ? "organic" : cleaned;
}

function buildTarget(kindSegment: string, idSegment: string | null): RouteTarget {
  switch (kindSegment) {
    case "activity":
      return { kind: "activity", id: decodeTargetId(idSegment) };
    case "store":
      return { kind: "store", sku: decodeTargetId(idSegment) };
    case "post":
      return { kind: "post", id: decodeTargetId(idSegment) };
    case "home":
      return { kind: "home" };
    default:
      throw new RangeError(`unknown deep link target kind: ${kindSegment}`);
  }
}

export function parseDeepLink(
  raw: string,
  policy: LinkPolicy,
  source: LinkSource = "push",
): DeepLink {
  if (typeof raw !== "string" || raw.trim() === "") {
    throw new RangeError("deep link must not be empty");
  }
  const trimmed = raw.trim();
  if (trimmed.length > policy.maxLength) {
    throw new RangeError(`deep link exceeds ${policy.maxLength} characters`);
  }
  if (!Number.isInteger(policy.campaignMaxLength) || policy.campaignMaxLength < 1) {
    throw new RangeError("campaignMaxLength must be a positive integer");
  }
  let url: URL;
  try {
    url = new URL(trimmed);
  } catch {
    throw new RangeError(`deep link is not a valid URL: ${trimmed}`);
  }
  const scheme = url.protocol.replace(/:$/, "").toLowerCase();
  let kindSegment: string;
  let idSegment: string | null;
  if (scheme === "http" || scheme === "https") {
    const host = url.host.toLowerCase();
    if (!policy.hosts.includes(host)) {
      throw new RangeError(`deep link host is not allowed: ${host}`);
    }
    const parts = url.pathname.split("/").filter((part) => part !== "");
    kindSegment = parts[0] ?? "";
    idSegment = parts[1] ?? null;
  } else {
    if (!policy.schemes.includes(scheme)) {
      throw new RangeError(`deep link scheme is not allowed: ${scheme}`);
    }
    kindSegment = url.host.toLowerCase();
    idSegment = url.pathname.replace(/^\/+/, "") || null;
  }
  return {
    source,
    campaign: sanitizeCampaign(url.searchParams.get("campaign"), policy.campaignMaxLength),
    target: buildTarget(kindSegment, idSegment),
    raw: trimmed,
  };
}

function targetId(target: RouteTarget): string | null {
  return target.kind === "home" ? null : target.kind === "store" ? target.sku : target.id;
}

function needsLogin(kind: RouteKind): boolean {
  return kind === "activity" || kind === "store";
}

function targetAvailable(target: RouteTarget, context: AppContext): boolean {
  switch (target.kind) {
    case "home":
      return true;
    case "activity":
      return context.activityIds.includes(target.id);
    case "store":
      return context.skuIds.includes(target.sku);
    case "post":
      return context.postIds.includes(target.id);
  }
}

export function resolveRoute(link: DeepLink, context: AppContext): RouteDecision {
  if (!Number.isFinite(context.appVersion) || !Number.isFinite(context.minVersion)) {
    throw new RangeError("appVersion and minVersion must be finite numbers");
  }
  const target = link.target;
  const requiresLogin = needsLogin(target.kind);
  const requiresUpgrade = context.appVersion < context.minVersion;
  const base = {
    kind: target.kind,
    id: targetId(target),
    campaign: link.campaign,
    requiresLogin,
    requiresUpgrade,
  };
  if (requiresUpgrade) {
    return { ...base, status: "upgrade-required", reason: "app-version-below-minimum" };
  }
  if (!targetAvailable(target, context)) {
    return { ...base, kind: "home", id: null, status: "fallback", reason: "target-unavailable" };
  }
  if (requiresLogin && !context.loggedIn) {
    return { ...base, status: "login-required", reason: "login-required" };
  }
  return { ...base, status: "ready", reason: "resolved" };
}

export function recoverPendingLink(
  pending: PendingLink,
  context: AppContext,
  policy: RecoveryPolicy,
  nowMs: number,
): RecoveryResult {
  if (!Number.isFinite(pending.receivedAtMs) || !Number.isFinite(nowMs)) {
    throw new RangeError("receivedAtMs and nowMs must be finite numbers");
  }
  if (nowMs < pending.receivedAtMs) {
    throw new RangeError("nowMs cannot be earlier than receivedAtMs");
  }
  if (!Number.isInteger(pending.attempts) || pending.attempts < 0) {
    throw new RangeError("attempts must be a non-negative integer");
  }
  if (!Number.isFinite(policy.ttlMs) || policy.ttlMs <= 0) {
    throw new RangeError("ttlMs must be a positive finite number");
  }
  if (!Number.isInteger(policy.maxAttempts) || policy.maxAttempts < 1) {
    throw new RangeError("maxAttempts must be a positive integer");
  }
  if (nowMs - pending.receivedAtMs > policy.ttlMs) {
    return { action: "discard", reason: "expired", link: null, attempts: pending.attempts };
  }
  if (pending.attempts >= policy.maxAttempts) {
    return { action: "discard", reason: "attempts-exhausted", link: null, attempts: pending.attempts };
  }
  const decision = resolveRoute(pending.link, context);
  if (decision.status === "upgrade-required") {
    return { action: "discard", reason: "upgrade-required", link: null, attempts: pending.attempts };
  }
  if (decision.status === "fallback") {
    return { action: "discard", reason: "target-unavailable", link: null, attempts: pending.attempts };
  }
  return { action: "resume", reason: decision.status, link: pending.link, attempts: pending.attempts + 1 };
}

export function formatRouteDecision(decision: RouteDecision): string {
  const target = decision.id === null ? decision.kind : `${decision.kind}:${decision.id}`;
  return `${target} status=${decision.status} campaign=${decision.campaign} login=${decision.requiresLogin} upgrade=${decision.requiresUpgrade} reason=${decision.reason}`;
}