环境搭建指南

1. 前置条件

组件	版本要求	说明
Python	3.10+	推荐 3.12 或 3.13
PostgreSQL	远程实例	需要可访问的 PostgreSQL 服务
pip	最新版	Python 包管理器

2. 安装步骤

2.1 克隆仓库并创建虚拟环境

git clone <repo-url> etl-billiards
cd etl-billiards

# 创建并激活虚拟环境
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

2.2 安装依赖

pip install -r requirements.txt

核心依赖说明：

包名	用途
`psycopg2-binary`	PostgreSQL 驱动
`requests`	上游 API HTTP 客户端
`python-dateutil` / `tzdata`	日期解析与时区处理
`python-dotenv`	`.env` 文件加载
`openpyxl`	Excel 导入导出（DWS 数据）
`PySide6`	Qt 桌面 GUI 框架
`flask`	可选 Web API

如需运行测试，还需安装：

pip install pytest hypothesis

2.3 配置环境变量

在项目根目录创建 .env 文件（禁止提交到版本控制）：

# 数据库连接
PG_DSN=postgresql://用户名:密码@主机:端口/数据库名
# 或分别指定
PG_HOST=localhost
PG_PORT=5432
PG_NAME=billiards
PG_USER=your_user
PG_PASSWORD=your_password

# 门店与 API
STORE_ID=1
API_TOKEN=your_bearer_token

# 可选
APP_TIMEZONE=Asia/Shanghai

安全提示：.env 文件包含敏感信息，已在 .gitignore 中排除。

3. 配置体系

系统采用三层配置叠加，优先级从低到高：

config/defaults.py  →  .env / 环境变量  →  CLI 参数

默认值定义在 config/defaults.py
环境变量通过 python-dotenv 加载，由 config/env_parser.py 解析
CLI 参数拥有最高优先级，可覆盖前两层
通过 AppConfig.get("dotted.path") 访问配置值，例如 config.get("db.dsn")

4. 数据库初始化

系统使用四个 Schema：

Schema	用途
`billiards_ods`	ODS 原始数据层
`billiards_dwd`	DWD 明细数据层
`billiards_dws`	DWS 汇总数据层
`etl_admin`	调度与运行记录

初始化步骤：

# 1. 执行 DDL 创建表结构
psql "$PG_DSN" -f database/schema_ods.sql
psql "$PG_DSN" -f database/schema_dwd.sql
psql "$PG_DSN" -f database/schema_dws.sql
psql "$PG_DSN" -f database/schema_etl_admin.sql

# 2. 执行种子数据（如有）
psql "$PG_DSN" -f database/seed_*.sql

# 3. 执行迁移脚本（按日期前缀顺序）
ls database/migrations/*.sql | sort | xargs -I {} psql "$PG_DSN" -f {}

5. 验证安装

# 试运行（不写库），确认连接和配置正常
python -m cli.main --dry-run --tasks ODS_MEMBER --store-id 1

# 运行单元测试
pytest tests/unit

# 运行集成测试（需要数据库）
TEST_DB_DSN="postgresql://..." pytest tests/integration

6. 运行入口

入口	命令	说明
CLI	`python -m cli.main`	主入口，支持全部参数
GUI	`python -m gui.main`	PySide6 桌面界面
批处理	`run_etl.bat` / `run_gui.bat`	Windows 快捷脚本

3.1 KiB Raw Blame History Unescape Escape

环境搭建指南

1. 前置条件

2. 安装步骤

2.1 克隆仓库并创建虚拟环境

2.2 安装依赖

2.3 配置环境变量

3. 配置体系

4. 数据库初始化

5. 验证安装

6. 运行入口

3.1 KiB

Raw Blame History