init: 项目初始提交 - NeoZQYY Monorepo 完整代码

apps/etl/pipelines/feiqiu/docs/operations/environment_setup.md

@@ -0,0 +1,134 @@
+# 环境搭建指南
+
+## 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 快捷脚本 |