《互联网产品的客户端架构·内容、社交与实时互动》9.2 可见性规则在端上的表达

// file: src/relations/visibility.ts
// tier: L1
// verify: node --test test/relations/visibility.test.ts
export type Visibility = "public" | "followers" | "friends" | "private";

// viewer 是「访问者相对作者」的关系：
// following = 访问者关注了作者；follower = 作者关注了访问者。
export type Viewer = "self" | "mutual" | "following" | "follower" | "none" | "blocked";

export type SurfaceState = "show" | "skeleton" | "locked" | "removed";

export type PredictionReason =
  | "public"
  | "self"
  | "mutual"
  | "following"
  | "owner-only"
  | "blocked"
  | "not-mutual"
  | "not-following";

export interface Prediction {
  visible: boolean;
  // certain 只表示「规则层面确定」，内容是否被删除或审核仍由服务端决定。
  confidence: "certain" | "hint";
  reason: PredictionReason;
}

export type ServerReason = "ok" | "blocked" | "restricted" | "deleted" | "not-found";

export interface ServerDecision {
  allowed: boolean;
  reason: ServerReason;
}

export interface ReconcileResult {
  state: "show" | "locked" | "removed";
  copy: string;
  cachedPreviewAllowed: boolean;
  correction: "none" | "too-optimistic" | "too-pessimistic";
}

export interface AudienceStats {
  followerCount: number;
  mutualCount: number;
}

export interface AudienceHint {
  label: string;
  detail: string;
}

export function predictVisibility(visibility: Visibility, viewer: Viewer): Prediction {
  if (viewer === "blocked") {
    return { visible: false, confidence: "certain", reason: "blocked" };
  }
  if (viewer === "self") {
    return { visible: true, confidence: "certain", reason: "self" };
  }
  if (visibility === "private") {
    return { visible: false, confidence: "certain", reason: "owner-only" };
  }
  if (visibility === "public") {
    return { visible: true, confidence: "certain", reason: "public" };
  }
  if (visibility === "friends") {
    return viewer === "mutual"
      ? { visible: true, confidence: "hint", reason: "mutual" }
      : { visible: false, confidence: "hint", reason: "not-mutual" };
  }
  return viewer === "following" || viewer === "mutual"
    ? { visible: true, confidence: "hint", reason: "following" }
    : { visible: false, confidence: "hint", reason: "not-following" };
}

// 只有规则层面确定的公开内容可以直接用缓存渲染。关注可见、好友可见
// 都只能先给骨架屏，等 service 确认后再展示正文。
export function initialSurface(prediction: Prediction): SurfaceState {
  if (!prediction.visible) return "locked";
  return prediction.confidence === "certain" ? "show" : "skeleton";
}

// 服务端拒绝后必须清掉端上缓存的标题、封面和摘要。这里的 copy 是固定文案，
// 不接收任何内容字段，从签名上就避免把不可见内容带进占位提示。
export function reconcile(prediction: Prediction, decision: ServerDecision): ReconcileResult {
  if (decision.allowed) {
    return {
      state: "show",
      copy: "",
      cachedPreviewAllowed: true,
      correction: prediction.visible ? "none" : "too-pessimistic",
    };
  }
  const removed = decision.reason === "deleted" || decision.reason === "not-found";
  return {
    state: removed ? "removed" : "locked",
    copy: placeholderCopy(decision.reason),
    cachedPreviewAllowed: false,
    correction: prediction.visible ? "too-optimistic" : "none",
  };
}

export function placeholderCopy(reason: ServerReason): string {
  if (reason === "deleted" || reason === "not-found") return "内容已删除";
  if (reason === "blocked") return "该内容暂不可见";
  return "内容暂不可见";
}

export function audienceHint(visibility: Visibility, stats: AudienceStats): AudienceHint {
  if (visibility === "public") {
    return { label: "所有人可见", detail: "公开内容可能出现在推荐与搜索里" };
  }
  if (visibility === "private") {
    return { label: "仅自己可见", detail: "不会进入他人的信息流" };
  }
  if (visibility === "friends") {
    const count = Math.max(0, Math.floor(stats.mutualCount));
    return {
      label: `互相关注的 ${count} 人可见`,
      detail: "互关关系解除后，历史内容会退出对方的可见范围",
    };
  }
  const count = Math.max(0, Math.floor(stats.followerCount));
  return {
    label: `关注你的 ${count} 人可见`,
    detail: "对方取关后，历史内容会退出其可见范围",
  };
}

$ node --test test/relations/visibility.test.ts
✔ 公开内容对所有关系都给出确定的可见预判 (0.806667ms)
✔ 关注可见只认「访问者关注作者」，被关注不算 (0.084292ms)
✔ 好友可见只认互关 (0.0595ms)
✔ 仅自己可见对他人一律隐藏，作者本人始终可见 (0.05875ms)
✔ 拉黑关系覆盖公开规则 (0.448583ms)
✔ 只有规则确定可见的内容可以直接渲染，其余先给骨架 (0.09625ms)
✔ 服务端决定覆盖预判：拒绝时清缓存，允许时纠正过严预判 (0.106334ms)
✔ 发布前的受众提示只写范围，不承诺具体名单 (0.132959ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 145.811708