daily-news-app/daily-news-SDD.md

每日報導 APP 功能規格書 (Functional Specification) 文件版本 1.2 建立日期 2025-11-24 最後更新 2025-01-27 專案名稱 每日報導 APP 專案類型 內部工具

1. 專案概述 1.1 專案目標 建立一套企業內部新聞彙整與分析系統，協助市場分析專員有效率地蒐集、篩選並彙整產業新聞，透過 AI 自動摘要功能產出綜合分析報告，供內部讀者訂閱閱讀。 1.2 用戶故事 用戶故事 A：市場分析專員 身為市場分析專員，我需要一個方法來縮短每天用關鍵字查找各大網站新聞的過程，因為目前耗用太多時間。 用戶故事 B：讀者 身為讀者，我需要一個方法來針對市場分析專員所提供的資料進行分析，因為目前耗用太多時間。 1.3 預估使用者規模 角色 人數 說明 系統管理員 1-2 位 負責系統設定與維護 市場分析專員 1 位 負責新聞篩選與發布 讀者 40 位 訂閱並閱讀報告

2. 系統架構 2.1 部署環境 • 部署方式：地端部署（1Panel 管理介面） • 前端平台：Web 優先，支援行動裝置響應式設計 • 系統語言：繁體中文 / 英文雙語介面 • 語言切換：用戶手動選擇（右上角切換）+ 系統自動偵測瀏覽器語言 • 內容翻譯：摘要內容支援自動翻譯（新聞內容不翻譯） 2.2 技術架構 • 前端框架：React（混合模式渲染） • 前端通訊：RESTful API • 後端框架：FastAPI (Python 3.11+) • 資料庫：MySQL 8.0 • 資料庫 ORM：SQLAlchemy（連線池管理） • 快取系統：Redis • 任務佇列：Celery + Redis/RabbitMQ • LLM 整合：支援 Google Gemini API / OpenAI API / Ollama 地端模型 • 認證整合：AD/LDAP 驗證 + 本地帳號

3. 角色與權限 角色 權限範圍 系統管理員 LLM 設定、AD 整合、群組管理、用戶管理、系統設定 市場分析專員 新聞抓取管理、篩選編輯、報告發布、群組內容設定 讀者 訂閱群組、閱讀報告、留言討論、個人收藏、匯出 PDF

4. 功能需求 4.1 新聞抓取模組 4.1.1 新聞來源 來源 登入方式 抓取內容 Digitimes 帳號密碼登入（付費訂閱） 全文擷取 經濟日報 公開網頁爬取 全文擷取 工商時報 公開網頁爬取 全文擷取

4.1.2 抓取技術 • 爬蟲框架：Scrapy（高效能爬蟲框架） • 登入狀態管理：維持 session，定期檢查有效性，使用 Cookie 持久化 • 去重機制：比對標題 + 發布時間，避免重複抓取 • 新聞欄位提取：標題（必填）、正文內容（必填）、發布時間（必填）

4.1.3 抓取排程 • 定時抓取：每日 08:00 執行 • 抓取範圍：即時累積至當日的新聞 • 資料存儲：建立新聞資料庫供日後查詢 • 處理方式：使用 Celery 任務佇列進行非同步處理

4.1.4 異常處理

1. 系統自動重試（最多 3 次，間隔 5 分鐘）
2. 部分成功的新聞先處理，失敗的稍後重試
3. 重試失敗後通知系統管理員
4. 專員可透過介面手動觸發重新抓取

4.2 關鍵字群組管理 4.2.1 群組分類方式 • 依產業別分群：半導體、面板、車用電子...等 • 依議題分群：政策法規、市場趨勢...等 4.2.2 群組設定項目 • 群組名稱與描述 • 關鍵字清單（可新增、編輯、刪除） • AI 摘要背景資訊設定 • AI 摘要方向設定（每個群組獨立設定） 4.2.3 群組與報告關係 一份報告 = 一個群組的彙整內容

4.3 AI 摘要模組 本系統整合多種大型語言模型 (LLM) 服務，提供靈活的 AI 摘要能力，系統管理員可依據需求切換不同的 LLM 提供者。 4.3.1 支援的 LLM 提供者 提供者 類型 建議模型 適用場景 Google Gemini 雲端 API gemini-1.5-pro 長文本分析、多語言 OpenAI 雲端 API gpt-4o / gpt-4o-mini 通用摘要、高品質輸出 Ollama 地端部署 llama3 / qwen2 / gemma2 資料不外流、離線使用

4.3.2 Google Gemini API 整合規格 API 端點 • Base URL: https://generativelanguage.googleapis.com/v1beta • 認證方式: API Key (透過 URL 參數或 Header) 支援模型 • gemini-1.5-pro: 最高品質，支援 100 萬 tokens 上下文 • gemini-1.5-flash: 快速回應，適合即時摘要 • gemini-1.0-pro: 穩定版本，成本較低 請求格式 POST /v1beta/models/{model}:generateContent Content-Type: application/json 設定參數 參數 預設值 說明 temperature 0.7 控制輸出隨機性 (0-1) maxOutputTokens 2048 最大輸出 token 數 topP 0.95 nucleus sampling 參數 topK 40 top-k sampling 參數

4.3.3 OpenAI API 整合規格 API 端點 • Base URL: https://api.openai.com/v1 • 認證方式: Bearer Token (Authorization Header) 支援模型 • gpt-4o: 最新多模態模型，高品質輸出 • gpt-4o-mini: 輕量版本，成本效益高 • gpt-4-turbo: 128K 上下文，適合長文 請求格式 POST /v1/chat/completions Content-Type: application/json 設定參數 參數 預設值 說明 temperature 0.7 控制輸出隨機性 (0-2) max_tokens 2048 最大輸出 token 數 top_p 1.0 nucleus sampling 參數 frequency_penalty 0 重複懲罰 (-2 至 2) presence_penalty 0 新話題懲罰 (-2 至 2)

4.3.4 Ollama API 整合規格（地端部署） API 端點 • Base URL: http://localhost:11434 (可自訂) • 認證方式: 無需認證（建議內網部署） 支援模型（需預先下載） • llama3:8b / llama3:70b: Meta 開源模型，繁中支援佳 • qwen2:7b / qwen2:72b: 阿里巴巴模型，中文最佳化 • gemma2:9b / gemma2:27b: Google 開源模型 • mistral:7b: 歐洲開源模型，效能優異 請求格式 POST /api/generate 或 POST /api/chat Content-Type: application/json 設定參數 參數 預設值 說明 temperature 0.7 控制輸出隨機性 (0-1) num_predict 2048 最大輸出 token 數 top_p 0.9 nucleus sampling 參數 top_k 40 top-k sampling 參數 stream false 是否串流輸出 硬體需求建議 模型規模 最低記憶體 建議配置 7B-8B 參數 8GB RAM 16GB RAM + GPU 8GB 13B-27B 參數 16GB RAM 32GB RAM + GPU 16GB 70B+ 參數 64GB RAM 128GB RAM + GPU 48GB+

4.3.5 LLM 設定管理介面 管理員設定功能 • 選擇 LLM 提供者（下拉選單切換） • 設定 API Key（加密儲存於資料庫） • 選擇使用的模型版本 • 設定 Ollama 端點 URL（地端部署時） • 調整生成參數（temperature, max_tokens 等） • 連線測試功能（顯示回應時間） 全系統統一設定 LLM 設定由系統管理員統一配置，所有群組共用相同的模型與參數，確保輸出品質一致性。

4.3.6 摘要處理邏輯 多篇新聞合併策略 • 全部合併成一段綜合分析（無數量限制） • 當新聞內容超過模型 token 限制時，先進行初步摘要再送 LLM • 背景資訊與摘要方向放在 user prompt 開頭傳遞給 LLM • 處理方式：串行處理（一個接一個群組依序產生摘要）

摘要輸出格式 • 多篇相關新聞合併產出一段綜合分析 • 純文字格式，適合閱讀與匯出 • 每個群組可設定專屬的背景資訊與摘要方向

4.3.7 錯誤處理與備援 • API 呼叫失敗時自動重試（最多 3 次） • 摘要失敗時通知專員手動處理 • 記錄錯誤日誌供管理員查看 • 支援設定備援 LLM 提供者（未來擴充）

4.4 報告發布模組（專員端） 4.4.1 篩選介面功能 • 勾選/排除特定新聞 • 可手動編輯 AI 摘要內容 • 預覽發布前報告呈現 4.4.2 發布規則 • 發布時間：工作日 09:00 前必須發出 • 工作日定義：週一至週五（排除假日），使用台灣行事曆 API 判斷 • 逾時處理：延遲發布時通知讀者 • 已發布報告：專員可以撤回（標記為已撤回），但不可修改內容

4.4.3 通知機制 Email 通知規格 • Email 內容：報告標題、發布日期、AI 摘要內容、線上閱讀連結 • Email 樣式：響應式 HTML（支援手機閱讀） • 發送策略：批次發送（每批 10 封） • 失敗處理：記錄失敗日誌、通知系統管理員

4.5 讀者端功能 4.5.1 訂閱管理 • 讀者可自行訂閱感興趣的群組 • 一位讀者可訂閱多個群組報告 4.5.2 閱讀介面 • 響應式設計，支援手機閱讀 • 報告瀏覽與歷史查詢 4.5.3 互動功能 • 留言功能：同群組讀者皆可見（討論性質） • 留言審核：關鍵字過濾後自動審核 • 收藏功能：個人收藏清單（未來擴充） • 標註功能：個人筆記用途（未來擴充）

4.5.4 匯出功能 PDF 匯出規格 • 生成技術：ReportLab • PDF 內容：公司 Logo、報告標題、發布日期、AI 摘要內容、相關新聞列表（標題 + 連結）、頁首頁尾文字 • PDF 樣式：固定樣式（不可自訂） • 權限：專員與讀者皆有權限匯出

4.6 系統管理模組 4.6.1 用戶管理 • AD/LDAP 整合：僅驗證帳密 • 支援非 AD 帳號（外部顧問、實習生等） • 角色指派與權限管理 4.6.2 LLM 設定 • 提供者選擇：Google Gemini / OpenAI / Ollama • API 金鑰管理：儲存在環境變數（加密儲存） • 加密金鑰輪換：每 3 個月定期輪換 • 模型版本選擇 • Ollama 端點設定（地端部署） • 連線測試與回應時間顯示

4.6.3 PDF 模板設定 • 可上傳公司 Logo • 自訂頁首頁尾文字 • 固定樣式模板（不可自訂）

5. 每日工作流程 時間 執行者 動作 08:00 系統 自動抓取各新聞來源當日累積新聞 08:00 系統 依關鍵字群組分類新聞並呼叫 LLM 產生 AI 摘要 08:30 專員 登入系統審核新聞，勾選/排除、編輯摘要 09:00 前 專員 確認無誤後發布報告 09:00 系統 發送 Email 通知給已訂閱該群組的讀者 全天 讀者 登入閱讀、留言、收藏、匯出 PDF

6. 非功能性需求 6.1 效能需求 • 新聞抓取完成時間：30 分鐘內（含 AI 摘要） • 頁面載入時間：3 秒內 • 同時在線用戶：至少 50 人 • LLM 摘要回應時間：單次請求 30 秒內 • 快取策略：使用 Redis 快取提升查詢效能 • 資料庫連線：使用 SQLAlchemy 連線池管理

6.2 資料保留政策 • 報告與新聞資料保留期限：60 天 • 操作日誌保留期限：60 天 • 過期資料自動清理機制

6.3 可用性需求 • 系統可用性：工作日 07:00-22:00 需正常運作 • 備份策略：每日增量備份 • 任務處理：使用 Celery + Redis/RabbitMQ 進行非同步任務處理

6.4 安全性需求 • AD/LDAP 認證整合 • HTTPS 加密傳輸 • API Key 加密儲存（AES-256），儲存在環境變數 • 加密金鑰輪換：每 3 個月定期輪換 • 操作日誌記錄：記錄用戶登入/登出、新聞抓取記錄、AI 摘要產生記錄、報告發布記錄、系統錯誤記錄、API 呼叫記錄

6.5 監控與告警 • 系統健康檢查 • 新聞抓取失敗告警 • AI 摘要失敗告警 • 資料庫連線異常告警 • 系統效能監控

7. LLM 成本估算 以下為各 LLM 提供者的預估成本（以每日 50 篇新聞、每篇 1000 字計算）： 提供者 輸入成本 輸出成本 每月估算 Google Gemini $0.00025/1K tokens $0.0005/1K tokens 約 $5-15 OpenAI GPT-4o $0.005/1K tokens $0.015/1K tokens 約 $30-60 OpenAI GPT-4o-mini $0.00015/1K tokens $0.0006/1K tokens 約 $3-8 Ollama (地端) 免費 免費 僅硬體成本

• 實際成本依使用量而異，建議先以小量測試確認

8. 資料庫設計 8.1 主要資料表 • users（用戶表）：儲存用戶基本資訊與角色 • groups（群組表）：儲存關鍵字群組設定 • keywords（關鍵字表）：儲存各群組的關鍵字清單 • news（新聞表）：儲存抓取的新聞內容 • reports（報告表）：儲存每日產出的報告 • report_news（報告新聞關聯表）：多對多關聯表，記錄報告與新聞的對應關係 • comments（留言表）：儲存讀者留言 • llm_settings（LLM 設定表）：儲存 LLM 提供者與參數設定 • system_logs（系統日誌表）：儲存系統操作與錯誤日誌 • user_group_subscriptions（用戶群組訂閱表）：記錄用戶訂閱的群組（多對多關係）

8.2 關聯關係 • 報告與新聞：多對多關係（一篇新聞可出現在多份報告），透過 report_news 關聯表 • 群組與報告：一對一關係（一份報告對應一個群組） • 用戶與群組：多對多關係（用戶可訂閱多個群組），透過 user_group_subscriptions 關聯表

8.3 索引策略 • 新聞標題索引：優化新聞查詢效能 • 新聞發布時間索引：優化時間範圍查詢 • 群組關鍵字索引：優化關鍵字匹配效能 • 用戶訂閱關係索引：優化訂閱查詢效能 • 報告發布時間索引：優化報告歷史查詢

9. 環境變數配置 所有敏感資訊與連線設定均透過環境變數管理，確保安全性與彈性。

9.1 資料庫連線（已確認） • DB_HOST：mysql.theaken.com • DB_PORT：33306 • DB_NAME：db_A101 • DB_USER：A101 • DB_PASSWORD：Aa123456 • 連線狀態：✅ 測試連線正常

9.2 Redis 連線（必填） • REDIS_HOST：Redis 主機位址（預設：localhost） • REDIS_PORT：Redis 埠號（預設：6379） • REDIS_PASSWORD：Redis 密碼（如有） • REDIS_DB：Redis 資料庫編號（預設：0）

9.3 Celery 設定（必填） • CELERY_BROKER_URL：訊息佇列 URL（格式：redis://[password@]host:port/db 或 amqp://user:password@host:port/vhost） • CELERY_RESULT_BACKEND：結果儲存位置（通常與 broker 相同）

9.4 SMTP 設定（必填） • SMTP_HOST：SMTP 伺服器位址 • SMTP_PORT：SMTP 埠號（預設：587） • SMTP_USERNAME：SMTP 帳號 • SMTP_PASSWORD：SMTP 密碼 • SMTP_FROM_EMAIL：寄件者 Email • SMTP_FROM_NAME：寄件者名稱（預設：每日報導系統） • SMTP_USE_TLS：是否使用 TLS（預設：True）

9.5 AD/LDAP 設定（選填） • LDAP_SERVER：LDAP 伺服器位址 • LDAP_PORT：LDAP 埠號（預設：389） • LDAP_BASE_DN：LDAP Base DN • LDAP_BIND_DN：LDAP 綁定 DN（如有） • LDAP_BIND_PASSWORD：LDAP 綁定密碼（如有） • LDAP_USER_SEARCH_FILTER：用戶搜尋過濾器（預設：(sAMAccountName={username})）

9.6 LLM API Keys（選填，依選擇的提供者設定） • GEMINI_API_KEY：Google Gemini API Key • OPENAI_API_KEY：OpenAI API Key • OLLAMA_ENDPOINT：Ollama 端點 URL（預設：http://localhost:11434）

9.7 Digitimes 帳號（必填） • DIGITIMES_USERNAME：Digitimes 登入帳號 • DIGITIMES_PASSWORD：Digitimes 登入密碼

9.8 應用程式設定（必填） • SECRET_KEY：應用程式密鑰（用於加密，建議至少 32 字元） • JWT_SECRET_KEY：JWT 簽章密鑰（建議至少 32 字元） • APP_ENV：環境（development/staging/production） • DEBUG：除錯模式（預設：False，生產環境必須為 False）

9.9 環境變數管理方式 • 開發環境：使用 .env 檔案（不納入版本控制） • 生產環境：使用 1Panel 環境變數設定介面 • 敏感資訊：API Keys、密碼等均加密儲存 • 加密方式：AES-256 加密，加密金鑰儲存在環境變數中

10. 附錄 10.1 名詞定義 名詞 定義 群組 依產業別或議題分類的關鍵字集合，作為新聞分類與報告產出的單位 報告 針對單一群組，彙整相關新聞並產出 AI 綜合摘要的每日產出物 專員 市場分析專員，負責新聞篩選、編輯與發布工作 讀者 訂閱並閱讀報告的內部用戶 LLM Large Language Model，大型語言模型，用於產生 AI 摘要 Ollama 開源的本地 LLM 執行框架，可在企業內部部署運行

10.2 待確認事項

1. Digitimes 帳號憑證管理方式 → 已確認：管理者設定
2. 經濟日報、工商時報爬蟲策略 → 已確認：請求間隔 3-5 秒
3. PDF Logo → 已確認：開放上傳選項
4. Email 發送服務 → 已確認：SMTP
5. LLM 提供者 → 已確認：Google Gemini / OpenAI / Ollama 三選一

— 文件結束 —