《互联网产品的客户端架构·交易、增长与平台化》8.1 会员状态与权益展示

// file: src/member/membership.ts
// tier: L1
// verify: node --test test/member/membership.test.ts
export type MemberTier = "free" | "silver" | "gold" | "platinum";
export type MembershipState = "none" | "active" | "expiring" | "expired";
export type BenefitState =
  | "active" | "expiring" | "claimable" | "used_up" | "not_started" | "expired";
export interface BenefitGrant {
  code: string; title: string; from: number; to: number | null;
  quotaTotal: number | null; quotaUsed: number;
  requiresClaim: boolean; claimed: boolean;
}
export interface MemberSnapshot {
  userId: string; tier: MemberTier; joinedAt: number;
  expiresAt: number | null; autoRenew: boolean; benefits: BenefitGrant[];
}
export interface BenefitView {
  code: string; title: string; state: BenefitState; owned: boolean;
  remainingMs: number | null; remainingQuota: number | null; text: string;
}
export interface MembershipView {
  state: MembershipState; tier: MemberTier; tierText: string;
  daysLeft: number | null; expiresAt: number | null;
  autoRenew: boolean; headline: string;
}
export interface PriceQuote {
  listCents: number; memberCents: number | null; payableCents: number;
  source: "list" | "member"; requiresConfirm: boolean; note: string;
}
export type NoticeLevel = "none" | "info" | "urgent" | "expired";
export interface RenewalNotice {
  level: NoticeLevel; daysLeft: number | null; title: string; detail: string;
}
const DAY = 86_400_000;
const TIER_TEXT: Record<MemberTier, string> = {
  free: "普通用户", silver: "白银会员", gold: "黄金会员", platinum: "铂金会员",
};
const MEMBERSHIP_TEXT: Record<MembershipState, string> = {
  none: "未开通会员", active: "会员有效",
  expiring: "会员即将到期", expired: "会员已到期",
};
const BENEFIT_TEXT: Record<BenefitState, string> = {
  active: "已生效", expiring: "即将到期", claimable: "待领取",
  used_up: "已用完", not_started: "未开始", expired: "已失效",
};
export function tierText(tier: MemberTier): string {
  return TIER_TEXT[tier];
}
// 会员状态只由服务端快照与服务端时间决定，端上计时器不是事实来源。
export function membershipState(
  member: MemberSnapshot,
  now: number,
  warnMs = 7 * DAY,
): MembershipState {
  assertMember(member);
  assertTime(now, "当前时间");
  if (member.tier === "free" && member.expiresAt === null) return "none";
  if (member.expiresAt === null) return "active";
  if (now >= member.expiresAt) return "expired";
  if (member.expiresAt - now <= warnMs) return "expiring";
  return "active";
}
export function membershipView(
  member: MemberSnapshot,
  now: number,
  warnMs = 7 * DAY,
): MembershipView {
  const state = membershipState(member, now, warnMs);
  return {
    state,
    tier: member.tier,
    tierText: tierText(member.tier),
    daysLeft: member.expiresAt === null
      ? null : Math.max(0, Math.ceil((member.expiresAt - now) / DAY)),
    expiresAt: member.expiresAt,
    autoRenew: member.autoRenew,
    headline: MEMBERSHIP_TEXT[state],
  };
}
// 「可领取」不等于「已拥有」；owned 只覆盖真正生效中的权益。
export function benefitView(
  grant: BenefitGrant,
  memberState: MembershipState,
  now: number,
  warnMs = 7 * DAY,
): BenefitView {
  assertGrant(grant);
  assertTime(now, "当前时间");
  let state: BenefitState;
  if (memberState === "none" || memberState === "expired") {
    state = "expired";
  } else if (now < grant.from) {
    state = "not_started";
  } else if (grant.to !== null && now >= grant.to) {
    state = "expired";
  } else if (grant.quotaTotal !== null && grant.quotaUsed >= grant.quotaTotal) {
    state = "used_up";
  } else if (grant.requiresClaim && !grant.claimed) {
    state = "claimable";
  } else if (grant.to !== null && grant.to - now <= warnMs) {
    state = "expiring";
  } else {
    state = "active";
  }
  return {
    code: grant.code,
    title: grant.title,
    state,
    owned: state === "active" || state === "expiring",
    remainingMs: grant.to === null ? null : Math.max(0, grant.to - now),
    remainingQuota: grant.quotaTotal === null
      ? null : Math.max(0, grant.quotaTotal - grant.quotaUsed),
    text: BENEFIT_TEXT[state],
  };
}
export function benefitViews(
  member: MemberSnapshot,
  now: number,
  warnMs = 7 * DAY,
): BenefitView[] {
  const state = membershipState(member, now, warnMs);
  return member.benefits.map((grant) => benefitView(grant, state, now, warnMs));
}
// 会员价是服务端给出的展示值，端上不自行计算；结算时必须重新确认。
export function memberPriceQuote(
  listCents: number,
  memberCents: number | null,
  member: MemberSnapshot,
  now: number,
  warnMs = 7 * DAY,
): PriceQuote {
  assertCents(listCents, "原价");
  if (memberCents !== null) assertCents(memberCents, "会员价");
  const state = membershipState(member, now, warnMs);
  const base: PriceQuote = {
    listCents, memberCents, payableCents: listCents,
    source: "list", requiresConfirm: false, note: "该商品不参与会员价",
  };
  if (memberCents === null) return base;
  if (state === "none" || state === "expired") {
    return { ...base, note: "会员已失效，按原价展示" };
  }
  if (memberCents > listCents) {
    return { ...base, note: "会员价高于原价，按原价展示" };
  }
  return {
    ...base, payableCents: memberCents, source: "member",
    requiresConfirm: true, note: "会员价，结算时以服务端价格为准",
  };
}
// 提醒只回答「要不要提醒」；是否已提醒由调用方持久化的 lastStage 决定。
export function renewalNotice(
  member: MemberSnapshot,
  now: number,
  warnDays = 7,
  urgentDays = 3,
): RenewalNotice {
  assertMember(member);
  assertTime(now, "当前时间");
  if (!Number.isInteger(warnDays) || warnDays < 1) {
    throw new Error("提醒窗口必须是正整数天");
  }
  if (!Number.isInteger(urgentDays) || urgentDays < 0 || urgentDays > warnDays) {
    throw new Error("紧急窗口必须在 0 到提醒窗口之间");
  }
  const state = membershipState(member, now);
  if (state === "none") {
    return { level: "none", daysLeft: null, title: "", detail: "" };
  }
  if (state === "expired") {
    return {
      level: "expired", daysLeft: 0, title: "会员已到期",
      detail: "会员价与专属权益已停止，续费后恢复；已支付订单不受影响。",
    };
  }
  const daysLeft = Math.ceil((member.expiresAt! - now) / DAY);
  if (member.autoRenew) {
    return {
      level: "none", daysLeft, title: "",
      detail: "已开启自动续费，到期前不重复提醒。",
    };
  }
  if (daysLeft > warnDays) {
    return { level: "none", daysLeft, title: "", detail: "" };
  }
  if (daysLeft <= urgentDays) {
    return {
      level: "urgent", daysLeft, title: `会员将在 ${daysLeft} 天内到期`,
      detail: "续费后权益立即延续；到期未续费将恢复原价。",
    };
  }
  return {
    level: "info", daysLeft, title: `会员还有 ${daysLeft} 天到期`,
    detail: "到期后会员价、免运费等权益将停止，已支付订单不受影响。",
  };
}
function assertMember(member: MemberSnapshot): void {
  if (!member.userId) throw new Error("会员快照缺少用户标识");
  if (!(member.tier in TIER_TEXT)) throw new Error(`未知会员等级：${String(member.tier)}`);
  assertTime(member.joinedAt, "开通时间");
  if (member.expiresAt !== null) {
    assertTime(member.expiresAt, "到期时间");
    if (member.expiresAt <= member.joinedAt) throw new Error("会员到期时间必须晚于开通时间");
  }
  if (typeof member.autoRenew !== "boolean") throw new Error("自动续费标记必须是布尔值");
  if (!Array.isArray(member.benefits)) throw new Error("权益清单必须是数组");
  for (const grant of member.benefits) assertGrant(grant);
}
function assertGrant(grant: BenefitGrant): void {
  if (!grant.code || !grant.title) throw new Error("权益缺少编码或标题");
  assertTime(grant.from, "权益开始时间");
  if (grant.to !== null) {
    assertTime(grant.to, "权益结束时间");
    if (grant.to <= grant.from) throw new Error(`权益结束必须晚于开始：${grant.code}`);
  }
  if (grant.quotaTotal !== null) {
    if (!Number.isInteger(grant.quotaTotal) || grant.quotaTotal < 1) {
      throw new Error(`权益总额度必须是正整数：${grant.code}`);
    }
    if (!Number.isInteger(grant.quotaUsed) || grant.quotaUsed < 0 || grant.quotaUsed > grant.quotaTotal) {
      throw new Error(`权益已用额度非法：${grant.code}`);
    }
  } else if (grant.quotaUsed !== 0) {
    throw new Error(`无限额度权益不应记录已用额度：${grant.code}`);
  }
  if (typeof grant.requiresClaim !== "boolean" || typeof grant.claimed !== "boolean") {
    throw new Error(`权益领取标记非法：${grant.code}`);
  }
}
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/membership.test.ts
✔ 会员等级有稳定的中文文案 (0.563541ms)
✔ 普通用户没有会员状态 (0.211125ms)
✔ 有效期内的会员处于 active 并给出剩余天数 (0.068375ms)
✔ 到期前七天进入 expiring，但仍可使用权益 (0.064667ms)
✔ 到期时间按开区间判定，等于到期时刻即失效 (0.080625ms)
✔ 没有到期时间的付费会员视为长期有效 (0.062291ms)
✔ 生效中的权益标记为已拥有并计算剩余额度 (0.097584ms)
✔ 尚未开始的权益不能展示成已有 (0.055375ms)
✔ 待领取的权益只是可领取，不算已拥有 (0.067417ms)
✔ 额度用完的权益不再标记为可用 (0.099791ms)
✔ 权益自身到期与会员到期分别判定 (0.07375ms)
✔ 权益临近到期时标记为 expiring (0.053583ms)
✔ 会员失效后所有权益一起失效 (0.07025ms)
✔ 有效会员展示服务端会员价并要求结算确认 (0.09725ms)
✔ 会员失效后回退原价并说明原因 (0.100834ms)
✔ 会员价高于原价时按原价展示 (0.053625ms)
✔ 商品不参与会员价时不制造优惠感 (0.043458ms)
✔ 到期提醒按窗口分成 info 与 urgent (0.113625ms)
✔ 窗口外的会员不提醒，自动续费也不重复提醒 (0.065667ms)
✔ 到期后的提醒明确已支付订单不受影响 (0.049542ms)
✔ 非法时间、等级与额度被拒绝 (0.24425ms)
✔ 会员价的金额必须是安全整数分 (0.070042ms)
ℹ tests 22
ℹ suites 0
ℹ pass 22
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 129.161708