《互联网产品的客户端架构·内容、社交与实时互动》9.3 拉黑与屏蔽：端上必须立即生效的部分

// file: src/relations/block.ts
// tier: L1
// verify: node --test test/relations/block.test.ts
export type Surface = "feed" | "detail" | "comment" | "search" | "dm";

export type BlockPhase = "active" | "pending" | "failed";

export type Clock = () => number;

export const SURFACES: readonly Surface[] = ["feed", "detail", "comment", "search", "dm"];

export interface BlockedEntry {
  userId: string;
  phase: BlockPhase;
  updatedAt: number;
  attempts: number;
}

export interface BlockResult {
  hidden: boolean;
  phase: BlockPhase;
  queued: boolean;
}

export interface SnapshotResult {
  added: number;
  keptLocal: number;
}

export class BlockStore {
  #entries = new Map<string, BlockedEntry>();
  #now: Clock;

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

  // 本地先行：调用瞬间就进入 pending 并立即隐藏，网络请求只是后续同步。
  block(userId: string): BlockResult {
    const existing = this.#entries.get(userId);
    if (existing && existing.phase !== "failed") {
      return { hidden: true, phase: existing.phase, queued: false };
    }
    const phase: BlockPhase = "pending";
    this.#entries.set(userId, {
      userId,
      phase,
      updatedAt: this.#now(),
      attempts: existing?.attempts ?? 0,
    });
    return { hidden: true, phase, queued: true };
  }

  confirm(userId: string): boolean {
    const entry = this.#entries.get(userId);
    if (!entry || entry.phase !== "pending") return false;
    entry.phase = "active";
    entry.updatedAt = this.#now();
    return true;
  }

  // 同步失败只改变同步状态，不解除隐藏。弱网下宁可不显示，也不能回显。
  fail(userId: string): boolean {
    const entry = this.#entries.get(userId);
    if (!entry || entry.phase !== "pending") return false;
    entry.phase = "failed";
    entry.attempts += 1;
    entry.updatedAt = this.#now();
    return true;
  }

  retry(userId: string): boolean {
    const entry = this.#entries.get(userId);
    if (!entry || entry.phase !== "failed") return false;
    entry.phase = "pending";
    entry.updatedAt = this.#now();
    return true;
  }

  // 解除拉黑先本地生效并返回旧条目；服务端失败时调用方用 restore 恢复，
  // 恢复的是隐藏，不会出现「失败后更可见」的方向。
  unblock(userId: string): BlockedEntry | null {
    const entry = this.#entries.get(userId);
    if (!entry) return null;
    this.#entries.delete(userId);
    return { ...entry };
  }

  restore(entry: BlockedEntry): void {
    this.#entries.set(entry.userId, { ...entry });
  }

  status(userId: string): BlockPhase | null {
    return this.#entries.get(userId)?.phase ?? null;
  }

  isHidden(userId: string): boolean {
    return this.#entries.has(userId);
  }

  hiddenSurfaces(userId: string): Surface[] {
    return this.isHidden(userId) ? [...SURFACES] : [];
  }

  filterAuthored<T extends { authorId: string }>(items: readonly T[]): T[] {
    return items.filter((item) => !this.isHidden(item.authorId));
  }

  filterThreads<T extends { participantIds: readonly string[] }>(threads: readonly T[]): T[] {
    return threads.filter((thread) => !thread.participantIds.some((id) => this.isHidden(id)));
  }

  pending(): string[] {
    return [...this.#entries.values()]
      .filter((entry) => entry.phase !== "active")
      .map((entry) => entry.userId);
  }

  // 服务端快照只增不减：它可以把未知 id 补成 active，也可以确认本地 pending，
  // 但不能因为快照里没有某个 id 就解除本地隐藏。快照本身可能滞后。
  applyServerList(ids: readonly string[]): SnapshotResult {
    const serverIds = new Set(ids);
    let added = 0;
    for (const id of serverIds) {
      const entry = this.#entries.get(id);
      if (!entry) {
        this.#entries.set(id, {
          userId: id,
          phase: "active",
          updatedAt: this.#now(),
          attempts: 0,
        });
        added += 1;
      } else if (entry.phase === "failed") {
        entry.phase = "active";
        entry.updatedAt = this.#now();
      }
    }
    let keptLocal = 0;
    for (const id of this.#entries.keys()) {
      if (!serverIds.has(id)) keptLocal += 1;
    }
    return { added, keptLocal };
  }
}

$ node --test test/relations/block.test.ts
✔ 拉黑在请求发出前就隐藏五个界面 (0.951917ms)
✔ 服务端确认后转为 active，仍保持隐藏 (0.106458ms)
✔ 同步失败转为 failed 且不回显 (0.101958ms)
✔ 失败后重试回到 pending，隐藏不中断 (0.084583ms)
✔ 解除拉黑返回旧条目，服务端失败可恢复隐藏 (0.526041ms)
✔ 信息流、详情、评论与搜索共用作者过滤 (0.074459ms)
✔ 私信会话只要包含被拉黑参与者就整条隐藏 (0.087458ms)
✔ 服务端快照只增不减，缺失的本地 pending 不会被解除 (0.100375ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 139.468292