《互联网产品的客户端架构·内容、社交与实时互动》5.2 评论的顺序、草稿与失败重发

POST /comments
{ "clientId": "c-7f3a...", "threadId": "t-42", "text": "..." }

// file: src/interaction/comments.ts
// tier: L2
// verify: node --test --test-concurrency=1 test/interaction/comments.test.ts
export type Clock = () => number;
export type PendingStatus = "sending" | "failed";

export interface CommentRecord {
  id: string;
  threadId: string;
  authorId: string;
  text: string;
  createdAt: number;
  clientId?: string;
}

export interface PendingComment {
  clientId: string;
  threadId: string;
  authorId: string;
  text: string;
  createdAt: number;
  status: PendingStatus;
  attempts: number;
  error: string | null;
}

export interface CommentRequest {
  clientId: string;
  threadId: string;
  text: string;
  attempt: number;
}

export interface SentResult {
  inserted: boolean;
  duplicate: boolean;
  entry: CommentRecord | null;
}

export interface TimelineEntry {
  kind: "confirmed" | "pending";
  id: string;
  clientId: string | null;
  text: string;
  createdAt: number;
  status: "sent" | PendingStatus;
}

interface OrderKey {
  createdAt: number;
  rank: number;
  key: string;
}

function orderKey(entry: TimelineEntry): OrderKey {
  return {
    createdAt: entry.createdAt,
    // 同一毫秒内先展示服务端已确认评论，再展示本地占位，最后按 id 稳定排序。
    rank: entry.kind === "confirmed" ? 0 : 1,
    key: entry.kind === "confirmed" ? entry.id : (entry.clientId ?? entry.id),
  };
}

function compareOrder(a: OrderKey, b: OrderKey): number {
  if (a.createdAt !== b.createdAt) return a.createdAt - b.createdAt;
  if (a.rank !== b.rank) return a.rank - b.rank;
  return a.key.localeCompare(b.key);
}

export class CommentThread {
  #confirmed = new Map<string, CommentRecord[]>();
  #pending = new Map<string, PendingComment>();
  #drafts = new Map<string, string>();
  #now: Clock;
  #idFactory: () => string;
  #authorId: string;

  constructor(options: { now?: Clock; idFactory?: () => string; authorId?: string } = {}) {
    this.#now = options.now ?? (() => Date.now());
    this.#idFactory = options.idFactory ?? (() => crypto.randomUUID());
    this.#authorId = options.authorId ?? "me";
  }

  seed(threadId: string, comments: CommentRecord[]): void {
    for (const comment of comments) {
      if (comment.threadId !== threadId) throw new Error("评论不属于该线程");
      if (!Number.isFinite(comment.createdAt)) throw new RangeError("createdAt 必须是时间戳");
    }
    this.#confirmed.set(threadId, [...comments].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)));
  }

  confirmed(threadId: string): CommentRecord[] {
    return [...(this.#confirmed.get(threadId) ?? [])];
  }

  pending(clientId: string): PendingComment | null {
    const comment = this.#pending.get(clientId);
    return comment ? { ...comment } : null;
  }

  // 草稿按线程隔离，不随提交其他线程或切换页面而清空。
  setDraft(threadId: string, text: string): void {
    if (text === "") {
      this.#drafts.delete(threadId);
      return;
    }
    this.#drafts.set(threadId, text);
  }

  draft(threadId: string): string {
    return this.#drafts.get(threadId) ?? "";
  }

  // 提交时生成 clientId 并消费草稿；重试必须复用同一个 clientId。
  submit(threadId: string, text: string, createdAt?: number): CommentRequest {
    const body = text.trim();
    if (body === "") throw new Error("评论内容不能为空");
    const clientId = this.#idFactory();
    if (this.#pending.has(clientId)) throw new Error(`clientId 重复：${clientId}`);
    const at = createdAt ?? this.#now();
    const comment: PendingComment = {
      clientId,
      threadId,
      authorId: this.#authorId,
      text: body,
      createdAt: at,
      status: "sending",
      attempts: 1,
      error: null,
    };
    this.#pending.set(clientId, comment);
    if (this.draft(threadId).trim() === body) this.#drafts.delete(threadId);
    return { clientId, threadId, text: body, attempt: 1 };
  }

  retry(clientId: string): CommentRequest | null {
    const comment = this.#pending.get(clientId);
    if (!comment || comment.status !== "failed") return null;
    comment.status = "sending";
    comment.attempts += 1;
    comment.error = null;
    if (this.draft(comment.threadId).trim() === comment.text) {
      this.#drafts.delete(comment.threadId);
    }
    return {
      clientId,
      threadId: comment.threadId,
      text: comment.text,
      attempt: comment.attempts,
    };
  }

  markFailed(clientId: string, error = "network"): PendingComment | null {
    const comment = this.#pending.get(clientId);
    if (!comment) return null;
    comment.status = "failed";
    comment.error = error;
    // 把原文放回草稿框，用户离开页面再回来也不会丢字；已有编辑则不动。
    if (this.draft(comment.threadId).trim() === "") {
      this.#drafts.set(comment.threadId, comment.text);
    }
    return { ...comment };
  }

  // 服务端确认可能晚于失败回执，也可能重复投递；clientId 与服务端 id 都要去重。
  markSent(clientId: string, server: CommentRecord): SentResult {
    const pending = this.#pending.get(clientId);
    const threadId = server.threadId;
    if (pending && pending.threadId !== threadId) {
      throw new Error("确认响应的线程与本地占位不一致");
    }
    const list = this.#confirmed.get(threadId) ?? [];
    const existing =
      list.find((comment) => comment.id === server.id || comment.clientId === clientId) ?? null;
    if (existing) {
      if (pending) this.#pending.delete(clientId);
      return { inserted: false, duplicate: true, entry: { ...existing } };
    }
    if (pending) {
      this.#pending.delete(clientId);
      if (this.draft(threadId).trim() === pending.text) this.#drafts.delete(threadId);
    }
    const record: CommentRecord = { ...server, clientId: server.clientId ?? clientId };
    const merged = [...list, record].sort(
      (a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id),
    );
    this.#confirmed.set(threadId, merged);
    return { inserted: true, duplicate: false, entry: { ...record } };
  }

  // 已确认评论与本地占位合并成一条按时间正序的时间线，发送中的评论不会被藏起来。
  timeline(threadId: string): TimelineEntry[] {
    const confirmed: TimelineEntry[] = (this.#confirmed.get(threadId) ?? []).map((comment) => ({
      kind: "confirmed" as const,
      id: comment.id,
      clientId: comment.clientId ?? null,
      text: comment.text,
      createdAt: comment.createdAt,
      status: "sent" as const,
    }));
    const pending: TimelineEntry[] = [...this.#pending.values()]
      .filter((comment) => comment.threadId === threadId)
      .map((comment) => ({
        kind: "pending" as const,
        id: comment.clientId,
        clientId: comment.clientId,
        text: comment.text,
        createdAt: comment.createdAt,
        status: comment.status,
      }));
    return [...confirmed, ...pending].sort((a, b) => compareOrder(orderKey(a), orderKey(b)));
  }
}

$ node --test --test-concurrency=1 test/interaction/comments.test.ts
✔ 提交后立即出现发送中占位，输入草稿被消费 (1.508875ms)
✔ 失败后恢复草稿，重试复用同一个 clientId 且不新增占位 (0.174083ms)
✔ 成功后占位被服务端评论替换，并按服务端时间重新排序 (0.829875ms)
✔ 同一 clientId 的重复确认只保留一条服务端评论 (0.112416ms)
✔ 多条本地占位与服务端评论按时间正序合并 (0.118708ms)
✔ 空评论不能提交，未知 clientId 的重试与失败回调都返回 null (0.24775ms)
✔ 草稿按线程隔离，提交只消费当前线程 (0.079042ms)
✔ 失败恢复的草稿被编辑后，成功回执不清空新草稿 (0.073625ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 160.798