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

apps/etl/pipelines/feiqiu/docs/architecture/README.md

@@ -0,0 +1,16 @@
+# 架构设计文档
+
+本目录存放飞球 ETL 系统的架构设计文档，涵盖系统整体架构、数据流向和模块交互关系。
+
+## 文档索引
+
+| 文档 | 说明 |
+|------|------|
+| [system_overview.md](system_overview.md) | 系统整体架构：技术栈、模块交互、执行链路 |
+| [data_flow.md](data_flow.md) | 数据流向详解：ODS → DWD → DWS 三层架构 |
+
+## 相关资源
+
+- [根 README](../../README.md) — 快速开始与命令参考
+- [数据库文档](../database/README.md) — 表结构与 Schema 说明
+- [业务规则文档](../business-rules/README.md) — 指数算法、口径定义等

apps/etl/pipelines/feiqiu/docs/architecture/data_flow.md

@@ -0,0 +1,119 @@
+# 数据流向详解：ODS → DWD → DWS
+
+## 整体数据流
+
+```
+上游 SaaS API / 离线 JSON
+        │
+        ▼
+┌───────────────────────────────────────┐
+│  ODS 层（billiards_ods）               │
+│  操作数据存储 — 原始数据落地            │
+│  保留源 payload，便于回溯              │
+│  22 张 ODS 表，对应 22 个 API 端点     │
+└───────────────┬───────────────────────┘
+                │ DWD_LOAD_FROM_ODS
+                ▼
+┌───────────────────────────────────────┐
+│  DWD 层（billiards_dwd）               │
+│  明细数据 — 清洗、标准化、关联          │
+│  维度表走 SCD2（缓慢变化维度）          │
+│  事实表按时间增量写入                   │
+└───────────────┬───────────────────────┘
+                │ DWS 汇总任务
+                ▼
+┌───────────────────────────────────────┐
+│  DWS 层（billiards_dws）               │
+│  数据服务 — 汇总、指标、指数            │
+│  助教业绩 / 财务日报 / 会员分析         │
+│  工资计算 / 自定义指数算法              │
+└───────────────────────────────────────┘
+```
+
+## ODS 层（操作数据存储）
+
+- Schema：`billiards_ods`
+- 职责：从上游 SaaS API 抓取原始数据并落地，保留完整源 payload
+- 数据来源：在线 API 抓取（`APIClient`）或离线 JSON 回放（`LocalJsonClient`）
+- 任务模式：每个业务实体对应一个 ODS 任务（如 `ORDERS`、`PAYMENTS`、`MEMBERS` 等）
+- 加载方式：通用 ODS 加载器，批量 upsert + 冲突处理
+
+### 核心业务实体（16 个）
+
+订单（settlement_records）、支付（payment_transactions）、退款（refund_transactions）、会员（member_profiles）、会员余额变动（member_balance_changes）、储值卡（member_stored_value_cards）、助教（assistant_accounts_master）、助教服务记录（assistant_service_records）、助教作废记录（assistant_cancellation_records）、台桌（site_tables_master）、商品（store_goods_master / tenant_goods_master）、库存变动（goods_stock_movements）、团购套餐（group_buy_packages）、团购核销（group_buy_redemption_records）、台费折扣（table_fee_discount_records）、台费流水（table_fee_transactions）等。
+
+## DWD 层（明细数据）
+
+- Schema：`billiards_dwd`
+- 职责：对 ODS 原始数据进行清洗、标准化、关联，生成可分析的明细数据
+- 核心任务：`DWD_LOAD_FROM_ODS`
+- 质量检查：`DWD_QUALITY_CHECK`
+
+### 维度处理（SCD2）
+
+维度表采用 SCD2（缓慢变化维度 Type 2）策略，由 `scd/` 模块处理：
+- 会员维度（`dim_member`）
+- 助教维度（`dim_assistant`）
+- 商品维度（`dim_product`）
+- 台桌维度（`dim_table`）
+- 套餐维度（`dim_package`）
+
+每条维度记录包含 `effective_from`、`effective_to`、`is_current` 字段，支持历史版本追溯。
+
+### 事实表处理
+
+事实表按时间增量写入，由 `loaders/facts/` 中的加载器处理：
+- 订单事实、支付事实、退款事实、小票明细、充值结算、台费流水等
+
+## DWS 层（数据服务）
+
+- Schema：`billiards_dws`
+- 职责：基于 DWD 明细数据进行汇总计算，输出业务指标和分析结果
+
+### 汇总任务分类
+
+| 类别 | 任务示例 | 建议频率 |
+|------|----------|----------|
+| 助教业绩 | `DWS_ASSISTANT_DAILY`、`DWS_ASSISTANT_MONTHLY` | 每小时 / 每日 |
+| 财务日报 | `DWS_FINANCE_DAILY`、`DWS_FINANCE_INCOME_STRUCTURE` | 每小时 |
+| 会员分析 | `DWS_MEMBER_CONSUMPTION`、`DWS_MEMBER_VISIT` | 每日 |
+| 工资计算 | `DWS_ASSISTANT_SALARY` | 每月（月初） |
+| 指数算法 | `DWS_WINBACK_INDEX`、`DWS_NEWCONV_INDEX`、`DWS_RELATION_INDEX` | 每 2-4 小时 |
+
+### 自定义指数算法
+
+系统实现了六个自定义业务指数，参数存储在 `billiards_dws.cfg_index_parameters`：
+
+| 指数 | 全称 | 说明 |
+|------|------|------|
+| WBI | Winback Index | 召回指数 |
+| NCI | New Conversion Index | 新客转化指数 |
+| RS | Relation Score | 关系评分 |
+| OS | Overall Score | 综合评分 |
+| MS | Member Score | 会员评分 |
+| ML | Manual Ledger | 人工台账 |
+
+公共参数：`percentile_lower/upper`（分位截断锚点）、`ewma_alpha`（指数加权移动平均平滑系数）。
+
+## ETL 管理层
+
+- Schema：`etl_admin`
+- 职责：调度元数据管理
+- 内容：游标（水位）记录、任务运行记录、调度配置
+- 关键组件：`cursor_manager.py`（水位管理）、`run_tracker.py`（运行记录）
+
+## 窗口切分与补偿
+
+大时间范围的数据抓取会按窗口切分执行，避免单次请求数据量过大：
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `run.window_split.unit` | `day` | 切分单位：day / week / month / none |
+| `run.window_split.days` | `10` | 切分天数 |
+| `run.window_split.compensation_hours` | `2` | 补偿小时数（处理跨窗口数据） |
+
+## 数据质量保障
+
+- `DWD_QUALITY_CHECK`：DWD 层质量检查
+- `quality/integrity_service.py`：完整性检查服务（余额一致性等）
+- `tasks/verification/`：ETL 后置校验（ODS/DWD/DWS/指数校验器）

apps/etl/pipelines/feiqiu/docs/architecture/system_overview.md

@@ -0,0 +1,103 @@
+# 系统整体架构
+
+## 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| 语言 | Python 3.10+ |
+| 数据库 | PostgreSQL（远程实例） |
+| DB 驱动 | psycopg2-binary |
+| HTTP 客户端 | requests |
+| 日期处理 | python-dateutil / tzdata |
+| 配置管理 | python-dotenv |
+| Excel 导入导出 | openpyxl |
+| 桌面 GUI | PySide6（Qt） |
+| Web API（可选） | Flask |
+| 测试 | pytest / hypothesis |
+
+## 模块交互关系
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      入口层                              │
+│  cli/main.py（CLI）    gui/main.py（GUI）                │
+└──────────┬──────────────────────┬───────────────────────┘
+           │ AppConfig            │
+           ▼                      ▼
+┌─────────────────────────────────────────────────────────┐
+│                     编排层                               │
+│  orchestration/                                          │
+│  ├── pipeline_runner.py   管线运行器                     │
+│  ├── task_executor.py     任务执行器                     │
+│  ├── task_registry.py     任务注册表                     │
+│  ├── scheduler.py         ETL 调度器                     │
+│  ├── cursor_manager.py    游标（水位）管理               │
+│  └── run_tracker.py       运行记录追踪                   │
+└──────────┬──────────────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────────────────────────┐
+│                     执行层                               │
+│  tasks/                                                  │
+│  ├── base_task.py         BaseTask 基类                  │
+│  ├── ods/                 ODS 抓取任务（16 个业务实体）   │
+│  ├── dwd/                 DWD 装载任务（维度/事实/质检）  │
+│  ├── dws/                 DWS 汇总与指数任务             │
+│  │   └── index/           指数计算（WBI/NCI/RS/OS/MS/ML）│
+│  ├── utility/             工具任务（Schema 初始化等）     │
+│  └── verification/        ETL 后置校验                   │
+└──────────┬──────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────┐  ┌───────────────────────────────┐
+│      数据源层         │  │         数据装载层             │
+│  api/                 │  │  loaders/                      │
+│  ├── APIClient        │  │  ├── base_loader.py            │
+│  ├── LocalJsonClient  │  │  ├── ods/         ODS 加载器   │
+│  └── RecordingClient  │  │  ├── dimensions/  SCD2 维度    │
+│                       │  │  └── facts/       事实表       │
+└───────────────────────┘  └───────────────────────────────┘
+           │                          │
+           ▼                          ▼
+┌─────────────────────────────────────────────────────────┐
+│                   PostgreSQL                             │
+│  billiards_ods │ billiards_dwd │ billiards_dws │ etl_admin│
+└─────────────────────────────────────────────────────────┘
+```
+
+## 执行链路
+
+系统采用三层架构，执行流程如下：
+
+1. **CLI 层**（`cli/main.py`）：解析命令行参数 → 生成 `AppConfig` → 依赖注入
+2. **编排层**（`orchestration/pipeline_runner.py`）：管道名称 → 层 → 任务列表解析；`processing_mode` 控制增量/校验流程
+3. **执行层**（`orchestration/task_executor.py`）：`DataSource` 枚举决定 fetch/ingest 路径，含游标管理、运行记录、失败标记
+
+## 核心架构模式
+
+### 任务模式
+
+每个 ETL 任务继承 `BaseTask`，遵循 Extract → Transform → Load 模板方法，在 `orchestration/task_registry.py` 中注册。任务代码采用大写蛇形命名（如 `DWD_LOAD_FROM_ODS`）。
+
+### 加载器模式
+
+每张目标表对应一个加载器，继承 `BaseLoader` 并实现 `upsert()` 方法。维度加载器位于 `loaders/dimensions/`（走 SCD2），事实加载器位于 `loaders/facts/`（增量写入）。核心是批量 upsert + 冲突处理策略。
+
+### 配置分层
+
+配置按优先级叠加：`config/defaults.py`（默认值）→ `.env` / 环境变量 → CLI 参数覆盖。通过 `AppConfig.get("dotted.path")` 统一访问。
+
+### API 抽象
+
+`APIClient`（HTTP 在线抓取）、`LocalJsonClient`（离线 JSON 回放）、`RecordingAPIClient`（抓取 + 落盘）共享相同接口，任务代码无需关心数据来源。
+
+### 管线模式
+
+通过 `--pipeline-flow` 或 `--data-source` 参数控制：
+- `FULL` / `hybrid`：在线抓取 + 入库
+- `FETCH_ONLY` / `online`：仅在线抓取
+- `INGEST_ONLY` / `offline`：仅离线入库
+
+### 调度与水位
+
+`ETLScheduler` 编排任务执行，`cursor_manager` 管理增量水位，`run_tracker` 在 `etl_admin` Schema 中记录运行状态，确保增量正确性和可重复性。