# BD_Manual — 飞球 ETL 数据库手册

> 本文档是 `docs/bd_manual/` 目录的导航索引，涵盖 ODS、DWD、DWS、ETL_Admin 四个数据层的表级文档、字段映射文档和变更记录。

## 目录结构

```
docs/bd_manual/
├── README.md                  ← 本文件（根索引）
├── ddl_compare_results.md     ← DDL 对比结果汇总
├── ODS/                       ← 操作数据存储层（billiards_ods schema）
│   ├── main/                  ←   表级文档
│   ├── mappings/              ←   API JSON → ODS 字段映射文档
│   └── changes/               ←   变更记录
├── DWD/                       ← 明细数据层（billiards_dwd schema）
│   ├── main/                  ←   表级文档
│   ├── Ex/                    ←   扩展表文档（SCD2 维度扩展等）
│   └── changes/               ←   变更记录
├── DWS/                       ← 数据服务层（billiards_dws schema）
│   ├── main/                  ←   表级文档
│   └── changes/               ←   变更记录
└── ETL_Admin/                 ← ETL 管理层（etl_admin schema）
    ├── main/                  ←   表级文档
    └── changes/               ←   变更记录
```

## 文档命名规范

| 文档类型 | 命名格式 | 示例 |
|----------|----------|------|
| 表级文档 | `BD_manual_{表名}.md` | `BD_manual_member_profiles.md` |
| 映射文档 | `mapping_{API端点名}_{ODS表名}.md` | `mapping_GetTenantMemberList_member_profiles.md` |
| 变更记录 | `{YYYYMMDD}_{变更简述}.md` 或 `{YYYY-MM-DD}_{变更简述}.md` | `2026-02-13_ddl_sync_ods.md` |

## ODS 层文档清单（billiards_ods）

### 表级文档（`ODS/main/`）— 共 23 份

| 序号 | 文件名 | 对应表 |
|------|--------|--------|
| 1 | `BD_manual_assistant_accounts_master.md` | assistant_accounts_master |
| 2 | `BD_manual_assistant_cancellation_records.md` | assistant_cancellation_records |
| 3 | `BD_manual_assistant_service_records.md` | assistant_service_records |
| 4 | `BD_manual_goods_stock_movements.md` | goods_stock_movements |
| 5 | `BD_manual_goods_stock_summary.md` | goods_stock_summary |
| 6 | `BD_manual_group_buy_packages.md` | group_buy_packages |
| 7 | `BD_manual_group_buy_redemption_records.md` | group_buy_redemption_records |
| 8 | `BD_manual_member_balance_changes.md` | member_balance_changes |
| 9 | `BD_manual_member_profiles.md` | member_profiles |
| 10 | `BD_manual_member_stored_value_cards.md` | member_stored_value_cards |
| 11 | `BD_manual_payment_transactions.md` | payment_transactions |
| 12 | `BD_manual_platform_coupon_redemption_records.md` | platform_coupon_redemption_records |
| 13 | `BD_manual_recharge_settlements.md` | recharge_settlements |
| 14 | `BD_manual_refund_transactions.md` | refund_transactions |
| 15 | `BD_manual_settlement_records.md` | settlement_records |
| 16 | `BD_manual_settlement_ticket_details.md` | settlement_ticket_details |
| 17 | `BD_manual_site_tables_master.md` | site_tables_master |
| 18 | `BD_manual_stock_goods_category_tree.md` | stock_goods_category_tree |
| 19 | `BD_manual_store_goods_master.md` | store_goods_master |
| 20 | `BD_manual_store_goods_sales_records.md` | store_goods_sales_records |
| 21 | `BD_manual_table_fee_discount_records.md` | table_fee_discount_records |
| 22 | `BD_manual_table_fee_transactions.md` | table_fee_transactions |
| 23 | `BD_manual_tenant_goods_master.md` | tenant_goods_master |

### API→ODS 字段映射文档（`ODS/mappings/`）— 共 23 份

| 序号 | 文件名 | API 端点 → ODS 表 |
|------|--------|-------------------|
| 1 | `mapping_GetAbolitionAssistant_assistant_cancellation_records.md` | GetAbolitionAssistant → assistant_cancellation_records |
| 2 | `mapping_GetAllOrderSettleList_settlement_records.md` | GetAllOrderSettleList → settlement_records |
| 3 | `mapping_GetGoodsInventoryList_store_goods_master.md` | GetGoodsInventoryList → store_goods_master |
| 4 | `mapping_GetGoodsSalesList_store_goods_sales_records.md` | GetGoodsSalesList → store_goods_sales_records |
| 5 | `mapping_GetGoodsStockReport_goods_stock_summary.md` | GetGoodsStockReport → goods_stock_summary |
| 6 | `mapping_GetMemberCardBalanceChange_member_balance_changes.md` | GetMemberCardBalanceChange → member_balance_changes |
| 7 | `mapping_GetOfflineCouponConsumePageList_platform_coupon_redemption_records.md` | GetOfflineCouponConsumePageList → platform_coupon_redemption_records |
| 8 | `mapping_GetOrderAssistantDetails_assistant_service_records.md` | GetOrderAssistantDetails → assistant_service_records |
| 9 | `mapping_GetOrderSettleTicketNew_settlement_ticket_details.md` | GetOrderSettleTicketNew → settlement_ticket_details |
| 10 | `mapping_GetPayLogListPage_payment_transactions.md` | GetPayLogListPage → payment_transactions |
| 11 | `mapping_GetRechargeSettleList_recharge_settlements.md` | GetRechargeSettleList → recharge_settlements |
| 12 | `mapping_GetRefundPayLogList_refund_transactions.md` | GetRefundPayLogList → refund_transactions |
| 13 | `mapping_GetSiteTableOrderDetails_table_fee_transactions.md` | GetSiteTableOrderDetails → table_fee_transactions |
| 14 | `mapping_GetSiteTables_site_tables_master.md` | GetSiteTables → site_tables_master |
| 15 | `mapping_GetSiteTableUseDetails_group_buy_redemption_records.md` | GetSiteTableUseDetails → group_buy_redemption_records |
| 16 | `mapping_GetTaiFeeAdjustList_table_fee_discount_records.md` | GetTaiFeeAdjustList → table_fee_discount_records |
| 17 | `mapping_GetTenantMemberCardList_member_stored_value_cards.md` | GetTenantMemberCardList → member_stored_value_cards |
| 18 | `mapping_GetTenantMemberList_member_profiles.md` | GetTenantMemberList → member_profiles |
| 19 | `mapping_QueryGoodsOutboundReceipt_goods_stock_movements.md` | QueryGoodsOutboundReceipt → goods_stock_movements |
| 20 | `mapping_QueryPackageCouponList_group_buy_packages.md` | QueryPackageCouponList → group_buy_packages |
| 21 | `mapping_QueryPrimarySecondaryCategory_stock_goods_category_tree.md` | QueryPrimarySecondaryCategory → stock_goods_category_tree |
| 22 | `mapping_QueryTenantGoods_tenant_goods_master.md` | QueryTenantGoods → tenant_goods_master |
| 23 | `mapping_SearchAssistantInfo_assistant_accounts_master.md` | SearchAssistantInfo → assistant_accounts_master |

### 变更记录（`ODS/changes/`）

| 文件名 | 说明 |
|--------|------|
| `2026-02-13_ddl_sync_ods.md` | DDL 对比同步 — ODS 层 |
| `20260213_align_ods_with_api.md` | ODS 表结构与 API 对齐 |
| `20260214_drop_ods_option_name_able_site_transfer.md` | 移除 ODS 冗余字段/表 |
| `20260214_drop_ods_settlelist.md` | 移除 ODS settle_list 表 |

## DWD 层文档清单（billiards_dwd）

### 表级文档（`DWD/main/`）— 共 22 份

| 序号 | 文件名 | 对应表 |
|------|--------|--------|
| 1 | `BD_manual_billiards_dwd.md` | billiards_dwd（层级概览） |
| 2 | `BD_manual_dim_assistant.md` | dim_assistant |
| 3 | `BD_manual_dim_goods_category.md` | dim_goods_category |
| 4 | `BD_manual_dim_groupbuy_package.md` | dim_groupbuy_package |
| 5 | `BD_manual_dim_member.md` | dim_member |
| 6 | `BD_manual_dim_member_card_account.md` | dim_member_card_account |
| 7 | `BD_manual_dim_site.md` | dim_site |
| 8 | `BD_manual_dim_store_goods.md` | dim_store_goods |
| 9 | `BD_manual_dim_table.md` | dim_table |
| 10 | `BD_manual_dim_tenant_goods.md` | dim_tenant_goods |
| 11 | `BD_manual_dwd_assistant_service_log.md` | dwd_assistant_service_log |
| 12 | `BD_manual_dwd_assistant_trash_event.md` | dwd_assistant_trash_event |
| 13 | `BD_manual_dwd_groupbuy_redemption.md` | dwd_groupbuy_redemption |
| 14 | `BD_manual_dwd_member_balance_change.md` | dwd_member_balance_change |
| 15 | `BD_manual_dwd_payment.md` | dwd_payment |
| 16 | `BD_manual_dwd_platform_coupon_redemption.md` | dwd_platform_coupon_redemption |
| 17 | `BD_manual_dwd_recharge_order.md` | dwd_recharge_order |
| 18 | `BD_manual_dwd_refund.md` | dwd_refund |
| 19 | `BD_manual_dwd_settlement_head.md` | dwd_settlement_head |
| 20 | `BD_manual_dwd_store_goods_sale.md` | dwd_store_goods_sale |
| 21 | `BD_manual_dwd_table_fee_adjust.md` | dwd_table_fee_adjust |
| 22 | `BD_manual_dwd_table_fee_log.md` | dwd_table_fee_log |

### 扩展表文档（`DWD/Ex/`）— 共 19 份

| 序号 | 文件名 | 对应扩展表 |
|------|--------|------------|
| 1 | `BD_manual_dim_assistant_ex.md` | dim_assistant_ex |
| 2 | `BD_manual_dim_groupbuy_package_ex.md` | dim_groupbuy_package_ex |
| 3 | `BD_manual_dim_member_card_account_ex.md` | dim_member_card_account_ex |
| 4 | `BD_manual_dim_member_ex.md` | dim_member_ex |
| 5 | `BD_manual_dim_site_ex.md` | dim_site_ex |
| 6 | `BD_manual_dim_store_goods_ex.md` | dim_store_goods_ex |
| 7 | `BD_manual_dim_table_ex.md` | dim_table_ex |
| 8 | `BD_manual_dim_tenant_goods_ex.md` | dim_tenant_goods_ex |
| 9 | `BD_manual_dwd_assistant_service_log_ex.md` | dwd_assistant_service_log_ex |
| 10 | `BD_manual_dwd_assistant_trash_event_ex.md` | dwd_assistant_trash_event_ex |
| 11 | `BD_manual_dwd_groupbuy_redemption_ex.md` | dwd_groupbuy_redemption_ex |
| 12 | `BD_manual_dwd_member_balance_change_ex.md` | dwd_member_balance_change_ex |
| 13 | `BD_manual_dwd_platform_coupon_redemption_ex.md` | dwd_platform_coupon_redemption_ex |
| 14 | `BD_manual_dwd_recharge_order_ex.md` | dwd_recharge_order_ex |
| 15 | `BD_manual_dwd_refund_ex.md` | dwd_refund_ex |
| 16 | `BD_manual_dwd_settlement_head_ex.md` | dwd_settlement_head_ex |
| 17 | `BD_manual_dwd_store_goods_sale_ex.md` | dwd_store_goods_sale_ex |
| 18 | `BD_manual_dwd_table_fee_adjust_ex.md` | dwd_table_fee_adjust_ex |
| 19 | `BD_manual_dwd_table_fee_log_ex.md` | dwd_table_fee_log_ex |

### 变更记录（`DWD/changes/`）

| 文件名 | 说明 |
|--------|------|
| `2026-02-13_ddl_sync_dwd.md` | DDL 对比同步 — DWD 层 |
| `20260214_drop_dwd_settle_list.md` | 移除 DWD settle_list 表 |

## DWS 层文档清单（billiards_dws）

### 表级文档（`DWS/main/`）— 共 29 份

| 序号 | 文件名 | 对应表 |
|------|--------|--------|
| 1 | `BD_manual_cfg_area_category.md` | cfg_area_category |
| 2 | `BD_manual_cfg_assistant_level_price.md` | cfg_assistant_level_price |
| 3 | `BD_manual_cfg_bonus_rules.md` | cfg_bonus_rules |
| 4 | `BD_manual_cfg_index_parameters.md` | cfg_index_parameters |
| 5 | `BD_manual_cfg_performance_tier.md` | cfg_performance_tier |
| 6 | `BD_manual_cfg_skill_type.md` | cfg_skill_type |
| 7 | `BD_manual_dws_assistant_customer_stats.md` | dws_assistant_customer_stats |
| 8 | `BD_manual_dws_assistant_daily_detail.md` | dws_assistant_daily_detail |
| 9 | `BD_manual_dws_assistant_finance_analysis.md` | dws_assistant_finance_analysis |
| 10 | `BD_manual_dws_assistant_monthly_summary.md` | dws_assistant_monthly_summary |
| 11 | `BD_manual_dws_assistant_recharge_commission.md` | dws_assistant_recharge_commission |
| 12 | `BD_manual_dws_assistant_salary_calc.md` | dws_assistant_salary_calc |
| 13 | `BD_manual_dws_finance_daily_summary.md` | dws_finance_daily_summary |
| 14 | `BD_manual_dws_finance_discount_detail.md` | dws_finance_discount_detail |
| 15 | `BD_manual_dws_finance_expense_summary.md` | dws_finance_expense_summary |
| 16 | `BD_manual_dws_finance_income_structure.md` | dws_finance_income_structure |
| 17 | `BD_manual_dws_finance_recharge_summary.md` | dws_finance_recharge_summary |
| 18 | `BD_manual_dws_index_percentile_history.md` | dws_index_percentile_history |
| 19 | `BD_manual_dws_member_assistant_intimacy.md` | dws_member_assistant_intimacy |
| 20 | `BD_manual_dws_member_assistant_relation_index.md` | dws_member_assistant_relation_index |
| 21 | `BD_manual_dws_member_consumption_summary.md` | dws_member_consumption_summary |
| 22 | `BD_manual_dws_member_newconv_index.md` | dws_member_newconv_index |
| 23 | `BD_manual_dws_member_visit_detail.md` | dws_member_visit_detail |
| 24 | `BD_manual_dws_member_winback_index.md` | dws_member_winback_index |
| 25 | `BD_manual_dws_ml_manual_order_alloc.md` | dws_ml_manual_order_alloc |
| 26 | `BD_manual_dws_ml_manual_order_source.md` | dws_ml_manual_order_source |
| 27 | `BD_manual_dws_order_summary.md` | dws_order_summary |
| 28 | `BD_manual_dws_platform_settlement.md` | dws_platform_settlement |
| 29 | `BD_manual_v_member_recall_priority.md` | v_member_recall_priority |

### 变更记录（`DWS/changes/`）

| 文件名 | 说明 |
|--------|------|
| `2026-02-13_ddl_sync_dws.md` | DDL 对比同步 — DWS 层 |

## ETL_Admin 层文档清单（etl_admin）

### 表级文档（`ETL_Admin/main/`）— 共 3 份

| 序号 | 文件名 | 对应表 |
|------|--------|--------|
| 1 | `BD_manual_etl_cursor.md` | etl_cursor |
| 2 | `BD_manual_etl_run.md` | etl_run |
| 3 | `BD_manual_etl_task.md` | etl_task |

### 变更记录（`ETL_Admin/changes/`）

暂无变更记录。

## 相关资源

| 资源 | 路径 | 说明 |
|------|------|------|
| ODS 数据字典 | `docs/dictionary/ods_tables_dictionary.md` | ODS 层所有表的概览汇总 |
| DDL 对比结果 | `docs/bd_manual/ddl_compare_results.md` | DDL 文件与数据库实际状态的对比报告 |
| DDL 文件 — ODS | `database/schema_ODS_doc.sql` | ODS 层表结构定义 |
| DDL 文件 — DWD | `database/schema_dwd_doc.sql` | DWD 层表结构定义 |
| DDL 文件 — DWS | `database/schema_dws.sql` | DWS 层表结构定义 |
| DDL 文件 — ETL_Admin | `database/schema_etl_admin.sql` | ETL_Admin 层表结构定义 |
| API 端点文档 | `docs/api-reference/endpoints/` | 上游 SaaS API 端点说明 |
| DDL 对比脚本 | `scripts/compare_ddl_db.py` | DDL 与数据库实际状态对比工具 |
| 文档验证脚本 | `scripts/validate_bd_manual.py` | BD_Manual 文档覆盖率和格式验证 |