# 环境搭建指南

## 1. 前置条件

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

## 2. 安装步骤

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

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

```bash
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 |

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

```bash
pip install pytest hypothesis
```

### 2.3 配置环境变量

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

```dotenv
# 数据库连接
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` | 调度与运行记录 |

初始化步骤：

```bash
# 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. 验证安装

```bash
# 试运行（不写库），确认连接和配置正常
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 快捷脚本 |