# 每日報導 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 部門或查看專案文檔。