專案日誌與交接文件：core-scraper

最後更新: 2025-10-07 整體狀態: ✅ 功能正常 | 初版開發完成

本文檔旨在記錄專案的開發過程、當前狀態以及未來的維護和開發建議，作為一份詳細的工作交接文件。

1. 現狀詳情 (Current Situation)

本專案是一個趨勢新聞聚合器。它透過一系列的爬蟲從多個來源（BBC、Google、PTT、Reddit）抓取熱門趨勢，並透過一個 Flask 網站應用程式將結果以統一的卡片佈局進行展示。

核心組件:

關鍵架構決策: 專案的核心設計理念是「統一化」。所有爬蟲的輸出都被標準化為統一的 TrendItem 資料結構 (scrapers/schema.py)。與此對應，前端 index.html 模板使用一個「通用卡片」元件來渲染所有資料，極大地簡化了前端邏輯並確保了視覺一致性。

目前，專案的初版功能已全部完成，所有已知的 Bug 都已修復，程式碼也經過了重構，並已提交至 Git 版本庫。

在本次開發週期中，我們完成了一次從「啟動與偵錯」到「重構與交付」的完整流程。

應用程式設定: 初始化了 Flask 應用、爬蟲結構和整體專案目錄。
關鍵錯誤修復:
1. Flask 啟動錯誤: 修復了因 Flask 版本更新，@app.before_first_request 被廢棄而導致的啟動失敗問題。
2. 資料載入錯誤: 解決了在 Flask 偵錯模式下，因 Werkzeug 重新載入器 (reloader) 的多進程模型，導致資料快取在工作進程中為空，頁面無法顯示內容的深層 Bug。
Google 爬蟲攻堅與重寫:
- 第一階段 (Playwright): 最初的瀏覽器模擬方案因 Google 的 reCAPTCHA 驗證而失敗。
- 第二階段 (pytrends): 嘗試使用非官方 API，但因 Google 伺服器回傳 404 錯誤而失敗。
- 最終方案 (RSS Feed): 最終採用了最穩健的 RSS Feed 方案，並透過 requests 函式庫添加 User-Agent 標頭，成功繞過了 Google 的基礎驗證，實現了穩定的資料抓取。
前端重構:
- 將 index.html 中針對不同來源的、複雜且重複的 if/elif 判斷區塊，重構為一個簡潔、統一的通用卡片渲染迴圈，大幅提升了程式碼的可讀性和可維護性。
專案與版本控制:
- 使用 uv 完成了所有依賴的安裝與管理（新增 pytrends、移除 playwright、最終加回 playwright）。
- 建立了 .gitignore 檔案以確保版本庫的潔淨。
- 以一份詳盡的提交訊息，將所有工作成果存入 Git 版本庫，完成了專案的首次提交。

爬蟲的脆弱性: 請注意，所有基於網頁爬取的程式都有其脆弱性。如果未來某個資料來源無法更新，請優先檢查 scrapers/ 目錄下對應的爬蟲檔案。目標網站的 HTML 結構變動是導致爬蟲失效的最常見原因。

[ ] 自動化執行: 建議設定一個排程任務 (例如 Windows 的「工作排程器」或 Linux 的 cron，甚至是 GitHub Actions)，週期性地執行 uv run -m main，以確保資料的時效性。
[ ] 錯誤處理與日誌: 目前的錯誤處理僅僅是將訊息印在控制台。可以引入更強大的日誌系統（例如 Python 內建的 logging 模組），將爬取過程中的錯誤記錄到檔案中，方便追蹤和排查。
[ ] 前端功能擴充: 目前的前端功能比較基礎。未來可以考慮增加：
- 依據 score (熱度) 或 timestamp (時間) 進行排序的功能。
- 關鍵字搜尋功能。
- 更豐富的視覺化圖表。
[ ] 新增資料來源: 得益於統一的架構，新增資料來源變得非常簡單。只需在 scrapers/ 目錄下建立一個新的爬蟲，確保其最終輸出的資料符合 TrendItem 結構，然後在 config.py 中加入對應的設定即可。