# ZIP Migration Quick Reference

## 🎯 重點摘要

**Gateway 更新後需要修改 2 個檔案，5 分鐘完成遷移。**

---

## ✅ 修改檢查清單

### 必須修改 (HIGH Priority)

- [ ] **檔案 1:** `packages/client/src/tradepose_client/batch/tester.py` (Lines 224-249)
- [ ] **檔案 2:** `packages/client/src/tradepose_client/batch/background.py` (Lines 148-214)

### 建議更新 (MEDIUM Priority)

- [ ] **檔案 3:** `packages/client/ARCHITECTURE.md` - 新增性能優化說明
- [ ] **檔案 4:** `packages/client/README.md` - 更新範例
- [ ] **檔案 5:** `packages/client/docs/API_REFERENCE.md` - 標記棄用方法

---

## 📝 核心修改

### 修改 1: tester.py (Lines 224-249)

**前:**
```python
# 2 次 API 呼叫
trades_df, perf_df = await asyncio.gather(
    client.tasks.download_result_by_type(task_id, "trades"),
    client.tasks.download_result_by_type(task_id, "performance")
)
```

**後:**
```python
# 1 次 API 呼叫 (ZIP)
trades_df, perf_df = await client.tasks.download_backtest_results(task_id)
```

---

### 修改 2: background.py (Lines 148-214)

**前:**
```python
download_tasks.append(
    asyncio.gather(
        client.tasks.download_result_by_type(task_id, "trades"),
        client.tasks.download_result_by_type(task_id, "performance")
    )
)
```

**後:**
```python
download_tasks.append(
    client.tasks.download_backtest_results(task_id)
)
```

**額外修改:** 結果解包
```python
# 新增解包邏輯
trades_df, perf_df = result_or_error  # Tuple unpacking
```

---

## 🧪 測試指令

```bash
# 1. 單元測試
uv run --package tradepose-client pytest packages/client/tests/resources/test_tasks.py -v

# 2. 整合測試 (需要測試環境)
uv run --package tradepose-client pytest packages/client/tests/integration/ -m integration

# 3. 手動驗證
uv run --package tradepose-client python -c "
from tradepose_client import BatchTester
from tradepose_client.batch import Period

tester = BatchTester(api_key='test')
batch = tester.submit(strategies=[...], periods=[Period.Q1(2024)])
batch.wait()
print('✅ Migration successful!')
"
```

---

## 📊 預期效益

| 指標 | 改善 |
|------|------|
| API 呼叫數 | **-50%** |
| 下載時間 | **-30~40%** |
| 檔案大小 | **-50%** (Performance Parquet vs JSON) |

**範例:** 40 個 tasks
- 舊版: 80 次 API 呼叫，~120 秒
- 新版: 40 次 API 呼叫，~72 秒

---

## ⚠️ 常見問題

### Q1: Performance 資料從 JSON 變成 DataFrame 怎麼辦？

**舊程式碼:**
```python
perf["total_return"]  # JSON dict
```

**新程式碼:**
```python
perf["total_return"][0]  # DataFrame (取第一列)
```

### Q2: 如何確認 Gateway 已更新？

```bash
# 測試 ZIP 端點
curl -H "Authorization: Bearer $TOKEN" \
  https://api.tradepose.com/api/v1/tasks/{task_id}/result \
  -o result.zip

# 檢查是否為 ZIP
file result.zip  # 應顯示 "Zip archive data"
```

### Q3: 舊程式碼還能用嗎？

✅ **可以!** `download_result_by_type()` 仍然可用，但效能較差。

---

## 🚀 快速開始

### 1 分鐘遷移指南

```bash
# 1. 開啟檔案
code packages/client/src/tradepose_client/batch/tester.py

# 2. 找到 Line 244-245
# 3. 替換為:
trades_df, perf_df = await client.tasks.download_backtest_results(task_id)

# 4. 重複上述步驟處理 background.py (Line 169-170)

# 5. 執行測試
uv run --package tradepose-client pytest packages/client/tests/ -v

# 6. 完成！
```

---

## 📚 詳細文檔

完整遷移計畫: [CLIENT_ZIP_MIGRATION_PLAN.md](./CLIENT_ZIP_MIGRATION_PLAN.md)

- 詳細程式碼範例
- 測試策略
- 故障排除
- 回滾計畫
- 性能基準測試

---

## 📞 需要協助？

- 完整文檔: `CLIENT_ZIP_MIGRATION_PLAN.md`
- GitHub Issues: https://github.com/your-org/tradepose-python/issues
- Email: support@tradepose.com
