Quick Start

快速開始

1. 安裝環境

需要 Python 3.11 以上（本專案以 Python 3.12.6 驗證過）。

# Windows PowerShell
python -m venv .venv
.venv\Scripts\pip install --upgrade pip
.venv\Scripts\pip install -r requirements.txt

# macOS / Linux
python3.11 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

2. 執行本機 Pipeline（不需要任何雲端設定）

.venv\Scripts\python demo\scripts\run_local_demo.py --scenario healthy_shadow_run

可用的 --scenario 選項：healthy_shadow_run、validation_rejection、order_filter_exclusions、reconciliation_mismatch（詳見 情境範例）。

執行完會在 runtime/<run_id>/ 產生以下檔案：

檔案	內容
metrics.jsonl	x1-x6 彙總指標
telemetry.jsonl	各階段的清洗後遙測事件
invalid_summary.json	不合法紀錄的彙總（不含原始資料）
run_manifest.json	這次執行的中繼資料（run_id、狀態、數量等）

3. 啟動 Dashboard

.venv\Scripts\python demo\scripts\run_dashboard.py

開啟瀏覽器進入 http://127.0.0.1:8000/（只會綁定在本機 127.0.0.1，不會對外開放）。選擇一個情境，按下「Run Local DirectRunner Demo」，就能看到這次執行的完整結果：Run 詳情、x1-x6 指標、不合法/對帳摘要、事件時間軸、以及根據真實遙測產生的說明面板。

4. 執行測試

.venv\Scripts\python -m pytest -q

應顯示全部通過（截至目前共 171 項測試）。

5. 執行安全檢查

.venv\Scripts\python demo\scripts\validate_project.py

這會做 9 項靜態安全檢查，例如：程式碼裡沒有敏感欄位、瀏覽器程式碼沒有直接呼叫 GCP API、沒有真實 Cyberbiz 參照等。全部應顯示 PASS。

疑難排解

若第 4、5 步任何一項失敗，代表是這個沙箱本身程式碼的問題，不代表需要額外的雲端設定——本機模式從頭到尾都不需要任何 GCP 資源。