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

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 中记录运行状态，确保增量正确性和可重复性。