初始提交：飞球 ETL 系统全量代码

docs/bd_manual/DWD/main/BD_manual_billiards_dwd.md

@@ -0,0 +1,131 @@
+# billiards_dwd Schema 数据字典
+
+> 生成时间：2026-01-28
+> 数据来源：数据库实时查询 + 500行样本数据分析
+> 不确定内容已使用 **[待确认]** 标记
+
+## 概述
+
+`billiards_dwd` 是台球门店数据仓库的明细层(DWD)，包含维度表(DIM)和事实表(DWD)。本 Schema 基于 SCD2 缓慢变化维度设计，支持历史数据追溯。
+---
+
+## 维度表 (Dimension Tables)
+
+| 序号 | 表名 | 说明 | 主键 | 扩展表 | 文档链接 |
+|------|------|------|------|--------|----------|
+| 1 | dim_assistant | 助教信息 | assistant_id, scd2_start_time | dim_assistant_ex | [主表](BD_manual_dim_assistant.md) / [扩展表](BD_manual_dim_assistant_ex.md) |
+| 2 | dim_goods_category | 商品分类 | category_id, scd2_start_time | 无 | [主表](BD_manual_dim_goods_category.md) |
+| 3 | dim_groupbuy_package | 团购套餐 | groupbuy_package_id, scd2_start_time | dim_groupbuy_package_ex | [主表](BD_manual_dim_groupbuy_package.md) / [扩展表](BD_manual_dim_groupbuy_package_ex.md) |
+| 4 | dim_member | 会员信息 | member_id, scd2_start_time | dim_member_ex | [主表](BD_manual_dim_member.md) / [扩展表](BD_manual_dim_member_ex.md) |
+| 5 | dim_member_card_account | 会员卡账户 | member_card_id, scd2_start_time | dim_member_card_account_ex | [主表](BD_manual_dim_member_card_account.md) / [扩展表](BD_manual_dim_member_card_account_ex.md) |
+| 6 | dim_site | 门店信息 | site_id, scd2_start_time | dim_site_ex | [主表](BD_manual_dim_site.md) / [扩展表](BD_manual_dim_site_ex.md) |
+| 7 | dim_store_goods | 门店商品 | site_goods_id, scd2_start_time | dim_store_goods_ex | [主表](BD_manual_dim_store_goods.md) / [扩展表](BD_manual_dim_store_goods_ex.md) |
+| 8 | dim_table | 台桌信息 | table_id, scd2_start_time | dim_table_ex | [主表](BD_manual_dim_table.md) / [扩展表](BD_manual_dim_table_ex.md) |
+| 9 | dim_tenant_goods | 租户商品 | tenant_goods_id, scd2_start_time | dim_tenant_goods_ex | [主表](BD_manual_dim_tenant_goods.md) / [扩展表](BD_manual_dim_tenant_goods_ex.md) |
+
+---
+
+## 事实表 (Fact Tables)
+
+| 序号 | 表名 | 说明 | 主键 | 扩展表 | 文档链接 |
+|------|------|------|------|--------|----------|
+| 1 | dwd_assistant_service_log | 助教服务流水 | assistant_service_id | dwd_assistant_service_log_ex | [主表](BD_manual_dwd_assistant_service_log.md) / [扩展表](BD_manual_dwd_assistant_service_log_ex.md) |
+| 2 | dwd_assistant_trash_event | 助教服务作废 | assistant_trash_event_id | dwd_assistant_trash_event_ex | [主表](BD_manual_dwd_assistant_trash_event.md) / [扩展表](BD_manual_dwd_assistant_trash_event_ex.md) |
+| 3 | dwd_groupbuy_redemption | 团购券核销 | redemption_id | dwd_groupbuy_redemption_ex | [主表](BD_manual_dwd_groupbuy_redemption.md) / [扩展表](BD_manual_dwd_groupbuy_redemption_ex.md) |
+| 4 | dwd_member_balance_change | 会员余额变动 | balance_change_id | dwd_member_balance_change_ex | [主表](BD_manual_dwd_member_balance_change.md) / [扩展表](BD_manual_dwd_member_balance_change_ex.md) |
+| 5 | dwd_payment | 支付流水 | payment_id | 无 | [主表](BD_manual_dwd_payment.md) |
+| 6 | dwd_platform_coupon_redemption | 平台券核销 | platform_coupon_redemption_id | dwd_platform_coupon_redemption_ex | [主表](BD_manual_dwd_platform_coupon_redemption.md) / [扩展表](BD_manual_dwd_platform_coupon_redemption_ex.md) |
+| 7 | dwd_recharge_order | 充值订单 | recharge_order_id | dwd_recharge_order_ex | [主表](BD_manual_dwd_recharge_order.md) / [扩展表](BD_manual_dwd_recharge_order_ex.md) |
+| 8 | dwd_refund | 退款流水 | refund_id | dwd_refund_ex | [主表](BD_manual_dwd_refund.md) / [扩展表](BD_manual_dwd_refund_ex.md) |
+| 9 | dwd_settlement_head | 结账单 | order_settle_id | dwd_settlement_head_ex | [主表](BD_manual_dwd_settlement_head.md) / [扩展表](BD_manual_dwd_settlement_head_ex.md) |
+| 10 | dwd_store_goods_sale | 商品销售流水 | store_goods_sale_id | dwd_store_goods_sale_ex | [主表](BD_manual_dwd_store_goods_sale.md) / [扩展表](BD_manual_dwd_store_goods_sale_ex.md) |
+| 11 | dwd_table_fee_adjust | 台费调整 | table_fee_adjust_id | dwd_table_fee_adjust_ex | [主表](BD_manual_dwd_table_fee_adjust.md) / [扩展表](BD_manual_dwd_table_fee_adjust_ex.md) |
+| 12 | dwd_table_fee_log | 台费计费流水 | table_fee_log_id | dwd_table_fee_log_ex | [主表](BD_manual_dwd_table_fee_log.md) / [扩展表](BD_manual_dwd_table_fee_log_ex.md) |
+
+---
+
+## SCD2 公共字段
+
+所有维度表都实现了 SCD2（缓慢变化维度类型2），包含以下公共字段：
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| scd2_start_time | TIMESTAMPTZ | 版本生效开始时间 |
+| scd2_end_time | TIMESTAMPTZ | 版本生效结束时间（NULL 或 9999-12-31 表示当前有效） |
+| scd2_is_current | INTEGER | 是否当前版本（1=是, 0=否） |
+| scd2_version | INTEGER | 版本号 |
+
+---
+
+## 最新值获取
+
+- 维度表（SCD2）：使用 scd2_is_current = 1 获取当前版本。
+- 事实表：无 SCD2 版本字段，按业务时间字段倒序获取最新记录（如 pay_time / create_time / update_time 等）。
+
+```sql
+-- 维度表取当前版本
+SELECT * FROM billiards_dwd.dim_member WHERE scd2_is_current = 1;
+-- 事实表取最新记录（示例：按 pay_time）
+SELECT * FROM billiards_dwd.dwd_payment ORDER BY pay_time DESC NULLS LAST LIMIT 1;
+```
+
+## 常见 ID 关联说明
+
+| ID 字段 | 关联表 | 说明 |
+|---------|--------|------|
+| tenant_id | - | 租户 ID，标识所属租户 |
+| site_id | dim_site | 门店 ID |
+| member_id | dim_member | 会员 ID（0=散客） |
+| tenant_member_card_id | dim_member_card_account | 会员卡账户 ID |
+| assistant_id | dim_assistant | 助教 ID |
+| table_id / site_table_id | dim_table | 台桌 ID |
+| tenant_goods_id | dim_tenant_goods | 租户商品 ID |
+| site_goods_id | dim_store_goods | 门店商品 ID |
+| order_settle_id | dwd_settlement_head | 结账单 ID |
+
+---
+
+## 表设计模式
+
+### 主表 + 扩展表模式
+
+大部分表采用"主表 + 扩展表"的设计模式：
+
+- **主表**：包含核心业务字段（如金额、状态、关键 ID）
+- **扩展表**：包含附属信息（如操作员、门店名称快照、各类详细字段）
+- 两表通过主键一对一关联
+
+### 枚举值说明
+
+文档中的枚举值格式为 `值(数量)=含义`，例如：
+
+- `1(100)=有效` 表示值为 1 的记录有 100 条，含义为"有效"
+- **[待确认]** 表示该值的含义无法从数据中确定
+
+---
+
+## 数据量统计
+
+| 表名 | 记录数 |
+|------|--------|
+| dwd_payment | 22,949 |
+| dwd_settlement_head | 22,475 |
+| dwd_table_fee_log | 18,386 |
+| dwd_store_goods_sale | 17,563 |
+| dwd_platform_coupon_redemption | 16,977 |
+| dwd_groupbuy_redemption | 11,420 |
+| dwd_member_balance_change | 4,745 |
+| dwd_table_fee_adjust | 2,849 |
+| dwd_assistant_service_log | 1,090 |
+| dwd_recharge_order | 455 |
+| dwd_assistant_trash_event | 98 |
+| dwd_refund | 45 |
+
+---
+
+## 注意事项
+
+1. **枚举值推断**：文档中的枚举值含义基于 500 行样本数据推断，可能不完整
+2. **[待确认] 标记**：不确定的字段含义或枚举值已明确标记
+3. **数据时效性**：文档基于 2026-01-28 的数据库快照生成
+4. **扩展表样本数据**：部分扩展表因日期解析问题无法获取样本数据