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

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/指数校验器）