《互联网产品的客户端架构·交易、增长与平台化》8.2 积分的加减与过期

// file: src/member/points.ts
// tier: L1
// verify: node --test test/member/points.test.ts
export type PointsFlow = "earn" | "redeem" | "refund" | "expire";
export interface PointsEntry {
  id: string; flow: PointsFlow; points: number; at: number;
  expiresAt: number | null; orderId: string | null; sourceId: string | null;
}
export interface PointsAccount { entries: PointsEntry[]; }
export interface PointsBatch {
  entryId: string; remaining: number; expiresAt: number | null; at: number;
}
export interface PointsSummary { available: number; batches: PointsBatch[]; }
export interface Allocation { entryId: string; points: number; }
export interface RedeemRequest { id: string; points: number; at: number; orderId: string; }
export interface RedeemResult {
  account: PointsAccount; accepted: boolean; allocations: Allocation[];
  reason: "accepted" | "duplicate" | "insufficient"; available: number;
}
export interface RefundRequest { id: string; redeemId: string; at: number; expiresAt: number | null; }
export interface RefundResult {
  account: PointsAccount; accepted: boolean;
  reason: "accepted" | "duplicate" | "missing"; available: number;
}
const FLOW_TEXT: Record<PointsFlow, string> = {
  earn: "发放", redeem: "抵扣", refund: "退回", expire: "过期",
};
export function flowText(flow: PointsFlow): string {
  return FLOW_TEXT[flow];
}
// 余额从流水重放得出，端上不在旧余额上做加减。
export function pointsSummary(account: PointsAccount, now: number): PointsSummary {
  assertAccount(account);
  assertTime(now, "查询时间");
  const batches: PointsBatch[] = [];
  for (const entry of sortEntries(account.entries)) {
    if (entry.at > now) continue;
    applyEntry(batches, entry);
  }
  const live = batches.filter((b) => b.remaining > 0 && !isExpired(b, now));
  return {
    available: live.reduce((sum, b) => sum + b.remaining, 0),
    batches: live.map((b) => ({ ...b })),
  };
}
export function redeem(
  account: PointsAccount, request: RedeemRequest,
): RedeemResult {
  assertAccount(account);
  assertRedeem(request);
  const existing = account.entries.find((entry) => entry.id === request.id);
  if (existing !== undefined) {
    if (existing.flow !== "redeem" || existing.points !== request.points
      || existing.at !== request.at || existing.orderId !== request.orderId) {
      throw new Error(`流水 id 冲突：${request.id}`);
    }
    return {
      account, accepted: true, reason: "duplicate", allocations: [],
      available: pointsSummary(account, request.at).available,
    };
  }
  const batches = replayTo(account, request.at);
  const available = batches.filter((b) => b.remaining > 0 && !isExpired(b, request.at))
    .reduce((sum, b) => sum + b.remaining, 0);
  if (available < request.points) {
    return { account, accepted: false, reason: "insufficient", allocations: [], available };
  }
  const allocations = consume(batches, request.points, request.at);
  const entry: PointsEntry = {
    id: request.id, flow: "redeem", points: request.points, at: request.at,
    expiresAt: null, orderId: request.orderId, sourceId: null,
  };
  const next: PointsAccount = { entries: [...account.entries, entry] };
  return {
    account: next, accepted: true, reason: "accepted", allocations,
    available: pointsSummary(next, request.at).available,
  };
}
// 抵扣失败时追加一条退回流水，不删除原抵扣；同一笔抵扣只能退一次。
export function refundRedeem(
  account: PointsAccount, request: RefundRequest,
): RefundResult {
  assertAccount(account);
  assertRefund(request);
  const existing = account.entries.find((entry) => entry.id === request.id);
  if (existing !== undefined) {
    if (existing.flow !== "refund" || existing.sourceId !== request.redeemId) {
      throw new Error(`流水 id 冲突：${request.id}`);
    }
    return {
      account, accepted: true, reason: "duplicate",
      available: pointsSummary(account, request.at).available,
    };
  }
  const already = account.entries.find(
    (entry) => entry.flow === "refund" && entry.sourceId === request.redeemId,
  );
  if (already !== undefined) {
    return {
      account, accepted: false, reason: "duplicate",
      available: pointsSummary(account, request.at).available,
    };
  }
  const original = account.entries.find((entry) => entry.id === request.redeemId);
  if (original === undefined || original.flow !== "redeem") {
    return {
      account, accepted: false, reason: "missing",
      available: pointsSummary(account, request.at).available,
    };
  }
  if (request.at <= original.at) throw new Error("退回时间必须晚于原抵扣时间");
  const entry: PointsEntry = {
    id: request.id, flow: "refund", points: original.points, at: request.at,
    expiresAt: request.expiresAt, orderId: original.orderId, sourceId: original.id,
  };
  const next: PointsAccount = { entries: [...account.entries, entry] };
  return {
    account: next, accepted: true, reason: "accepted",
    available: pointsSummary(next, request.at).available,
  };
}
// 多端合并按流水 id 去重，再按时间与 id 排序，结果与到达顺序无关。
export function mergeLedgers(
  local: PointsAccount, remote: PointsAccount,
): PointsAccount {
  assertAccount(local);
  assertAccount(remote);
  const byId = new Map<string, PointsEntry>();
  for (const entry of [...local.entries, ...remote.entries]) {
    const seen = byId.get(entry.id);
    if (seen !== undefined) {
      if (entryKey(seen) !== entryKey(entry)) {
        throw new Error(`同一流水出现不同内容：${entry.id}`);
      }
      continue;
    }
    byId.set(entry.id, entry);
  }
  return { entries: sortEntries([...byId.values()]) };
}
function applyEntry(batches: PointsBatch[], entry: PointsEntry): void {
  if (entry.flow === "earn" || entry.flow === "refund") {
    batches.push({
      entryId: entry.id, remaining: entry.points,
      expiresAt: entry.expiresAt, at: entry.at,
    });
  } else if (entry.flow === "redeem") {
    consume(batches, entry.points, entry.at);
  }
  // 过期流水是审计记录；批次是否失效由时间边界判定，避免重复扣减。
}
function replayTo(account: PointsAccount, at: number): PointsBatch[] {
  const batches: PointsBatch[] = [];
  for (const entry of sortEntries(account.entries)) {
    if (entry.at > at) break;
    applyEntry(batches, entry);
  }
  return batches;
}
// 先到期先出；无到期时间的批次最后使用，同到期时间按入账时间与 id。
function consume(batches: PointsBatch[], points: number, at: number): Allocation[] {
  const candidates = batches
    .filter((b) => b.remaining > 0 && !isExpired(b, at)).sort(compareBatch);
  let left = points;
  const allocations: Allocation[] = [];
  for (const batch of candidates) {
    if (left === 0) break;
    const used = Math.min(batch.remaining, left);
    batch.remaining -= used;
    left -= used;
    allocations.push({ entryId: batch.entryId, points: used });
  }
  if (left > 0) throw new Error("流水不足以支持抵扣");
  return allocations;
}
function compareBatch(a: PointsBatch, b: PointsBatch): number {
  const ae = a.expiresAt ?? Number.MAX_SAFE_INTEGER;
  const be = b.expiresAt ?? Number.MAX_SAFE_INTEGER;
  if (ae !== be) return ae - be;
  if (a.at !== b.at) return a.at - b.at;
  return a.entryId < b.entryId ? -1 : a.entryId > b.entryId ? 1 : 0;
}
function isExpired(batch: PointsBatch, at: number): boolean {
  return batch.expiresAt !== null && at >= batch.expiresAt;
}
function sortEntries(entries: PointsEntry[]): PointsEntry[] {
  return [...entries].sort((a, b) => {
    if (a.at !== b.at) return a.at - b.at;
    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
  });
}
function entryKey(entry: PointsEntry): string {
  return [entry.id, entry.flow, entry.points, entry.at,
    entry.expiresAt, entry.orderId, entry.sourceId].join("|");
}
function assertAccount(account: PointsAccount): void {
  if (!Array.isArray(account.entries)) throw new Error("积分账本必须是流水数组");
  const ids = new Set<string>();
  for (const entry of account.entries) {
    assertEntry(entry);
    if (ids.has(entry.id)) throw new Error(`流水 id 重复：${entry.id}`);
    ids.add(entry.id);
  }
}
function assertEntry(entry: PointsEntry): void {
  if (!entry.id) throw new Error("流水缺少 id");
  if (!(entry.flow in FLOW_TEXT)) {
    throw new Error(`未知积分流水类型：${String(entry.flow)}`);
  }
  assertPoints(entry.points);
  assertTime(entry.at, "入账时间");
  if (entry.expiresAt !== null) {
    assertTime(entry.expiresAt, "过期时间");
    if (entry.expiresAt <= entry.at) {
      throw new Error(`过期时间必须晚于入账时间：${entry.id}`);
    }
  }
  if (entry.flow === "redeem" && entry.expiresAt !== null) {
    throw new Error(`抵扣流水不应带过期时间：${entry.id}`);
  }
  if (entry.flow === "expire" && entry.sourceId === null) {
    throw new Error(`过期流水必须指明批次：${entry.id}`);
  }
}
function assertRedeem(request: RedeemRequest): void {
  if (!request.id || !request.orderId) throw new Error("抵扣请求缺少 id 或订单号");
  assertPoints(request.points);
  assertTime(request.at, "抵扣时间");
}
function assertRefund(request: RefundRequest): void {
  if (!request.id || !request.redeemId) throw new Error("退回请求缺少 id");
  assertTime(request.at, "退回时间");
  if (request.expiresAt !== null) {
    assertTime(request.expiresAt, "退回过期时间");
    if (request.expiresAt <= request.at) {
      throw new Error("退回积分的过期时间必须晚于退回时间");
    }
  }
}
function assertPoints(points: number): void {
  if (!Number.isInteger(points) || points <= 0) throw new Error("积分必须是正整数");
}
function assertTime(at: number, label: string): void {
  if (!Number.isSafeInteger(at) || at < 0) {
    throw new Error(`${label}必须是安全整数毫秒`);
  }
}

$ node --test test/member/points.test.ts
✔ 四类流水有稳定文案 (0.569584ms)
✔ 余额由发放流水推导并保留批次 (0.246292ms)
✔ 未来入账的积分不计入可用余额 (0.0715ms)
✔ 抵扣按先到期先出顺序选择批次 (0.568708ms)
✔ 余额不足时拒绝抵扣且不产生部分流水 (0.085417ms)
✔ 抵扣成功后余额下降并记录分配批次 (0.11175ms)
✔ 重复提交同一抵扣 id 幂等返回，不重复扣分 (0.097708ms)
✔ 同一 id 携带不同内容时拒绝合并 (0.23125ms)
✔ 抵扣失败后追加退回流水，余额恢复 (0.194708ms)
✔ 退回不存在的抵扣返回 missing (0.104167ms)
✔ 同一笔抵扣不能被第二次退回 (0.093375ms)
✔ 重复提交同一退回 id 幂等返回 (0.086375ms)
✔ 超过到期时间的批次不再计入余额 (0.049208ms)
✔ 过期流水只是审计记录，不会二次扣减 (0.061583ms)
✔ 抵扣不能使用入账时间尚未到达的积分 (0.060041ms)
✔ 多端账本合并去重且与到达顺序无关 (0.148ms)
✔ 同一流水在不同端内容不一致时拒绝合并 (0.071167ms)
✔ 非法流水类型、积分与过期批次被拒绝 (0.104416ms)
✔ 账本自身不足以支持历史抵扣时拒绝计算 (0.077041ms)
ℹ tests 19
ℹ suites 0
ℹ pass 19
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 154.20125