Architecture

架構總覽

兩個套件的關係

本專案分成兩個套件，各自的目的不同：

套件	是什麼	跟 Cyberbiz 有關嗎
beam_pipeline_toolkit/	通用、可重用的 Apache Beam 管線框架（解析 → 驗證 → 彙總 → 輸出的骨架、Dataflow 控制平面 API、安全層），沒有寫死任何商業邏輯	沒有，任何欄位名稱、資料表結構都沒有寫死
demo/	套用在「電商情境」的具體展示：Session／訂單／客戶、x1-x6 指標、DBT 相容的訂單篩選	只有「形狀」相似（電商報表管線常見的樣子），資料全部是合成的

資料流程圖

flowchart TD
    A[瀏覽器 Dashboard] -->|選擇情境, 送出 Run| B[FastAPI 後端]
    B -->|本機模式: 直接執行| C["Apache Beam Pipeline<br/>(DirectRunner)"]
    B -.->|雲端模式: 已閘門, 預設關閉| D[Pub/Sub 輸入主題]
    D -.-> E["Apache Beam Pipeline<br/>(DataflowRunner)"]
    C --> F[本機清洗後的<br/>metrics / telemetry 檔案]
    E -.-> G[BigQuery 彙總表]
    E -.-> H[Pub/Sub 遙測主題]
    F --> B
    G -.-> B
    H -.-> B
    B --> A

Loading

實線代表「目前預設會執行」的路徑（本機模式）；虛線代表「已預留但預設關閉」的雲端路徑，需要三個安全閘門旗標同時開啟才會啟用（見 安全機制）。

Pipeline 內部階段

flowchart LR
    R[讀取合成事件] --> P[解析 / 正規化]
    P --> V[驗證]
    V -->|合法| K["依 run_id + 商店代號<br/>+ 日期 分組"]
    V -->|不合法| I[彙總成無害的統計數字]
    K --> AG[每日彙總]
    AG --> M[x1-x6 指標列]
    AG --> T[已清洗的階段遙測]

Loading

每個階段都會產生「已清洗」的遙測事件，絕不會把原始資料（例如姓名、電話）往下傳遞——詳見 安全機制。

本機模式 vs. 雲端模式

	本機模式（現在）	雲端模式（未來，預設關閉）
Runner	DirectRunner	DataflowRunner
輸入	合成情境直接產生事件	Pub/Sub 主題
輸出	本機清洗後的 .jsonl 檔案	BigQuery 彙總表 + Pub/Sub 遙測
需要 GCP 設定嗎	不需要	需要，且需三個閘門旗標同時開啟

兩種模式跑的是同一套 Pipeline 程式碼，差別只在輸入/輸出的組裝方式。