Initial commit with 2026 World Cup Quant Platform core modules and CI/CD

docs/professional-data-reference.md

@@ -0,0 +1,241 @@
+# 專業外部資料參考台帳（完整版）
+
+本頁定義 2026 世界盃投注研究站的「參考來源矩陣」，目標是從官方公告、賠率市場、新聞訊號、球隊統計、場地天氣五大軸建立可追溯的高勝率研究底盤。  
+所有時區均以 **Asia/Taipei（UTC+8）** 對齊顯示。
+
+## 一、來源接入分級
+
+- `active`：已在系統中可直接抓取並回報健康狀態
+- `conditional`：有條件接入（依環境金鑰）
+- `planned`：規劃中，作為未來接入候選
+- `reference_only`：僅作人工/參考核對，不列為即時抓取來源
+
+## 二、主流外部來源矩陣
+
+### 1. 官方與賽事主體
+
+1. FIFA 官方 — `fifa_official`
+   - 網址：`https://www.fifa.com/fifa-world-cup`
+   - 類型：官方主辦
+   - 狀態：reference_only
+   - 權重：1.00
+   - 用途：規則、公告、賽制、場地政策、重大異動參考
+
+2. FIFA 官方賽程與賽果 — `fifa_world_cup_fixtures`
+   - 網址：`https://www.fifa.com/fifa-world-cup/fixtures-and-results`
+   - 類型：官方主辦
+   - 狀態：reference_only
+   - 權重：0.98
+   - 用途：核對開賽時間、場次順序、場地異動
+
+### 2. 賠率與市場資料
+
+1. The Odds API — `the_odds_api`
+   - 網址：`https://api.the-odds-api.com`
+   - 類型：API
+   - 狀態：active
+   - 權重：0.96
+   - 用途：主體市場抓取（1X2、讓球、大小球、BTTS）
+
+2. Sportradar — `sportradar`
+   - 網址：`https://developer.sportradar.com`
+   - 類型：API（企業授權）
+   - 狀態：planned
+   - 權重：0.90
+   - 用途：賽事事件與場內關鍵事件補強
+
+3. API-FOOTBALL Odds — `apifootball_odds`
+   - 網址：`https://www.api-football.com`
+   - 類型：API（商用授權）
+   - 狀態：planned
+   - 權重：0.85
+   - 用途：賠率備援與市場交叉驗證
+
+4. Odds API 社群備援 — `odds_api_fallback`
+   - 網址：`https://www.odds-api.com`
+   - 類型：聚合參考
+   - 狀態：reference_only
+   - 權重：0.75
+   - 用途：主幹與外部市場口徑偏差觀察
+
+### 3. 新聞與事件訊號
+
+1. NewsAPI — `newsapi`
+   - 網址：`https://newsapi.org`
+   - 類型：API
+   - 狀態：conditional
+   - 權重：0.82
+   - 用途：有金鑰時抓取英文新聞與情緒信號
+
+2. Google News RSS — `google_news_rss`
+   - 網址：`https://news.google.com`
+   - 類型：RSS
+   - 狀態：active
+   - 權重：0.70
+   - 用途：無金鑰新聞備援，保證資訊補充持續可用
+
+3. Reuters — `reuters`
+   - 網址：`https://www.reuters.com/sports`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.90
+   - 用途：突發與敏感事件高可信核對
+
+4. BBC Sport — `bbc_sport`
+   - 網址：`https://www.bbc.com/sport`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.84
+   - 用途：主流新聞來源交叉核對
+
+5. ESPN FC — `espn`
+   - 網址：`https://www.espn.com/soccer/`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.80
+   - 用途：前瞻、輪替、戰術文本信號
+
+6. Goal.com — `goal`
+   - 網址：`https://www.goal.com`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.74
+   - 用途：傷病與賽前動態補充
+
+7. Sky Sports — `skysports`
+   - 網址：`https://www.skysports.com/football`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.69
+   - 用途：歐洲戰術與賽前觀察補充
+
+8. The Guardian — `guardian_sport`
+   - 網址：`https://www.theguardian.com/football`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.71
+   - 用途：深度報導、風險語意交叉核對
+
+9. Associated Press — `associated_press`
+   - 網址：`https://apnews.com`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.77
+   - 用途：突發事件高可見度校驗
+
+10. OneFootball — `onefootball`
+   - 網址：`https://onefootball.com`
+   - 類型：官方媒體
+   - 狀態：reference_only
+   - 權重：0.66
+   - 用途：跨區域社群與賽事摘要補充
+
+### 4. 球隊/球員與高階數據
+
+1. SofaScore — `sofascore`
+   - 網址：`https://www.sofascore.com`
+   - 類型：Web
+   - 狀態：planned
+   - 權重：0.76
+   - 用途：先發與戰況補強觀測
+
+2. WhoScored — `whoscored`
+   - 網址：`https://www.whoscored.com`
+   - 類型：Web
+   - 狀態：planned
+   - 權重：0.81
+   - 用途：場面效率與球員表現深度指標
+
+3. FBref — `fbref`
+   - 網址：`https://fbref.com`
+   - 類型：Web
+   - 狀態：planned
+   - 權重：0.78
+   - 用途：xG、節奏、每90分鐘效率
+
+4. Understat — `understat`
+   - 網址：`https://understat.com`
+   - 類型：Web
+   - 狀態：planned
+   - 權重：0.79
+   - 用途：xG 分佈與得分質量
+
+5. WorldFootball.net — `worldfootball`
+   - 網址：`https://www.worldfootball.net`
+   - 類型：Web
+   - 狀態：reference_only
+   - 權重：0.64
+   - 用途：歷史交手、賽事流程補充
+
+6. Soccerway — `soccerway`
+   - 網址：`https://int.soccerway.com`
+   - 類型：Web
+   - 狀態：reference_only
+   - 權重：0.62
+   - 用途：賽程與歷史進程交叉
+
+7. Transfermarkt — `transfermarkt`
+   - 網址：`https://www.transfermarkt.com`
+   - 類型：Web
+   - 狀態：reference_only
+   - 權重：0.70
+   - 用途：球員輪值、傷停、出場補充
+
+8. Statbunker — `statbunker`
+   - 網址：`https://www.statbunker.com`
+   - 類型：Web
+   - 狀態：reference_only
+   - 權重：0.58
+   - 用途：場均效率與歷史指標補充
+
+9. Footystats — `footystats`
+   - 網址：`https://footystats.org`
+   - 類型：Web
+   - 狀態：reference_only
+   - 權重：0.60
+   - 用途：效率模型參考
+
+### 5. 比賽環境（天氣）
+
+1. Open-Meteo — `open_meteo`
+   - 網址：`https://open-meteo.com`
+   - 類型：氣象 API
+   - 狀態：planned
+   - 權重：0.68
+   - 用途：風速、溫濕度、降雨條件修正
+
+2. WeatherAPI — `weatherapi`
+   - 網址：`https://www.weatherapi.com`
+   - 類型：氣象 API
+   - 狀態：planned
+   - 權重：0.64
+   - 用途：天候補強與模型對照
+
+3. OpenWeather — `openweathermap`
+   - 網址：`https://openweathermap.org`
+   - 類型：氣象 API
+   - 狀態：planned
+   - 權重：0.60
+   - 用途：天氣交叉比對備援
+
+## 三、資料使用原則（專業投注研究）
+
+1. 先用官方公告與賽程基準定義「比賽可比性」。
+2. 以 The Odds API 作為主幹，計算市場共識機率與賠率偏離。
+3. 將新聞事件（Reuter/ESPN/Goal/Google RSS）轉為「風險熱度」與「臨場訊號」。
+4. 在 2026 世界盃短天數高密度賽事下，優先看多源一致方向，降低單源誤差對單場判斷影響。
+5. 使用官方/高可信來源權重作為優先裁決條件，reference_only 僅作核查，不與 active 源同等作決策。
+
+## 四、系統落地映射
+
+- `GET /api/source-registry`：回傳本台帳中的每個來源、整合層級、目前 runtime 狀態、延遲與錯誤摘要。
+- `GET /api/today-insights`：回傳台北時區「今日可下注賽事」高/中/低/爆冷摘要，做為首頁主題化投研入口資料。
+- 主幹賠率：`the_odds_api`（失敗會直接反映為 source-registry error）
+- 新聞雙通道：`newsapi`（有金鑰）與 `google_news_rss` fallback
+- 參考層：`reference_only` 僅保留為研究證據，不列為即時決策主因
+
+## 五、建議的下一階段高價值接入
+
+1. 將 `weatherapi/open_meteo/openweathermap` 其中一個正式接入，做場地環境修正模型。
+2. 接入至少一個可授權備援 odds provider（如 Sportradar 或 API-FOOTBALL）降低單點失效。
+3. 訓練新聞關鍵字模型（`injury`、`rotation`、`rest`）到權重輸入，提升短期決策穩定性。

docs/professional-market-architecture.md

@@ -0,0 +1,86 @@
+# 2026 世界盃對標市場主流版：資料驅動量化架構藍圖（Gemini 路線）
+
+## 一、目標
+將網站從「賠率列表」提升為「市場主流級決策中心」：
+- 跨平台賠率矩陣化（多書比較）
+- 走勢與成交量監測（Line Movement + Sharp/Public 分流）
+- 量化模型直接回傳投注信號（EV / Poisson / Monte Carlo）
+- 個人資金回報與 CLV 監控（Portfolio Tracker）
+
+## 二、資料分層
+- **Ingestion（來源層）**：主力 Odds API + 可擴展的 Odds/Stats/News Feed。
+- **Normalization（正規化層）**：統一 `matchId / teamId / market / outcome`。
+- **Feature Store（特徵層）**：暫存賽事快照、盤口快取、賽中事件。
+- **Analytics Engine（分析層）**：EV、Poisson、Monte Carlo 的模型輸出。
+- **Presentation Layer（展示層）**：儀表板頁面 + API。
+
+## 三、資料庫建議（PostgreSQL）
+以下為最小可用表結構：
+
+### teams
+- `id` UUID
+- `name` TEXT
+- `fifa_code` TEXT
+
+### matches
+- `id` UUID
+- `provider_match_id` TEXT
+- `stage` TEXT
+- `kickoff_at` TIMESTAMPTZ
+- `venue` TEXT
+- `city` TEXT
+- `altitude` NUMERIC
+- `home_team_id` UUID
+- `away_team_id` UUID
+
+### odds_history`（建議以 `match_id, provider, market, updated_at` 分區）
+- `id` BIGSERIAL
+- `match_id` UUID
+- `provider` TEXT
+- `market` TEXT
+- `outcome` TEXT
+- `point` NUMERIC
+- `odds` NUMERIC
+- `updated_at` TIMESTAMPTZ
+
+### betting_tickets
+- `id` BIGSERIAL
+- `match_id` UUID
+- `market` TEXT
+- `selection` TEXT
+- `point` NUMERIC
+- `tickets_pct` NUMERIC
+- `handle_pct` NUMERIC
+- `provider` TEXT
+- `snapshot_at` TIMESTAMPTZ
+
+### portfolio_bets（本機用量化追蹤）
+- `id` UUID
+- `match_id` UUID
+- `market` TEXT
+- `selection` TEXT
+- `odds` NUMERIC
+- `stake` NUMERIC
+- `result` TEXT
+- `settled_at` TIMESTAMPTZ
+
+## 四、快取與即時性
+- **Redis key 建議**
+  - `live:match:{matchId}:latest`
+  - `odds:market:{matchId}:{market}`
+  - `stats:line:{matchId}:{market}:{outcome}`
+
+## 五、量化分析模型
+- **EV Detector**：以模型機率與市場隱含機率對照，EV > 0 直接產生 `value_bet=true`。
+- **Poisson**：推估雙方進球分佈與比分機率，輸出 1-3 機率最高 score。
+- **Monte Carlo**：10k 次模擬輸出「淨勝 2 球以上」、「高波動場次」
+
+## 六、實作進度接軸
+本次提交已完成：
+1. 量化模組核心引擎（Node）
+2. 市場矩陣 + 線路變化 API
+3. 資金流偏差與走勢資料快照 API
+4. 組合/組合式投資組合 CLV API（in-memory prototype）
+5. 量化儀表頁樣式與 API 串接骨架
+
+後續可無縫接入 PostgreSQL/Redis：將 in-memory 資料改為 DB Repository 注入。