Google 搜索重构的空白页教训：大规模上线时，边缘场景怎么兜底？

"""简化版搜索服务：演示优先级翻转后的 fallback 设计"""

from dataclasses import dataclass
from typing import Optional

@dataclass
class SearchResult:
    ai_overview: Optional[str] = None
    traditional_links: list[str] = None

    def render(self) -> str:
        """渲染搜索结果，保证至少有内容输出"""
        parts = []
        if self.ai_overview:
            parts.append(f"[AI 概览]\n{self.ai_overview}")
        if self.traditional_links:
            parts.append(f"[传统链接]\n" + "\n".join(f"  - {l}" for l in self.traditional_links))
        # 关键：如果两部分都为空，返回兜底提示而不是空白
        if not parts:
            parts.append("[兜底] 未找到相关结果，请尝试其他关键词")
        return "\n\n".join(parts)


def generate_ai_overview(query: str) -> Optional[str]:
    """模拟 AI 概览生成——某些词判定无需生成，返回 None"""
    skip_words = {"disregard", "ignore", "omit", "skip"}
    if query.lower().strip() in skip_words:
        # 这里是关键：不是静默跳过，而是明确返回 None 并记录原因
        print(f"[LOG] AI Overview 跳过词 '{query}'：判定为泛指词，无需生成摘要")
        return None
    return f"关于 {query} 的生成式摘要内容..."


def fetch_traditional_links(query: str) -> list[str]:
    """模拟传统搜索链接"""
    if not query.strip():
        return []
    return [f"https://example.com/search?q={query}&page=1",
            f"https://example.com/search?q={query}&page=2"]


def search(query: str) -> SearchResult:
    """搜索入口：AI 概览优先，失败时 fallback 到传统链接"""
    ai_overview = generate_ai_overview(query)
    traditional_links = fetch_traditional_links(query)

    # fallback 检查：如果 AI 概览为空，确保传统链接不为空
    if ai_overview is None and not traditional_links:
        print(f"[WARN] 查询 '{query}'：AI 概览和传统链接均空，触发兜底逻辑")

    return SearchResult(ai_overview=ai_overview, traditional_links=traditional_links)


# ---- 测试 ----
if __name__ == "__main__":
    test_queries = ["python async", "disregard", "", "machine learning"]

    for q in test_queries:
        print(f"\n{'='*40}")
        print(f"查询: '{q}'")
        print(f"{'='*40}")
        result = search(q)
        print(result.render())

# edge-case-checklist.yaml — 大规模重构前的边缘场景审查模板
review:
  priority_inversion:
    description: "检查所有优先级翻转的模块，确认 fallback 路径完整"
    checks:
      - 新默认模块失败时，旧模块是否能自动接管？
      - 接管后的输出是否对用户可见（而不是留白）？
      - 接管过程是否有日志和监控？

  empty_input:
    description: "合法但极端的输入值"
    checks:
      - 空字符串、单字符、纯数字输入是否都有处理？
      - 输入被上层模块跳过时，下层模块是否仍能收到请求？

  silent_failure:
    description: "模块返回 None/空但不报错的情况"
    checks:
      - 是否有全局兜底渲染逻辑（空白页防护）？
      - 静默跳过的决策是否有结构化日志？
      - 监控面板是否能区分"无结果"和"渲染失败"？

  regression_test:
    description: "旧功能在新架构下的可用性"
    checks:
      - 传统路径是否仍可独立工作（不依赖新模块）？
      - 是否有自动化测试覆盖 top 100之外的查询词？
      - 是否有灰度机制允许逐步切换优先级？