# 技术栈与构建

## 语言与运行时
- Python 3.10+（测试缓存中观察到 3.13）
- 未提交虚拟环境；用户自行管理

## 核心依赖（requirements.txt）
- `psycopg2-binary>=2.9.0` — PostgreSQL 驱动
- `requests>=2.28.0` — 上游 API 的 HTTP 客户端
- `python-dateutil>=2.8.0` / `tzdata>=2023.0` — 日期解析与时区处理
- `python-dotenv` — `.env` 文件加载
- `openpyxl>=3.1.0` — Excel 导入导出（DWS 数据）
- `PySide6>=6.5.0` — Qt 桌面 GUI 框架
- `flask>=2.3` — 可选 Web API
- `pyinstaller>=6.0.0` — 可选，仅打包 EXE 时需要

## 数据库
- PostgreSQL（连接远程实例）
- Schema：`billiards`（OLTP/ODS）、`billiards_dwd`、`billiards_dws`、`etl_admin`
- DDL 文件位于 `database/schema_*.sql`，种子脚本位于 `database/seed_*.sql`
- 迁移脚本位于 `database/migrations/`（纯 SQL，日期前缀命名）

## 测试
- 框架：`pytest`（未固定在 requirements 中，需单独安装）
- 配置：`pytest.ini` 设置 `pythonpath = .`
- 结构：`tests/unit/`（基于 mock，无需数据库）、`tests/integration/`（需要 `TEST_DB_DSN`）
- 测试工具：`tests/unit/task_test_utils.py` 提供 FakeDB/FakeAPI 辅助类

## 常用命令
```bash
# 安装依赖
pip install -r requirements.txt

# 在线全流程 ETL（抓取 + 入库）
python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"

# 运行指定任务
python -m cli.main --tasks INIT_ODS_SCHEMA,MANUAL_INGEST --pipeline-flow INGEST_ONLY

# 试运行（不写库）
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS

# 单元测试
pytest tests/unit

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

# 启动 GUI
python -m gui.main
```

## 配置体系
- 分层叠加：`config/defaults.py` < `.env` / 环境变量 < CLI 参数
- 配置类：`config.settings.AppConfig`，支持点号路径访问（`config.get("db.dsn")`）
- 敏感值（DSN、API Token）放在 `.env` 中，禁止提交

## 打包
- 已移除 EXE 打包支持（`build_exe.py`、`setup.py` 已归档至 `.Deleted/`）
- 直接通过 `python -m cli.main` 或 `python -m gui.main` 运行