File Guide ZH

English version

檔案導覽

repo 內每一個原始檔案、它的功能、以及在哪裡可以找到它(main 分支)。測試檔案列於測試頁面。

根目錄

檔案	功能
README.md	頂層專案介紹、安裝/測試說明、repo 結構
pyproject.toml	專案中繼資料 + pytest 設定 (testpaths = tests)
setup.py	僅供 DataflowRunner 使用的打包檔案(透過 --setup_file)，用於將套件部署到遠端 worker；本地 DirectRunner 模式不會用到
requirements.txt	直接相依套件(apache-beam[gcp]、google-auth、requests、pytest、build)
requirements.lock.txt	完整鎖定的間接相依版本
.gitignore	排除 .venv、快取、建置產物、日誌、.idea/.vscode

beam_pipeline_toolkit/

檔案	功能
README.md	以下每個套件的完整 API 文件與可執行範例程式碼
__init__.py	僅包含套件說明字串

pipeline/ — 詳見 Pipeline 模組

檔案	功能
__init__.py	套件說明字串
main.py	build_pipeline、run_local、run_cloud、apply_streaming_window — 組裝並執行完整的轉換流程
parsing.py	ParseNormalize — PARSE_NORMALIZE 階段：JSON 解碼 + 呼叫端提供的 normalize_fn
validation.py	Validate — VALIDATE 階段：套用呼叫端的 validate_fn，標記合法/不合法
aggregation.py	AggregateAndEmit、tag_origin — AGGREGATE 階段：分組鍵、GroupByKey、呼叫 build_outcome_fn，並對每個輸出做外洩檢查
sinks.py	write_jsonl/read_jsonl(本地)、build_cloud_pubsub_sink/build_cloud_bigquery_sink(有關卡保護的雲端 sink)
schema.py	PipelineSchema — 呼叫端提供的契約物件(metrics 命名空間、允許的 stage/status)
options.py	BaseToolkitPipelineOptions — 共用的本地/雲端/關卡 CLI 參數，沒有寫死任何預設值
metrics.py	serialize_metric_row/decimal_to_json_string — Decimal 安全的 JSON 序列化
telemetry.py	build_telemetry_event — 消毒過、經 schema 驗證的遙測事件產生器
run_manifest.py	build_run_manifest — 一次管線執行的消毒過摘要

controlplane/ — 詳見控制平面模組

檔案	功能
__init__.py	套件說明字串
google_auth_client.py	get_authorized_session — 共用、僅使用 ADC 的已驗證 HTTP session
dataflow_submit.py	submit_job、generate_job_name — 「先檢查關卡、再提交」的模式
dataflow_stop.py	request_job_cancellation — 透過 REST 請求 JOB_STATE_CANCELLED
dataflow_evidence.py	get_dataflow_job_summary、get_dataflow_job_metrics、is_job_running — 唯讀的任務中繼資料與 counters

log/ — 詳見日誌模組

檔案	功能
__init__.py	套件說明字串
execution_log.py	exception_event、build_execution_log_event — 消毒過的例外/生命週期事件
stage_timing.py	StageTimer、build_stage_timing_event、summarize_stage_durations — 各階段的實際耗時記錄
dataflow_logs.py	get_dataflow_job_logs、get_all_dataflow_job_logs — 唯讀讀取任務自身的 Cloud Logging 紀錄

safety/ — 詳見安全模組

檔案	功能
__init__.py	套件說明字串
leak_guard.py	LeakGuard、assert_safe、is_safe — 遞迴式禁用鍵值掃描器
cloud_gate.py	assert_gates_open — 建立任何真實雲端資源前的唯一關卡

ecommerce/ — 詳見電商模組

檔案	功能
__init__.py	套件說明字串
schemas.py	SessionRecord/OrderRecord/CustomerRecord/DailyMetricRow/InvalidRecord NamedTuple
metrics.py	compute_daily_metrics — Decimal 安全的轉換率/客單價/營收計算
order_policies.py	exclude_cancelled_and_returned、accept_all_orders、partition_by_policy — 可替換的訂單有效性規則
validation.py	build_validate_fn、deduplicate_sessions — 結構檢查 + 重複 session 處理
pipeline.py	build_ecommerce_pipeline、build_outcome_fn_factory — 完整的實作範例

tests/

完整清單與說明請見測試頁面。