《互联网产品的客户端架构·交易、增长与平台化》8.3 权益降级与到期提醒

// file: src/member/downgrade.ts
// tier: L1
// verify: node --test test/member/downgrade.test.ts
export type Tier = "free" | "silver" | "gold" | "platinum";
export type ReminderStage = "none" | "advance" | "week" | "final" | "expired";
export type OrderStatus = "pending_payment" | "paid" | "cancelled";
export interface TierBenefit { code: string; title: string; minTier: Tier; }
export interface BenefitLoss { code: string; title: string; text: string; }
export interface BenefitComparison {
  from: Tier; to: Tier; lost: BenefitLoss[]; kept: TierBenefit[];
}
export interface ReminderInput {
  expiresAt: number | null; now: number; autoRenew: boolean;
  optedOut: boolean; lastStage: ReminderStage;
}
export interface ReminderDecision {
  stage: ReminderStage; shouldNotify: boolean; daysLeft: number | null;
  title: string; detail: string;
}
export interface OrderPriceSnapshot {
  orderId: string; status: OrderStatus; createdAt: number; holdUntil: number;
  tierAtPurchase: Tier; listCents: number; memberCents: number | null;
  snapshotCents: number;
}
export interface CurrentMemberQuote { tier: Tier; memberCents: number | null; }
export interface OrderPriceView {
  orderId: string; payableCents: number; source: "snapshot" | "current" | "none";
  locked: boolean; requiresConfirm: boolean; note: string;
}
export interface DowngradeNotice {
  tier: Tier; expired: boolean; title: string; detail: string;
}
const DAY = 86_400_000;
const RANK: Record<Tier, number> = { free: 0, silver: 1, gold: 2, platinum: 3 };
const TIER_TEXT: Record<Tier, string> = {
  free: "普通用户", silver: "白银会员", gold: "黄金会员", platinum: "铂金会员",
};
const STAGE_RANK: Record<ReminderStage, number> = {
  none: 0, advance: 1, week: 2, final: 3, expired: 4,
};
const BENEFITS: TierBenefit[] = [
  { code: "basic", title: "基础购物权益", minTier: "free" },
  { code: "member_price", title: "会员价", minTier: "silver" },
  { code: "free_shipping", title: "免运费", minTier: "silver" },
  { code: "points_boost", title: "积分加速", minTier: "gold" },
  { code: "priority_service", title: "优先客服", minTier: "platinum" },
];
export function tierText(tier: Tier): string {
  assertTier(tier);
  return TIER_TEXT[tier];
}
export function benefitsOf(tier: Tier): TierBenefit[] {
  assertTier(tier);
  return BENEFITS.filter((b) => RANK[b.minTier] <= RANK[tier]).map((b) => ({ ...b }));
}
// 降级比较只回答「少了什么、留下什么」，不把升级写成降级。
export function benefitDiff(from: Tier, to: Tier): BenefitComparison {
  assertTier(from);
  assertTier(to);
  const after = new Set(benefitsOf(to).map((b) => b.code));
  const lost: BenefitLoss[] = [];
  const kept: TierBenefit[] = [];
  for (const benefit of benefitsOf(from)) {
    if (after.has(benefit.code)) {
      kept.push(benefit);
    } else {
      lost.push({
        code: benefit.code, title: benefit.title,
        text: `降级后不再享有${benefit.title}`,
      });
    }
  }
  return { from, to, lost, kept };
}
// 提醒只升不降：同一阶段不重复，跨阶段只提醒一次。
export function reminderFor(input: ReminderInput): ReminderDecision {
  assertReminder(input);
  if (input.expiresAt === null) {
    return none(null, "长期有效，无到期提醒。");
  }
  const daysLeft = daysLeftOf(input.expiresAt, input.now);
  if (input.optedOut) return none(daysLeft, "用户已关闭到期提醒。");
  if (input.autoRenew) return none(daysLeft, "已开启自动续费，到期前不重复提醒。");
  let stage: ReminderStage = "none";
  if (daysLeft <= 0) stage = "expired";
  else if (daysLeft <= 1) stage = "final";
  else if (daysLeft <= 7) stage = "week";
  else if (daysLeft <= 30) stage = "advance";
  if (stage === "none" || STAGE_RANK[stage] <= STAGE_RANK[input.lastStage]) {
    return { stage, shouldNotify: false, daysLeft, title: "", detail: "" };
  }
  const copy = stageCopy(stage, daysLeft);
  return { stage, shouldNotify: true, daysLeft, ...copy };
}
// 已支付订单永久保留快照价；待支付订单只保留到支付截止时间。
export function orderPriceAfterExpiry(
  order: OrderPriceSnapshot,
  current: CurrentMemberQuote,
  now: number,
): OrderPriceView {
  assertOrder(order);
  assertCurrent(current);
  assertTime(now, "查询时间");
  if (order.status === "cancelled") {
    return view(order.orderId, 0, "none", true, false, "订单已取消，不涉及价格。");
  }
  if (order.status === "paid") {
    return view(order.orderId, order.snapshotCents, "snapshot", true, false,
      "已支付订单按下单快照结算，不受会员到期影响。");
  }
  if (now <= order.holdUntil) {
    return view(order.orderId, order.snapshotCents, "snapshot", true, false,
      "会员价保留至支付截止时间。");
  }
  const renewed = current.tier !== "free" && current.memberCents !== null
    && current.memberCents <= order.listCents;
  if (renewed) {
    return view(order.orderId, current.memberCents as number, "current", false, true,
      "已续费，按当前会员价重新确认后支付。");
  }
  return view(order.orderId, order.listCents, "current", false, true,
    "会员价保留期已过，按原价重新确认后支付。");
}
export function downgradeNotice(
  tier: Tier, expiresAt: number | null, now: number,
): DowngradeNotice {
  assertTier(tier);
  assertTime(now, "查询时间");
  if (expiresAt === null) {
    return { tier, expired: false, title: "长期有效", detail: "当前等级没有到期时间，不触发降级。" };
  }
  assertTime(expiresAt, "到期时间");
  if (now >= expiresAt) {
    return {
      tier, expired: true, title: "会员已到期",
      detail: "当前按普通用户权益展示；已支付订单按下单快照结算。",
    };
  }
  const daysLeft = daysLeftOf(expiresAt, now);
  return {
    tier, expired: false, title: `会员将于 ${daysLeft} 天后到期`,
    detail: "到期后会员价与免运费停止；已支付订单不受影响。",
  };
}
function none(daysLeft: number | null, detail: string): ReminderDecision {
  return { stage: "none", shouldNotify: false, daysLeft, title: "", detail };
}
function view(
  orderId: string, payableCents: number, source: OrderPriceView["source"],
  locked: boolean, requiresConfirm: boolean, note: string,
): OrderPriceView {
  return { orderId, payableCents, source, locked, requiresConfirm, note };
}
function stageCopy(
  stage: Exclude<ReminderStage, "none">,
  days: number,
): { title: string; detail: string } {
  if (stage === "expired") {
    return {
      title: "会员已到期",
      detail: "会员价与专属权益已停止，续费后恢复；已支付订单不受影响。",
    };
  }
  if (stage === "final") {
    return {
      title: `会员将在 ${days} 天内到期`,
      detail: "续费后权益立即延续；到期未续费将恢复原价。",
    };
  }
  if (stage === "week") {
    return {
      title: `会员还有 ${days} 天到期`,
      detail: "续费可保留当前权益；已支付订单不受影响。",
    };
  }
  return {
    title: `会员还有 ${days} 天到期`,
    detail: "可提前续费；到期后会员价与免运费将停止。",
  };
}
function daysLeftOf(expiresAt: number, now: number): number {
  return Math.max(0, Math.ceil((expiresAt - now) / DAY));
}
function assertTier(tier: Tier): void {
  if (!(tier in RANK)) throw new Error(`未知会员等级：${String(tier)}`);
}
function assertReminder(input: ReminderInput): void {
  assertTime(input.now, "提醒时间");
  if (input.expiresAt !== null) assertTime(input.expiresAt, "到期时间");
  if (typeof input.autoRenew !== "boolean" || typeof input.optedOut !== "boolean") {
    throw new Error("提醒开关必须是布尔值");
  }
  if (!(input.lastStage in STAGE_RANK)) {
    throw new Error(`未知提醒阶段：${String(input.lastStage)}`);
  }
}
function assertOrder(order: OrderPriceSnapshot): void {
  if (!order.orderId) throw new Error("订单快照缺少订单号");
  if (!(order.status in ORDER_STATUS)) {
    throw new Error(`未知订单状态：${String(order.status)}`);
  }
  assertTier(order.tierAtPurchase);
  assertTime(order.createdAt, "下单时间");
  assertTime(order.holdUntil, "支付截止时间");
  if (order.holdUntil < order.createdAt) throw new Error("支付截止时间不能早于下单时间");
  assertCents(order.listCents, "原价");
  if (order.memberCents !== null) assertCents(order.memberCents, "会员价");
  assertCents(order.snapshotCents, "快照价");
  if (order.snapshotCents > order.listCents) throw new Error("快照价不能高于原价");
}
function assertCurrent(current: CurrentMemberQuote): void {
  assertTier(current.tier);
  if (current.memberCents !== null) assertCents(current.memberCents, "当前会员价");
}
const ORDER_STATUS: Record<OrderStatus, string> = {
  pending_payment: "待支付", paid: "已支付", cancelled: "已取消",
};
function assertCents(cents: number, label: string): void {
  if (!Number.isSafeInteger(cents) || cents < 0) {
    throw new Error(`${label}必须是非负安全整数分`);
  }
}
function assertTime(at: number, label: string): void {
  if (!Number.isSafeInteger(at) || at < 0) {
    throw new Error(`${label}必须是安全整数毫秒`);
  }
}

$ node --test test/member/downgrade.test.ts
✔ 等级文案稳定，普通用户只有基础权益 (0.99125ms)
✔ 白银会员获得会员价与免运费 (0.075041ms)
✔ 黄金会员在白银基础上增加积分加速 (0.058125ms)
✔ 铂金会员拥有全部权益 (0.077583ms)
✔ 白银降为普通用户时列出两项损失并保留基础权益 (0.1195ms)
✔ 黄金降为白银只损失积分加速 (0.080167ms)
✔ 升级不产生任何损失 (0.054667ms)
✔ 距到期超过三十天不提醒 (0.126292ms)
✔ 距到期三十天内进入提前提醒 (0.086708ms)
✔ 距到期七天内进入周提醒 (0.101333ms)
✔ 距到期一天内进入最后提醒 (0.0655ms)
✔ 到期时刻按已到期处理 (0.097792ms)
✔ 开启自动续费后不再重复提醒 (0.062ms)
✔ 用户关闭提醒后不再打扰 (0.050125ms)
✔ 同一阶段重复调用不重复提醒 (0.045166ms)
✔ 提醒阶段可以向后升级一次 (0.045459ms)
✔ 已支付订单在会员到期后仍按下单快照结算 (0.13725ms)
✔ 待支付订单在保留期内仍锁定会员价 (0.05675ms)
✔ 保留期过后未续费按原价重新确认 (0.044708ms)
✔ 保留期过后已续费则使用当前会员价 (0.038417ms)
✔ 已取消订单不展示应付金额 (0.040917ms)
✔ 降级文案区分未到期、已到期与长期有效 (0.066292ms)
✔ 剩余天数向上取整，不足一天按一天显示 (0.038542ms)
✔ 非法等级、订单时间与快照价格被拒绝 (0.228ms)
ℹ tests 24
ℹ suites 0
ℹ pass 24
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 135.885875