数据流向详解：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/指数校验器）

5.6 KiB Raw Blame History Unescape Escape