《互联网产品的客户端架构·内容、社交与实时互动》12.3 发现页的推荐位与内容流的差异

interface FixedSlot {
  slotId: string;
  source: "promotion" | "ranking" | "topic";
  position: number;
  limit: number;
}

// file: src/search/discover.ts
// tier: L1
// verify: node --test test/search/discover.test.ts
import type { ContentItem } from "../core/content-model.ts";

export type DiscoverSource = "feed" | "promotion" | "ranking" | "topic";
export type FixedSource = Exclude<DiscoverSource, "feed">;

export interface SourcePage {
  source: DiscoverSource;
  items: ContentItem[];
}

export interface FixedSlot {
  slotId: string;
  source: FixedSource;
  position: number;
  limit: number;
}

export interface DiscoverLayout {
  total: number;
  fixed: FixedSlot[];
}

export interface DiscoverEntry {
  position: number;
  slotId: string;
  source: DiscoverSource;
  item: ContentItem | null;
  impressionKey: string | null;
}

export interface DiscoverResult {
  entries: DiscoverEntry[];
  duplicates: number;
  placeholders: number;
}

export function exposureKey(slotId: string, itemId: string): string {
  return `${slotId}:${itemId}`;
}

export function validateLayout(layout: DiscoverLayout): void {
  if (!Number.isInteger(layout.total) || layout.total < 1) throw new Error("total 必须是正整数");
  const seen = new Set<string>();
  const slots = [...layout.fixed].sort((a, b) => a.position - b.position);
  let previousEnd = 0;
  for (const slot of slots) {
    if (slot.slotId.trim() === "") throw new Error("slotId 不能为空");
    if (seen.has(slot.slotId)) throw new Error(`slotId 重复：${slot.slotId}`);
    seen.add(slot.slotId);
    if (!Number.isInteger(slot.position) || slot.position < 0) throw new Error(`槽位 ${slot.slotId} 的 position 非法`);
    if (!Number.isInteger(slot.limit) || slot.limit < 1) throw new Error(`槽位 ${slot.slotId} 的 limit 非法`);
    if (slot.position + slot.limit > layout.total) throw new Error(`槽位 ${slot.slotId} 超出页面范围`);
    if (slot.position < previousEnd) throw new Error(`槽位 ${slot.slotId} 与前一个槽位重叠`);
    previousEnd = slot.position + slot.limit;
  }
}

export function composeDiscover(layout: DiscoverLayout, pages: SourcePage[]): DiscoverResult {
  validateLayout(layout);
  const bySource = new Map<DiscoverSource, ContentItem[]>();
  for (const page of pages) {
    const list = bySource.get(page.source) ?? [];
    list.push(...page.items);
    bySource.set(page.source, list);
  }

  const used = new Set<string>();
  const cursors = new Map<DiscoverSource, number>();
  let duplicates = 0;
  let placeholders = 0;

  const take = (source: DiscoverSource, limit: number): ContentItem[] => {
    const list = bySource.get(source) ?? [];
    let index = cursors.get(source) ?? 0;
    const picked: ContentItem[] = [];
    while (picked.length < limit && index < list.length) {
      const item = list[index];
      index += 1;
      if (used.has(item.id)) {
        duplicates += 1;
        continue;
      }
      used.add(item.id);
      picked.push(item);
    }
    cursors.set(source, index);
    return picked;
  };

  const reserved = new Set<number>();
  const entriesByPosition = new Map<number, DiscoverEntry>();
  const fixed = [...layout.fixed].sort((a, b) => a.position - b.position);
  for (const slot of fixed) {
    for (let offset = 0; offset < slot.limit; offset += 1) {
      const position = slot.position + offset;
      reserved.add(position);
      const [item] = take(slot.source, 1);
      if (!item) {
        placeholders += 1;
        entriesByPosition.set(position, {
          position,
          slotId: slot.slotId,
          source: slot.source,
          item: null,
          impressionKey: null,
        });
        continue;
      }
      entriesByPosition.set(position, {
        position,
        slotId: slot.slotId,
        source: slot.source,
        item,
        impressionKey: exposureKey(slot.slotId, item.id),
      });
    }
  }

  for (let position = 0; position < layout.total; position += 1) {
    if (reserved.has(position)) continue;
    const [item] = take("feed", 1);
    // 信息流取尽后页面到此结束；固定槽位仍按声明位置保留。
    if (!item) break;
    entriesByPosition.set(position, {
      position,
      slotId: "feed",
      source: "feed",
      item,
      impressionKey: exposureKey("feed", item.id),
    });
  }

  return {
    entries: [...entriesByPosition.values()].sort((a, b) => a.position - b.position),
    duplicates,
    placeholders,
  };
}

$ node --test --test-concurrency=1 test/search/discover.test.ts
✔ 固定槽位内容不足时留占位，后续槽位位置不变 (0.997041ms)
✔ 跨源去重时位置靠前的槽位优先，信息流跳过已用内容 (0.136791ms)
✔ 信息流只填充未被固定槽位占用的位置 (0.468084ms)
✔ 同一来源内的重复 id 只取一次并计入去重 (0.1115ms)
✔ 曝光 key 与位置无关，与槽位和内容有关 (0.109416ms)
✔ 布局校验拒绝重叠、越界与重复槽位 (0.275417ms)
✔ 信息流取尽后页面结束，后面的固定槽位仍按声明位置输出 (0.080708ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 128.837833