feat: implement detail caching for news articles to optimize content fetching

README.md

@@ -26,6 +26,8 @@ news_service/
     mainnews.json
     ranknews.json
     worldnews.json
+    detail-cache.json
+    images/
   src/
     app/
     config/
@@ -110,6 +112,12 @@ POST /api/news/refresh
 POST /api/news/refresh?category=flashnews
 ```
 
+## 缓存
+
+- 分类列表和前端返回数据会落盘到 `data/<category>.json`。
+- 详情正文会按详情页 URL 去重缓存到 `data/detail-cache.json`，同一篇新闻后续刷新不会重复抓详情页。
+- 正文图片会下载到 `data/images/`，正文 HTML 里的图片地址会替换成 `/api/news/images/<file>`。
+
 ## Docker
 
 ```bash

src/services/NewsApiClient.js

@@ -20,6 +20,7 @@ class NewsApiClient {
     this._pageSize = options.pageSize || 20
     this._fetch = options.fetchImplementation || fetch
     this._imageStorage = options.imageStorage || new NewsImageStorage(options.dataDirectory)
+    this._detailCache = options.detailCache || new NewsDetailCache(options.dataDirectory)
   }
 
   /**
@@ -172,6 +173,11 @@ class NewsApiClient {
    * @returns {Promise<string>}
    */
   async _fetchArticleContent(detailUrl, worldNews) {
+    const cachedContent = await this._detailCache.get(detailUrl)
+    if (cachedContent) {
+      return cachedContent
+    }
+
     let response
     try {
       response = await this._fetch(detailUrl)
@@ -186,7 +192,11 @@ class NewsApiClient {
       ? this._extractElementHtmlById(html, 'content')
       : this._extractTagHtml(html, 'article')
 
-    return this._replaceContentImages(content || '', detailUrl)
+    const normalizedContent = await this._replaceContentImages(content || '', detailUrl)
+    if (normalizedContent) {
+      await this._detailCache.set(detailUrl, normalizedContent)
+    }
+    return normalizedContent
   }
 
   /**
@@ -317,6 +327,60 @@ class NewsImageStorage {
   }
 }
 
+class NewsDetailCache {
+  constructor(dataDirectory) {
+    this._cachePath = path.resolve(dataDirectory || './data', 'detail-cache.json')
+    this._entries = null
+  }
+
+  /**
+   * @param {string} detailUrl
+   * @returns {Promise<string>}
+   */
+  async get(detailUrl) {
+    const entries = await this._load()
+    const entry = entries[detailUrl]
+    return entry?.content || ''
+  }
+
+  /**
+   * @param {string} detailUrl
+   * @param {string} content
+   * @returns {Promise<void>}
+   */
+  async set(detailUrl, content) {
+    const entries = await this._load()
+    entries[detailUrl] = {
+      content,
+      cachedAt: new Date().toISOString()
+    }
+    await fs.mkdir(path.dirname(this._cachePath), { recursive: true })
+    await fs.writeFile(this._cachePath, `${JSON.stringify(entries, null, 2)}\n`)
+  }
+
+  /**
+   * @returns {Promise<Record<string, {content: string, cachedAt: string}>>}
+   */
+  async _load() {
+    if (this._entries) {
+      return this._entries
+    }
+
+    try {
+      const raw = await fs.readFile(this._cachePath, 'utf8')
+      const parsed = JSON.parse(raw)
+      this._entries = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        this._entries = {}
+        return this._entries
+      }
+      this._entries = {}
+    }
+    return this._entries
+  }
+}
+
 function extensionFromContentType(contentType) {
   const normalized = String(contentType || '').split(';')[0].trim().toLowerCase()
   const byContentType = {
@@ -370,5 +434,6 @@ function escapeRegExp(value) {
 
 module.exports = {
   NewsApiClient,
-  NewsImageStorage
+  NewsImageStorage,
+  NewsDetailCache
 }