《互联网产品的客户端架构·交易、增长与平台化》5.2 支付结果不确定时的状态机

// file: src/pay/result-state.ts
// tier: L1
// verify: node --test test/pay/result-state.test.ts

export type PayState = "pending" | "unknown" | "succeeded" | "failed" | "cancelled";

export type ReturnHint = "success" | "fail" | "cancel";

export type PayEvent =
  | { kind: "launch_ok"; at: number }
  | { kind: "launch_failed"; at: number; reason: string }
  | { kind: "return_signal"; at: number; result: ReturnHint }
  | { kind: "timeout"; at: number }
  | { kind: "query"; at: number; serverSeq: number; status: PayState; reason?: string };

export interface PaySnapshot {
  state: PayState;
  verified: boolean;
  serverSeq: number | null;
  reason: string | null;
  retries: number;
  history: string[];
}

const PRIORITY: Record<PayState, number> = {
  unknown: 0,
  pending: 1,
  failed: 2,
  cancelled: 3,
  succeeded: 4,
};

export function isTerminal(state: PayState): boolean {
  return state === "succeeded" || state === "failed" || state === "cancelled";
}

export function canRetry(
  state: PayState,
  verified: boolean,
  retries: number,
  maxRetries = 2,
): boolean {
  return state === "failed" && verified && retries < maxRetries;
}

function isPayState(value: string): value is PayState {
  return value in PRIORITY;
}

function requireText(value: string, label: string): string {
  const text = value.trim();
  if (text === "") throw new Error(`${label}不能为空`);
  return text;
}

// 支付结果只能由服务端查询确认；回跳、超时与拉起成功都只是线索。
export class PayResultMachine {
  state: PayState;
  verified: boolean;
  serverSeq: number | null;
  reason: string | null;
  retries: number;
  maxRetries: number;
  history: string[];

  constructor(maxRetries = 2) {
    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
      throw new Error("最大重试次数必须是非负整数");
    }
    this.state = "pending";
    this.verified = false;
    this.serverSeq = null;
    this.reason = null;
    this.retries = 0;
    this.maxRetries = maxRetries;
    this.history = ["init:pending"];
  }

  snapshot(): PaySnapshot {
    return {
      state: this.state,
      verified: this.verified,
      serverSeq: this.serverSeq,
      reason: this.reason,
      retries: this.retries,
      history: [...this.history],
    };
  }

  note(entry: string): void {
    this.history.push(entry);
  }

  apply(event: PayEvent): PaySnapshot {
    if (!Number.isFinite(event.at)) throw new Error("事件时间必须是有限数字");
    switch (event.kind) {
      case "launch_ok":
        if (isTerminal(this.state)) {
          this.note("ignore:launch_ok_terminal");
        } else if (this.state === "pending") {
          this.reason = "launching";
          this.note("launch_ok");
        } else {
          this.note("ignore:launch_ok_late");
        }
        break;
      case "launch_failed": {
        if (this.state === "succeeded") {
          this.note("ignore:absorbing");
          break;
        }
        this.state = "failed";
        this.verified = true;
        this.reason = requireText(event.reason, "失败原因");
        this.note(`launch_failed:${this.reason}`);
        break;
      }
      case "return_signal":
        if (isTerminal(this.state)) {
          this.note("ignore:return_terminal");
        } else {
          this.state = "unknown";
          this.verified = false;
          this.reason = `return_${event.result}_unverified`;
          this.note(`return:${event.result}`);
        }
        break;
      case "timeout":
        if (isTerminal(this.state)) {
          this.note("ignore:timeout_terminal");
        } else if (this.state === "pending") {
          this.state = "unknown";
          this.verified = false;
          this.reason = "timeout";
          this.note("timeout");
        } else {
          this.note("timeout_again");
        }
        break;
      case "query": {
        if (!Number.isInteger(event.serverSeq) || event.serverSeq < 0) {
          throw new Error("服务端序号必须是非负整数");
        }
        if (!isPayState(event.status)) {
          throw new Error(`未知支付状态：${String(event.status)}`);
        }
        if (this.state === "succeeded") {
          this.note("ignore:absorbing");
          break;
        }
        if (!isTerminal(event.status) && isTerminal(this.state)) {
          this.note("ignore:terminal_guard");
          break;
        }
        if (this.serverSeq !== null) {
          if (event.serverSeq < this.serverSeq) {
            this.note(`ignore:stale#${event.serverSeq}`);
            break;
          }
          if (
            event.serverSeq === this.serverSeq &&
            PRIORITY[event.status] <= PRIORITY[this.state]
          ) {
            this.note(`ignore:weaker#${event.serverSeq}`);
            break;
          }
        }
        this.state = event.status;
        this.serverSeq = event.serverSeq;
        this.verified = true;
        this.reason = event.reason ?? (isTerminal(event.status) ? event.status : null);
        this.note(`query:${event.status}#${event.serverSeq}`);
        break;
      }
      default:
        throw new Error("未知支付事件");
    }
    return this.snapshot();
  }

  retryable(maxRetries = this.maxRetries): boolean {
    return canRetry(this.state, this.verified, this.retries, maxRetries);
  }

  recordRetry(): PaySnapshot {
    if (!this.retryable()) throw new Error("当前状态不允许再次支付");
    this.retries += 1;
    this.state = "pending";
    this.verified = false;
    this.serverSeq = null;
    this.reason = "retry_requested";
    this.note(`retry#${this.retries}`);
    return this.snapshot();
  }
}

$ node --test --test-concurrency=1 test/pay/result-state.test.ts
✔ 初始状态是待支付且未经验证 (0.897125ms)
✔ 拉起成功只记录进行中，不改写支付结果 (0.141ms)
✔ 渠道明确拉起失败进入可重试的失败态 (0.092875ms)
✔ 拉起失败不能覆盖已经成功的支付 (0.072875ms)
✔ 回跳成功只进入未知态，不算验证成功 (0.070375ms)
✔ 回跳失败与取消同样只进入未知态 (0.066167ms)
✔ 查询确认成功后才进入成功态 (0.062917ms)
✔ 查询返回待支付时从未知态回到待支付 (0.053ms)
✔ 查询仍不确定时保持未知态 (0.059209ms)
✔ 超时把待支付转为未知但不判失败 (0.103583ms)
✔ 超时不会覆盖已经确认的终态 (0.063625ms)
✔ 旧序号查询结果被忽略 (0.052167ms)
✔ 同序号成功压过失败 (0.051166ms)
✔ 同序号更弱的结果被忽略 (0.051583ms)
✔ 更高序号的终态可以修正先前判断 (0.049458ms)
✔ 成功后吸收后续所有查询 (0.043584ms)
✔ 未知与待支付不能把终态降级 (0.042333ms)
✔ 只有已确认的失败才允许再次支付 (0.042833ms)
✔ 记录重试会回到待支付并递增次数 (0.2585ms)
✔ 取消与成功都不允许再次支付 (0.063584ms)
✔ 非法序号与未知状态被拒绝 (0.09525ms)
✔ 每个事件都留下可排查的历史 (0.044041ms)
✔ 构造时校验最大重试次数 (0.056709ms)
ℹ tests 23
ℹ suites 0
ℹ pass 23
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 135.364167