《互联网产品的客户端架构·规模化与架构演进》2.3 多品牌与多业务复用

// file: src/design/multi-brand.ts
// tier: L1
// verify: node --test test/design/multi-brand.test.ts

import { ALL_TOKENS } from "./design-tokens.ts";
import type { TokenTier } from "./design-tokens.ts";

export type PackageKind = "brand" | "business";
export type LayerName = "brand" | "business";

export type BrandPackage = {
  id: string;
  brand: string;
  kind: PackageKind;
  overrides: Record<string, string>;
};
export type MergeConflict = {
  token: string;
  layer: LayerName;
  contenders: { packageId: string; value: string }[];
};
export type ShadowedOverride = { token: string; from: string; by: string };
export type RejectedPackage = { packageId: string; errors: string[] };
export type MergeResult = {
  brand: string;
  values: Record<string, string>;
  applied: string[];
  rejected: RejectedPackage[];
  conflicts: MergeConflict[];
  shadowed: ShadowedOverride[];
};
export type UsageRecord = { business: string; component: string };
export type ReuseScore = { component: string; businesses: string[]; reuse: number };

export const PLATFORM_BASE: Record<string, string> = {
  "color.bg.canvas": "#ffffff",
  "color.text.primary": "#111827",
  "color.action.primary": "#3b82f6",
  "button.radius": "4px",
  "button.height.md": "40px",
  "business.checkout.accent": "#3b82f6",
  "business.profile.accent": "#3b82f6",
};

export const SAMPLE_PACKAGES: BrandPackage[] = [
  {
    id: "brand-shared",
    brand: "shared",
    kind: "brand",
    overrides: { "button.radius": "6px" },
  },
  {
    id: "brand-aurora",
    brand: "aurora",
    kind: "brand",
    overrides: {
      "color.action.primary": "#7c3aed",
      "button.radius": "8px",
      "button.height.md": "48px",
    },
  },
  {
    id: "brand-nebula",
    brand: "nebula",
    kind: "brand",
    overrides: { "color.action.primary": "#0ea5e9" },
  },
  {
    id: "aurora-checkout",
    brand: "aurora",
    kind: "business",
    overrides: {
      "business.checkout.accent": "#7c3aed",
      "button.height.md": "44px",
    },
  },
  {
    id: "aurora-profile",
    brand: "aurora",
    kind: "business",
    overrides: { "business.profile.accent": "#7c3aed" },
  },
  {
    id: "nebula-checkout",
    brand: "nebula",
    kind: "business",
    overrides: { "business.checkout.accent": "#0ea5e9" },
  },
];

const TIER_BY_NAME: Map<string, TokenTier> = new Map(
  ALL_TOKENS.map((token) => [token.name, token.tier]),
);

export function packageRank(pkg: BrandPackage): number {
  if (pkg.kind === "brand") {
    return pkg.brand === "shared" ? 1 : 2;
  }
  return pkg.brand === "shared" ? 3 : 4;
}

export function packageLayer(pkg: BrandPackage): LayerName {
  return pkg.kind;
}

export function validatePackage(pkg: BrandPackage): string[] {
  const errors: string[] = [];
  if (pkg.id.trim() === "") {
    errors.push("package id 不能为空");
  }
  if (pkg.kind === "brand" && pkg.brand.trim() === "") {
    errors.push("品牌包必须声明 brand");
  }
  for (const token of Object.keys(pkg.overrides)) {
    const tier = TIER_BY_NAME.get(token);
    if (pkg.kind === "brand" && tier === "primitive") {
      errors.push(`品牌包不得覆盖原始 token: ${token}`);
    }
    if (pkg.kind === "business") {
      if (tier === "primitive" || tier === "semantic") {
        errors.push(`业务包不得覆盖基础 token: ${token}`);
      }
      if (tier === undefined && !token.startsWith("business.")) {
        errors.push(`业务包只能扩展 business.* token: ${token}`);
      }
    }
  }
  return errors;
}

export function selectPackages(brand: string, packages: BrandPackage[]): BrandPackage[] {
  return packages.filter((pkg) => pkg.brand === "shared" || pkg.brand === brand);
}

export function mergeForBrand(
  brand: string,
  packages: BrandPackage[],
  base: Record<string, string> = PLATFORM_BASE,
): MergeResult {
  const selected = selectPackages(brand, packages);
  const rejected: RejectedPackage[] = [];
  const valid: BrandPackage[] = [];

  for (const pkg of selected) {
    const errors = validatePackage(pkg);
    if (errors.length > 0) {
      rejected.push({ packageId: pkg.id, errors });
    } else {
      valid.push(pkg);
    }
  }

  valid.sort(
    (a, b) =>
      packageRank(a) - packageRank(b) || a.id.localeCompare(b.id),
  );

  const values: Record<string, string> = { ...base };
  const owners = new Map<string, { rank: number; packageId: string; value: string }>();
  for (const [token, value] of Object.entries(base)) {
    owners.set(token, { rank: 0, packageId: "platform", value });
  }

  const shadowed: ShadowedOverride[] = [];
  const conflicts = new Map<string, MergeConflict>();

  for (const pkg of valid) {
    const rank = packageRank(pkg);
    const layer = packageLayer(pkg);
    for (const [token, value] of Object.entries(pkg.overrides)) {
      const existing = owners.get(token);
      if (existing === undefined) {
        owners.set(token, { rank, packageId: pkg.id, value });
        values[token] = value;
        continue;
      }
      if (existing.rank === rank) {
        if (existing.value !== value) {
          const key = `${layer}:${token}`;
          const conflict = conflicts.get(key) ?? {
            token,
            layer,
            contenders: [{ packageId: existing.packageId, value: existing.value }],
          };
          conflict.contenders.push({ packageId: pkg.id, value });
          conflicts.set(key, conflict);
        }
        continue;
      }
      if (existing.value !== value) {
        shadowed.push({ token, from: existing.packageId, by: pkg.id });
      }
      owners.set(token, { rank, packageId: pkg.id, value });
      values[token] = value;
    }
  }

  return {
    brand,
    values,
    applied: valid.map((pkg) => pkg.id),
    rejected,
    conflicts: [...conflicts.values()].sort((a, b) =>
      a.token.localeCompare(b.token),
    ),
    shadowed,
  };
}

export function reuseMatrix(usages: UsageRecord[]): Record<string, string[]> {
  const grouped = new Map<string, Set<string>>();
  for (const usage of usages) {
    if (usage.business.trim() === "" || usage.component.trim() === "") {
      continue;
    }
    const existing = grouped.get(usage.component) ?? new Set<string>();
    existing.add(usage.business);
    grouped.set(usage.component, existing);
  }
  const matrix: Record<string, string[]> = {};
  for (const component of [...grouped.keys()].sort()) {
    matrix[component] = [...(grouped.get(component) ?? new Set<string>())].sort();
  }
  return matrix;
}

export function reuseScores(usages: UsageRecord[]): ReuseScore[] {
  const matrix = reuseMatrix(usages);
  const totalBusinesses = new Set(
    usages
      .filter((usage) => usage.business.trim() !== "" && usage.component.trim() !== "")
      .map((usage) => usage.business),
  ).size;
  return Object.entries(matrix)
    .map(([component, businesses]) => ({
      component,
      businesses,
      reuse: totalBusinesses === 0 ? 0 : businesses.length / totalBusinesses,
    }))
    .sort(
      (a, b) =>
        b.reuse - a.reuse || a.component.localeCompare(b.component),
    );
}

export function sharedComponents(usages: UsageRecord[], minimum = 2): string[] {
  return reuseScores(usages)
    .filter((score) => score.businesses.length >= minimum)
    .map((score) => score.component)
    .sort();
}

export function forkCandidates(usages: UsageRecord[]): string[] {
  return reuseScores(usages)
    .filter((score) => score.businesses.length === 1)
    .map((score) => score.component)
    .sort();
}

export const SAMPLE_USAGE: UsageRecord[] = [
  { business: "checkout", component: "Button" },
  { business: "profile", component: "Button" },
  { business: "checkout", component: "Input" },
  { business: "profile", component: "Input" },
  { business: "search", component: "Input" },
  { business: "search", component: "Carousel" },
  { business: "checkout", component: "Carousel" },
  { business: "search", component: "Toast" },
  { business: "checkout", component: "Button" },
];