# GitHub Actions 與 UV 整合總結

## 已完成的改進

### 1. 依賴管理統一化
✅ 將測試依賴整合到 `pyproject.toml` 中
```toml
[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "pytest-mock>=3.11.1",
    "pytest-asyncio>=0.21.0",
]
```

### 2. GitHub Actions 使用 UV
✅ 完整的 UV 整合流程：

```yaml
- name: 📦 Install uv
  uses: astral-sh/setup-uv@v5
  with:
    enable-cache: true

- name: 📦 Install dependencies
  run: |
    uv sync --extra dev

- name: 🧪 Run all tests
  run: |
    uv run pytest tests/ -v --tb=short --cov=tools --cov=utils
```

### 3. 所有測試命令都使用 UV

✅ 三種測試模式都已更新：
- `uv run pytest` - 執行所有測試
- `uv run pytest tests/e2e/test_esg_api.py` - ESG API 測試
- `uv run pytest tests/test_api_client.py` - API Client 測試

## 優勢

### 🚀 速度提升
- UV 比 pip 快 10-100 倍
- GitHub Actions 啟用了 UV cache，第二次執行更快

### 📦 依賴管理
- 單一來源（`pyproject.toml`）管理所有依賴
- 自動鎖定版本（`uv.lock`）
- 開發依賴與生產依賴分離

### 🔒 可重現性
- `uv.lock` 確保所有環境使用相同版本
- 本地開發環境與 CI/CD 完全一致

### 🛠️ 簡化流程
- 不需要分別管理 `requirements.txt` 和 `requirements-dev.txt`
- 一個命令安裝所有依賴：`uv sync --extra dev`

## 本地開發工作流程

### 初次設定
```bash
# 安裝 UV (如果尚未安裝)
pip install uv

# 同步專案依賴（包含開發依賴）
uv sync --extra dev
```

### 日常開發
```bash
# 執行測試
uv run pytest

# 執行特定測試
uv run pytest tests/e2e/test_esg_api.py -v

# 產生覆蓋率報告
uv run pytest --cov=tools --cov=utils --cov-report=html

# 執行快速測試腳本
uv run python run_tests.py quick
```

### 新增依賴
```bash
# 新增生產依賴
uv add requests

# 新增開發依賴
uv add --dev pytest-timeout

# 同步依賴
uv sync
```

## CI/CD 工作流程

### 自動觸發
- Push 到 main/develop → 自動執行完整測試
- Pull Request → 自動執行完整測試
- 每天早上 9:00 → 自動執行完整測試（偵測 API 變化）

### 手動觸發
1. 前往 GitHub Actions 頁面
2. 選擇 "TWSE API E2E Tests"
3. 點擊 "Run workflow"
4. 選擇測試範圍（all/esg/api_client）
5. 執行

## 檔案清單

### 核心設定檔
- ✅ `pyproject.toml` - 專案依賴與元資料
- ✅ `uv.lock` - 鎖定版本（由 uv 自動生成）
- ✅ `.github/workflows/api-tests.yml` - CI/CD 設定

### 測試相關
- ✅ `pytest.ini` - Pytest 設定
- ✅ `tests/` - 測試程式碼目錄
- ✅ `tests/conftest.py` - Pytest fixtures
- ✅ `tests/e2e/test_esg_api.py` - ESG API E2E 測試
- ✅ `tests/test_api_client.py` - API Client 測試

### 文件
- ✅ `TESTING.md` - 測試指南
- ✅ `.github/ACTIONS_GUIDE.md` - GitHub Actions 使用指南
- ✅ `run_tests.py` - 快速測試腳本

## 相容性說明

### 保留 requirements-dev.txt
為了相容不使用 UV 的環境，我們仍保留 `requirements-dev.txt`：
```bash
# 傳統方式（不推薦）
pip install -r requirements-dev.txt
pytest
```

### 推薦方式
```bash
# UV 方式（推薦）
uv sync --extra dev
uv run pytest
```

## 疑難排解

### Q: UV 找不到？
```bash
pip install uv
```

### Q: 依賴安裝失敗？
```bash
# 清除快取重新安裝
uv cache clean
uv sync --extra dev
```

### Q: GitHub Actions 失敗？
檢查日誌中的 "Install dependencies" 步驟，確認：
1. UV 是否成功安裝
2. `uv sync --extra dev` 是否執行成功
3. 所有測試命令是否都使用 `uv run pytest`

## 檢查清單

在推送之前，確認：
- [ ] `pyproject.toml` 包含所有必要依賴
- [ ] 本地執行 `uv run pytest` 成功
- [ ] `.github/workflows/api-tests.yml` 所有命令都使用 `uv run`
- [ ] 文件已更新（TESTING.md、ACTIONS_GUIDE.md）

## 下一步

1. ✅ 推送到 GitHub
2. ✅ 觀察 GitHub Actions 執行結果
3. ✅ 手動觸發一次測試驗證
4. ✅ 檢查測試覆蓋率報告
5. ✅ 如果成功，在 README 加入測試 badge
