—— Global-Stock-Feature-Engine 的 KR 資料下載機制解析
📌 本文聚焦於 韓國市場（KR）的資料取得困境與解決方案，並簡要說明
main.py如何協調全球六個市場的同步流程。
❓ 問題背景：GitHub Actions 無法直接抓韓股清單
在自動化流程中，我們希望每天透過 GitHub Actions 更新全球股市資料庫。然而，韓國股市的股票清單來源（如 pykrx 所依賴的 KRX 官網）會封鎖來自 GitHub 伺服器的 IP，導致：
- 無法取得完整的韓股代碼列表
- 下載流程直接跳過 KR 市場，或僅回傳預設的三星電子（005930.KS）
這使得自動化更新「韓國部分」失效。
✅ 解決方案：手動預備 kr_list_all.csv
為繞過此限制，我們採用「離線準備 + 雲端快取」策略：
步驟 1️⃣：在 Colab 或本機執行以下程式碼，取得完整韓股清單
python编辑# 在 Google Colab 執行（需安裝 pykrx）
!pip install pykrx pandas
from pykrx import stock as krx
import pandas as pd
from datetime import datetime
today = datetime.now().strftime("%Y%m%d")
items = []
for market, suffix in [("KOSPI", ".KS"), ("KOSDAQ", ".KQ")]:
tickers = krx.get_market_ticker_list(today, market=market)
for t in tickers:
items.append({
"code": t,
"name": krx.get_market_ticker_name(t),
"board": market
})
df = pd.DataFrame(items)
df.to_csv("kr_list_all.csv", index=False, encoding="utf-8-sig")
print(f"✅ 已儲存 {len(df)} 檔韓股清單至 kr_list_all.csv")
步驟 2️⃣：將 kr_list_all.csv 上傳至 Google Drive
- 與你的
kr_stock_warehouse.db放在同一資料夾 - 確保 GitHub Secrets 中的
GDRIVE_FOLDER_ID指向該資料夾
步驟 3️⃣：downloader_kr.py 會優先讀取此檔案！
程式碼中的「四重保險」機制如下：
python编辑# ========== 3. 獲取韓股清單 (四重保險) ==========
def get_kr_stock_list():
# [保險 0] 優先嘗試讀取本地 kr_list_all.csv
if os.path.exists(LIST_CSV_PATH):
... # 成功則直接使用
return items
# [保險 1] 嘗試用 pykrx（在 GitHub Actions 通常失敗）
try:
...
except:
pass
# [保險 2] 最後 fallback 到預設股票（三星）
return [("005930.KS", "Samsung Electronics", ...)]
💡 只要雲端有
kr_list_all.csv，就能完整下載所有韓股歷史資料！
🌐 main.py：全球市場同步的指揮中心
main.py 是整個專案的「大腦」，負責協調以下動作：
🔁 1. 增量更新（Incremental Sync）
- 檢查本地或雲端 DB 的最後日期（例如
2025-12-31） - 只下載「隔天至今」的資料（例如
2026-01-01 ~ 2026-01-04） - 避免每日重複下載數年數據，大幅節省時間與 API 用量
☁️ 2. Google Drive 快取機制
- 啟動時自動從雲端下載
.db與kr_list_all.csv - 結束前上傳更新版，供下次使用或 Streamlit 儀表板讀取
⚙️ 3. 特徵工程自動觸發
- 若
processor.py存在，會在下載完成後自動執行：python编辑process_market_data(db_file) # 加工 KD / MACD / 背離 / 未來報酬等欄位
📤 4. 穩健的上傳重試機制
- 自動偵測 SSL 連線錯誤（常見於大檔案上傳）
- 採用「指數退避」重試，最多 3 次
- 失敗時仍保留本地
.db檔，避免資料遺失
🧩 特別提醒：韓國市場是「可選」的
- 如果你對韓股沒興趣，完全可以忽略
kr_list_all.csv downloader_kr.py在無清單時會 fallback 到三星電子，不影響其他市場運作- 整個系統設計為「模組化」，六個市場（TW/US/CN/HK/JP/KR）彼此獨立
🛠️ 使用建議
使用情境操作方式只想跑台股+美股不需處理 KR 相關檔案，直接執行 python main.py tw us想完整支援韓股1. 用 Colab 產出 kr_list_all.csv2. 上傳至 Google Drive3. 執行 python main.py kr 或 all部署到 GitHub Actions確保 Secrets 設定正確，且 Drive 資料夾內已有 kr_list_all.csv
📚 延伸資源
🔍 真正的自動化，不是「完全無人介入」，而是「知道何時需要人為協助」。
韓國市場的設計，正是這種務實哲學的體現—— 當自動化遇到牆，我們提供一條簡單的手動通道，讓系統依然能持續運轉。
（完）
