news-base：从抓取到页面展示的简化时序图

归类：开发工具 / 内容聚合 / VitePress 发生时间：2026-03-30 状态：✅ 已落地

---

一、背景

news-base 不是单纯的“抓新闻脚本”，而是一条完整的数据到页面链路：

1. 抓取真实新闻源或 GitHub Trending。
2. 当某个分类结果不足时自动补齐兜底内容。
3. 统一生成静态 JSON 契约。
4. 由 VitePress 页面组件直接消费这些 JSON 完成展示。

这意味着页面层并不直接依赖抓取实现，而是依赖稳定的数据产物。

二、简化时序图

sequenceDiagram
  autonumber
  participant Trigger as CLI / GitHub Actions
  participant Crawler as scripts/crawl_news.js
  participant Sources as 真实新闻源 / GitHub Trending
  participant Fallback as 分类兜底数据
  participant Json as public/api + docs/public/api
  participant Archive as data/daily + archive/*
  participant Page as VitePress 页面
  participant Components as NewsMetrics / NewsDashboard / NewsBoard
  participant User as 读者

  Trigger->>Crawler: 执行 pnpm run crawl / site:prepare
  Crawler->>Sources: 按来源配置抓取 RSS / HTML / Trending
  Sources-->>Crawler: 返回原始条目
  Crawler->>Crawler: 规范化、去重、排序、补充热度与 importance
  alt 某分类内容不足
    Crawler->>Fallback: 读取 fallbackCatalog
    Fallback-->>Crawler: 补足分类最小条数
  end
  Crawler->>Json: 写入 latest / overview / stats / categories/*
  Crawler->>Archive: 写入 daily/*.json 并重建 archive/index 与 months/*
  Page->>Components: 加载首页、今日页、分类页
  Components->>Json: fetch /api/*.json
  Json-->>Components: 返回结构化 JSON
  Components-->>User: 渲染概览卡片、新闻列表、分类专区与后台说明页

三、这条链路怎么理解

1. 抓取层

抓取入口是 scripts/crawl_news.js。它会读取来源配置，并根据不同来源类型抓 RSS、Atom、HTML 或 GitHub Trending 页面，再把返回结果统一转换成站点内部的新闻模型。

2. 兜底层

真实源会受网络、页面结构变化或平台限制影响，所以脚本不会把“真实抓取失败”直接等同于“站点不可用”。如果某个分类结果不足，脚本会从内置的 fallbackCatalog 补齐内容，保证每个专区都有最小可展示条数。

3. 产物层

抓取和补齐完成后，脚本会一次性生成多份静态产物：

• latest.json：今日总览与完整列表
• overview.json：首页指标、分类概览与重点摘要
• stats.json：标签、热度与整体统计
• categories/{id}.json：分类专区数据
• daily/{date}.json：按日归档快照
• archive/index.json 与 archive/months/*.json：在线归档与月度聚合

这些 JSON 会被同步写到运行时目录和文档站点目录，保证本地构建与发布态消费同一份结构。

4. 展示层

页面组件只做一件事：读取 JSON 并渲染。

• NewsMetrics.vue 读取 overview.json
• NewsDashboard.vue 读取 latest.json
• NewsBoard.vue 读取 categories/{id}.json

因此，首页、今日页、分类页、reader 模式和 admin 模式都能共用同一套数据契约。

四、为什么这种设计值得复用

1. 页面层和抓取层解耦，后续替换抓取器时不需要重写站点页面。
2. 真实源优先、分类兜底补齐，让自动化构建更稳，不会因为单一来源失败导致页面整体空白。
3. JSON 既是页面消费产物，也是文档说明和自动化归档的中间层，方便调试、发布和回溯。
4. reader 模式与 admin 模式共用一套数据，只是展示壳和导航策略不同，避免了双份实现。

五、适合记住的核心结论

如果要快速向团队解释 news-base，可以直接用一句话概括：

news-base 先把多来源内容收敛成统一 JSON，再让页面组件只围绕 JSON 工作，所以抓取、归档、文档和展示可以稳定闭环。