《互联网产品的客户端架构·内容、社交与实时互动》5.3 回滚的边界：哪些操作不能乐观

// file: src/interaction/rollback.ts
// tier: L1
// verify: node --test test/interaction/rollback.test.ts
export type OperationKind =
  | "like"
  | "favorite"
  | "follow"
  | "comment"
  | "upload"
  | "payment"
  | "order";

export type Reversibility = "instant" | "compensable" | "irreversible";
export type OptimisticPolicy = "optimistic" | "optimistic-with-reconcile" | "confirm-first" | "never";
export type RetryMode = "automatic" | "manual";

export interface OperationProfile {
  kind: OperationKind;
  label: string;
  reversibility: Reversibility;
  externalEffect: boolean;
  settlement: boolean;
  idempotent: boolean;
  serverTruthRequired: boolean;
  localPreview: boolean;
}

export interface Decision {
  kind: OperationKind;
  policy: OptimisticPolicy;
  retry: RetryMode;
  reasons: string[];
  rollback: string;
}

const PROFILES: Record<OperationKind, OperationProfile> = {
  like: {
    kind: "like",
    label: "点赞",
    reversibility: "instant",
    externalEffect: false,
    settlement: false,
    idempotent: true,
    serverTruthRequired: false,
    localPreview: false,
  },
  favorite: {
    kind: "favorite",
    label: "收藏",
    reversibility: "instant",
    externalEffect: false,
    settlement: false,
    idempotent: true,
    serverTruthRequired: false,
    localPreview: false,
  },
  follow: {
    kind: "follow",
    label: "关注",
    reversibility: "instant",
    externalEffect: true,
    settlement: false,
    idempotent: true,
    serverTruthRequired: false,
    localPreview: false,
  },
  comment: {
    kind: "comment",
    label: "评论",
    reversibility: "compensable",
    externalEffect: true,
    settlement: false,
    idempotent: true,
    serverTruthRequired: false,
    localPreview: true,
  },
  upload: {
    kind: "upload",
    label: "上传并发布",
    reversibility: "compensable",
    externalEffect: false,
    settlement: false,
    idempotent: true,
    serverTruthRequired: true,
    localPreview: true,
  },
  payment: {
    kind: "payment",
    label: "支付",
    reversibility: "irreversible",
    externalEffect: false,
    settlement: true,
    idempotent: true,
    serverTruthRequired: true,
    localPreview: false,
  },
  order: {
    kind: "order",
    label: "下单",
    reversibility: "compensable",
    externalEffect: true,
    settlement: true,
    idempotent: true,
    serverTruthRequired: true,
    localPreview: false,
  },
};

const ROLLBACK: Record<OperationKind, string> = {
  like: "恢复计数与选中态，不需要向用户解释",
  favorite: "恢复收藏态，列表与详情共用同一份状态",
  follow: "恢复关注态；对方可能已收到通知，服务端需要去抖",
  comment: "移除本地占位并保留原文，允许重试或改为草稿",
  upload: "撤销本地预览，保留可续传任务，不宣称发布成功",
  payment: "不允许本地回滚，转人工对账与退款流程",
  order: "不允许本地回滚，取消订单由服务端确认库存与支付状态",
};

export function profileOf(kind: OperationKind): OperationProfile {
  return { ...PROFILES[kind] };
}

// 规则有明确优先级：不可逆与结算优先于幂等，服务端真相优先于外部影响。
export function decide(profile: OperationProfile): Decision {
  const reasons: string[] = [];
  const retry = retryMode(profile);

  if (profile.settlement || profile.reversibility === "irreversible") {
    if (profile.settlement) reasons.push("涉及资金或库存结算，服务端是唯一事实来源");
    if (profile.reversibility === "irreversible") reasons.push("操作不可逆，本地没有补偿手段");
    return {
      kind: profile.kind,
      policy: "never",
      retry,
      reasons,
      rollback: ROLLBACK[profile.kind],
    };
  }

  if (profile.serverTruthRequired) {
    reasons.push("完成状态只能由服务端确认，本地只能展示进行中");
    return {
      kind: profile.kind,
      policy: "confirm-first",
      retry,
      reasons,
      rollback: ROLLBACK[profile.kind],
    };
  }

  if (profile.externalEffect || profile.reversibility === "compensable" || !profile.idempotent) {
    if (profile.externalEffect) reasons.push("操作会触达其他人，撤回无法收回已发出的通知");
    if (profile.reversibility === "compensable") reasons.push("回滚有成本，需要服务端对账");
    if (!profile.idempotent) reasons.push("请求不幂等，自动重试可能产生重复副作用");
    return {
      kind: profile.kind,
      policy: "optimistic-with-reconcile",
      retry,
      reasons,
      rollback: ROLLBACK[profile.kind],
    };
  }

  reasons.push("即时可逆、无外部影响且请求幂等");
  return {
    kind: profile.kind,
    policy: "optimistic",
    retry,
    reasons,
    rollback: ROLLBACK[profile.kind],
  };
}

export function retryMode(profile: OperationProfile): RetryMode {
  if (profile.settlement || !profile.idempotent) return "manual";
  return "automatic";
}

export function canAutoRetry(profile: OperationProfile): boolean {
  return retryMode(profile) === "automatic";
}

// 本地最多能表现到什么程度：计数、占位气泡、进度条，或者什么都不做。
export function localRepresentation(
  profile: OperationProfile,
): "count" | "state" | "placeholder" | "progress" | "none" {
  if (profile.settlement || profile.reversibility === "irreversible") return "none";
  if (profile.kind === "upload") return "progress";
  if (profile.kind === "comment") return "placeholder";
  if (profile.kind === "follow") return "state";
  if (profile.kind === "like" || profile.kind === "favorite") return "count";
  return "none";
}

export function decisionTable(): Decision[] {
  return Object.values(PROFILES).map((profile) => decide(profile));
}

$ node --test test/interaction/rollback.test.ts
✔ 点赞与收藏即时可逆、无外部影响，可以完全乐观 (0.606917ms)
✔ 关注虽然即时可逆，但会触达对方，降级为乐观加对账 (0.111542ms)
✔ 评论回滚有成本且对外可见，只允许占位式乐观 (0.073041ms)
✔ 上传完成必须等服务端确认，本地只展示进度与预览 (0.073084ms)
✔ 支付与下单永不乐观，重试也交给人工确认 (0.135875ms)
✔ 不可逆规则优先于幂等与其他标记 (0.080667ms)
✔ 非幂等写操作只能对账式乐观，重试必须人工触发 (0.074708ms)
✔ 决策表覆盖全部操作，策略与回滚说明都不为空 (0.895666ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 197.629