《互联网产品的客户端架构·交易、增长与平台化》6.3 退款与售后状态

// file: src/reconcile/refund.ts
// tier: L1
// verify: node --test test/reconcile/refund.test.ts

export type RefundState = "reviewing" | "refunding" | "settled" | "failed";

export interface RefundOrder {
  refundId: string; orderId: string; payId: string; amountCents: number;
  state: RefundState; reason: string; requestedAt: number; updatedAt: number;
  settledAt: number | null; attempts: number;
}

export interface PaymentForRefund { payId: string; orderId: string; paidCents: number; paid: boolean; }

export interface RefundLine { skuId: string; title: string; unitPriceCents: number; quantity: number; }

export interface RefundRequest { orderId: string; payId: string; amountCents: number; reason: string; }

export type RefundScope = "full" | "partial";

export interface RefundAllocation { skuId: string; cents: number; }

export interface RefundSummary { settledCents: number; inFlightCents: number; failedCents: number; }

export interface RefundView {
  label: string; hint: string; stage: number; settledAt: number | null;
  action: "none" | "wait" | "retry" | "contact";
}

const BUDGET_STATES: RefundState[] = ["reviewing", "refunding", "settled"];

const TRANSITIONS: Record<RefundState, RefundState[]> = {
  reviewing: ["refunding", "failed"],
  refunding: ["settled", "failed"],
  settled: [],
  failed: ["refunding"],
};

function assertCents(cents: number, label: string): void {
  if (!Number.isSafeInteger(cents) || cents <= 0) {
    throw new Error(`${label}必须是正整数分`);
  }
}

function assertPayment(payment: PaymentForRefund): void {
  if (payment.payId.trim() === "") throw new Error("支付单号不能为空");
  if (payment.orderId.trim() === "") throw new Error("订单号不能为空");
  assertCents(payment.paidCents, "实付金额");
  if (!payment.paid) throw new Error("支付单未支付，不能退款");
}

function assertRefunds(payment: PaymentForRefund, refunds: RefundOrder[]): void {
  for (const refund of refunds) {
    if (refund.payId !== payment.payId) {
      throw new Error(`退款单 ${refund.refundId} 不属于支付单 ${payment.payId}`);
    }
    assertCents(refund.amountCents, `退款金额 ${refund.refundId}`);
  }
}

// 已退与在途都占用额度，失败退款释放额度。
export function refundableCents(payment: PaymentForRefund, refunds: RefundOrder[]): number {
  assertPayment(payment);
  assertRefunds(payment, refunds);
  const used = refunds
    .filter((refund) => BUDGET_STATES.includes(refund.state))
    .reduce((sum, refund) => sum + refund.amountCents, 0);
  if (used > payment.paidCents) {
    throw new Error("历史退款金额已超过实付金额");
  }
  return payment.paidCents - used;
}

export function classifyRefund(
  payment: PaymentForRefund,
  refunds: RefundOrder[],
  amountCents: number,
): RefundScope {
  assertCents(amountCents, "退款金额");
  const remaining = refundableCents(payment, refunds);
  if (amountCents > remaining) {
    throw new Error(`退款金额超过可退额度：${amountCents} > ${remaining}`);
  }
  return amountCents === payment.paidCents ? "full" : "partial";
}

// 退款单必须挂在原支付单上，且只能退实付金额。
export function planRefund(
  payment: PaymentForRefund,
  refunds: RefundOrder[],
  request: RefundRequest,
  now: number,
): RefundOrder {
  assertPayment(payment);
  if (request.payId !== payment.payId) throw new Error("退款支付单号与支付单不一致");
  if (request.orderId !== payment.orderId) throw new Error("退款订单号与支付单不一致");
  const reason = request.reason.trim();
  if (reason === "") throw new Error("退款原因不能为空");
  if (!Number.isFinite(now)) throw new Error("申请时间必须是有限数字");
  const scope = classifyRefund(payment, refunds, request.amountCents);
  const seq = refunds.filter((refund) => refund.payId === payment.payId).length + 1;
  return {
    refundId: `rf-${payment.payId}-${seq}`,
    orderId: payment.orderId,
    payId: payment.payId,
    amountCents: request.amountCents,
    state: "reviewing",
    reason,
    requestedAt: now,
    updatedAt: now,
    settledAt: null,
    attempts: 0,
  };
}

// 状态迁移是白名单；失败可重试，已到账不可回退。
export function transitionRefund(
  refund: RefundOrder,
  to: RefundState,
  now: number,
): RefundOrder {
  if (!Number.isFinite(now)) throw new Error("状态时间必须是有限数字");
  if (!TRANSITIONS[refund.state].includes(to)) {
    throw new Error(`退款状态不能从 ${refund.state} 变为 ${to}`);
  }
  const next: RefundOrder = {
    ...refund,
    state: to,
    updatedAt: now,
    settledAt: to === "settled" ? now : null,
  };
  if (to === "failed") next.attempts = refund.attempts + 1;
  return next;
}

// 按行金额比例分摊退款，最大余数法保证分摊之和精确等于退款金额。
export function allocateRefund(lines: RefundLine[], amountCents: number): RefundAllocation[] {
  if (lines.length === 0) throw new Error("退款分摊需要至少一条订单行");
  if (!Number.isSafeInteger(amountCents) || amountCents < 0) {
    throw new Error("分摊金额必须是非负整数分");
  }
  let total = 0;
  for (const line of lines) {
    if (line.skuId.trim() === "") throw new Error("订单行缺少 SKU");
    if (!Number.isSafeInteger(line.unitPriceCents) || line.unitPriceCents < 0) {
      throw new Error(`单价非法：${line.skuId}`);
    }
    if (!Number.isInteger(line.quantity) || line.quantity < 1) {
      throw new Error(`数量非法：${line.skuId}`);
    }
    const lineTotal = line.unitPriceCents * line.quantity;
    if (!Number.isSafeInteger(lineTotal)) throw new Error(`行金额溢出：${line.skuId}`);
    total += lineTotal;
    if (!Number.isSafeInteger(total)) throw new Error("订单金额溢出");
  }
  if (amountCents > total) {
    throw new Error(`分摊金额超过订单总额：${amountCents} > ${total}`);
  }
  if (total === 0) {
    if (amountCents > 0) throw new Error("订单总额为零，不能分摊退款");
    return lines.map((line) => ({ skuId: line.skuId, cents: 0 }));
  }
  const shares = lines.map((line) => {
    const lineTotal = line.unitPriceCents * line.quantity;
    const product = amountCents * lineTotal;
    if (!Number.isSafeInteger(product)) throw new Error(`分摊计算溢出：${line.skuId}`);
    return {
      skuId: line.skuId,
      cents: Math.floor(product / total),
      fraction: product % total,
      index: 0,
    };
  });
  let remainder = amountCents - shares.reduce((sum, share) => sum + share.cents, 0);
  const order = shares
    .map((share, index) => ({ index, fraction: share.fraction }))
    .sort((a, b) => (a.fraction === b.fraction ? a.index - b.index : b.fraction - a.fraction));
  for (const item of order) {
    if (remainder === 0) break;
    shares[item.index].cents += 1;
    remainder -= 1;
  }
  const sum = shares.reduce((acc, share) => acc + share.cents, 0);
  if (sum !== amountCents) throw new Error("退款分摊结果与退款金额不一致");
  return shares.map((share) => ({ skuId: share.skuId, cents: share.cents }));
}

export function arrivalEstimate(channel: string): string {
  switch (channel.trim()) {
    case "alipay":
      return "预计 1-2 个工作日到账";
    case "wechat":
      return "预计 1-3 个工作日到账";
    case "card":
      return "预计 3-7 个工作日到账";
    default:
      return "预计 1-5 个工作日到账";
  }
}

// 端上只展示服务端给的退款状态，不自行推测到账。
export function refundView(refund: RefundOrder, channel = "unknown"): RefundView {
  switch (refund.state) {
    case "reviewing":
      return {
        label: "审核中",
        hint: "预计 1 个工作日内完成审核",
        stage: 1,
        settledAt: null,
        action: "wait",
      };
    case "refunding":
      return {
        label: "退款中",
        hint: arrivalEstimate(channel),
        stage: 2,
        settledAt: null,
        action: "wait",
      };
    case "settled":
      return {
        label: "已到账",
        hint: "退款已原路退回",
        stage: 3,
        settledAt: refund.settledAt,
        action: "none",
      };
    default:
      return refund.attempts >= 3
        ? {
            label: "退款失败",
            hint: "多次退款未成功，请联系客服",
            stage: 0,
            settledAt: null,
            action: "contact",
          }
        : {
            label: "退款失败",
            hint: "可重新发起退款",
            stage: 0,
            settledAt: null,
            action: "retry",
          };
  }
}

export function summarizeRefunds(refunds: RefundOrder[]): RefundSummary {
  let settledCents = 0;
  let inFlightCents = 0;
  let failedCents = 0;
  for (const refund of refunds) {
    assertCents(refund.amountCents, `退款金额 ${refund.refundId}`);
    if (refund.state === "settled") settledCents += refund.amountCents;
    else if (refund.state === "failed") failedCents += refund.amountCents;
    else inFlightCents += refund.amountCents;
  }
  return { settledCents, inFlightCents, failedCents };
}

$ node --test --test-concurrency=1 test/reconcile/refund.test.ts
✔ 可退金额扣除已退与在途 (0.65875ms)
✔ 失败退款不占用可退额度 (0.070625ms)
✔ 小于实付金额的退款是部分退 (0.066166ms)
✔ 等于实付金额的退款是整单退 (0.054333ms)
✔ 超过可退额度的退款被拒绝 (0.288333ms)
✔ 零或负退款金额被拒绝 (0.143ms)
✔ 未支付的支付单不能退款 (0.07525ms)
✔ 退款单必须挂在原支付单与原订单上 (0.14725ms)
✔ 多笔退款累计不能超过实付金额 (0.132083ms)
✔ 失败退款释放额度后可以重新申请整单退 (0.154416ms)
✔ 整单退按行金额分摊 (0.606417ms)
✔ 部分退分摊之和精确等于退款金额 (0.085334ms)
✔ 最大余数法把剩余分给小数部分更大的行 (0.0815ms)
✔ 分摊金额超过订单总额被拒绝 (0.061625ms)
✔ 空明细无法分摊退款 (0.062875ms)
✔ 审核中可以直接进入退款中 (0.042ms)
✔ 退款中到已到账时记录到账时间 (0.037208ms)
✔ 已到账的退款不能回退状态 (0.061667ms)
✔ 审核中可以直接失败并记录一次尝试 (0.034ms)
✔ 失败后可重新发起并累计失败次数 (0.048333ms)
✔ 四种退款状态有稳定的展示口径 (0.155125ms)
✔ 失败三次后引导联系客服 (0.037041ms)
✔ 按渠道给出到账时间口径 (0.037333ms)
✔ 汇总已退、在途与失败金额 (0.060042ms)
ℹ tests 24
ℹ suites 0
ℹ pass 24
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 131.004875