《互联网产品的客户端架构·规模化与架构演进》9.3 区域能力差异与降级

// file: src/i18n/region-capability.ts
// tier: L1
// verify: node --test test/i18n/region-capability.test.ts

export type Capability = "payment" | "logistics" | "maps" | "support";

export type CapabilityState = "native" | "partner" | "limited" | "missing";

export type RegionCode = string;

export type RegionSource = "explicit" | "account" | "ip" | "timezone" | "locale" | "default";

export type RegionInput = {
  explicit?: string;
  account?: string;
  ipCountry?: string;
  timezone?: string;
  locale?: string;
};

export type RegionResolution = {
  region: RegionCode;
  source: RegionSource;
  confidence: number;
  reason: string;
};

export type FallbackStep = {
  state: CapabilityState;
  channel: string;
};

export type DegradationPlan = {
  region: RegionCode;
  capability: Capability;
  state: CapabilityState;
  path: string[];
  degraded: boolean;
};

export const CAPABILITIES: Capability[] = ["payment", "logistics", "maps", "support"];

export const CAPABILITY_RANK: Record<CapabilityState, number> = {
  native: 3,
  partner: 2,
  limited: 1,
  missing: 0,
};

export const DEFAULT_REGION: RegionCode = "US";

export const REGION_CAPABILITIES: Record<RegionCode, Partial<Record<Capability, CapabilityState>>> = {
  CN: { payment: "native", logistics: "native", maps: "native", support: "native" },
  US: { payment: "native", logistics: "partner", maps: "native", support: "native" },
  JP: { payment: "native", logistics: "partner", maps: "partner", support: "limited" },
  SG: { payment: "native", logistics: "partner", maps: "native", support: "native" },
  DE: { payment: "partner", logistics: "partner", maps: "partner", support: "limited" },
  BR: { payment: "partner", logistics: "limited", maps: "partner", support: "limited" },
  IN: { payment: "partner", logistics: "partner", maps: "native", support: "limited" },
  AE: { payment: "partner", logistics: "partner", maps: "native", support: "limited" },
};

export const FALLBACKS: Record<Capability, FallbackStep[]> = {
  payment: [
    { state: "native", channel: "in-app-pay" },
    { state: "partner", channel: "hosted-checkout" },
    { state: "limited", channel: "web-checkout" },
    { state: "missing", channel: "invoice-manual" },
  ],
  logistics: [
    { state: "native", channel: "in-app-tracking" },
    { state: "partner", channel: "carrier-tracking" },
    { state: "limited", channel: "pickup-point" },
    { state: "missing", channel: "manual-tracking" },
  ],
  maps: [
    { state: "native", channel: "in-app-map" },
    { state: "partner", channel: "map-sdk" },
    { state: "limited", channel: "static-map" },
    { state: "missing", channel: "address-text" },
  ],
  support: [
    { state: "native", channel: "in-app-chat" },
    { state: "partner", channel: "vendor-desk" },
    { state: "limited", channel: "email-ticket" },
    { state: "missing", channel: "faq-only" },
  ],
};

export const TIMEZONE_REGIONS: Record<string, RegionCode> = {
  "Asia/Shanghai": "CN",
  "Asia/Chongqing": "CN",
  "Asia/Urumqi": "CN",
  "Asia/Tokyo": "JP",
  "Asia/Seoul": "KR",
  "Asia/Singapore": "SG",
  "Asia/Kolkata": "IN",
  "Asia/Calcutta": "IN",
  "Asia/Dubai": "AE",
  "Europe/Berlin": "DE",
  "Europe/Paris": "FR",
  "Europe/London": "GB",
  "America/New_York": "US",
  "America/Chicago": "US",
  "America/Los_Angeles": "US",
  "America/Sao_Paulo": "BR",
  "America/Argentina": "AR",
  "America/Indiana": "US",
};

const CONFIDENCE: Record<RegionSource, number> = {
  explicit: 1,
  account: 0.9,
  ip: 0.75,
  timezone: 0.55,
  locale: 0.4,
  default: 0.2,
};

export function normalizeRegion(value?: string): RegionCode | undefined {
  if (!value) return undefined;
  const code = value.trim().toUpperCase();
  return /^[A-Z]{2}$/.test(code) ? code : undefined;
}

export function regionFromLocale(locale: string): RegionCode | undefined {
  const parts = locale.replace(/_/g, "-").split("-").filter((part) => part.length > 0);
  for (let index = parts.length - 1; index >= 1; index -= 1) {
    if (/^[A-Za-z]{2}$/.test(parts[index])) return parts[index].toUpperCase();
  }
  return undefined;
}

export function regionFromTimeZone(timeZone: string): RegionCode | undefined {
  const exact = TIMEZONE_REGIONS[timeZone];
  if (exact) return exact;
  for (const [prefix, region] of Object.entries(TIMEZONE_REGIONS)) {
    if (timeZone.startsWith(`${prefix}/`)) return region;
  }
  return undefined;
}

export function capabilityFor(region: string, capability: Capability): CapabilityState {
  const code = normalizeRegion(region);
  if (!code) return "missing";
  return REGION_CAPABILITIES[code]?.[capability] ?? "missing";
}

export function degradationPlan(region: string, capability: Capability): DegradationPlan {
  const state = capabilityFor(region, capability);
  const steps = FALLBACKS[capability];
  const index = steps.findIndex((step) => step.state === state);
  const start = index < 0 ? steps.length - 1 : index;
  const path = state === "native" ? [steps[0].channel] : steps.slice(start).map((step) => step.channel);
  return {
    region: normalizeRegion(region) ?? region.trim().toUpperCase(),
    capability,
    state,
    path,
    degraded: state !== "native",
  };
}

export function capabilityGaps(
  region: string,
  required: Capability[],
  minimum: CapabilityState = "limited",
): Capability[] {
  const threshold = CAPABILITY_RANK[minimum];
  return required.filter((capability) => CAPABILITY_RANK[capabilityFor(region, capability)] < threshold);
}

export function supportedCapabilities(region: string): Capability[] {
  return CAPABILITIES.filter((capability) => capabilityFor(region, capability) !== "missing");
}

function resolution(
  region: RegionCode,
  source: RegionSource,
  reason: string,
): RegionResolution {
  return { region, source, confidence: CONFIDENCE[source], reason };
}

export function resolveRegion(input: RegionInput, fallback: RegionCode = DEFAULT_REGION): RegionResolution {
  const explicit = normalizeRegion(input.explicit);
  if (explicit) return resolution(explicit, "explicit", `explicit region: ${explicit}`);

  const account = normalizeRegion(input.account);
  if (account) return resolution(account, "account", `account region: ${account}`);

  const ip = normalizeRegion(input.ipCountry);
  if (ip) return resolution(ip, "ip", `ip country: ${ip}`);

  if (input.timezone) {
    const fromZone = regionFromTimeZone(input.timezone);
    if (fromZone) return resolution(fromZone, "timezone", `timezone: ${input.timezone}`);
  }

  if (input.locale) {
    const fromLocale = regionFromLocale(input.locale);
    if (fromLocale) return resolution(fromLocale, "locale", `locale: ${input.locale}`);
  }

  const safeFallback = normalizeRegion(fallback) ?? DEFAULT_REGION;
  return resolution(safeFallback, "default", "no signal matched");
}