# 环境搭建指南

## 1. 前置条件

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

## 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
uv sync
```

核心依赖说明：

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

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

```bash
uv sync --group test
```

### 2.3 配置环境变量

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

```dotenv
# 数据库连接（推荐使用 DSN 模式）
PG_DSN=postgresql://用户名:密码@主机:端口/数据库名
# 或分离式配置（不使用 DSN 时启用）
PG_HOST=localhost
PG_PORT=5432
PG_NAME=your_database
PG_USER=your_user
PG_PASSWORD=your_password

# 业务库 DSN（后端 / 跨模块脚本使用）
APP_DB_DSN=postgresql://用户名:密码@主机:端口/数据库名

# 门店与 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 视图层 |

初始化步骤：

```bash
# 推荐使用 CLI 工具任务初始化（DDL 基线见 docs/database/ddl/）
python -m cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA,INIT_DWS_SCHEMA,SEED_DWS_CONFIG --pg-dsn "$PG_DSN"

# 或手动执行 DDL（从 docs/database/ddl/ 获取最新基线）
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__meta.sql
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__ods.sql
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dwd.sql
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dws.sql

# 执行种子数据
psql "$PG_DSN" -f db/etl_feiqiu/seeds/seed_*.sql
```

> 注：旧的 `db/etl_feiqiu/schemas/` 和 `db/etl_feiqiu/migrations/` 已归档至 `db/_archived/`。
> DDL 基线现由 `docs/database/ddl/` 统一管理，可通过 `python scripts/ops/gen_consolidated_ddl.py` 重新生成。

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

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

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