《互联网产品的客户端架构·规模化与架构演进》13.1 端到端：多端同一笔交易的体验一致性

// file: src/summary/multi-end-e2e.ts
// tier: L2
// verify: node --test test/summary/multi-end-e2e.test.ts

export type EndpointId = "web" | "ios" | "android" | "miniprogram" | "desktop";
export type FieldId = "amountCents" | "displayAmount" | "currency" | "orderStatus" | "paymentStatus" | "statusCopy";
export type PromiseLevel = "identical" | "equivalent" | "allowed-diff";
export type DifferenceClass = "none" | "presentation" | "environment" | "contract" | "unknown";

export type FieldAssertion = { field: FieldId; promise: PromiseLevel; allowedValues?: string[] };

export type Scenario = {
  id: string;
  title: string;
  requiredEnds: EndpointId[];
  fields: FieldAssertion[];
  environmentDiffs?: FieldId[];
  observations: Partial<Record<EndpointId, Partial<Record<FieldId, string>>>>;
};

export type FieldResult = {
  field: FieldId;
  promise: PromiseLevel;
  values: Partial<Record<EndpointId, string>>;
  missing: EndpointId[];
  difference: DifferenceClass;
  detail: string;
};

export type Decision = "pass" | "warn" | "block";
export type ScenarioResult = {
  id: string;
  title: string;
  decision: Decision;
  fields: FieldResult[];
  blockers: string[];
  warnings: string[];
};
export type ReleaseResult = {
  decision: Decision;
  passed: string[];
  warned: string[];
  blocked: string[];
};

export const ENDPOINTS: EndpointId[] = ["web", "ios", "android", "miniprogram", "desktop"];

const STATUS_ALIASES: Record<string, string> = {
  paid: "paid", success: "paid", 已支付: "paid", 支付成功: "paid", 已付款: "paid",
  shipped: "shipped", 待发货: "shipped", 已发货: "shipped",
  pending: "pending", 处理中: "pending", 待支付: "pending",
  refunding: "refunding", 退款中: "refunding", 退款处理中: "refunding",
};

export function normalizeValue(field: FieldId, value: string): string {
  const trimmed = value.trim();
  if (field === "amountCents") {
    const parsed = Number(trimmed);
    return Number.isFinite(parsed) ? String(parsed) : trimmed;
  }
  if (field === "displayAmount") return trimmed.replace(/\s+/g, " ");
  if (field === "currency") return trimmed.toUpperCase();
  const lower = trimmed.toLowerCase();
  return STATUS_ALIASES[trimmed] ?? STATUS_ALIASES[lower] ?? lower.replace(/\s+/g, "");
}

export function evaluateField(assertion: FieldAssertion, scenario: Scenario): FieldResult {
  const values: Partial<Record<EndpointId, string>> = {};
  const missing: EndpointId[] = [];
  for (const endpoint of scenario.requiredEnds) {
    const value = scenario.observations[endpoint]?.[assertion.field];
    if (value === undefined) missing.push(endpoint);
    else values[endpoint] = value;
  }
  const base = { field: assertion.field, promise: assertion.promise, values, missing };
  if (missing.length > 0) {
    return { ...base, difference: "unknown", detail: `缺少观测：${missing.join(", ")}` };
  }

  const raws = scenario.requiredEnds.map((endpoint) => values[endpoint] as string);
  const normalized = raws.map((value) => normalizeValue(assertion.field, value));
  const unique = [...new Set(normalized)];
  if (unique.length === 1) {
    const rawDiffer = new Set(raws).size > 1;
    return { ...base, difference: rawDiffer ? "presentation" : "none", detail: rawDiffer ? "归一化后一致" : "逐字一致" };
  }
  if (assertion.promise === "identical") {
    return { ...base, difference: "contract", detail: `承诺逐字一致，实际 ${unique.length} 种取值` };
  }
  if (assertion.promise === "equivalent") {
    return { ...base, difference: "contract", detail: `承诺语义等价，归一化后仍不一致：${unique.join(" / ")}` };
  }

  const allowed = new Set((assertion.allowedValues ?? []).map((v) => normalizeValue(assertion.field, v)));
  if (normalized.every((value) => allowed.has(value))) {
    return { ...base, difference: "presentation", detail: "取值均在登记的白名单内" };
  }
  return { ...base, difference: "unknown", detail: `出现未登记取值：${unique.filter((v) => !allowed.has(v)).join(" / ")}` };
}

export function evaluateScenario(scenario: Scenario): ScenarioResult {
  const environment = new Set(scenario.environmentDiffs ?? []);
  const fields = scenario.fields.map((assertion) => {
    const result = evaluateField(assertion, scenario);
    if (result.difference === "presentation" && environment.has(result.field)) {
      return { ...result, difference: "environment" as DifferenceClass, detail: "已登记的环境差异" };
    }
    return result;
  });
  const blockers = fields
    .filter((r) => r.difference === "contract" || r.difference === "unknown")
    .map((r) => `${scenario.id}.${r.field}`);
  const warnings = fields
    .filter((r) => r.difference === "presentation" || r.difference === "environment")
    .map((r) => `${scenario.id}.${r.field}`);
  const decision: Decision = blockers.length > 0 ? "block" : warnings.length > 0 ? "warn" : "pass";
  return { id: scenario.id, title: scenario.title, decision, fields, blockers, warnings };
}

export function releaseDecision(results: ScenarioResult[]): ReleaseResult {
  const passed = results.filter((r) => r.decision === "pass").map((r) => r.id);
  const warned = results.filter((r) => r.decision === "warn").map((r) => r.id);
  const blocked = results.filter((r) => r.decision === "block").map((r) => r.id);
  const decision: Decision = blocked.length > 0 ? "block" : warned.length > 0 ? "warn" : "pass";
  return { decision, passed, warned, blocked };
}

export function differenceSummary(results: ScenarioResult[]): Record<DifferenceClass, number> {
  const summary: Record<DifferenceClass, number> = {
    none: 0, presentation: 0, environment: 0, contract: 0, unknown: 0,
  };
  for (const scenario of results) {
    for (const field of scenario.fields) summary[field.difference] += 1;
  }
  return summary;
}

export function scenarioCoverage(scenario: Scenario): number {
  const covered = scenario.requiredEnds.filter((endpoint) =>
    scenario.fields.every((assertion) => scenario.observations[endpoint]?.[assertion.field] !== undefined),
  );
  return covered.length / scenario.requiredEnds.length;
}

const ALL_ENDS: EndpointId[] = ENDPOINTS;
const BASE_FIELDS: FieldAssertion[] = [
  { field: "amountCents", promise: "identical" },
  { field: "displayAmount", promise: "identical" },
  { field: "currency", promise: "equivalent" },
  { field: "orderStatus", promise: "identical" },
  { field: "paymentStatus", promise: "identical" },
  { field: "statusCopy", promise: "equivalent" },
];

function buildScenario(
  id: string,
  title: string,
  overrides: Partial<Record<EndpointId, Partial<Record<FieldId, string>>>>,
): Scenario {
  const base: Partial<Record<FieldId, string>> = {
    amountCents: "129900", displayAmount: "¥1,299.00", currency: "CNY",
    orderStatus: "paid", paymentStatus: "paid", statusCopy: "已支付",
  };
  const observations: Scenario["observations"] = {};
  for (const endpoint of ALL_ENDS) observations[endpoint] = { ...base, ...(overrides[endpoint] ?? {}) };
  return { id, title, requiredEnds: ALL_ENDS, fields: BASE_FIELDS, observations };
}

export const SAMPLE_SCENARIOS: Scenario[] = [
  buildScenario("paid-order", "已支付订单五端回放", {}),
  buildScenario("copy-only", "文案措辞不同但语义一致", {
    ios: { statusCopy: "支付成功" }, android: { statusCopy: "支付成功" },
  }),
  buildScenario("amount-unit", "金额单位错位", {
    miniprogram: { amountCents: "1299", displayAmount: "¥12.99" },
  }),
  buildScenario("missing-end", "桌面端缺少订单状态", { desktop: { orderStatus: undefined } }),
];