在准备环境前提交次全部更改。

2026-02-19 08:35:13 +08:00
parent ded6dfb9d8
commit 4eac07da47
1387 changed files with 6107191 additions and 33002 deletions
--- a/apps/etl/connectors/feiqiu/docs/operations/environment_setup.md
+++ b/apps/etl/connectors/feiqiu/docs/operations/environment_setup.md
@@ -0,0 +1,140 @@
+# 环境搭建指南
+
+## 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
+# 数据库连接
+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 视图层 |
+
+初始化步骤：
+
+```bash
+# 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 工具任务初始化：
+
+```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 开发服务器 |