《互联网产品的客户端架构·内容、社交与实时互动》11.3 举报链路与证据留存

// file: src/moderation/report.ts
// tier: L2
// verify: node --test --test-concurrency=1 test/moderation/report.test.ts
import { createHash } from "node:crypto";
import type { ContentBlock, ContentItem } from "../core/content-model.ts";

export type ReportReason =
  "spam" | "harassment" | "hate" | "sexual" | "violence" | "misinfo" | "other";

export type ReportStatus = "queued" | "failed" | "sent";

export interface SnapshotBlock {
  readonly type: ContentBlock["type"];
  readonly text: string | null;
  readonly src: string | null;
  readonly alt: string | null;
}

export interface ContentSnapshot {
  readonly contentId: string;
  readonly authorId: string;
  readonly capturedAt: number;
  readonly blocks: readonly SnapshotBlock[];
  readonly hash: string;
}

export interface ReportInput {
  contentId: string;
  reason: ReportReason;
  detail?: string;
  snapshot: ContentSnapshot;
}

export interface ReportPayload {
  readonly reportId: string;
  readonly contentId: string;
  readonly reason: ReportReason;
  readonly detail: string;
  readonly snapshotAt: number;
  readonly snapshotHash: string;
  readonly evidence: ContentSnapshot;
  readonly createdAt: number;
}

export interface ReportView {
  payload: ReportPayload;
  status: ReportStatus;
  attempts: number;
  nextAttemptAt: number;
  sentAt: number | null;
  receiptId: string | null;
}

export interface EnqueueResult {
  status: "queued" | "duplicate";
  id: string;
}

export interface FlushResult {
  sent: number;
  failed: number;
  skipped: number;
  remaining: number;
  offline: boolean;
}

export interface QueueOptions {
  dedupeWindowMs?: number;
  maxAttempts?: number;
  backoffMs?: number;
}

const REASONS: readonly ReportReason[] = [
  "spam", "harassment", "hate", "sexual", "violence", "misinfo", "other",
];

function assertReason(value: string): asserts value is ReportReason {
  if (!(REASONS as readonly string[]).includes(value)) {
    throw new Error(`未知的举报理由：${value}`);
  }
}

function hashParts(parts: {
  contentId: string;
  authorId: string;
  capturedAt: number;
  blocks: readonly SnapshotBlock[];
}): string {
  const body = JSON.stringify({
    contentId: parts.contentId,
    authorId: parts.authorId,
    capturedAt: parts.capturedAt,
    blocks: parts.blocks,
  });
  return createHash("sha256").update(body).digest("hex");
}

// 深拷贝成只含可序列化字段的快照，并冻结；之后作者怎么改都不影响证据。
export function takeSnapshot(item: ContentItem, capturedAt: number): ContentSnapshot {
  if (!Number.isFinite(capturedAt) || capturedAt < 0) {
    throw new Error("capturedAt 必须是非负时间戳");
  }
  const blocks = Object.freeze(
    item.blocks.map((block) =>
      Object.freeze({
        type: block.type,
        text: block.text ?? null,
        src: block.src ?? null,
        alt: block.alt ?? null,
      }),
    ),
  );
  const base = { contentId: item.id, authorId: item.authorId, capturedAt, blocks };
  return Object.freeze({ ...base, hash: hashParts(base) });
}

export class ReportQueue {
  #entries = new Map<string, ReportView>();
  #byContent = new Map<string, string>();
  #now: () => number;
  #seq = 0;
  #online = true;
  #dedupeWindowMs: number;
  #maxAttempts: number;
  #backoffMs: number;

  constructor(now: () => number = () => Date.now(), options: QueueOptions = {}) {
    this.#now = now;
    this.#dedupeWindowMs = options.dedupeWindowMs ?? 10 * 60_000;
    this.#maxAttempts = options.maxAttempts ?? 3;
    this.#backoffMs = options.backoffMs ?? 5_000;
    if (this.#dedupeWindowMs < 0) throw new Error("dedupeWindowMs 不能为负");
    if (!Number.isInteger(this.#maxAttempts) || this.#maxAttempts < 1) {
      throw new Error("maxAttempts 必须是正整数");
    }
    if (this.#backoffMs < 0) throw new Error("backoffMs 不能为负");
  }

  get online(): boolean {
    return this.#online;
  }

  setOnline(online: boolean): void {
    this.#online = online;
  }

  enqueue(input: ReportInput): EnqueueResult {
    assertReason(input.reason);
    if (input.snapshot.contentId !== input.contentId) {
      throw new Error("快照内容与举报内容不一致");
    }
    const now = this.#now();
    this.#prune(now);
    const existingId = this.#byContent.get(input.contentId);
    if (existingId !== undefined) return { status: "duplicate", id: existingId };
    const reportId = `r-${(this.#seq += 1)}`;
    const payload: ReportPayload = Object.freeze({
      reportId,
      contentId: input.contentId,
      reason: input.reason,
      detail: (input.detail ?? "").trim().slice(0, 500),
      snapshotAt: input.snapshot.capturedAt,
      snapshotHash: input.snapshot.hash,
      evidence: input.snapshot,
      createdAt: now,
    });
    this.#entries.set(reportId, {
      payload,
      status: "queued",
      attempts: 0,
      nextAttemptAt: now,
      sentAt: null,
      receiptId: null,
    });
    this.#byContent.set(input.contentId, reportId);
    return { status: "queued", id: reportId };
  }

  report(id: string): ReportView | null {
    const view = this.#entries.get(id);
    return view ? { ...view } : null;
  }

  async flush(
    transport: (payload: ReportPayload) => Promise<{ receiptId: string }>,
  ): Promise<FlushResult> {
    const result: FlushResult = {
      sent: 0,
      failed: 0,
      skipped: 0,
      remaining: 0,
      offline: !this.#online,
    };
    if (!this.#online) {
      result.skipped = this.#queuedEntries().length;
      result.remaining = result.skipped;
      return result;
    }
    this.#prune(this.#now());
    for (const entry of this.#queuedEntries()) {
      if (entry.nextAttemptAt > this.#now()) {
        result.skipped += 1;
        continue;
      }
      try {
        const receipt = await transport(entry.payload);
        entry.status = "sent";
        entry.sentAt = this.#now();
        entry.receiptId = receipt.receiptId;
        result.sent += 1;
      } catch {
        entry.attempts += 1;
        entry.nextAttemptAt = this.#now() + this.#backoffMs * entry.attempts;
        result.failed += 1;
        if (entry.attempts >= this.#maxAttempts) entry.status = "failed";
        // 网络失败时停止本轮，保留剩余条目，避免失败期间继续放大请求。
        break;
      }
    }
    result.remaining = this.#queuedEntries().length;
    return result;
  }

  #queuedEntries(): ReportView[] {
    return [...this.#entries.values()]
      .filter((entry) => entry.status === "queued")
      .sort(
        (a, b) =>
          a.payload.createdAt - b.payload.createdAt ||
          a.payload.reportId.localeCompare(b.payload.reportId),
      );
  }

  // 已发送条目过了去重窗口、失败条目过了窗口，都从内存移除，允许重新举报。
  #prune(now: number): void {
    for (const [id, entry] of this.#entries) {
      const sentExpired =
        entry.status === "sent" && entry.sentAt !== null && now - entry.sentAt >= this.#dedupeWindowMs;
      const failedExpired =
        entry.status === "failed" && now - entry.payload.createdAt >= this.#dedupeWindowMs;
      if (!sentExpired && !failedExpired) continue;
      this.#entries.delete(id);
      if (this.#byContent.get(entry.payload.contentId) === id) {
        this.#byContent.delete(entry.payload.contentId);
      }
    }
  }
}

$ node --test --test-concurrency=1 test/moderation/report.test.ts
✔ 快照是冻结的深拷贝，作者改正文不会覆盖证据 (1.025292ms)
✔ 离线时只入队不调用传输层，恢复联网后仍能补发 (0.79575ms)
✔ 联网后按入队顺序发送并记录回执与发送时间 (0.243959ms)
✔ 同一内容在去重窗口内只保留一条，窗口外允许再次举报 (0.170583ms)
✔ 传输失败后保留队列并退避，本轮不再尝试后面的条目 (0.205708ms)
✔ 达到最大尝试次数后标记失败，窗口过后允许重新举报 (0.215041ms)
✔ 快照与举报内容不一致、理由非法时拒绝入队 (0.139708ms)
✔ 举报载荷带上快照时间、哈希与证据，长描述被裁剪 (0.150958ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 181.222209