《互联网产品的客户端架构·内容、社交与实时互动》5.1 点赞与收藏：本地先行、服务端为准

PUT /contents/{id}/reaction
{ "kind": "like", "active": true }

// file: src/interaction/optimistic.ts
// tier: L2
// verify: node --test --test-concurrency=1 test/interaction/optimistic.test.ts
export type ReactionKind = "like" | "favorite";
export type Clock = () => number;
export type DeltaSource = "self" | "other";

export interface ReactionSnapshot {
  active: boolean;
  count: number;
}

export interface ReactionView {
  like: ReactionSnapshot;
  favorite: ReactionSnapshot;
}

export interface ReactionRequest {
  seq: number;
  id: string;
  kind: ReactionKind;
  active: boolean;
  sentAt: number;
}

export interface SettleResult {
  applied: boolean;
  stale: boolean;
  pending: boolean;
  view: ReactionSnapshot;
}

export interface FailResult {
  applied: boolean;
  stale: boolean;
  needsRefresh: boolean;
  view: ReactionSnapshot;
}

export interface SnapshotResult {
  pending: number;
}

interface KindState {
  confirmed: ReactionSnapshot;
  // null 表示用户没有未确认的意图；true/false 表示本地希望服务端最终处于的状态。
  desired: boolean | null;
  // 已经采纳过的最大响应序号，用来丢弃乱序后到的旧响应。
  latestSeq: number;
}

const KINDS: readonly ReactionKind[] = ["like", "favorite"];

function emptyState(): KindState {
  return {
    confirmed: { active: false, count: 0 },
    desired: null,
    latestSeq: 0,
  };
}

function assertSnapshot(snapshot: ReactionSnapshot): void {
  if (typeof snapshot.active !== "boolean") throw new TypeError("active 必须是布尔值");
  if (!Number.isInteger(snapshot.count) || snapshot.count < 0) {
    throw new RangeError("count 必须是非负整数");
  }
}

// 展示值 = 服务端绝对基数 + 尚未确认的本地意图带来的偏移。
function render(state: KindState): ReactionSnapshot {
  const active = state.desired ?? state.confirmed.active;
  const shift = (active ? 1 : 0) - (state.confirmed.active ? 1 : 0);
  return { active, count: Math.max(0, state.confirmed.count + shift) };
}

export class ReactionStore {
  #items = new Map<string, Record<ReactionKind, KindState>>();
  #seq = 0;
  #now: Clock;

  constructor(options: { now?: Clock } = {}) {
    this.#now = options.now ?? (() => Date.now());
  }

  // 列表、详情或刷新响应都可以播种；已经存在的条目只覆盖服务端确认部分。
  seed(id: string, view: Partial<ReactionView> = {}): void {
    if (id.trim() === "") throw new Error("id 不能为空");
    const pair = this.#items.get(id) ?? { like: emptyState(), favorite: emptyState() };
    for (const kind of KINDS) {
      const snapshot = view[kind];
      if (!snapshot) continue;
      assertSnapshot(snapshot);
      pair[kind].confirmed = { active: snapshot.active, count: snapshot.count };
    }
    this.#items.set(id, pair);
  }

  view(id: string): ReactionView {
    const pair = this.#pair(id);
    return {
      like: render(pair.like),
      favorite: render(pair.favorite),
    };
  }

  pending(id: string, kind: ReactionKind): boolean {
    return this.#state(id, kind).desired !== null;
  }

  // 每次点击都发送「最终状态」而不是 toggle 动作，重复投递因此天然幂等。
  toggle(id: string, kind: ReactionKind): ReactionRequest {
    const state = this.#state(id, kind);
    const current = render(state);
    state.desired = !current.active;
    this.#seq += 1;
    return {
      seq: this.#seq,
      id,
      kind,
      active: state.desired,
      sentAt: this.#now(),
    };
  }

  settle(request: ReactionRequest, server: ReactionSnapshot): SettleResult {
    assertSnapshot(server);
    const state = this.#state(request.id, request.kind);
    if (request.seq <= state.latestSeq) {
      return {
        applied: false,
        stale: true,
        pending: this.#hasPending(state),
        view: render(state),
      };
    }
    state.confirmed = { active: server.active, count: server.count };
    state.latestSeq = request.seq;
    // 服务端确认态与用户意图一致时，意图已经兑现，不必再保留。
    if (state.desired === null || state.desired === server.active) {
      state.desired = null;
    }
    return {
      applied: true,
      stale: false,
      pending: this.#hasPending(state),
      view: render(state),
    };
  }

  fail(request: ReactionRequest): FailResult {
    const state = this.#state(request.id, request.kind);
    if (request.seq <= state.latestSeq) {
      return {
        applied: false,
        stale: true,
        needsRefresh: false,
        view: render(state),
      };
    }
    // 失败时先退回最后一次服务端确认态，再要求调用方拉一次绝对快照。
    state.latestSeq = request.seq;
    state.desired = null;
    return {
      applied: true,
      stale: false,
      needsRefresh: true,
      view: render(state),
    };
  }

  // 任何来源的绝对快照都覆盖确认基数，但不覆盖尚未兑现的本地意图。
  applySnapshot(id: string, view: Partial<ReactionView>): SnapshotResult {
    const pair = this.#pair(id);
    let pending = 0;
    for (const kind of KINDS) {
      const snapshot = view[kind];
      if (!snapshot) continue;
      assertSnapshot(snapshot);
      const state = pair[kind];
      state.confirmed = { active: snapshot.active, count: snapshot.count };
      if (state.desired === snapshot.active) state.desired = null;
      if (state.desired !== null) pending += 1;
    }
    return { pending };
  }

  // 实时增量只改确认基数；自己的回显必须忽略，否则会和确认响应重复计数。
  applyDelta(id: string, kind: ReactionKind, delta: number, source: DeltaSource): number {
    if (!Number.isInteger(delta) || delta === 0) {
      throw new RangeError("delta 必须是非零整数");
    }
    const state = this.#state(id, kind);
    if (source === "self") return render(state).count;
    state.confirmed.count = Math.max(0, state.confirmed.count + delta);
    return render(state).count;
  }

  #hasPending(state: KindState): boolean {
    return state.desired !== null && state.desired !== state.confirmed.active;
  }

  #pair(id: string): Record<ReactionKind, KindState> {
    const pair = this.#items.get(id);
    if (!pair) throw new Error(`未知内容 ${id}，先 seed 再读取`);
    return pair;
  }

  #state(id: string, kind: ReactionKind): KindState {
    return this.#pair(id)[kind];
  }
}

$ node --test --test-concurrency=1 test/interaction/optimistic.test.ts
✔ 点赞先本地生效，服务端确认前计数先加一 (0.996708ms)
✔ 连点两次回到原状态，两次请求各自携带绝对状态 (0.677166ms)
✔ 服务端响应乱序时旧序号被丢弃，界面不回退 (0.121083ms)
✔ 列表与详情共用同一状态，后到的旧快照不会覆盖未确认意图 (0.140542ms)
✔ 绝对计数覆盖增量，他人事件累加而自己的回显被忽略 (0.12375ms)
✔ 同一响应重复投递只采纳一次 (0.077042ms)
✔ 失败回滚到已确认状态并要求重新拉取绝对快照 (0.098042ms)
✔ 未知内容与非法计数在边界处直接拒绝 (0.291625ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 156.65225