daily-news-app/系統解析.md

# 每日報導 APP - 系統解析文檔

## 📋 系統概述

**每日報導 APP** 是一個企業內部新聞彙整與分析系統，主要功能是自動抓取多個新聞來源、使用 AI 進行智慧摘要、依產業別或議題分類，並自動生成每日報告發送給訂閱者。

---

## 🏗️ 系統架構

### 技術棧

| 層級 | 技術 | 說明 |
|------|------|------|
| **後端框架** | FastAPI 0.109.0 | 現代化的 Python Web 框架，支援異步處理 |
| **Python 版本** | Python 3.11 | 使用最新穩定版本 |
| **資料庫** | MySQL 8.0 / SQLite | 支援 MySQL（生產）和 SQLite（開發） |
| **ORM** | SQLAlchemy 2.0.25 | 資料庫操作抽象層 |
| **認證** | JWT + LDAP/AD | 支援本地帳號和企業 AD/LDAP 整合 |
| **LLM 整合** | OpenAI / Gemini / Ollama | 支援多種 AI 模型進行摘要生成 |
| **排程** | APScheduler 3.10.4 | 定時任務排程（新聞抓取、報告生成） |
| **Email** | aiosmtplib 3.0.1 | 異步 SMTP 郵件發送 |
| **PDF 生成** | WeasyPrint 60.2 | 報告 PDF 匯出功能 |
| **部署** | Docker + Docker Compose | 容器化部署，支援 1Panel |

### 系統架構圖

```
┌─────────────────────────────────────────────────────────┐
│                    前端介面 (UI)                          │
│              (響應式設計，支援手機閱讀)                    │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/HTTPS
┌────────────────────▼────────────────────────────────────┐
│              FastAPI 應用程式 (app/main.py)               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Auth API │  │ Users API│  │Groups API│  │Reports  │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
└────┬───────────────┬───────────────┬────────────────────┘
     │               │               │
┌────▼────┐  ┌──────▼──────┐  ┌────▼──────┐
│ Services│  │   Models     │  │  Database │
│  Layer  │  │   (ORM)      │  │  (MySQL)  │
└────┬────┘  └──────────────┘  └───────────┘
     │
┌────▼──────────────────────────────────────┐
│        核心服務模組                         │
│  • Crawler Service (新聞爬蟲)              │
│  • LLM Service (AI 摘要)                   │
│  • Notification Service (Email 通知)        │
│  • Scheduler Service (排程任務)             │
└───────────────────────────────────────────┘
```

---

## 🔑 核心功能模組

### 1. 認證與授權 (`app/api/v1/endpoints/auth.py`)
- **JWT Token 認證**：使用 JWT 進行用戶認證
- **LDAP/AD 整合**：支援企業 Active Directory 統一認證
- **本地帳號**：支援本地用戶帳號密碼登入
- **角色權限**：admin（管理員）、editor（編輯）、reader（讀者）

### 2. 用戶管理 (`app/api/v1/endpoints/users.py`)
- 用戶列表查詢
- 用戶新增、編輯、停用
- 角色分配
- 最後登入時間追蹤

### 3. 群組管理 (`app/api/v1/endpoints/groups.py`)
- **群組分類**：產業別（industry）或議題（topic）
- **關鍵字管理**：為每個群組設定關鍵字，用於新聞匹配
- **AI 設定**：可為群組設定 AI 背景資訊和摘要提示
- **啟用/停用**：控制群組是否參與自動匹配

### 4. 新聞抓取 (`app/services/crawler_service.py`)
- **支援來源**：
  - Digitimes（需付費帳號）
  - 經濟日報（公開）
  - 工商時報（公開）
- **自動排程**：每日定時抓取（預設 08:00）
- **關鍵字匹配**：根據群組關鍵字自動匹配新聞
- **防重複**：使用外部 ID 避免重複抓取
- **錯誤重試**：支援自動重試機制

### 5. 報告管理 (`app/api/v1/endpoints/reports.py`)
- **報告生成**：每日為每個群組自動生成報告
- **AI 摘要**：使用 LLM 生成綜合摘要
- **編輯功能**：專員可編輯 AI 摘要
- **文章篩選**：專員可選擇是否納入報告
- **發布流程**：草稿 → 待審核 → 已發布
- **PDF 匯出**：支援匯出 PDF 格式

### 6. 訂閱管理 (`app/api/v1/endpoints/subscriptions.py`)
- 用戶訂閱群組
- Email 通知開關
- 訂閱列表查詢

### 7. AI 摘要服務 (`app/services/llm_service.py`)
- **多 LLM 支援**：
  - Google Gemini（預設）
  - OpenAI GPT-4
  - Ollama（本地部署）
- **摘要生成**：根據群組設定和新聞內容生成摘要
- **可配置模型**：可選擇不同模型和參數

### 8. 通知服務 (`app/services/notification_service.py`)
- **Email 通知**：報告發布時自動發送 Email
- **通知記錄**：記錄所有通知發送狀態
- **失敗重試**：支援失敗通知重試

### 9. 排程服務 (`app/services/scheduler_service.py`)
- **定時抓取**：每日定時執行新聞抓取
- **報告生成**：定時生成每日報告
- **通知發送**：定時發送通知

### 10. 系統設定 (`app/api/v1/endpoints/settings.py`)
- LLM 設定（API Key、模型選擇）
- SMTP 設定（Email 發送）
- PDF 設定（Logo、頁首頁尾）
- 系統參數設定

---

## 📊 資料庫結構

### 核心資料表

1. **用戶與權限**
   - `roles`：角色表（admin, editor, reader）
   - `users`：用戶表（支援 AD/LDAP 和本地帳號）

2. **新聞來源與文章**
   - `news_sources`：新聞來源設定
   - `news_articles`：抓取的新聞文章
   - `crawl_jobs`：抓取任務記錄

3. **群組與關鍵字**
   - `groups`：群組表（產業別/議題）
   - `keywords`：關鍵字表
   - `article_group_matches`：新聞-群組匹配關聯

4. **報告**
   - `reports`：報告表
   - `report_articles`：報告-新聞關聯表

5. **讀者互動**
   - `subscriptions`：訂閱表
   - `favorites`：收藏表
   - `comments`：留言表
   - `notes`：個人筆記表

6. **系統**
   - `system_settings`：系統設定表
   - `audit_logs`：操作日誌表
   - `notification_logs`：通知記錄表

### 資料保留策略
- 預設保留 60 天資料
- 使用 MySQL Event Scheduler 自動清理過期資料

---

## 🔐 安全機制

### 1. 認證安全
- JWT Token 認證
- 密碼使用 bcrypt 雜湊
- LDAP 注入防護
- Token 過期時間控制（生產環境建議 60-120 分鐘）

### 2. 資料安全
- 敏感資訊加密儲存（API Keys、密碼）
- SQL 注入防護（使用 ORM）
- XSS 防護（輸入驗證和輸出編碼）

### 3. 環境安全
- 生產環境強制關閉 Debug 模式
- 生產環境關閉 API 文檔（/docs）
- CORS 嚴格控制（生產環境不允許 `*`）
- 密鑰長度驗證（至少 32 字元）

### 4. 日誌與審計
- 操作日誌記錄（audit_logs）
- 錯誤日誌記錄
- 通知發送記錄

---

## 📁 目錄結構說明

```
daily-news-app/
├── app/                          # 應用程式主目錄
│   ├── api/v1/                   # API 路由
│   │   ├── endpoints/            # API 端點實作
│   │   │   ├── auth.py           # 認證相關
│   │   │   ├── users.py          # 用戶管理
│   │   │   ├── groups.py         # 群組管理
│   │   │   ├── reports.py        # 報告管理
│   │   │   ├── subscriptions.py # 訂閱管理
│   │   │   └── settings.py      # 系統設定
│   │   └── router.py             # 路由總管理
│   ├── core/                     # 核心設定
│   │   ├── config.py             # 環境變數設定
│   │   ├── security.py           # 安全相關（JWT、LDAP）
│   │   └── logging_config.py     # 日誌設定
│   ├── db/                       # 資料庫
│   │   └── session.py            # 資料庫連線管理
│   ├── models/                   # 資料模型（SQLAlchemy）
│   │   ├── user.py               # 用戶模型
│   │   ├── news.py               # 新聞模型
│   │   ├── group.py              # 群組模型
│   │   ├── report.py             # 報告模型
│   │   ├── interaction.py        # 互動模型（訂閱、收藏等）
│   │   └── system.py             # 系統模型
│   ├── schemas/                  # Pydantic Schema（API 驗證）
│   │   ├── user.py
│   │   ├── group.py
│   │   └── report.py
│   ├── services/                 # 商業邏輯服務
│   │   ├── crawler_service.py    # 新聞爬蟲
│   │   ├── llm_service.py         # AI 摘要
│   │   ├── notification_service.py # Email 通知
│   │   └── scheduler_service.py  # 排程任務
│   ├── utils/                    # 工具函數
│   └── main.py                   # 應用程式入口
├── scripts/                      # 腳本
│   ├── init_db_sqlite.py         # SQLite 初始化
│   └── init.sql                  # MySQL 初始化 SQL
├── templates/                    # Email 模板
├── tests/                        # 測試檔案
├── logs/                         # 日誌目錄
├── uploads/                      # 上傳檔案目錄
├── docker-compose.yml            # Docker Compose 配置
├── Dockerfile                    # Docker 映像檔配置
├── requirements.txt              # Python 依賴套件
├── run.py                        # 啟動腳本
└── README.md                     # 專案說明
```

---

## 🔄 系統流程

### 1. 新聞抓取流程
```
排程觸發 (08:00)
    ↓
讀取所有啟用的新聞來源
    ↓
對每個來源執行抓取
    ↓
解析文章列表
    ↓
取得文章內容
    ↓
儲存到 news_articles
    ↓
根據群組關鍵字匹配
    ↓
建立 article_group_matches 關聯
    ↓
記錄抓取任務狀態
```

### 2. 報告生成流程
```
每日定時觸發
    ↓
查詢所有啟用的群組
    ↓
對每個群組：
    ├─ 查詢匹配的新聞文章
    ├─ 使用 LLM 生成 AI 摘要
    ├─ 建立報告（狀態：draft）
    └─ 關聯新聞文章
    ↓
專員審核與編輯
    ↓
發布報告（狀態：published）
    ↓
發送 Email 通知給訂閱者
```

### 3. 用戶登入流程
```
用戶提交帳號密碼
    ↓
判斷認證類型（AD/LDAP 或本地）
    ↓
驗證帳號密碼
    ↓
查詢用戶資訊和角色
    ↓
生成 JWT Token
    ↓
返回 Token 給前端
```

---

## 🌐 API 端點總覽

### 認證相關
- `POST /api/v1/auth/login` - 用戶登入
- `GET /api/v1/auth/me` - 取得當前用戶資訊

### 用戶管理
- `GET /api/v1/users` - 用戶列表
- `POST /api/v1/users` - 新增用戶
- `GET /api/v1/users/{id}` - 用戶詳情
- `PUT /api/v1/users/{id}` - 更新用戶
- `DELETE /api/v1/users/{id}` - 刪除用戶

### 群組管理
- `GET /api/v1/groups` - 群組列表
- `POST /api/v1/groups` - 新增群組
- `GET /api/v1/groups/{id}` - 群組詳情
- `PUT /api/v1/groups/{id}` - 更新群組
- `DELETE /api/v1/groups/{id}` - 刪除群組

### 報告管理
- `GET /api/v1/reports` - 報告列表
- `GET /api/v1/reports/{id}` - 報告詳情
- `POST /api/v1/reports/{id}/publish` - 發布報告
- `GET /api/v1/reports/{id}/pdf` - 匯出 PDF

### 訂閱管理
- `GET /api/v1/subscriptions` - 我的訂閱
- `POST /api/v1/subscriptions` - 新增訂閱
- `DELETE /api/v1/subscriptions/{id}` - 取消訂閱

### 系統設定
- `GET /api/v1/settings` - 取得設定
- `PUT /api/v1/settings` - 更新設定

---

## 🔧 環境變數說明

系統使用 `.env` 檔案管理環境變數，主要包含：

### 應用程式設定
- `APP_ENV`：環境（development/staging/production）
- `DEBUG`：除錯模式（生產環境必須為 false）
- `SECRET_KEY`：應用程式密鑰（至少 32 字元）
- `JWT_SECRET_KEY`：JWT 簽章密鑰（至少 32 字元）

### 資料庫設定
- `DB_HOST`：資料庫主機（或 "sqlite" 使用 SQLite）
- `DB_PORT`：資料庫埠號
- `DB_NAME`：資料庫名稱
- `DB_USER`：資料庫用戶
- `DB_PASSWORD`：資料庫密碼

### LLM 設定
- `LLM_PROVIDER`：LLM 提供者（gemini/openai/ollama）
- `GEMINI_API_KEY`：Gemini API Key
- `OPENAI_API_KEY`：OpenAI API Key
- `OLLAMA_ENDPOINT`：Ollama 端點 URL

### SMTP 設定
- `SMTP_HOST`：SMTP 伺服器
- `SMTP_PORT`：SMTP 埠號
- `SMTP_USERNAME`：SMTP 帳號
- `SMTP_PASSWORD`：SMTP 密碼
- `SMTP_FROM_EMAIL`：寄件者 Email

### LDAP/AD 設定
- `LDAP_SERVER`：LDAP 伺服器位址
- `LDAP_BASE_DN`：LDAP Base DN

### 其他設定
- `DIGITIMES_USERNAME`：Digitimes 帳號
- `DIGITIMES_PASSWORD`：Digitimes 密碼

---

## 📝 注意事項

1. **生產環境部署**
   - 必須設定強隨機的 `SECRET_KEY` 和 `JWT_SECRET_KEY`
   - 必須關閉 `DEBUG` 模式
   - 必須明確設定 `CORS_ORIGINS`（不能使用 `*`）
   - 建議設定 `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` 為 60-120 分鐘

2. **資料庫選擇**
   - 開發環境可使用 SQLite（設定 `DB_HOST=sqlite`）
   - 生產環境建議使用 MySQL 8.0

3. **LLM 選擇**
   - Gemini：需要 API Key，費用較低
   - OpenAI：需要 API Key，品質較高
   - Ollama：本地部署，無需 API Key，但需要 GPU 資源

4. **新聞來源**
   - Digitimes 需要付費帳號
   - 經濟日報和工商時報為公開來源

---

## 📚 相關文檔

- `README.md` - 專案說明
- `daily-news-SDD.md` - 系統設計文檔
- `安全修復完成報告.md` - 安全修復記錄
- `執行步驟.md` - 詳細執行步驟（見下一個文檔）