环境搭建指南

1. 前置条件

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

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 安装依赖

uv sync

核心依赖说明：

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

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

uv sync --group test

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	用途
`meta`	调度与运行记录（游标、任务注册）
`ods`	ODS 原始数据层
`dwd`	DWD 明细数据层
`core`	跨门店标准化层
`dws`	DWS 汇总数据层
`app`	RLS 视图层

初始化步骤：

# 1. 执行 DDL 创建表结构（DDL 文件位于 db/etl_feiqiu/schemas/）
psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_etl_admin.sql
psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_ODS_doc.sql
psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_dwd_doc.sql
psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_dws.sql

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

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

或使用 CLI 工具任务初始化：

python -m cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA,INIT_DWS_SCHEMA,SEED_DWS_CONFIG --pg-dsn "$PG_DSN"

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`	主入口，支持全部参数
后端 API	`cd apps/backend && uvicorn app.main:app --reload`	FastAPI 后端服务
管理后台	`cd apps/admin-web && pnpm dev`	React + Vite 开发服务器

3.4 KiB Raw Blame History Unescape Escape

环境搭建指南

1. 前置条件

2. 安装步骤

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

2.2 安装依赖

2.3 配置环境变量

3. 配置体系

4. 数据库初始化

5. 验证安装

6. 运行入口

3.4 KiB

Raw Blame History