dzakialthalsy/BufferOverFlow1-picoCTF

# KBA 电信公司流失分析 商业智能与分析项目，旨在帮助电信公司监控客户流失、细分客户群并确定保留优先级。该方案采用 Medallion 管道、DuckDB 作为分析型数据仓库、用于流失评分的机器学习模型以及用于商业仪表板的 Metabase。 ## 主要特性 - Medallion ETL：在 DuckDB 中实现 Bronze、Silver 和 Gold 三层。 - 电信客户数据清洗：缺失值填充、去重、数据类型校正、异常值截断、对数转换以及特征工程。 - 用于商业分析的 Gold 层：流失摘要、客户细分、流失风险，以及基于 ML 的流失预测（如果可用评分）。 - 为仪表板导出专用的 DuckDB，使 Metabase 仅读取 Gold schema。 - 自动设置 Metabase，包含数据库、角色、组和演示用户。 - 可选的 FastAPI 应用程序，用于预测单个客户的流失情况。 ## 数据架构 ``` data/raw/Telecom_customer.csv -> bronze.telecom_raw -> silver.telecom_cleaned -> gold.customer_segments -> gold.churn_risk -> gold.churn_summary -> gold.churn_prediction (jika ml/models/churn_scores.csv tersedia) -> data/gold/telco_warehouse_readonly.duckdb untuk Metabase ``` 主仓库文件位于 `data/gold/telco_warehouse.duckdb`。管道仍将在主仓库中保留所有层，然后创建单独的只读文件供仪表板使用。 ## 文件夹结构 ``` KBA-Telecommunication-Company-Churn-Analytics/ |-- dashboard/ # FastAPI predictor, template UI, builder inference bundle |-- data/ | |-- raw/ # Dataset CSV sumber | |-- bronze/ # Placeholder layer Bronze | |-- silver/ # Placeholder layer Silver | `-- gold/ # Output DuckDB warehouse dan export dashboard |-- docs/ # Dokumen PM, handoff, dan dokumentasi pendukung |-- etl/ | |-- layers/ | | |-- bronze.py # Ingest data mentah ke bronze.telecom_raw | | |-- silver.py # Cleaning dan feature engineering ke silver.telecom_cleaned | | `-- gold.py # Tabel bisnis di schema gold | |-- export_metabase.py # Export schema Gold untuk Metabase | `-- run_pipeline.py # Entry point pipeline ETL |-- ml/ | |-- colab/ # Notebook training dan eksperimen ML | |-- models/ # Model dan skor churn | `-- reports/ # Laporan evaluasi model |-- scripts/ # Health check, init catalog, setup Metabase RBAC |-- tests/ # Unit test pipeline |-- docker-compose.yml # catalog_db, etl, metabase, metabase_setup |-- Dockerfile # Image ETL |-- Dockerfile.inference # Image predictor FastAPI |-- Dockerfile.metabase # Image Metabase + plugin DuckDB |-- requirements.txt `-- .env.example ``` ## 前置条件 - Python 3.11 或兼容版本。 - Docker 和 Docker Compose，用于运行管道和 Metabase。 - Kaggle Telecom Customer Churn 数据集存储在 `data/raw/` 文件夹中。 - 基于 `.env.example` 创建的 `.env` 文件。 数据集注意事项：确保 `.env` 中的 `RAW_DATA_PATH` 值与 `data/raw/` 中 CSV 文件的名称完全一致。在 Docker/Linux 中，大小写是敏感的。如果文件名为 `Telecom_customer.csv`，请精确使用该路径。 ## 本地快速启动 ``` cd C:\Users\dzakialthalsyah\Downloads\KBA-Telecommunication-Company-Churn-Analytics copy .env.example .env python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt python scripts\health_check.py python etl\run_pipeline.py ``` 如果使用 Git Bash 或 WSL，请使用 `cp .env.example .env` 代替 `copy`。 ## 使用 Docker 和 Metabase 运行 ``` docker compose up --build ``` 运行的服务： | 服务 | 功能 | | --- | --- | | `catalog_db` | PostgreSQL catalog，用于存储元数据和 RBAC 需求。 | | `etl` | 运行 Bronze -> Silver -> Gold 管道。 | | `metabase` | BI 仪表板，位于 `http://localhost:3000`。 | | `metabase_setup` | 一次性设置，用于配置数据库、组、权限和演示用户。 | 本地 Metabase 访问： | 角色 | 电子邮件 | 密码 | | --- | --- | --- | | 管理员 | `admin@telco.com` | `Admin@1234` | | 高管 | `ceo@telco.com` | `Exec@1234` | | 运维 | `ops@telco.com` | `Ops@1234` | | 分析师 | `analyst@telco.com` | `Analyst@1234` | 上述凭证遵循项目的默认值，仅适用于本地演示。如果修改了 `.env`，请使用该文件中的凭证。 ## Gold 层输出 | 表 | 用途 | 主要消费者 | | --- | --- | --- | | `gold.churn_summary` | 聚合 KPI：总客户数、流失率、保留率、ARPU 和风险客户。 | 高管 | | `gold.customer_segments` | 客户细分：流失、高风险、关注、高价值、稳定。 | 运维 | | `gold.churn_risk` | 每个客户的流失风险评分、风险级别和支持信息。 | 运维 / 分析师 | | `gold.churn_prediction` | ML 预测结果，用于测试/评分客户数据（如果 `churn_scores.csv` 可用）。 | 高管 / 分析师 | | `gold.telecom_cleaned` | 从 Silver 层导出到 Gold schema 的完整清洗数据，专用于 Metabase 中的分析。 | 分析师 | ## 机器学习集成 Gold 管道将尝试从 `ml/models/churn_scores.csv` 读取 ML 评分。支持的列格式： | 列 | 说明 | | --- | --- | | `Customer_ID`, `customer_id`, 或 `CustomerID` | 客户 ID。 | | `ml_churn_score` | 模型输出的流失概率。 | | `ml_churn_label` | 流失预测标签。 | 如果 ML 评分文件不可用或格式不符，管道将使用基于 `fe_churn_risk_rule` 特征的回退规则继续运行。 从 notebook 导出评分的示例： ``` scores_df = pd.DataFrame({ "customer_id": test_ids, "ml_churn_score": model.predict_proba(X_test)[:, 1], "ml_churn_label": model.predict(X_test), }) scores_df.to_csv("ml/models/churn_scores.csv", index=False) ``` 评分文件准备好后，重新运行： ``` python etl\run_pipeline.py ``` ## 可选的 FastAPI 预测器 用于创建推理包并运行预测应用程序： ``` python dashboard\build_inference_bundle.py uvicorn dashboard.churn_app:app --host 0.0.0.0 --port 8000 ``` 主要端点： | 端点 | 功能 | | --- | --- | | `GET /` | 基于 HTML 模板的流失预测表单。 | | `GET /health` | 应用程序健康检查。 | | `POST /predict` | 根据客户特征的负载进行流失预测。 | Docker 替代方案： ``` docker build -f Dockerfile.inference -t telco-churn-inference . docker run --rm -p 8000:8000 telco-churn-inference ``` ## 重要环境变量 | 变量 | 功能 | | --- | --- | | `RAW_DATA_PATH` | 源 CSV 数据集的位置。 | | `DUCKDB_PATH` | 主 DuckDB 仓库的位置。 | | `ML_SCORES_PATH` | 用于 Gold 层的 ML 评分文件的位置。 | | `ETL_LOG_LEVEL` | ETL 日志记录级别。 | | `METABASE_URL` | 用于自动设置的 Metabase URL。 | | `METABASE_USER` | Metabase 管理员邮箱。 | | `METABASE_PASS` | Metabase 管理员密码。 | | `METABASE_DB_NAME` | 在 Metabase 中注册的数据库名称。 | | `CATALOG_URL` | PostgreSQL catalog 连接字符串。 | ## 验证与测试 ``` python scripts\health_check.py python -m pytest ``` `health_check.py` 验证数据集、各层文件夹、`.env`、Python 依赖、ETL 文件以及可用 ML 评分的存在。 ## 简易故障排除 | 问题 | 常见原因 | 解决方案 | | --- | --- | --- | | 未找到数据集 | `RAW_DATA_PATH` 与实际文件名不匹配。 | 调整 `.env` 中的路径或重命名 CSV 文件。 | | Metabase 未显示表 | 数据库同步未完成或 ETL 尚未成功运行。 | 稍等片刻，检查 `etl` 和 `metabase_setup` 的日志。 | | `gold.churn_prediction` 不存在 | `ml/models/churn_scores.csv` 尚未可用或读取失败。 | 导出 ML 评分，确保包含必需的列，然后重新运行 ETL。 | | 预测器启动失败 | `churn_inference_bundle.joblib` 尚未生成。 | 运行 `python dashboard\build_inference_bundle.py`。 |

标签：Apex, AV绕过, DuckDB, ETL管道, FastAPI, Metabase, Python编程, 代码示例, 仪表板, 分层存储, 商业智能, 客户保留, 客户细分, 数据仓库, 数据分析, 数据清洗, 数据管理, 机器学习, 测试用例, 特征工程, 电信流失分析, 营业智能, 营销分析, 请求拦截, 逆向工具, 风险预测