《互联网产品的客户端架构·内容、社交与实时互动》11.1 端上预检：能拦什么、不能拦什么

// file: src/moderation/precheck.ts
// tier: L1
// verify: node --test test/moderation/precheck.test.ts

export type PrecheckAction = "fix" | "review" | "hint";

export type PrecheckCode =
  | "empty"
  | "too-short"
  | "too-long"
  | "control-char"
  | "too-many-links"
  | "blocked-term";

export interface PrecheckIssue {
  code: PrecheckCode;
  action: PrecheckAction;
  message: string;
  detail?: string;
}

export interface PrecheckRules {
  minChars: number;
  maxChars: number;
  maxLinks: number;
  blockedTerms: readonly string[];
  allowPhrases: readonly string[];
  rulesVersion: string;
  appealPath: string;
}

export interface DraftInput {
  text: string;
  mediaCount?: number;
  links?: readonly string[];
}

export interface PrecheckResult {
  passed: boolean;
  canSubmit: boolean;
  requiresReview: boolean;
  appealPath: string | null;
  issues: PrecheckIssue[];
  rulesVersion: string;
}

const ZERO_WIDTH = /[\u200b-\u200f\u202a-\u202e\u2060\ufeff]/g;
const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/u;
const MAX_TERM_ISSUES = 3;
const segmenter = new Intl.Segmenter("zh", { granularity: "grapheme" });

// 按字素计数，避免一个家庭 emoji 被当成四五个字。
export function countGraphemes(text: string): number {
  let count = 0;
  for (const _ of segmenter.segment(text)) count += 1;
  return count;
}

// 只做 NFKC 与零宽字符清理；不删除空格和标点，避免把「黄。金」拼成「黄金」。
export function normalizeForMatch(text: string): string {
  return text.normalize("NFKC").toLowerCase().replace(ZERO_WIDTH, "");
}

export function createRules(input: {
  minChars: number;
  maxChars: number;
  maxLinks: number;
  blockedTerms: readonly string[];
  allowPhrases?: readonly string[];
  rulesVersion: string;
  appealPath: string;
}): PrecheckRules {
  if (!Number.isInteger(input.minChars) || input.minChars < 0) {
    throw new Error("minChars 必须是非负整数");
  }
  if (!Number.isInteger(input.maxChars) || input.maxChars <= input.minChars) {
    throw new Error("maxChars 必须是大于 minChars 的整数");
  }
  if (!Number.isInteger(input.maxLinks) || input.maxLinks < 0) {
    throw new Error("maxLinks 必须是非负整数");
  }
  const blockedTerms = input.blockedTerms.map(normalizeForMatch);
  for (const term of blockedTerms) {
    if (countGraphemes(term) < 2) {
      throw new Error(`本地术语必须是至少两个字符的短语：${term}`);
    }
    if (CONTROL.test(term)) throw new Error(`本地术语不能包含控制字符：${term}`);
  }
  const allowPhrases = (input.allowPhrases ?? []).map(normalizeForMatch).filter(Boolean);
  if (!input.rulesVersion.trim()) throw new Error("rulesVersion 不能为空");
  if (!input.appealPath.startsWith("/")) throw new Error("appealPath 必须是站内路径");
  return Object.freeze({
    minChars: input.minChars,
    maxChars: input.maxChars,
    maxLinks: input.maxLinks,
    blockedTerms: Object.freeze(blockedTerms),
    allowPhrases: Object.freeze(allowPhrases),
    rulesVersion: input.rulesVersion,
    appealPath: input.appealPath,
  });
}

// 允许短语先被遮掉，再在剩余文本里找术语；只遮短语本身，不影响其他位置。
function maskAllowed(text: string, allowPhrases: readonly string[]): string {
  let masked = text;
  for (const phrase of allowPhrases) {
    if (!phrase) continue;
    masked = masked.split(phrase).join("□".repeat(countGraphemes(phrase)));
  }
  return masked;
}

export function precheck(draft: DraftInput, rules: PrecheckRules): PrecheckResult {
  const text = draft.text ?? "";
  const mediaCount = draft.mediaCount ?? 0;
  const links = draft.links ?? [];
  const trimmed = text.trim();
  const issues: PrecheckIssue[] = [];

  if (trimmed === "" && mediaCount === 0 && links.length === 0) {
    issues.push({
      code: "empty",
      action: "fix",
      message: "内容为空，写点什么再提交",
    });
  }

  const chars = countGraphemes(trimmed);
  if (trimmed !== "" && chars < rules.minChars) {
    issues.push({
      code: "too-short",
      action: "hint",
      message: `只有 ${chars} 个字，太短的内容更容易被误解`,
      detail: `${chars}/${rules.minChars}`,
    });
  }
  if (chars > rules.maxChars) {
    issues.push({
      code: "too-long",
      action: "fix",
      message: `正文最多 ${rules.maxChars} 个字，当前 ${chars} 个`,
      detail: `${chars}/${rules.maxChars}`,
    });
  }
  if (CONTROL.test(text)) {
    issues.push({
      code: "control-char",
      action: "fix",
      message: "正文包含不可见的控制字符，请清除后重试",
    });
  }
  if (links.length > rules.maxLinks) {
    issues.push({
      code: "too-many-links",
      action: "fix",
      message: `最多放 ${rules.maxLinks} 个链接，当前 ${links.length} 个`,
      detail: `${links.length}/${rules.maxLinks}`,
    });
  }

  const normalized = normalizeForMatch(trimmed);
  const masked = maskAllowed(normalized, rules.allowPhrases);
  const hits: string[] = [];
  for (const term of rules.blockedTerms) {
    if (masked.includes(term) && !hits.includes(term)) hits.push(term);
  }
  for (const term of hits.slice(0, MAX_TERM_ISSUES)) {
    issues.push({
      code: "blocked-term",
      action: "review",
      message: "这段文字包含需要人工确认的词，可以直接提交复核",
      detail: term,
    });
  }

  const blocking = issues.some((issue) => issue.action !== "hint");
  const requiresReview = issues.some((issue) => issue.action === "review");
  return {
    passed: !blocking,
    canSubmit: !issues.some((issue) => issue.action === "fix"),
    requiresReview,
    appealPath: requiresReview ? rules.appealPath : null,
    issues,
    rulesVersion: rules.rulesVersion,
  };
}

$ node --test test/moderation/precheck.test.ts
✔ 空内容不可提交，也没有申诉入口 (1.135708ms)
✔ 长度按字素计数，家庭 emoji 只算一个字 (0.140583ms)
✔ 单字术语与非法规则在构造时就被拒绝 (0.282375ms)
✔ 命中术语只要求复核，不阻止提交并给出申诉路径 (0.13775ms)
✔ 允许短语只遮住自身区间，不放过区间外的命中 (0.124417ms)
✔ 零宽字符不能绕过匹配，NFKC 统一全角与大小写 (0.083ms)
✔ 控制字符与过多链接都是硬阻断，不提供申诉 (0.099084ms)
✔ 过短只是提示，仍然算通过并可提交 (0.086333ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 198.315458