Initial commit: Daily News App

企業內部新聞彙整與分析系統 - 自動新聞抓取 (Digitimes, 經濟日報, 工商時報) - AI 智慧摘要 (OpenAI/Claude/Ollama) - 群組管理與訂閱通知 - 已清理 Python 快取檔案 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-03 23:53:24 +08:00
commit db0f0bbfe7
50 changed files with 11883 additions and 0 deletions
--- a/執行步驟.md
+++ b/執行步驟.md
@@ -0,0 +1,504 @@
+# 每日報導 APP - 執行步驟指南
+
+本文檔提供系統的詳細執行步驟，包含本地開發和生產部署兩種方式。
+
+---
+
+## 📋 前置需求
+
+### 系統需求
+- **作業系統**：Linux / macOS / Windows
+- **Python**：3.11 或以上版本
+- **Docker**：20.10 或以上版本（使用 Docker 部署時）
+- **Docker Compose**：2.0 或以上版本（使用 Docker 部署時）
+- **MySQL**：8.0 或以上版本（生產環境，或使用 Docker 時自動安裝）
+
+### 必要帳號與 API Key
+- **LLM API Key**（三選一）：
+  - Google Gemini API Key
+  - OpenAI API Key
+  - 或使用 Ollama（本地部署，無需 API Key）
+- **Digitimes 帳號**（如需抓取 Digitimes 新聞）
+- **SMTP 設定**（如需發送 Email 通知）
+
+---
+
+## 🚀 方式一：本地開發環境
+
+### 步驟 1：環境準備
+
+#### 1.1 複製專案（如尚未複製）
+```bash
+# 如果專案在 Git 倉庫
+git clone <repository-url>
+cd daily-news-app
+
+# 或直接進入專案目錄
+cd /Users/peelerwu/Documents/AICoding/daily-news-app
+```
+
+#### 1.2 建立 Python 虛擬環境
+```bash
+# 建立虛擬環境
+python3 -m venv venv
+
+# 啟動虛擬環境
+# macOS/Linux:
+source venv/bin/activate
+# Windows:
+# venv\Scripts\activate
+```
+
+#### 1.3 安裝 Python 依賴套件
+```bash
+pip install -r requirements.txt
+```
+
+### 步驟 2：環境變數設定
+
+#### 2.1 建立 `.env` 檔案
+```bash
+# 複製範例檔案（如果存在）
+cp .env.example .env
+
+# 或手動建立
+touch .env
+```
+
+#### 2.2 編輯 `.env` 檔案
+使用文字編輯器開啟 `.env`，填入以下設定：
+
+```env
+# ============================================
+# 應用程式設定
+# ============================================
+APP_ENV=development
+DEBUG=true
+SECRET_KEY=your-secret-key-here-min-32-chars-change-in-production
+JWT_SECRET_KEY=your-jwt-secret-key-here-min-32-chars-change-in-production
+
+# ============================================
+# 資料庫設定（開發環境可使用 SQLite）
+# ============================================
+# 選項 1：使用 SQLite（簡單，適合開發）
+DB_HOST=sqlite
+DB_NAME=daily_news_app
+
+# 選項 2：使用 MySQL（需先啟動 MySQL）
+# DB_HOST=localhost
+# DB_PORT=3306
+# DB_NAME=daily_news_app
+# DB_USER=root
+# DB_PASSWORD=your-mysql-password
+
+# ============================================
+# LLM 設定（選擇一個）
+# ============================================
+# 選項 1：使用 Gemini（推薦，費用較低）
+LLM_PROVIDER=gemini
+GEMINI_API_KEY=your-gemini-api-key-here
+GEMINI_MODEL=gemini-1.5-pro
+
+# 選項 2：使用 OpenAI
+# LLM_PROVIDER=openai
+# OPENAI_API_KEY=your-openai-api-key-here
+# OPENAI_MODEL=gpt-4o
+
+# 選項 3：使用 Ollama（本地部署）
+# LLM_PROVIDER=ollama
+# OLLAMA_ENDPOINT=http://localhost:11434
+# OLLAMA_MODEL=llama3
+
+# ============================================
+# SMTP 設定（Email 通知，選填）
+# ============================================
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USERNAME=your-smtp-username
+SMTP_PASSWORD=your-smtp-password
+SMTP_FROM_EMAIL=noreply@example.com
+SMTP_FROM_NAME=每日報導系統
+
+# ============================================
+# LDAP/AD 設定（選填，如需企業認證）
+# ============================================
+LDAP_SERVER=ldap.example.com
+LDAP_PORT=389
+LDAP_BASE_DN=DC=example,DC=com
+LDAP_BIND_DN=
+LDAP_BIND_PASSWORD=
+
+# ============================================
+# Digitimes 帳號（選填，如需抓取 Digitimes）
+# ============================================
+DIGITIMES_USERNAME=your-digitimes-username
+DIGITIMES_PASSWORD=your-digitimes-password
+
+# ============================================
+# 其他設定
+# ============================================
+CORS_ORIGINS=["http://localhost:3000","http://localhost:8000"]
+```
+
+#### 2.3 產生強隨機密鑰（生產環境必做）
+```bash
+# 使用 Python 產生
+python3 -c "import secrets; print('SECRET_KEY=' + secrets.token_urlsafe(32)); print('JWT_SECRET_KEY=' + secrets.token_urlsafe(32))"
+```
+
+將產生的密鑰填入 `.env` 檔案。
+
+### 步驟 3：資料庫初始化
+
+#### 3.1 使用 SQLite（開發環境推薦）
+```bash
+# 執行初始化腳本
+python scripts/init_db_sqlite.py
+```
+
+這會自動建立 SQLite 資料庫檔案 `daily_news_app.db` 並建立所有資料表。
+
+#### 3.2 使用 MySQL（如需）
+```bash
+# 1. 確保 MySQL 服務已啟動
+# macOS (Homebrew):
+brew services start mysql
+# Linux:
+sudo systemctl start mysql
+# Windows: 從服務管理員啟動 MySQL
+
+# 2. 建立資料庫
+mysql -u root -p
+CREATE DATABASE daily_news_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+EXIT;
+
+# 3. 執行初始化 SQL
+mysql -u root -p daily_news_app < scripts/init.sql
+```
+
+### 步驟 4：啟動應用程式
+
+#### 4.1 使用啟動腳本（推薦）
+```bash
+python run.py
+```
+
+#### 4.2 或使用 uvicorn 直接啟動
+```bash
+uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+#### 4.3 驗證啟動成功
+開啟瀏覽器訪問：
+- **API 文件**：http://127.0.0.1:8000/docs
+- **健康檢查**：http://127.0.0.1:8000/health
+- **根路徑**：http://127.0.0.1:8000/
+
+### 步驟 5：初始化資料（可選）
+
+如果需要建立預設用戶或測試資料：
+
+```bash
+# 進入 Python 互動環境
+python
+
+# 執行初始化（範例）
+from app.db.session import SessionLocal
+from app.models.user import User, Role
+from app.core.security import get_password_hash
+
+db = SessionLocal()
+# 建立管理員用戶
+admin_role = db.query(Role).filter(Role.code == "admin").first()
+if admin_role:
+    admin_user = User(
+        username="admin",
+        password_hash=get_password_hash("admin123"),
+        display_name="系統管理員",
+        email="admin@example.com",
+        auth_type="local",
+        role_id=admin_role.id,
+        is_active=True
+    )
+    db.add(admin_user)
+    db.commit()
+db.close()
+```
+
+---
+
+## 🐳 方式二：Docker 部署（生產環境推薦）
+
+### 步驟 1：環境準備
+
+#### 1.1 確認 Docker 已安裝
+```bash
+docker --version
+docker-compose --version
+```
+
+#### 1.2 建立 `.env` 檔案
+在專案根目錄建立 `.env` 檔案，內容參考「方式一」的步驟 2.2，但需調整以下設定：
+
+```env
+# 生產環境設定
+APP_ENV=production
+DEBUG=false
+
+# 資料庫設定（Docker Compose 會自動建立 MySQL）
+DB_HOST=mysql
+DB_PORT=3306
+DB_NAME=daily_news_app
+DB_USER=root
+DB_PASSWORD=your-strong-mysql-password-here
+
+# 必須使用強隨機密鑰
+SECRET_KEY=your-strong-secret-key-min-32-chars
+JWT_SECRET_KEY=your-strong-jwt-secret-key-min-32-chars
+
+# 其他設定與方式一相同
+```
+
+### 步驟 2：啟動服務
+
+#### 2.1 使用 Docker Compose 啟動
+```bash
+# 啟動所有服務（應用程式 + MySQL）
+docker-compose up -d
+
+# 查看日誌
+docker-compose logs -f app
+
+# 查看所有服務狀態
+docker-compose ps
+```
+
+#### 2.2 使用 Ollama（可選，本地 LLM）
+```bash
+# 啟動包含 Ollama 的服務
+docker-compose --profile ollama up -d
+
+# 下載模型
+docker exec -it daily-news-ollama ollama pull llama3
+```
+
+### 步驟 3：資料庫初始化
+
+#### 3.1 等待 MySQL 就緒
+```bash
+# 檢查 MySQL 健康狀態
+docker-compose ps mysql
+```
+
+#### 3.2 執行初始化 SQL
+```bash
+# 方法 1：使用 docker exec
+docker exec -i daily-news-mysql mysql -uroot -p${DB_PASSWORD} daily_news_app < scripts/init.sql
+
+# 方法 2：進入容器執行
+docker exec -it daily-news-mysql bash
+mysql -uroot -p
+# 輸入密碼後
+USE daily_news_app;
+SOURCE /docker-entrypoint-initdb.d/init.sql;
+EXIT;
+```
+
+**注意**：如果 `docker-compose.yml` 中已設定 `init.sql` 掛載，MySQL 容器啟動時會自動執行。
+
+### 步驟 4：驗證部署
+
+```bash
+# 檢查應用程式健康狀態
+curl http://localhost:8000/health
+
+# 查看應用程式日誌
+docker-compose logs -f app
+```
+
+### 步驟 5：存取系統
+
+- **API 文件**：http://localhost:8000/docs（生產環境可能已關閉）
+- **健康檢查**：http://localhost:8000/health
+- **API 端點**：http://localhost:8000/api/v1
+
+---
+
+## 🔧 常用操作
+
+### 查看日誌
+```bash
+# 本地開發
+tail -f logs/app.log
+
+# Docker
+docker-compose logs -f app
+```
+
+### 停止服務
+```bash
+# 本地開發
+# 按 Ctrl+C 停止
+
+# Docker
+docker-compose down
+
+# 停止並刪除資料（謹慎使用）
+docker-compose down -v
+```
+
+### 重啟服務
+```bash
+# Docker
+docker-compose restart app
+
+# 或重新建立
+docker-compose up -d --force-recreate app
+```
+
+### 進入容器
+```bash
+# 進入應用程式容器
+docker exec -it daily-news-app bash
+
+# 進入 MySQL 容器
+docker exec -it daily-news-mysql bash
+```
+
+### 資料庫備份
+```bash
+# MySQL 備份
+docker exec daily-news-mysql mysqldump -uroot -p${DB_PASSWORD} daily_news_app > backup_$(date +%Y%m%d).sql
+
+# SQLite 備份
+cp daily_news_app.db backup_$(date +%Y%m%d).db
+```
+
+### 資料庫還原
+```bash
+# MySQL 還原
+docker exec -i daily-news-mysql mysql -uroot -p${DB_PASSWORD} daily_news_app < backup_20240101.sql
+```
+
+---
+
+## 🧪 測試系統
+
+### 1. 測試 API 端點
+```bash
+# 健康檢查
+curl http://localhost:8000/health
+
+# 登入（需先建立用戶）
+curl -X POST http://localhost:8000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+### 2. 測試新聞抓取
+```bash
+# 進入容器或虛擬環境
+python
+
+# 執行測試
+from app.services.crawler_service import CrawlerService
+crawler = CrawlerService()
+# 測試抓取（需先設定新聞來源）
+```
+
+### 3. 測試 LLM 摘要
+```bash
+# 進入容器或虛擬環境
+python
+
+# 執行測試
+from app.services.llm_service import LLMService
+llm = LLMService()
+# 測試摘要生成
+```
+
+---
+
+## ⚠️ 常見問題
+
+### 問題 1：資料庫連線失敗
+**症狀**：啟動時出現資料庫連線錯誤
+
+**解決方法**：
+1. 檢查 `.env` 中的資料庫設定是否正確
+2. 確認 MySQL 服務已啟動（本地開發）
+3. 確認 Docker 容器中的 MySQL 已就緒（Docker 部署）
+4. 檢查防火牆設定
+
+### 問題 2：LLM API 呼叫失敗
+**症狀**：生成摘要時出現 API 錯誤
+
+**解決方法**：
+1. 檢查 API Key 是否正確設定
+2. 檢查 API Key 是否有足夠額度
+3. 檢查網路連線
+4. 查看日誌了解詳細錯誤
+
+### 問題 3：Email 發送失敗
+**症狀**：通知無法發送
+
+**解決方法**：
+1. 檢查 SMTP 設定是否正確
+2. 檢查 SMTP 伺服器是否需要 TLS/SSL
+3. 檢查防火牆是否阻擋 SMTP 埠號
+4. 查看 `notification_logs` 表了解錯誤詳情
+
+### 問題 4：新聞抓取失敗
+**症狀**：定時抓取沒有執行或失敗
+
+**解決方法**：
+1. 檢查排程服務是否正常啟動
+2. 檢查新聞來源設定是否正確
+3. 檢查 Digitimes 帳號是否有效（如需）
+4. 查看 `crawl_jobs` 表了解錯誤詳情
+
+### 問題 5：權限錯誤
+**症狀**：無法執行某些操作
+
+**解決方法**：
+1. 檢查用戶角色是否正確
+2. 檢查 JWT Token 是否有效
+3. 檢查 API 端點的權限設定
+
+---
+
+## 📝 後續設定
+
+### 1. 建立初始用戶
+使用 API 或直接操作資料庫建立管理員用戶。
+
+### 2. 設定新聞來源
+在系統設定中配置新聞來源（Digitimes、經濟日報、工商時報）。
+
+### 3. 建立群組
+建立產業別或議題群組，並設定關鍵字。
+
+### 4. 設定排程
+確認排程服務正常運作，每日定時抓取和生成報告。
+
+### 5. 測試完整流程
+1. 手動觸發新聞抓取
+2. 檢查新聞是否正確匹配到群組
+3. 生成測試報告
+4. 測試 Email 通知
+
+---
+
+## 🔗 相關資源
+
+- **API 文件**：http://localhost:8000/docs
+- **專案 README**：`README.md`
+- **系統解析**：`系統解析.md`
+- **系統設計文檔**：`daily-news-SDD.md`
+
+---
+
+## 📞 支援
+
+如有問題，請聯繫 IT 部門或查看專案文檔。
+