# HBR Taiwan 文章爬蟲系統

這是一個自動化的 HBR Taiwan 文章爬蟲系統，每週一自動爬取最新文章並透過 Gmail 發送 CSV 檔案。

## 功能特色

- 🕷️ 自動爬取 HBR Taiwan 網站文章
- 📧 每週一自動發送文章清單到指定信箱
- 🔒 支援付費文章識別（不爬取內容）
- 📊 輸出結構化 CSV 格式
- ⚡ 使用 GitHub Actions 免維護伺服器

## 專案結構

```
├── hbr_crawler/           # Scrapy 爬蟲專案
│   ├── hbr_crawler/
│   │   ├── spiders/
│   │   │   └── hbr.py     # HBR 爬蟲主程式
│   │   ├── items.py       # 資料結構定義
│   │   ├── pipelines.py   # CSV 輸出管道
│   │   └── settings.py    # 爬蟲設定
│   └── scrapy.cfg
├── .github/workflows/
│   └── weekly.yml         # GitHub Actions 排程
├── send_mail.py           # 郵件發送腳本
├── requirements.txt       # Python 依賴
└── README.md
```

## 快速開始

### 1. 安裝依賴

```bash
pip install -r requirements.txt
```

### 2. 手動測試爬蟲

```bash
cd hbr_crawler
scrapy crawl hbr
```

這會產生 `hbr_articles.csv` 檔案在專案根目錄。

### 3. 設定 Gmail 環境變數

```bash
export GMAIL_USERNAME='yourname@gmail.com'
export GMAIL_APP_PASSWORD='your-16-digit-app-password'
export MAIL_TO='kaeruzak@gmail.com'
```

### 4. 測試郵件發送

```bash
python send_mail.py hbr_articles.csv
```

## Gmail App Password 設定

1. 前往 [Google 帳戶設定](https://myaccount.google.com/)
2. 安全性 → 兩步驟驗證（需先啟用）
3. 應用程式密碼 → 選擇「郵件」
4. 複製產生的 16 碼密碼

## GitHub Actions 自動化

### 設定 Secrets

在 GitHub 專案的 Settings → Secrets and variables → Actions 新增：

- `GMAIL_USERNAME`: 您的 Gmail 地址
- `GMAIL_APP_PASSWORD`: 16 碼 App Password
- `MAIL_TO`: kaeruzak@gmail.com

### 排程設定

系統預設每週一 08:00 (Asia/Taipei) 自動執行，對應 GitHub Actions 的 cron 設定：

```yaml
schedule:
  - cron: "0 0 * * 1"   # 週一 00:00 UTC ≈ 台北 08:00
```

## 輸出格式

CSV 檔案包含以下欄位：

- `title`: 文章標題
- `url`: 文章連結
- `author`: 作者
- `publish_date`: 發布日期
- `summary`: 文章摘要
- `is_paywalled`: 是否為付費文章 (1/0)
- `category`: 文章分類
- `tags`: 標籤（逗號分隔）
- `content`: 文章內容（僅非付費文章）

## 注意事項

- 系統遵守 robots.txt 規則
- 付費文章僅標記為 `is_paywalled=1`，不爬取內容
- 若網站改版，可能需要調整 `hbr.py` 中的 CSS 選擇器
- 空結果週會跳過寄信（可修改為發送通知）

## 故障排除

### 爬蟲無法找到文章

檢查 `hbr_crawler/hbr_crawler/spiders/hbr.py` 中的 CSS 選擇器是否與網站結構匹配。

### 郵件發送失敗

1. 確認 Gmail App Password 正確
2. 檢查環境變數設定
3. 確認網路連線正常

### GitHub Actions 失敗

1. 檢查 Secrets 設定
2. 查看 Actions 執行日誌
3. 確認 Python 版本相容性

## 授權

此專案僅供學習和研究使用，請遵守 HBR Taiwan 網站的使用條款。