root/feiqiu-ETL
Template
1
0
Fork 0
Code Pull Requests Packages Releases Wiki Activity

Updata2

Browse Source
This commit is contained in:
Neo
2026-02-04 21:39:01 +08:00
parent ee773a9b52
commit a3f4d04335
148 changed files with 31455 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
etl_billiards/.env
View File

@@ -32,7 +32,7 @@ SCHEMA_ETL=etl_admin
# API 配置
# ------------------------------------------------------------------------------
API_BASE=https://pc.ficoo.vip/apiprod/admin/v1/
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6IktlbTVsdHRqZ2tSUExOcVA2ajhNakdQYnFrNW5mRzBQNzRvMHE0b295VVE9IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzIvOCDkuIvljYg2OjU3OjA1IiwibmVlZENoZWNrVG9rZW4iOiJmYWxzZSIsImV4cCI6MTc3MDU0ODIyNSwiaXNzIjoidGVzdCIsImF1ZCI6IlVzZXIifQ.wJlm7pTqUzp769nUGdxx0e1bVMy4x9Prp9U_UMWQvlk
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6IjlES1lWcEVkYWw1bEc5cTMrdFptMkJXeTlyMkVMeEY5MHZuUWRyRnNYVFU9IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzIvOSDkuIrljYgyOjQzOjU0IiwibmVlZENoZWNrVG9rZW4iOiJmYWxzZSIsImV4cCI6MTc3MDU3NjIzNCwiaXNzIjoidGVzdCIsImF1ZCI6IlVzZXIifQ._1gnWcJHw8O26pcfiT1x8tgQRGn3g56vv2IZP8shgGU
# API 请求超时（秒）
API_TIMEOUT=20

59
etl_billiards/database/schema_ODS_doc.sql
View File

@@ -19,6 +19,11 @@ CREATE TABLE IF NOT EXISTS billiards_ods.member_profiles (
status INT,
user_status INT,
create_time TIMESTAMP,
pay_money_sum NUMERIC(18,2),
person_tenant_org_id BIGINT,
person_tenant_org_name TEXT,
recharge_money_sum NUMERIC(18,2),
register_source TEXT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -75,6 +80,9 @@ CREATE TABLE IF NOT EXISTS billiards_ods.member_balance_changes (
operator_name TEXT,
is_delete INT,
create_time TIMESTAMP,
principal_after NUMERIC(18,2),
principal_before NUMERIC(18,2),
principal_data TEXT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -185,6 +193,13 @@ CREATE TABLE IF NOT EXISTS billiards_ods.member_stored_value_cards (
tenantName TEXT,
pdAssisnatLevel TEXT,
cxAssisnatLevel TEXT,
able_share_member_discount BOOLEAN,
electricity_deduct_radio NUMERIC(18,4),
electricity_discount NUMERIC(18,4),
electricitycarddeduct BOOLEAN,
member_grade BIGINT,
principal_balance NUMERIC(18,2),
rechargefreezebalance NUMERIC(18,2),
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -331,6 +346,12 @@ CREATE TABLE IF NOT EXISTS billiards_ods.recharge_settlements (
isfirst INT,
rechargecardamount NUMERIC(18,2),
giftcardamount NUMERIC(18,2),
electricityadjustmoney NUMERIC(18,2),
electricitymoney NUMERIC(18,2),
mervousalesamount NUMERIC(18,2),
plcouponsaleamount NUMERIC(18,2),
realelectricitymoney NUMERIC(18,2),
settlelist JSONB,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -469,6 +490,12 @@ CREATE TABLE IF NOT EXISTS billiards_ods.settlement_records (
isfirst INT,
rechargecardamount NUMERIC(18,2),
giftcardamount NUMERIC(18,2),
electricityadjustmoney NUMERIC(18,2),
electricitymoney NUMERIC(18,2),
mervousalesamount NUMERIC(18,2),
plcouponsaleamount NUMERIC(18,2),
realelectricitymoney NUMERIC(18,2),
settlelist JSONB,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -559,6 +586,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.assistant_cancellation_records (
tableName TEXT,
trashReason TEXT,
createTime TIMESTAMP,
tenant_id BIGINT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -792,6 +820,8 @@ CREATE TABLE IF NOT EXISTS billiards_ods.assistant_service_records (
get_grade_times INT,
is_not_responding INT,
is_confirm INT,
assistantteamname TEXT,
real_service_money NUMERIC(18,2),
payload JSONB NOT NULL,
content_hash TEXT NOT NULL,
source_file TEXT,
@@ -897,6 +927,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.site_tables_master (
table_status INT,
temporary_light_second INT,
virtual_table INT,
order_id BIGINT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -957,6 +988,14 @@ CREATE TABLE IF NOT EXISTS billiards_ods.table_fee_discount_records (
order_trade_no TEXT,
is_delete INT,
create_time TIMESTAMP,
area_type_id BIGINT,
charge_free BOOLEAN,
site_table_area_id BIGINT,
site_table_area_name TEXT,
sitename TEXT,
table_name TEXT,
table_price NUMERIC(18,2),
tenant_name TEXT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -1032,6 +1071,9 @@ CREATE TABLE IF NOT EXISTS billiards_ods.table_fee_transactions (
salesman_org_id BIGINT,
salesman_user_id BIGINT,
create_time TIMESTAMP,
activity_discount_amount NUMERIC(18,2),
order_consumption_type INT,
real_service_money NUMERIC(18,2),
payload JSONB NOT NULL,
content_hash TEXT NOT NULL,
source_file TEXT,
@@ -1234,6 +1276,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.payment_transactions (
create_time TIMESTAMP,
payment_method INT,
online_pay_channel INT,
tenant_id BIGINT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -1440,6 +1483,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.tenant_goods_master (
remark_name TEXT,
create_time TIMESTAMP,
update_time TIMESTAMP,
not_sale BOOLEAN,
payload JSONB NOT NULL,
content_hash TEXT NOT NULL,
source_file TEXT,
@@ -1522,6 +1566,9 @@ CREATE TABLE IF NOT EXISTS billiards_ods.group_buy_packages (
area_tag_type INT,
creator_name TEXT,
create_time TIMESTAMP,
is_first_limit BOOLEAN,
sort INT,
tenantcouponsaleorderitemid BIGINT,
content_hash TEXT NOT NULL,
source_file TEXT,
source_endpoint TEXT,
@@ -1616,6 +1663,15 @@ CREATE TABLE IF NOT EXISTS billiards_ods.group_buy_redemption_records (
is_single_order INT,
is_delete INT,
create_time TIMESTAMP,
assistant_service_share_money NUMERIC(18,2),
assistant_share_money NUMERIC(18,2),
coupon_sale_id BIGINT,
good_service_share_money NUMERIC(18,2),
goods_share_money NUMERIC(18,2),
member_discount_money NUMERIC(18,2),
recharge_share_money NUMERIC(18,2),
table_service_share_money NUMERIC(18,2),
table_share_money NUMERIC(18,2),
payload JSONB NOT NULL,
content_hash TEXT NOT NULL,
source_file TEXT,
@@ -1812,6 +1868,8 @@ CREATE TABLE IF NOT EXISTS billiards_ods.store_goods_master (
goods_cover TEXT,
create_time TIMESTAMP,
update_time TIMESTAMP,
commodity_code TEXT,
not_sale INTEGER,
payload JSONB NOT NULL,
content_hash TEXT NOT NULL,
source_file TEXT,
@@ -1923,6 +1981,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.store_goods_sales_records (
tenant_goods_business_id BIGINT,
tenant_goods_category_id BIGINT,
create_time TIMESTAMP,
coupon_share_money NUMERIC(18,2),
payload JSONB NOT NULL,
content_hash TEXT NOT NULL,
source_file TEXT,

91
etl_billiards/database/schema_dwd_doc.sql
View File

@@ -107,7 +107,7 @@ COMMENT ON COLUMN billiards_dwd.dim_site.scd2_is_current IS '【说明】SCD2
COMMENT ON COLUMN billiards_dwd.dim_site.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】table_fee_transactions - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_site_Ex (
CREATE TABLE IF NOT EXISTS dim_site_ex (
site_id BIGINT,
avatar TEXT,
address TEXT,
@@ -172,6 +172,7 @@ CREATE TABLE IF NOT EXISTS dim_table (
site_table_area_name TEXT,
tenant_table_area_id BIGINT,
table_price NUMERIC(18,2),
order_id BIGINT,
SCD2_start_time TIMESTAMPTZ DEFAULT now(),
SCD2_end_time TIMESTAMPTZ DEFAULT '9999-12-31',
SCD2_is_current INT DEFAULT 1,
@@ -193,7 +194,7 @@ COMMENT ON COLUMN billiards_dwd.dim_table.scd2_is_current IS '【说明】SCD2
COMMENT ON COLUMN billiards_dwd.dim_table.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】site_tables_master - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_table_Ex (
CREATE TABLE IF NOT EXISTS dim_table_ex (
table_id BIGINT,
show_status INTEGER,
is_online_reservation INTEGER,
@@ -265,7 +266,7 @@ COMMENT ON COLUMN billiards_dwd.dim_assistant.scd2_is_current IS '【说明】SC
COMMENT ON COLUMN billiards_dwd.dim_assistant.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】assistant_accounts_master - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_assistant_Ex (
CREATE TABLE IF NOT EXISTS dim_assistant_ex (
assistant_id BIGINT,
gender INTEGER,
birth_date TIMESTAMPTZ,
@@ -379,6 +380,8 @@ CREATE TABLE IF NOT EXISTS dim_member (
member_card_grade_name TEXT,
create_time TIMESTAMPTZ,
update_time TIMESTAMPTZ,
pay_money_sum NUMERIC(18,2),
recharge_money_sum NUMERIC(18,2),
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -403,7 +406,7 @@ COMMENT ON COLUMN billiards_dwd.dim_member.scd2_is_current IS '【说明】SCD2
COMMENT ON COLUMN billiards_dwd.dim_member.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】member_profiles - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_member_Ex (
CREATE TABLE IF NOT EXISTS dim_member_ex (
member_id BIGINT,
referrer_member_id BIGINT,
point NUMERIC(18,2),
@@ -411,6 +414,9 @@ CREATE TABLE IF NOT EXISTS dim_member_Ex (
growth_value NUMERIC(18,2),
user_status INTEGER,
status INTEGER,
person_tenant_org_id BIGINT,
person_tenant_org_name TEXT,
register_source TEXT,
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -450,6 +456,8 @@ CREATE TABLE IF NOT EXISTS dim_member_card_account (
last_consume_time TIMESTAMPTZ,
status INTEGER,
is_delete INTEGER,
principal_balance NUMERIC(18,2),
member_grade BIGINT,
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -481,7 +489,7 @@ COMMENT ON COLUMN billiards_dwd.dim_member_card_account.scd2_is_current IS '【
COMMENT ON COLUMN billiards_dwd.dim_member_card_account.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】member_stored_value_cards - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_member_card_account_Ex (
CREATE TABLE IF NOT EXISTS dim_member_card_account_ex (
member_card_id BIGINT,
site_name TEXT,
tenant_name VARCHAR(64),
@@ -534,6 +542,11 @@ CREATE TABLE IF NOT EXISTS dim_member_card_account_Ex (
goodsCategoryId TEXT,
pdAssisnatLevel TEXT,
cxAssisnatLevel TEXT,
able_share_member_discount BOOLEAN,
electricity_deduct_radio NUMERIC(18,4),
electricity_discount NUMERIC(18,4),
electricity_card_deduct BOOLEAN,
recharge_freeze_balance NUMERIC(18,2),
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -615,6 +628,7 @@ CREATE TABLE IF NOT EXISTS dim_tenant_goods (
create_time TIMESTAMPTZ,
update_time TIMESTAMPTZ,
is_delete INTEGER,
not_sale INTEGER,
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -643,7 +657,7 @@ COMMENT ON COLUMN billiards_dwd.dim_tenant_goods.scd2_is_current IS '【说明
COMMENT ON COLUMN billiards_dwd.dim_tenant_goods.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】tenant_goods_master - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_tenant_goods_Ex (
CREATE TABLE IF NOT EXISTS dim_tenant_goods_ex (
tenant_goods_id BIGINT,
remark_name VARCHAR(128),
pinyin_initial VARCHAR(128),
@@ -715,6 +729,8 @@ CREATE TABLE IF NOT EXISTS dim_store_goods (
enable_status INTEGER,
send_state INTEGER,
is_delete INTEGER,
commodity_code TEXT,
not_sale INTEGER,
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -749,7 +765,7 @@ COMMENT ON COLUMN billiards_dwd.dim_store_goods.scd2_is_current IS '【说明】
COMMENT ON COLUMN billiards_dwd.dim_store_goods.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】store_goods_master - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_store_goods_Ex (
CREATE TABLE IF NOT EXISTS dim_store_goods_ex (
site_goods_id BIGINT,
site_name TEXT,
unit TEXT,
@@ -872,6 +888,8 @@ CREATE TABLE IF NOT EXISTS dim_groupbuy_package (
create_time TIMESTAMPTZ,
tenant_table_area_id_list VARCHAR(512),
card_type_ids VARCHAR(255),
sort INTEGER,
is_first_limit BOOLEAN,
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -902,7 +920,7 @@ COMMENT ON COLUMN billiards_dwd.dim_groupbuy_package.scd2_is_current IS '【说
COMMENT ON COLUMN billiards_dwd.dim_groupbuy_package.scd2_version IS '【说明】SCD2 版本号（自增），用于与时间段一起避免版本重叠。 【示例】1（SCD2 版本号（自增），用于与时间段一起避免版本重叠）。 【ODS来源】group_buy_packages - 无（DWD慢变元数据）。 【JSON字段】无 - DWD慢变元数据 - 无。';
CREATE TABLE IF NOT EXISTS dim_groupbuy_package_Ex (
CREATE TABLE IF NOT EXISTS dim_groupbuy_package_ex (
groupbuy_package_id BIGINT,
site_name VARCHAR(100),
usable_count INTEGER,
@@ -923,6 +941,7 @@ CREATE TABLE IF NOT EXISTS dim_groupbuy_package_Ex (
effective_status INTEGER,
max_selectable_categories INTEGER,
creator_name VARCHAR(100),
tenant_coupon_sale_order_item_id BIGINT,
SCD2_start_time TIMESTAMPTZ,
SCD2_end_time TIMESTAMPTZ,
SCD2_is_current INT,
@@ -990,6 +1009,11 @@ CREATE TABLE IF NOT EXISTS dwd_settlement_head (
coupon_amount NUMERIC(18,2),
rounding_amount NUMERIC(18,2),
point_amount NUMERIC(18,2),
electricity_money NUMERIC(18,2),
real_electricity_money NUMERIC(18,2),
electricity_adjust_money NUMERIC(18,2),
pl_coupon_sale_amount NUMERIC(18,2),
mervou_sales_amount NUMERIC(18,2),
PRIMARY KEY (order_settle_id)
);
@@ -1028,7 +1052,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_settlement_head.rounding_amount IS '【说
COMMENT ON COLUMN billiards_dwd.dwd_settlement_head.point_amount IS '【说明】金额字段，用于计费/结算/核算等金额计算。 【示例】NULL（金额字段，用于计费/结算/核算等金额计算）。 【ODS来源】settlement_records - pointamount。 【JSON字段】settlement_records.json - $ - pointamount。';
CREATE TABLE IF NOT EXISTS dwd_settlement_head_Ex (
CREATE TABLE IF NOT EXISTS dwd_settlement_head_ex (
order_settle_id BIGINT,
serial_number INTEGER,
settle_status INTEGER,
@@ -1059,6 +1083,7 @@ CREATE TABLE IF NOT EXISTS dwd_settlement_head_Ex (
order_remark VARCHAR(255),
operator_id BIGINT,
salesman_user_id BIGINT,
settle_list JSONB,
PRIMARY KEY (order_settle_id)
);
@@ -1123,6 +1148,8 @@ CREATE TABLE IF NOT EXISTS dwd_table_fee_log (
ledger_status INTEGER,
is_single_order INTEGER,
is_delete INTEGER,
activity_discount_amount NUMERIC(18,2),
real_service_money NUMERIC(18,2),
PRIMARY KEY (table_fee_log_id)
);
@@ -1156,7 +1183,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_table_fee_log.is_single_order IS '【说明
COMMENT ON COLUMN billiards_dwd.dwd_table_fee_log.is_delete IS '【说明】布尔/开关字段，用于表示是否/可用性等业务开关。 【示例】0（布尔/开关字段，用于表示是否/可用性等业务开关）。 【ODS来源】table_fee_transactions - is_delete。 【JSON字段】table_fee_transactions.json - data.siteTableUseDetailsList - is_delete。';
CREATE TABLE IF NOT EXISTS dwd_table_fee_log_Ex (
CREATE TABLE IF NOT EXISTS dwd_table_fee_log_ex (
table_fee_log_id BIGINT,
operator_name VARCHAR(64),
salesman_name VARCHAR(64),
@@ -1169,6 +1196,7 @@ CREATE TABLE IF NOT EXISTS dwd_table_fee_log_Ex (
operator_id BIGINT,
salesman_user_id BIGINT,
salesman_org_id BIGINT,
order_consumption_type INTEGER,
PRIMARY KEY (table_fee_log_id)
);
@@ -1201,6 +1229,9 @@ CREATE TABLE IF NOT EXISTS dwd_table_fee_adjust (
ledger_status INTEGER,
is_delete INTEGER,
adjust_time TIMESTAMPTZ,
table_name TEXT,
table_price NUMERIC(18,2),
charge_free BOOLEAN,
PRIMARY KEY (table_fee_adjust_id)
);
@@ -1220,7 +1251,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_table_fee_adjust.is_delete IS '【说明】
COMMENT ON COLUMN billiards_dwd.dwd_table_fee_adjust.adjust_time IS '【说明】时间/日期字段，用于记录业务时间与统计口径对齐。 【示例】2025-11-09 23:25:11（时间/日期字段，用于记录业务时间与统计口径对齐）。 【ODS来源】table_fee_discount_records - create_time。 【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - create_time。';
CREATE TABLE IF NOT EXISTS dwd_table_fee_adjust_Ex (
CREATE TABLE IF NOT EXISTS dwd_table_fee_adjust_ex (
table_fee_adjust_id BIGINT,
adjust_type INTEGER,
ledger_count INTEGER,
@@ -1229,6 +1260,11 @@ CREATE TABLE IF NOT EXISTS dwd_table_fee_adjust_Ex (
operator_name VARCHAR(64),
applicant_id BIGINT,
operator_id BIGINT,
area_type_id BIGINT,
site_table_area_id BIGINT,
site_table_area_name TEXT,
site_name TEXT,
tenant_name TEXT,
PRIMARY KEY (table_fee_adjust_id)
);
@@ -1267,6 +1303,7 @@ CREATE TABLE IF NOT EXISTS dwd_store_goods_sale (
ledger_status INTEGER,
is_delete INTEGER,
create_time TIMESTAMPTZ,
coupon_share_money NUMERIC(18,2),
PRIMARY KEY (store_goods_sale_id)
);
@@ -1296,7 +1333,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_store_goods_sale.is_delete IS '【说明】
COMMENT ON COLUMN billiards_dwd.dwd_store_goods_sale.create_time IS '【说明】时间/日期字段，用于记录业务时间与统计口径对齐。 【示例】2025-11-09 23:35:57（时间/日期字段，用于记录业务时间与统计口径对齐）。 【ODS来源】store_goods_sales_records - create_time。 【JSON字段】store_goods_sales_records.json - data.orderGoodsLedgers - create_time。';
CREATE TABLE IF NOT EXISTS dwd_store_goods_sale_Ex (
CREATE TABLE IF NOT EXISTS dwd_store_goods_sale_ex (
store_goods_sale_id BIGINT,
legacy_order_goods_id BIGINT,
site_name TEXT,
@@ -1392,6 +1429,7 @@ CREATE TABLE IF NOT EXISTS dwd_assistant_service_log (
start_use_time TIMESTAMPTZ,
last_use_time TIMESTAMPTZ,
is_delete INTEGER,
real_service_money NUMERIC(18,2),
PRIMARY KEY (assistant_service_id)
);
@@ -1430,7 +1468,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_assistant_service_log.last_use_time IS '【
COMMENT ON COLUMN billiards_dwd.dwd_assistant_service_log.is_delete IS '【说明】布尔/开关字段，用于表示是否/可用性等业务开关。 【示例】0（布尔/开关字段，用于表示是否/可用性等业务开关）。 【ODS来源】assistant_service_records - is_delete。 【JSON字段】assistant_service_records.json - data.orderAssistantDetails - is_delete。';
CREATE TABLE IF NOT EXISTS dwd_assistant_service_log_Ex (
CREATE TABLE IF NOT EXISTS dwd_assistant_service_log_ex (
assistant_service_id BIGINT,
table_name VARCHAR(64),
assistant_name VARCHAR(64),
@@ -1461,6 +1499,7 @@ CREATE TABLE IF NOT EXISTS dwd_assistant_service_log_Ex (
get_grade_times INTEGER,
grade_status INTEGER,
composite_grade_time TIMESTAMPTZ,
assistant_team_name TEXT,
PRIMARY KEY (assistant_service_id)
);
@@ -1508,6 +1547,7 @@ CREATE TABLE IF NOT EXISTS dwd_assistant_trash_event (
abolish_amount NUMERIC(18,2),
trash_reason VARCHAR(255),
create_time TIMESTAMPTZ,
tenant_id BIGINT,
PRIMARY KEY (assistant_trash_event_id)
);
@@ -1524,7 +1564,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_assistant_trash_event.trash_reason IS '【
COMMENT ON COLUMN billiards_dwd.dwd_assistant_trash_event.create_time IS '【说明】时间/日期字段，用于记录业务时间与统计口径对齐。 【示例】2025-11-09 19:23:29（时间/日期字段，用于记录业务时间与统计口径对齐）。 【ODS来源】assistant_cancellation_records - createTime。 【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - createTime。';
CREATE TABLE IF NOT EXISTS dwd_assistant_trash_event_Ex (
CREATE TABLE IF NOT EXISTS dwd_assistant_trash_event_ex (
assistant_trash_event_id BIGINT,
table_name VARCHAR(64),
table_area_name VARCHAR(64),
@@ -1557,6 +1597,8 @@ CREATE TABLE IF NOT EXISTS dwd_member_balance_change (
change_time TIMESTAMPTZ,
is_delete INTEGER,
remark VARCHAR(255),
principal_before NUMERIC(18,2),
principal_after NUMERIC(18,2),
PRIMARY KEY (balance_change_id)
);
@@ -1582,13 +1624,14 @@ COMMENT ON COLUMN billiards_dwd.dwd_member_balance_change.is_delete IS '【说
COMMENT ON COLUMN billiards_dwd.dwd_member_balance_change.remark IS '【说明】明细字段，用于记录事实取值。 【示例】充值退款（明细字段，用于记录事实取值）。 【ODS来源】member_balance_changes - remark。 【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - remark。';
CREATE TABLE IF NOT EXISTS dwd_member_balance_change_EX (
CREATE TABLE IF NOT EXISTS dwd_member_balance_change_ex (
balance_change_id BIGINT,
pay_site_name VARCHAR(64),
register_site_name VARCHAR(64),
refund_amount NUMERIC(18,2),
operator_id BIGINT,
operator_name VARCHAR(64),
principal_data TEXT,
PRIMARY KEY (balance_change_id)
);
@@ -1625,6 +1668,8 @@ CREATE TABLE IF NOT EXISTS dwd_groupbuy_redemption (
is_delete INTEGER,
ledger_name VARCHAR(128),
create_time TIMESTAMPTZ,
member_discount_money NUMERIC(18,2),
coupon_sale_id BIGINT,
PRIMARY KEY (redemption_id)
);
@@ -1654,7 +1699,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_groupbuy_redemption.ledger_name IS '【说
COMMENT ON COLUMN billiards_dwd.dwd_groupbuy_redemption.create_time IS '【说明】时间/日期字段，用于记录业务时间与统计口径对齐。 【示例】2025-11-09 23:35:57（时间/日期字段，用于记录业务时间与统计口径对齐）。 【ODS来源】group_buy_redemption_records - create_time。 【JSON字段】group_buy_redemption_records.json - data.siteTableUseDetailsList - create_time。';
CREATE TABLE IF NOT EXISTS dwd_groupbuy_redemption_Ex (
CREATE TABLE IF NOT EXISTS dwd_groupbuy_redemption_ex (
redemption_id BIGINT,
site_name VARCHAR(64),
table_name VARCHAR(64),
@@ -1676,6 +1721,13 @@ CREATE TABLE IF NOT EXISTS dwd_groupbuy_redemption_Ex (
salesman_role_id BIGINT,
salesman_org_id BIGINT,
ledger_group_name VARCHAR(128),
table_share_money NUMERIC(18,2),
table_service_share_money NUMERIC(18,2),
goods_share_money NUMERIC(18,2),
good_service_share_money NUMERIC(18,2),
assistant_share_money NUMERIC(18,2),
assistant_service_share_money NUMERIC(18,2),
recharge_share_money NUMERIC(18,2),
PRIMARY KEY (redemption_id)
);
@@ -1750,7 +1802,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_platform_coupon_redemption.create_time IS '
COMMENT ON COLUMN billiards_dwd.dwd_platform_coupon_redemption.consume_time IS '【说明】时间/日期字段，用于记录业务时间与统计口径对齐。 【示例】2025-11-09 23:41:04（时间/日期字段，用于记录业务时间与统计口径对齐）。 【ODS来源】platform_coupon_redemption_records - consume_time。 【JSON字段】platform_coupon_redemption_records.json - $ - consume_time。';
CREATE TABLE IF NOT EXISTS dwd_platform_coupon_redemption_Ex (
CREATE TABLE IF NOT EXISTS dwd_platform_coupon_redemption_ex (
platform_coupon_redemption_id BIGINT,
coupon_cover VARCHAR(255),
coupon_remark VARCHAR(255),
@@ -1814,7 +1866,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_recharge_order.create_time IS '【说明】
COMMENT ON COLUMN billiards_dwd.dwd_recharge_order.pay_time IS '【说明】时间/日期字段，用于记录业务时间与统计口径对齐。 【示例】NULL（时间/日期字段，用于记录业务时间与统计口径对齐）。 【ODS来源】recharge_settlements - paytime。 【JSON字段】recharge_settlements.json - $ - paytime。';
CREATE TABLE IF NOT EXISTS dwd_recharge_order_Ex (
CREATE TABLE IF NOT EXISTS dwd_recharge_order_ex (
recharge_order_id BIGINT,
site_name_snapshot TEXT,
settle_status INTEGER,
@@ -1919,6 +1971,7 @@ CREATE TABLE IF NOT EXISTS dwd_payment (
create_time TIMESTAMPTZ,
pay_time TIMESTAMPTZ,
pay_date DATE,
tenant_id BIGINT,
PRIMARY KEY (payment_id)
);
@@ -1967,7 +2020,7 @@ COMMENT ON COLUMN billiards_dwd.dwd_refund.member_id IS '【说明】标识类 I
COMMENT ON COLUMN billiards_dwd.dwd_refund.member_card_id IS '【说明】标识类 ID 字段，用于关联/定位相关实体。 【示例】0（标识类 ID 字段，用于关联/定位相关实体）。 【ODS来源】refund_transactions - member_card_id。 【JSON字段】refund_transactions.json - $ - member_card_id。';
CREATE TABLE IF NOT EXISTS dwd_refund_Ex (
CREATE TABLE IF NOT EXISTS dwd_refund_ex (
refund_id BIGINT,
tenant_name VARCHAR(64),
pay_sn BIGINT,

1334
etl_billiards/database/schema_dws.sql
View File

File diff suppressed because it is too large Load Diff

118
etl_billiards/database/seed_index_parameters.sql Normal file
View File

@@ -0,0 +1,118 @@
-- =============================================================================
-- 指数算法参数初始化脚本
-- 版本: v1.0
-- 创建日期: 2026-02-03
-- 描述: 为客户召回指数和客户-助教亲密指数插入默认参数
-- =============================================================================
-- 清空旧数据（如果需要重新初始化）
-- DELETE FROM billiards_dws.cfg_index_parameters WHERE index_type IN ('RECALL', 'INTIMACY');
-- =============================================================================
-- 客户召回指数（RECALL）参数
-- =============================================================================
INSERT INTO billiards_dws.cfg_index_parameters
(index_type, param_name, param_value, description, effective_from)
VALUES
-- 基础参数
('RECALL', 'lookback_days', 60, '回溯窗口（天）：分析近60天的数据', CURRENT_DATE),
('RECALL', 'sigma_min', 2.0, '波动下限（天）：避免σ过小导致超期过敏', CURRENT_DATE),
-- 半衰期参数
('RECALL', 'halflife_new', 7, '新客户半衰期（天）：7天后新客户加分衰减到一半', CURRENT_DATE),
('RECALL', 'halflife_recharge', 10, '刚充值半衰期（天）：10天后充值加分衰减到一半', CURRENT_DATE),
-- 权重参数
('RECALL', 'weight_overdue', 3.0, '超期紧急性权重：主导因子，建议3.0', CURRENT_DATE),
('RECALL', 'weight_new', 1.0, '新客户权重：建议1.0', CURRENT_DATE),
('RECALL', 'weight_recharge', 1.0, '刚充值权重：建议1.0', CURRENT_DATE),
('RECALL', 'weight_hot', 1.0, '热度断档权重：建议1.0', CURRENT_DATE),
-- 映射参数
('RECALL', 'percentile_lower', 5, '下锚分位数：5分位', CURRENT_DATE),
('RECALL', 'percentile_upper', 95, '上锚分位数：95分位', CURRENT_DATE),
('RECALL', 'ewma_alpha', 0.2, 'EWMA平滑系数：越小越平滑，建议0.2', CURRENT_DATE)
ON CONFLICT (index_type, param_name, effective_from) DO UPDATE SET
param_value = EXCLUDED.param_value,
description = EXCLUDED.description,
updated_at = NOW();
-- =============================================================================
-- 客户-助教亲密指数（INTIMACY）参数
-- =============================================================================
INSERT INTO billiards_dws.cfg_index_parameters
(index_type, param_name, param_value, description, effective_from)
VALUES
-- 基础参数
('INTIMACY', 'lookback_days', 60, '回溯窗口（天）：分析近60天的数据', CURRENT_DATE),
('INTIMACY', 'session_merge_hours', 4, '会话合并间隔（小时）：4小时内的服务算同次', CURRENT_DATE),
('INTIMACY', 'recharge_attribute_hours', 1, '充值归因窗口（小时）：服务结束后1小时内', CURRENT_DATE),
('INTIMACY', 'amount_base', 500, '金额压缩基准（元）：选门店常见充值档位', CURRENT_DATE),
('INTIMACY', 'incentive_weight', 1.5, '附加课权重倍数：附加课=基础课的1.5倍', CURRENT_DATE),
-- 半衰期参数
('INTIMACY', 'halflife_session', 14, '会话衰减半衰期（天）：14天后权重衰减到一半', CURRENT_DATE),
('INTIMACY', 'halflife_last', 10, '最近一次半衰期（天）：10天后温度衰减到一半', CURRENT_DATE),
('INTIMACY', 'halflife_recharge', 21, '充值衰减半衰期（天）：21天后充值贡献衰减到一半', CURRENT_DATE),
('INTIMACY', 'halflife_short', 7, '短期激增检测半衰期（天）：用于Burst检测', CURRENT_DATE),
('INTIMACY', 'halflife_long', 30, '长期激增检测半衰期（天）：用于Burst检测', CURRENT_DATE),
-- 权重参数
('INTIMACY', 'weight_frequency', 2.0, '频次权重：建议2.0', CURRENT_DATE),
('INTIMACY', 'weight_recency', 1.5, '最近一次权重：建议1.5', CURRENT_DATE),
('INTIMACY', 'weight_recharge', 2.0, '归因充值权重：建议2.0', CURRENT_DATE),
('INTIMACY', 'weight_duration', 0.5, '时长权重：次要因素，建议0.5', CURRENT_DATE),
('INTIMACY', 'burst_gamma', 0.6, '激增放大系数γ：建议0.6', CURRENT_DATE),
-- 映射参数
('INTIMACY', 'percentile_lower', 5, '下锚分位数：5分位', CURRENT_DATE),
('INTIMACY', 'percentile_upper', 95, '上锚分位数：95分位', CURRENT_DATE),
('INTIMACY', 'ewma_alpha', 0.2, 'EWMA平滑系数：越小越平滑，建议0.2', CURRENT_DATE)
ON CONFLICT (index_type, param_name, effective_from) DO UPDATE SET
param_value = EXCLUDED.param_value,
description = EXCLUDED.description,
updated_at = NOW();
-- =============================================================================
-- 验证
-- =============================================================================
-- 检查参数数量
DO $$
DECLARE
recall_count INTEGER;
intimacy_count INTEGER;
BEGIN
SELECT COUNT(*) INTO recall_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'RECALL';
SELECT COUNT(*) INTO intimacy_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'INTIMACY';
RAISE NOTICE '召回指数参数数量: %', recall_count;
RAISE NOTICE '亲密指数参数数量: %', intimacy_count;
IF recall_count < 10 THEN
RAISE WARNING '召回指数参数不完整，期望至少10个';
END IF;
IF intimacy_count < 15 THEN
RAISE WARNING '亲密指数参数不完整，期望至少15个';
END IF;
END $$;
-- 显示所有参数
SELECT
index_type,
param_name,
param_value,
description,
effective_from
FROM billiards_dws.cfg_index_parameters
ORDER BY index_type, param_name;

82
etl_billiards/docs/DWS 数据库处理需求.md
View File

@@ -5,17 +5,91 @@
本文档描述在ETL已完成的DWD层数据基础上对DWS层的数据处理：
- 完成对DWS层数据库的处理，即数据库设计，成果为DDL的SQL语句。
- 数据读取处理到落库，即DWD读取，Python处理，SQL写入。
- 在动手之前，先出一个任务计划文档，写明事实的具体技术方案细节。
文档更多聚焦业务描述，你需要使用专业技能，使用面向对象编程OOP思想，完成程序设计直至代码完成：
- 参考.\README.md 了解现在项目现状。
- 参考.\etl_billiards\docs\dwd_main_tables_dictionary.md 了解 DWD的schema的表和字段（若与数据库有出路，则以当前数据库为准。）
- 参考.\etl_billiards\docs 了解 DWD的schema的表和字段。
- SQL和Python代码需要详尽的，高密度的中文注释。
- 完成内容，需要详尽高密度的补充至.\README.md，以方便后续维护。
- DWS的表与表的字段 参考.\etl_billiards\docs\dwd_main_tables_dictionary.md 完成类似的数据库文档，方便后续维护。
- 注意中文编码需求。
## 具体需求
### 助教视角
- 需要
## 通用需求
### 数据分层
我希望使用互联网软件的业内通用方法，将数据按照更新时间分为4层，以符合业务层面的查询效率速度。
- 第一层：回溯两天前到当前数据。
- 第二层：回溯1个月前到当前数据。
- 第三层：回溯3个月前到当前数据。
- 第四层：全量数据。
- 需要有配套的机制及时添加删除整理数据。
### 统计注意
当统计一些数据时，注意口径，数据有效性标识。举例：
- 计算助教业绩/工资时，需要参考助教废除表，相关业务数据的影响。
- 计算助教业绩/工资时，注意辨别 助教课 附加课影响。
## 业务需求
### 系统设置
- 助教新的绩效考核和工资结算方式更新为以下算法，影响工资结算和财务账务方面的统计核算，相关内容需要落库，以方便后续调整。还要标记执行时间（如哪个月执行哪个标准等），执行相关结算和计算逻辑。：
档位原因考虑 总业绩小时数阈值 专业课抽成（元/小时） 打赏课抽成 次月休假（天）
0档 淘汰压力 H <100 28 50% 3
1档 及格档（重点激励） 100≤ H <130 18 40% 4
2档 良好档（重点激励） 130≤ H <160 15 38% 4
3档 优秀档 160≤ H <190 13 35% 5
4档 卓越加速档（高端人才倾斜） 190≤ H <220 10 33% 6
5档 冠军加速档（高端人才倾斜） H ≥220 8 30% 休假自由
*课程分为2种（dwd_assistant_service_log表的skill_name）：
基础课：又名 专业课 上桌 上钟，是为客户提供台球助教陪练的课程，按时长统计。精确到分钟。
附加课：又名 超休 激励 打赏，是客户支付较为高昂的价格，买断整小时与助教外出。
总业绩小时数阈值指基础课和附加课总和。
各级别助教（dim_assistant表的level）基础课，对客户收费：初级 98元/小时；中级 108元/小时；高级 118元/小时；星级 138元/小时；
附加课对客户收费统一为190元/小时。
充值提成：
冲刺奖 达成奖金
当月 H ≥ 190：300 元
当月 H ≥ 220：800 元（与上条不叠加，取高）
额外奖金：
冲刺奖 达成奖金
当月 H ≥ 190：300 元
当月 H ≥ 220：800 元（与上条不叠加，取高）
Top3 奖金：
第1名：1000 元
第2名：600 元
第3名：400 元
规则：
1、过档后，所有时长按新档位进行计算。
举例，当前某中级助教已完成185小时，基础课占170小时，附加课15小时。则该月工资计算方法：
170*（108-13）+15*（1-0.35）
2、本月新入职助教，定档方案：
按照日均*30的总业绩小时数定档。
在该25日之后入职的新助教，最高定档至3档。
该折算仅用于定档，不适用于“冲刺奖”和“Top3奖”的计算口径。
### 助教维度
以每个助教个体的视角
- 我要知道我的业绩档位，历史月份与本月档位进度，档位影响的收入单价。及相邻月份的变化。
- 我要知道我的有效业绩：历史月份与本月的 基础课课时，激励课课时，全部课课时。相邻月份的变化。
- 我要知道我的收入：历史月份与本月的收入（注意助教等级，业绩档位，课程种类等因素的总和计算）。相邻月份的变化。
- 我要知道我的客户情况：过去7天、10天、15天、30天、60天、90天 的跨度进行统计，我服务过（基础课+附加课）的客户数据，并关联每次服务的 时间 时长 台桌 分类 等详细信息。
### 客户维度
统计每个客户的信息
- 我要知道每个客户：过去7天、10天、15天、30天、60天、90天 的跨度进行统计，来店消费情况，并关联每次服务的 时间 食品饮品 时长 台桌 分类 助教服务 等详细信息。
### 财务维度
财务维度的需求（已经落到原型图需求级别了），见财务页面需求.md

1122
etl_billiards/docs/DWS_任务计划_v1.md Normal file
View File

File diff suppressed because it is too large Load Diff

1353
etl_billiards/docs/DWS_任务计划_v2.md Normal file
View File

File diff suppressed because it is too large Load Diff

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_assistant_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_assistant_ex.md
View File

9
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_groupbuy_package_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_groupbuy_package_ex.md
View File

@@ -37,10 +37,11 @@
| 18 | effective_status | INTEGER | YES | | 生效状态。**枚举值**: 1(24)=有效, 3(10)=失效 **[待确认]** |
| 19 | max_selectable_categories | INTEGER | YES | | 最大可选分类数（当前数据全为 0） |
| 20 | creator_name | VARCHAR(100) | YES | | 创建人。**样本值**: "店长:郑丽珊", "管理员：郑丽珊" |
| 21 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 22 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 23 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 24 | scd2_version | INTEGER | YES | | 版本号 |
| 21 | tenant_coupon_sale_order_item_id | BIGINT | YES | | 租户券销售订单项 ID |
| 22 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 23 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 24 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 25 | scd2_version | INTEGER | YES | | 版本号 |
## 样本数据

13
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_member_card_account_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_member_card_account_ex.md
View File

@@ -69,10 +69,15 @@
| 50 | goodscategoryid | TEXT | YES | | 可用商品分类 ID 列表（当前数据全为空） |
| 51 | pdassisnatlevel | TEXT | YES | | 陪打助教等级限制。**当前值**: "{}" |
| 52 | cxassisnatlevel | TEXT | YES | | 促销助教等级限制。**当前值**: "{}" |
| 53 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 54 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 55 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 56 | scd2_version | INTEGER | YES | | 版本号 |
| 53 | able_share_member_discount | BOOLEAN | YES | | 是否可共享会员折扣 |
| 54 | electricity_deduct_radio | NUMERIC(18,4) | YES | | 电费扣减比例 |
| 55 | electricity_discount | NUMERIC(18,4) | YES | | 电费折扣 |
| 56 | electricity_card_deduct | BOOLEAN | YES | | 电费卡扣 |
| 57 | recharge_freeze_balance | NUMERIC(18,2) | YES | | 充值冻结余额 |
| 58 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 59 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 60 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 61 | scd2_version | INTEGER | YES | | 版本号 |
## 使用说明

11
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_member_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_member_ex.md
View File

@@ -24,10 +24,13 @@
| 5 | growth_value | NUMERIC(18,2) | YES | | 成长值 |
| 6 | user_status | INTEGER | YES | | 用户状态。**枚举值**: 1(556)=正常 |
| 7 | status | INTEGER | YES | | 账户状态。**枚举值**: 1(490)=正常, 3(66)=**[含义待确认]** |
| 8 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 9 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 10 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 11 | scd2_version | INTEGER | YES | | 版本号 |
| 8 | person_tenant_org_id | BIGINT | YES | | 人员租户组织 ID |
| 9 | person_tenant_org_name | TEXT | YES | | 人员租户组织名称 |
| 10 | register_source | TEXT | YES | | 注册来源 |
| 11 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 12 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 13 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 14 | scd2_version | INTEGER | YES | | 版本号 |
## 样本数据

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_site_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_site_ex.md
View File

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_store_goods_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_store_goods_ex.md
View File

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_table_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_table_ex.md
View File

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dim_tenant_goods_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dim_tenant_goods_ex.md
View File

1
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_assistant_service_log_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_assistant_service_log_ex.md
View File

@@ -47,6 +47,7 @@
| 28 | get_grade_times | INTEGER | YES | | 评分次数（当前数据全为 0） |
| 29 | grade_status | INTEGER | YES | | 评分状态。**枚举值**: 0(216)=未评分, 1(4787)=已评分 **[待确认]** |
| 30 | composite_grade_time | TIMESTAMPTZ | YES | | 评分时间 |
| 31 | assistant_team_name | TEXT | YES | | 助教团队名称 |
## 使用说明

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_assistant_trash_event_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_assistant_trash_event_ex.md
View File

7
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_groupbuy_redemption_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_groupbuy_redemption_ex.md
View File

@@ -38,6 +38,13 @@
| 19 | salesman_role_id | BIGINT | YES | | 销售员角色 ID（当前数据全为 0） |
| 20 | salesman_org_id | BIGINT | YES | | 销售员组织 ID（当前数据全为 0） |
| 21 | ledger_group_name | VARCHAR(128) | YES | | 账本分组名称（当前数据全为 NULL） |
| 22 | table_share_money | NUMERIC(18,2) | YES | | 台费分摊金额 |
| 23 | table_service_share_money | NUMERIC(18,2) | YES | | 台费服务分摊金额 |
| 24 | goods_share_money | NUMERIC(18,2) | YES | | 商品分摊金额 |
| 25 | good_service_share_money | NUMERIC(18,2) | YES | | 商品服务分摊金额 |
| 26 | assistant_share_money | NUMERIC(18,2) | YES | | 助教分摊金额 |
| 27 | assistant_service_share_money | NUMERIC(18,2) | YES | | 助教服务分摊金额 |
| 28 | recharge_share_money | NUMERIC(18,2) | YES | | 充值分摊金额 |
## 台区核销分布

1
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_member_balance_change_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_member_balance_change_ex.md
View File

@@ -23,6 +23,7 @@
| 4 | refund_amount | NUMERIC(18,2) | YES | | 退款金额 |
| 5 | operator_id | BIGINT | YES | | 操作员 ID |
| 6 | operator_name | VARCHAR(64) | YES | | 操作员名称。**枚举值**: "收银员:郑丽珊"(4101), "店长:郑丽珊"(223), "管理员：郑丽珊"(153), "店长:蒋雨轩"(124), "店长:谢晓洪"(115), "店长:黄月柳"(29) |
| 7 | principal_data | TEXT | YES | | 本金变动数据 |
## 操作员分布

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_platform_coupon_redemption_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_platform_coupon_redemption_ex.md
View File

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_recharge_order_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_recharge_order_ex.md
View File

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_refund_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_refund_ex.md
View File

1
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_settlement_head_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_settlement_head_ex.md
View File

@@ -47,6 +47,7 @@
| 28 | order_remark | VARCHAR(255) | YES | | 订单备注。**样本值**: "五折"(42), "轩哥"(24), "陈德韩"(7), "免台费"(3) |
| 29 | operator_id | BIGINT | YES | | 操作员 ID |
| 30 | salesman_user_id | BIGINT | YES | | 销售员用户 ID（当前数据全为 0） |
| 31 | settle_list | JSONB | YES | | 结算明细列表（JSON数组） |
## 使用说明

0
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_store_goods_sale_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_store_goods_sale_ex.md
View File

5
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_table_fee_adjust_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_table_fee_adjust_ex.md
View File

@@ -25,6 +25,11 @@
| 6 | operator_name | VARCHAR(64) | YES | | 操作员名称。**枚举值**: "收银员:郑丽珊"(2849) |
| 7 | applicant_id | BIGINT | YES | | 申请人 ID |
| 8 | operator_id | BIGINT | YES | | 操作员 ID |
| 9 | area_type_id | BIGINT | YES | | 区域类型 ID |
| 10 | site_table_area_id | BIGINT | YES | | 门店台区 ID |
| 11 | site_table_area_name | TEXT | YES | | 门店台区名称 |
| 12 | site_name | TEXT | YES | | 门店名称 |
| 13 | tenant_name | TEXT | YES | | 租户名称 |
## 样本数据

1
etl_billiards/docs/bd_manual/Ex/BD_manual_dwd_table_fee_log_ex.md → etl_billiards/docs/bd_manual/DWD/Ex/BD_manual_dwd_table_fee_log_ex.md
View File

@@ -29,6 +29,7 @@
| 10 | operator_id | BIGINT | YES | | 操作员 ID。**枚举值**: 3个不同ID |
| 11 | salesman_user_id | BIGINT | YES | | 销售员用户 ID（当前数据全为 0） |
| 12 | salesman_org_id | BIGINT | YES | | 销售员组织 ID（当前数据全为 0） |
| 13 | order_consumption_type | INTEGER | YES | | 订单消费类型 |
## 样本数据

0
etl_billiards/docs/bd_manual/main/BD_manual_billiards_dwd.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_billiards_dwd.md
View File

0
etl_billiards/docs/bd_manual/main/BD_manual_dim_assistant.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_assistant.md
View File

6
etl_billiards/docs/bd_manual/main/BD_manual_dim_goods_category.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_goods_category.md
View File

@@ -19,10 +19,10 @@
|------|--------|------|------|------|------|
| 1 | category_id | BIGINT | NO | PK | 分类唯一标识 |
| 2 | tenant_id | BIGINT | YES | | 租户 ID（当前值: 2790683160709957） |
| 3 | category_name | VARCHAR | YES | | 分类名称。**样本值**: "槟榔", "皮头" 等 |
| 4 | alias_name | VARCHAR | YES | | 分类别名（当前数据大部分为空） |
| 3 | category_name | VARCHAR(50) | YES | | 分类名称。**样本值**: "槟榔", "皮头" 等 |
| 4 | alias_name | VARCHAR(50) | YES | | 分类别名（当前数据大部分为空） |
| 5 | parent_category_id | BIGINT | YES | | 父级分类 ID（0=一级分类）→ 自关联 |
| 6 | business_name | VARCHAR | YES | | 业务大类名称。**样本值**: "酒水", "器材" 等 |
| 6 | business_name | VARCHAR(50) | YES | | 业务大类名称。**样本值**: "酒水", "器材" 等 |
| 7 | tenant_goods_business_id | BIGINT | YES | | 业务大类 ID |
| 8 | category_level | INTEGER | YES | | 分类层级。**枚举值**: 1=一级大类, 2=二级子类 |
| 9 | is_leaf | INTEGER | YES | | 是否叶子节点。**枚举值**: 0=非叶子, 1=叶子 |

18
etl_billiards/docs/bd_manual/main/BD_manual_dim_groupbuy_package.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_groupbuy_package.md
View File

@@ -20,23 +20,25 @@
| 1 | groupbuy_package_id | BIGINT | NO | PK | 团购套餐 ID |
| 2 | tenant_id | BIGINT | YES | | 租户 ID（当前值: 2790683160709957） |
| 3 | site_id | BIGINT | YES | | 门店 ID → dim_site（当前值: 2790685415443269） |
| 4 | package_name | VARCHAR | YES | | 套餐名称。**样本值**: "中八、斯诺克包厢两小时", "斯诺克两小时"等 |
| 4 | package_name | VARCHAR(200) | YES | | 套餐名称。**样本值**: "中八、斯诺克包厢两小时", "斯诺克两小时"等 |
| 5 | package_template_id | BIGINT | YES | | 套餐模板 ID |
| 6 | selling_price | NUMERIC(10,2) | YES | | 售卖价格（每笔订单不同，从核销记录中dwd_groupbuy_redemption获取） |
| 7 | coupon_face_value | NUMERIC(10,2) | YES | | 券面值（每笔订单不同，从核销记录中dwd_groupbuy_redemption获取） |
| 8 | duration_seconds | INTEGER | YES | | 套餐时长（秒）。**样本值**: 3600=1小时, 7200=2小时, 14400=4小时 等 |
| 9 | start_time | TIMESTAMPTZ | YES | | 套餐生效开始时间 |
| 10 | end_time | TIMESTAMPTZ | YES | | 套餐生效结束时间 |
| 11 | table_area_name | VARCHAR | YES | | 适用台区名称。**枚举值**: "A区", "VIP包厢", "斯诺克区", "B区", "麻将房", "888" |
| 11 | table_area_name | VARCHAR(100) | YES | | 适用台区名称。**枚举值**: "A区", "VIP包厢", "斯诺克区", "B区", "麻将房", "888" |
| 12 | is_enabled | INTEGER | YES | | 启用状态。**枚举值**: 1=启用, 2=停用 |
| 13 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 14 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 15 | tenant_table_area_id_list | VARCHAR | YES | | 租户级台区 ID 列表 |
| 16 | card_type_ids | VARCHAR | YES | | 允许使用的卡类型 ID 列表（当前数据为 "0"） |
| 17 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 18 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 19 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 20 | scd2_version | INTEGER | YES | | 版本号 |
| 15 | tenant_table_area_id_list | VARCHAR(512) | YES | | 租户级台区 ID 列表 |
| 16 | card_type_ids | VARCHAR(255) | YES | | 允许使用的卡类型 ID 列表（当前数据为 "0"） |
| 17 | sort | INTEGER | YES | | 排序 |
| 18 | is_first_limit | BOOLEAN | YES | | 是否首单限制 |
| 19 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 20 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 21 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 22 | scd2_version | INTEGER | YES | | 版本号 |
## 使用说明

10
etl_billiards/docs/bd_manual/main/BD_manual_dim_member.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_member.md
View File

@@ -27,10 +27,12 @@
| 8 | member_card_grade_name | TEXT | YES | | 卡等级名称。**枚举值**: "储值卡", "台费卡", "年卡", "活动抵用券", "月卡" |
| 9 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 10 | update_time | TIMESTAMPTZ | YES | | 更新时间 |
| 11 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 12 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 13 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 14 | scd2_version | INTEGER | YES | | 版本号 |
| 11 | pay_money_sum | NUMERIC(18,2) | YES | | 累计支付金额 |
| 12 | recharge_money_sum | NUMERIC(18,2) | YES | | 累计充值金额 |
| 13 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 14 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 15 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 16 | scd2_version | INTEGER | YES | | 版本号 |
## 使用说明

10
etl_billiards/docs/bd_manual/main/BD_manual_dim_member_card_account.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_member_card_account.md
View File

@@ -34,10 +34,12 @@
| 15 | last_consume_time | TIMESTAMPTZ | YES | | 最近消费时间 |
| 16 | status | INTEGER | YES | | 卡状态。**枚举值**: 1=正常, 4=过期 |
| 17 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 18 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 19 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 20 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 21 | scd2_version | INTEGER | YES | | 版本号 |
| 18 | principal_balance | NUMERIC(18,2) | YES | | 本金余额 |
| 19 | member_grade | INTEGER | YES | | 会员等级 |
| 20 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 21 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 22 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 23 | scd2_version | INTEGER | YES | | 版本号 |
## 卡种分布

0
etl_billiards/docs/bd_manual/main/BD_manual_dim_site.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_site.md
View File

10
etl_billiards/docs/bd_manual/main/BD_manual_dim_store_goods.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_store_goods.md
View File

@@ -37,10 +37,12 @@
| 18 | enable_status | INTEGER | YES | | 启用状态。**枚举值**: 1=启用 |
| 19 | send_state | INTEGER | YES | | 配送状态。暂无作用 |
| 20 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 21 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 22 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 23 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 24 | scd2_version | INTEGER | YES | | 版本号 |
| 21 | commodity_code | TEXT | YES | | 商品编码 |
| 22 | not_sale | INTEGER | YES | | 是否停售 |
| 23 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 24 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 25 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 26 | scd2_version | INTEGER | YES | | 版本号 |
## 样本数据

9
etl_billiards/docs/bd_manual/main/BD_manual_dim_table.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_table.md
View File

@@ -24,10 +24,11 @@
| 5 | site_table_area_name | TEXT | YES | | 台区名称。**样本值**: "A区", "B区", "补时长", "C区", "麻将房", "K包", "VIP包厢", "斯诺克区", "666", "k包活动区", "M7" 等 |
| 6 | tenant_table_area_id | BIGINT | YES | | 租户级台区 ID |
| 7 | table_price | NUMERIC(18,2) | YES | | 台桌单价（当前数据全为 0.00） |
| 8 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 9 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 10 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 11 | scd2_version | INTEGER | YES | | 版本号 |
| 8 | order_id | BIGINT | YES | | 订单 ID |
| 9 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 10 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 11 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 12 | scd2_version | INTEGER | YES | | 版本号 |
## 台区分布

17
etl_billiards/docs/bd_manual/main/BD_manual_dim_tenant_goods.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dim_tenant_goods.md
View File

@@ -20,21 +20,22 @@
| 1 | tenant_goods_id | BIGINT | NO | PK | 租户商品 ID（SKU） |
| 2 | tenant_id | BIGINT | YES | | 租户 ID |
| 3 | supplier_id | BIGINT | YES | | 供应商 ID（当前数据全为 0） |
| 4 | category_name | VARCHAR | YES | | 分类名称（二级分类）。**样本值**: "零食", "饮料", "香烟"等 |
| 4 | category_name | VARCHAR(64) | YES | | 分类名称（二级分类）。**样本值**: "零食", "饮料", "香烟"等 |
| 5 | goods_category_id | BIGINT | YES | | 一级分类 ID |
| 6 | goods_second_category_id | BIGINT | YES | | 二级分类 ID |
| 7 | goods_name | VARCHAR | YES | | 商品名称。**样本值**: "海之言", "西梅多多饮品", "美汁源果粒橙", "三诺橙汁"等 |
| 8 | goods_number | VARCHAR | YES | | 商品编号（序号） |
| 9 | unit | VARCHAR | YES | | 商品单位。**枚举值**: "包", "瓶", "个", "份"等 |
| 7 | goods_name | VARCHAR(128) | YES | | 商品名称。**样本值**: "海之言", "西梅多多饮品", "美汁源果粒橙", "三诺橙汁"等 |
| 8 | goods_number | VARCHAR(64) | YES | | 商品编号（序号） |
| 9 | unit | VARCHAR(16) | YES | | 商品单位。**枚举值**: "包", "瓶", "个", "份"等 |
| 10 | market_price | NUMERIC(18,2) | YES | | 市场价/吊牌价（元） |
| 11 | goods_state | INTEGER | YES | | 商品状态。**枚举值**: 1=上架, 2=下架 |
| 12 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 13 | update_time | TIMESTAMPTZ | YES | | 更新时间 |
| 14 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 15 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 16 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 17 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 18 | scd2_version | INTEGER | YES | | 版本号 |
| 15 | not_sale | INTEGER | YES | | 是否停售 |
| 16 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
| 17 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
| 18 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
| 19 | scd2_version | INTEGER | YES | | 版本号 |
## 使用说明

9
etl_billiards/docs/bd_manual/main/BD_manual_dwd_assistant_service_log.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_assistant_service_log.md
View File

@@ -28,16 +28,16 @@
| 9 | site_table_id | BIGINT | YES | | 台桌 ID → dim_table（0=非台桌服务） |
| 10 | tenant_member_id | BIGINT | YES | | 会员 ID → dim_member（0=散客） |
| 11 | system_member_id | BIGINT | YES | | 系统会员 ID（0=散客） |
| 12 | assistant_no | VARCHAR | YES | | 助教工号。**样本值**: "2", "9"等 |
| 13 | nickname | VARCHAR | YES | | 助教昵称。**样本值**: "佳怡", "婉婉", "七七"等 |
| 12 | assistant_no | VARCHAR(64) | YES | | 助教工号。**样本值**: "2", "9"等 |
| 13 | nickname | VARCHAR(64) | YES | | 助教昵称。**样本值**: "佳怡", "婉婉", "七七"等 |
| 14 | site_assistant_id | BIGINT | YES | | 助教 ID → dim_assistant |
| 15 | user_id | BIGINT | YES | | 助教用户 ID |
| 16 | assistant_team_id | BIGINT | YES | | 助教团队 ID。**枚举值**: 2792011585884037=1组, 2959085810992645=2组 |
| 17 | person_org_id | BIGINT | YES | | 人事组织 ID |
| 18 | assistant_level | INTEGER | YES | | 助教等级。**枚举值**: 8=助教管理, 10=初级, 20=中级, 30=高级, 40=星级 |
| 19 | level_name | VARCHAR | YES | | 等级名称。**枚举值**: "助教管理", "初级", "中级", "高级", "星级" |
| 19 | level_name | VARCHAR(64) | YES | | 等级名称。**枚举值**: "助教管理", "初级", "中级", "高级", "星级" |
| 20 | skill_id | BIGINT | YES | | 技能 ID **枚举值**: 2790683529513797 = 基础课 , 2790683529513798 = 附加课/激励课, 3039912271463941 = 包厢课 |
| 21 | skill_name | VARCHAR | YES | | 技能名称。 **枚举值**: "基础课","附加课","包厢课"|
| 21 | skill_name | VARCHAR(64) | YES | | 技能名称。 **枚举值**: "基础课","附加课","包厢课"|
| 22 | ledger_unit_price | NUMERIC(10,2) | YES | | 单价（元/小时），**样本值**: 98.00/108.00/190.00 等 |
| 23 | ledger_amount | NUMERIC(10,2) | YES | | 计费金额 |
| 24 | projected_income | NUMERIC(10,2) | YES | | 预估收入 |
@@ -49,6 +49,7 @@
| 30 | start_use_time | TIMESTAMPTZ | YES | | 服务开始时间 |
| 31 | last_use_time | TIMESTAMPTZ | YES | | 服务结束时间 |
| 32 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 33 | real_service_money | NUMERIC(18,2) | YES | | 实际服务费金额 |
## 使用说明

7
etl_billiards/docs/bd_manual/main/BD_manual_dwd_assistant_trash_event.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_assistant_trash_event.md
View File

@@ -21,12 +21,13 @@
| 2 | site_id | BIGINT | YES | | 门店 ID |
| 3 | table_id | BIGINT | YES | | 台桌 ID → dim_table |
| 4 | table_area_id | BIGINT | YES | | 台区 ID |
| 5 | assistant_no | VARCHAR | YES | | 助教工号/昵称。**样本值**: "七七", "乔西", "球球"等 |
| 6 | assistant_name | VARCHAR | YES | | 助教名称，与 assistant_no 相同 |
| 5 | assistant_no | VARCHAR(32) | YES | | 助教工号/昵称。**样本值**: "七七", "乔西", "球球"等 |
| 6 | assistant_name | VARCHAR(64) | YES | | 助教名称，与 assistant_no 相同 |
| 7 | charge_minutes_raw | INTEGER | YES | | 原计费时长（秒）。**样本值**: 0, 3600=1h, 10800=3h 等 |
| 8 | abolish_amount | NUMERIC(18,2) | YES | | 作废金额（元）。**样本值**: 0.00, 190.00, 570.00 等 |
| 9 | trash_reason | VARCHAR | YES | | 作废原因（当前数据全为 NULL） |
| 9 | trash_reason | VARCHAR(255) | YES | | 作废原因（当前数据全为 NULL） |
| 10 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 11 | tenant_id | BIGINT | YES | | 租户 ID |
## 使用说明

6
etl_billiards/docs/bd_manual/main/BD_manual_dwd_groupbuy_redemption.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_groupbuy_redemption.md
View File

@@ -35,11 +35,13 @@
| 16 | ledger_amount | NUMERIC(18,2) | YES | | 账本金额（元）。**样本值**: 48.00, 96.00, 68.00 等 |
| 17 | coupon_money | NUMERIC(18,2) | YES | | 券面额（元）。**样本值**: 48.00, 116.00, 96.00, 68.00 等 |
| 18 | promotion_seconds | INTEGER | YES | | 促销时长（秒）。**样本值**: 3600=1h, 7200=2h, 14400=4h 等 |
| 19 | coupon_code | VARCHAR | YES | | 券码 |
| 19 | coupon_code | VARCHAR(64) | YES | | 券码 |
| 20 | is_single_order | INTEGER | YES | | 是否独立订单。**枚举值**: 0=否, 1=是 |
| 21 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 22 | ledger_name | VARCHAR | YES | | 套餐名称。**样本值**: "全天A区中八一小时", "中八A区新人特惠一小时" 等 |
| 22 | ledger_name | VARCHAR(128) | YES | | 套餐名称。**样本值**: "全天A区中八一小时", "中八A区新人特惠一小时" 等 |
| 23 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 24 | member_discount_money | NUMERIC(18,2) | YES | | 会员折扣金额 |
| 25 | coupon_sale_id | BIGINT | YES | | 优惠券销售 ID |
## 使用说明

11
etl_billiards/docs/bd_manual/main/BD_manual_dwd_member_balance_change.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_member_balance_change.md
View File

@@ -25,9 +25,9 @@
| 6 | system_member_id | BIGINT | YES | | 系统会员 ID |
| 7 | tenant_member_card_id | BIGINT | YES | | 会员卡 ID → dim_member_card_account |
| 8 | card_type_id | BIGINT | YES | | 卡类型 ID |
| 9 | card_type_name | VARCHAR | YES | | 卡类型名称。**枚举值**: "储值卡", "活动抵用券", "台费卡", "酒水卡", "年卡", "月卡" |
| 10 | member_name | VARCHAR | YES | | 会员名称快照 |
| 11 | member_mobile | VARCHAR | YES | | 会员手机号快照 |
| 9 | card_type_name | VARCHAR(32) | YES | | 卡类型名称。**枚举值**: "储值卡", "活动抵用券", "台费卡", "酒水卡", "年卡", "月卡" |
| 10 | member_name | VARCHAR(64) | YES | | 会员名称快照 |
| 11 | member_mobile | VARCHAR(20) | YES | | 会员手机号快照 |
| 12 | balance_before | NUMERIC(18,2) | YES | | 变动前余额 |
| 13 | change_amount | NUMERIC(18,2) | YES | | 变动金额（正=充值/赠送，负=消费） |
| 14 | balance_after | NUMERIC(18,2) | YES | | 变动后余额 |
@@ -35,7 +35,10 @@
| 16 | payment_method | INTEGER | YES | | 支付方式，暂未启用。 |
| 17 | change_time | TIMESTAMPTZ | YES | | 变动时间 |
| 18 | is_delete | INTEGER | YES | | 删除标记 |
| 19 | remark | VARCHAR | YES | | 备注。**样本值**: "注销会员", "充值退款" 等 |
| 19 | remark | VARCHAR(255) | YES | | 备注。**样本值**: "注销会员", "充值退款" 等 |
| 20 | principal_before | NUMERIC(18,2) | YES | | 变动前本金 |
| 21 | principal_after | NUMERIC(18,2) | YES | | 变动后本金 |
| 22 | principal_change_amount | NUMERIC(18,2) | YES | | 本金变动金额（正=增加，负=减少） |
## 卡类型余额变动分布

1
etl_billiards/docs/bd_manual/main/BD_manual_dwd_payment.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_payment.md
View File

@@ -28,6 +28,7 @@
| 9 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 10 | pay_time | TIMESTAMPTZ | YES | | 支付时间 |
| 11 | pay_date | DATE | YES | | 支付日期 |
| 12 | tenant_id | BIGINT | YES | | 租户 ID |
## 使用说明

8
etl_billiards/docs/bd_manual/main/BD_manual_dwd_platform_coupon_redemption.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_platform_coupon_redemption.md
View File

@@ -20,9 +20,9 @@
| 1 | platform_coupon_redemption_id | BIGINT | NO | PK | 核销 ID |
| 2 | tenant_id | BIGINT | YES | | 租户 ID |
| 3 | site_id | BIGINT | YES | | 门店 ID |
| 4 | coupon_code | VARCHAR | YES | | 券码 |
| 4 | coupon_code | VARCHAR(64) | YES | | 券码 |
| 5 | coupon_channel | INTEGER | YES | | 券渠道。**枚举值**: 1=美团, 2=抖音 |
| 6 | coupon_name | VARCHAR | YES | | 券名称。**样本值**: "【全天可用】中八桌球一小时（A区）", "【全天可用】中八桌球两小时（A区）" 等 |
| 6 | coupon_name | VARCHAR(200) | YES | | 券名称。**样本值**: "【全天可用】中八桌球一小时（A区）", "【全天可用】中八桌球两小时（A区）" 等 |
| 7 | sale_price | NUMERIC(10,2) | YES | | 售卖价（元）。**样本值**: 29.90, 69.90, 59.90, 39.90, 19.90 等 |
| 8 | coupon_money | NUMERIC(10,2) | YES | | 券面额（元）。**样本值**: 48.00, 96.00, 116.00, 68.00 等 |
| 9 | coupon_free_time | INTEGER | YES | | 券赠送时长（当前数据全为 0） |
@@ -31,8 +31,8 @@
| 12 | group_package_id | BIGINT | YES | | 团购套餐 ID（当前数据全为 0） |
| 13 | site_order_id | BIGINT | YES | | 门店订单 ID |
| 14 | table_id | BIGINT | YES | | 台桌 ID → dim_table |
| 15 | certificate_id | VARCHAR | YES | | 凭证 ID |
| 16 | verify_id | VARCHAR | YES | | 核验 ID（仅抖音券有值） |
| 15 | certificate_id | VARCHAR(64) | YES | | 凭证 ID |
| 16 | verify_id | VARCHAR(64) | YES | | 核验 ID（仅抖音券有值） |
| 17 | use_status | INTEGER | YES | | 使用状态。**枚举值**: 1=已使用, 2=已撤销 |
| 18 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 19 | create_time | TIMESTAMPTZ | YES | | 创建时间 |

0
etl_billiards/docs/bd_manual/main/BD_manual_dwd_recharge_order.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_recharge_order.md
View File

0
etl_billiards/docs/bd_manual/main/BD_manual_dwd_refund.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_refund.md
View File

17
etl_billiards/docs/bd_manual/main/BD_manual_dwd_settlement_head.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_settlement_head.md
View File

@@ -20,19 +20,19 @@
| 1 | order_settle_id | BIGINT | NO | PK | 结账单 ID |
| 2 | tenant_id | BIGINT | YES | | 租户 ID |
| 3 | site_id | BIGINT | YES | | 门店 ID → dim_site |
| 4 | site_name | VARCHAR | YES | | 门店名称。**当前值**: "朗朗桌球" |
| 4 | site_name | VARCHAR(100) | YES | | 门店名称。**当前值**: "朗朗桌球" |
| 5 | table_id | BIGINT | YES | | 台桌 ID → dim_table（0=非台桌订单，如商城订单） |
| 6 | settle_name | VARCHAR | YES | | 结账名称。**样本值**: "商城订单", "A区 A3", "A区 A4", "斯诺克区 S1" |
| 6 | settle_name | VARCHAR(100) | YES | | 结账名称。**样本值**: "商城订单", "A区 A3", "A区 A4", "斯诺克区 S1" |
| 7 | order_trade_no | BIGINT | YES | | 订单号 |
| 8 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 9 | pay_time | TIMESTAMPTZ | YES | | 支付时间 |
| 10 | settle_type | INTEGER | YES | | 结账类型。**枚举值**: 1=台桌结账, 3=商城订单, 6=退货订单, 7=退款订单 |
| 11 | revoke_order_id | BIGINT | YES | | 撤销订单 ID（当前数据全为 0） |
| 12 | member_id | BIGINT | YES | | 会员 ID → dim_member（0=散客，占比约 82.8%） |
| 13 | member_name | VARCHAR | YES | | 会员名称 |
| 14 | member_phone | VARCHAR | YES | | 会员电话 |
| 13 | member_name | VARCHAR(100) | YES | | 会员名称 |
| 14 | member_phone | VARCHAR(50) | YES | | 会员电话 |
| 15 | member_card_account_id | BIGINT | YES | | 会员卡账户 ID（当前数据全为 0） |
| 16 | member_card_type_name | VARCHAR | YES | | 卡类型名称（当前数据全为空） |
| 16 | member_card_type_name | VARCHAR(100) | YES | | 卡类型名称（当前数据全为空） |
| 17 | is_bind_member | BOOLEAN | YES | | 是否绑定会员。**枚举值**: False=否 |
| 18 | member_discount_amount | NUMERIC(18,2) | YES | | 会员折扣金额 |
| 19 | consume_money | NUMERIC(18,2) | YES | | 消费总金额（元） |
@@ -40,7 +40,7 @@
| 21 | goods_money | NUMERIC(18,2) | YES | | 商品金额 |
| 22 | real_goods_money | NUMERIC(18,2) | YES | | 实收商品金额 |
| 23 | assistant_pd_money | NUMERIC(18,2) | YES | | 助教陪打费用 |
| 24 | assistant_cx_money | NUMERIC(18,2) | YES | | 助教促销费用 |
| 24 | assistant_cx_money | NUMERIC(18,2) | YES | | 助教超休费用 |
| 25 | adjust_amount | NUMERIC(18,2) | YES | | 调整金额 |
| 26 | pay_amount | NUMERIC(18,2) | YES | | 实付金额 |
| 27 | balance_amount | NUMERIC(18,2) | YES | | 余额支付金额 |
@@ -49,6 +49,11 @@
| 30 | coupon_amount | NUMERIC(18,2) | YES | | 券抵扣金额 |
| 31 | rounding_amount | NUMERIC(18,2) | YES | | 抹零金额 |
| 32 | point_amount | NUMERIC(18,2) | YES | | 积分抵扣等值金额 |
| 33 | electricity_money | NUMERIC(18,2) | YES | | 电费金额 |
| 34 | real_electricity_money | NUMERIC(18,2) | YES | | 实际电费金额 |
| 35 | electricity_adjust_money | NUMERIC(18,2) | YES | | 电费调整金额 |
| 36 | pl_coupon_sale_amount | NUMERIC(18,2) | YES | | 平台券销售额 |
| 37 | mervou_sales_amount | NUMERIC(18,2) | YES | | 商户券销售额 |
## 使用说明

5
etl_billiards/docs/bd_manual/main/BD_manual_dwd_store_goods_sale.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_store_goods_sale.md
View File

@@ -29,8 +29,8 @@
| 10 | tenant_goods_category_id | BIGINT | YES | | 商品分类 ID |
| 11 | tenant_goods_business_id | BIGINT | YES | | 业务大类 ID |
| 12 | site_table_id | BIGINT | YES | | 台桌 ID（0=商城订单，非台桌消费） |
| 13 | ledger_name | VARCHAR | YES | | 商品名称。**样本值**: "哇哈哈矿泉水", "东方树叶", "可乐" 等 |
| 14 | ledger_group_name | VARCHAR | YES | | 商品分类。**样本值**: "酒水", "零食", "香烟" 等 |
| 13 | ledger_name | VARCHAR(200) | YES | | 商品名称。**样本值**: "哇哈哈矿泉水", "东方树叶", "可乐" 等 |
| 14 | ledger_group_name | VARCHAR(100) | YES | | 商品分类。**样本值**: "酒水", "零食", "香烟" 等 |
| 15 | ledger_unit_price | NUMERIC(18,2) | YES | | 单价（元） |
| 16 | ledger_count | INTEGER | YES | | 购买数量。**样本值**: 1, 2, 3, 4 等 |
| 17 | ledger_amount | NUMERIC(18,2) | YES | | 销售金额（元） |
@@ -40,6 +40,7 @@
| 21 | ledger_status | INTEGER | YES | | 账本状态。**枚举值**: 1=已结算 |
| 22 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 23 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 24 | coupon_share_money | NUMERIC(18,2) | YES | | 优惠券分摊金额 |
## 使用说明

6
etl_billiards/docs/bd_manual/main/BD_manual_dwd_table_fee_adjust.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_table_fee_adjust.md
View File

@@ -24,11 +24,15 @@
| 5 | site_id | BIGINT | YES | | 门店 ID |
| 6 | table_id | BIGINT | YES | | 台桌 ID → dim_table |
| 7 | table_area_id | BIGINT | YES | | 台区 ID |
| 8 | table_area_name | VARCHAR | YES | | 台区名称（当前数据全为 NULL） |
| 8 | table_area_name | VARCHAR(64) | YES | | 台区名称（当前数据全为 NULL） |
| 9 | tenant_table_area_id | BIGINT | YES | | 租户台区 ID |
| 10 | ledger_amount | NUMERIC(18,2) | YES | | 调整金额（元） |
| 11 | ledger_status | INTEGER | YES | | 账本状态。**枚举值**: 0=待确认, 1=已确认 |
| 12 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 13 | table_name | TEXT | YES | | 台桌名称 |
| 14 | table_price | NUMERIC(18,2) | YES | | 台桌价格 |
| 15 | charge_free | BOOLEAN | YES | | 是否免费 |
| 16 | adjust_time | TIMESTAMPTZ | YES | | 调整时间 |
## 使用说明

6
etl_billiards/docs/bd_manual/main/BD_manual_dwd_table_fee_log.md → etl_billiards/docs/bd_manual/DWD/main/BD_manual_dwd_table_fee_log.md
View File

@@ -25,10 +25,10 @@
| 6 | site_id | BIGINT | YES | | 门店 ID |
| 7 | site_table_id | BIGINT | YES | | 台桌 ID → dim_table |
| 8 | site_table_area_id | BIGINT | YES | | 台区 ID |
| 9 | site_table_area_name | VARCHAR | YES | | 台区名称。**枚举值**: "A区", "B区", "斯诺克区", "麻将房", "C区", "补时长", "VIP包厢" 等 |
| 9 | site_table_area_name | VARCHAR(64) | YES | | 台区名称。**枚举值**: "A区", "B区", "斯诺克区", "麻将房", "C区", "补时长", "VIP包厢" 等 |
| 10 | tenant_table_area_id | BIGINT | YES | | 租户级台区 ID |
| 11 | member_id | BIGINT | YES | | 会员 ID（0=散客，占比约 82.4%） |
| 12 | ledger_name | VARCHAR | YES | | 台桌名称。**样本值**: "A3", "A5", "A4", "S1", "B5", "M3" 等 |
| 12 | ledger_name | VARCHAR(64) | YES | | 台桌名称。**样本值**: "A3", "A5", "A4", "S1", "B5", "M3" 等 |
| 13 | ledger_unit_price | NUMERIC(18,2) | YES | | 单价（元/小时），如 48.00/58.00/68.00 |
| 14 | ledger_count | INTEGER | YES | | 计费时长（秒）。**样本值**: 3600=1h, 7200=2h, 10800=3h 等 |
| 15 | ledger_amount | NUMERIC(18,2) | YES | | 计费金额（元） |
@@ -44,6 +44,8 @@
| 25 | ledger_status | INTEGER | YES | | 账本状态。**枚举值**: 1=已结算 |
| 26 | is_single_order | INTEGER | YES | | 是否独立订单。**枚举值**: 0=合并订单, 1=独立订单 |
| 27 | is_delete | INTEGER | YES | | 删除标记。**枚举值**: 0=未删除 |
| 28 | activity_discount_amount | NUMERIC(18,2) | YES | | 活动折扣金额 |
| 29 | real_service_money | NUMERIC(18,2) | YES | | 实际服务费金额 |
## 使用说明

74
etl_billiards/docs/bd_manual/dws/BD_manual_cfg_area_category.md Normal file
View File

@@ -0,0 +1,74 @@
# cfg_area_category 台区分类映射表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | cfg_area_category |
| 主键 | category_id |
| 数据来源 | 手工维护/seed脚本（基于dim_table实际数据） |
| 说明 | 将dim_table.site_table_area_name映射到财务报表区域分类 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | category_id | SERIAL | NO | PK | 分类ID（自增） |
| 2 | source_area_name | VARCHAR(100) | NO | UK | 源区域名称（来自dim_table.site_table_area_name） |
| 3 | category_code | VARCHAR(20) | NO | | 分类代码。**枚举值**: BILLIARD, BILLIARD_VIP, SNOOKER, MAHJONG, KTV, SPECIAL, OTHER |
| 4 | category_name | VARCHAR(50) | NO | | 分类名称 |
| 5 | match_type | VARCHAR(10) | NO | | 匹配类型。**枚举值**: EXACT（精确）, LIKE（模糊）, DEFAULT（兜底） |
| 6 | match_priority | INTEGER | NO | | 匹配优先级（数字越小优先级越高） |
| 7 | is_active | BOOLEAN | NO | | 是否启用 |
| 8 | description | TEXT | YES | | 说明 |
| 9 | created_at | TIMESTAMPTZ | NO | | 创建时间 |
| 10 | updated_at | TIMESTAMPTZ | NO | | 更新时间 |
## 分类映射示例
| 源区域名称 | 分类代码 | 分类名称 |
|------------|----------|----------|
| A区 | BILLIARD | 台球散台 |
| B区 | BILLIARD | 台球散台 |
| C区 | BILLIARD | 台球散台 |
| TV台 | BILLIARD | 台球散台 |
| VIP包厢 | BILLIARD_VIP | 台球VIP |
| 斯诺克区 | SNOOKER | 斯诺克 |
| 麻将房 | MAHJONG | 麻将棋牌 |
| M7 | MAHJONG | 麻将棋牌 |
| M8 | MAHJONG | 麻将棋牌 |
| 666 | MAHJONG | 麻将棋牌 |
| 发财 | MAHJONG | 麻将棋牌 |
| K包 | KTV | K歌娱乐 |
| k包活动区 | KTV | K歌娱乐 |
| 幸会158 | KTV | K歌娱乐 |
| 补时长 | SPECIAL | 补时长 |
## 使用说明
**取值方式**
```sql
-- 将台区名称映射到分类
SELECT
dt.site_table_area_name,
COALESCE(ac.category_code, 'OTHER') AS category_code,
COALESCE(ac.category_name, '其他') AS category_name
FROM billiards_dwd.dim_table dt
LEFT JOIN billiards_dws.cfg_area_category ac
ON dt.site_table_area_name = ac.source_area_name
AND ac.is_active = TRUE
WHERE dt.scd2_is_current = 1;
-- 按分类汇总收入
SELECT
COALESCE(ac.category_name, '其他') AS category_name,
SUM(tfl.ledger_amount) AS total_amount
FROM billiards_dwd.dwd_table_fee_log tfl
LEFT JOIN billiards_dwd.dim_table dt ON dt.table_id = tfl.site_table_id
LEFT JOIN billiards_dws.cfg_area_category ac ON dt.site_table_area_name = ac.source_area_name
GROUP BY COALESCE(ac.category_name, '其他');
```

56
etl_billiards/docs/bd_manual/dws/BD_manual_cfg_assistant_level_price.md Normal file
View File

@@ -0,0 +1,56 @@
# cfg_assistant_level_price 助教等级定价表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | cfg_assistant_level_price |
| 主键 | price_id |
| 数据来源 | 手工维护/seed脚本 |
| 说明 | 助教等级对应的基础课和附加课单价配置 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | price_id | SERIAL | NO | PK | 定价ID（自增） |
| 2 | level_code | INTEGER | NO | | 等级代码。**枚举值**: 8=助教管理, 10=初级, 20=中级, 30=高级, 40=星级 |
| 3 | level_name | VARCHAR(20) | NO | | 等级名称 |
| 4 | base_course_price | NUMERIC(10,2) | NO | | 基础课单价（元/小时） |
| 5 | bonus_course_price | NUMERIC(10,2) | NO | | 附加课单价（元/小时），固定50元 |
| 6 | effective_from | DATE | NO | | 生效起始日期（含） |
| 7 | effective_to | DATE | NO | | 生效截止日期（含） |
| 8 | description | TEXT | YES | | 说明 |
| 9 | created_at | TIMESTAMPTZ | NO | | 创建时间 |
| 10 | updated_at | TIMESTAMPTZ | NO | | 更新时间 |
## 定价配置示例
| 等级代码 | 等级名称 | 基础课单价 | 附加课单价 |
|----------|----------|------------|------------|
| 8 | 助教管理 | 98元/小时 | 50元/小时 |
| 10 | 初级 | 98元/小时 | 50元/小时 |
| 20 | 中级 | 108元/小时 | 50元/小时 |
| 30 | 高级 | 118元/小时 | 50元/小时 |
| 40 | 星级 | 138元/小时 | 50元/小时 |
## 使用说明
**取值方式**
SCD2口径：助教等级来自dim_assistant，取数时需按有效期as-of join
```sql
-- 获取助教在指定日期的等级定价
SELECT p.*
FROM billiards_dws.cfg_assistant_level_price p
JOIN billiards_dwd.dim_assistant a ON p.level_code = a.level
WHERE a.assistant_id = 123
AND a.scd2_start_time <= '2026-01-15'
AND (a.scd2_end_time IS NULL OR a.scd2_end_time > '2026-01-15')
AND p.effective_from <= '2026-01-15'
AND p.effective_to >= '2026-01-15';
```

73
etl_billiards/docs/bd_manual/dws/BD_manual_cfg_bonus_rules.md Normal file
View File

@@ -0,0 +1,73 @@
# cfg_bonus_rules 奖金规则配置表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | cfg_bonus_rules |
| 主键 | rule_id |
| 数据来源 | 手工维护/seed脚本 |
| 说明 | 冲刺奖金（按小时阈值）和Top3排名奖金配置 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | rule_id | SERIAL | NO | PK | 规则ID（自增） |
| 2 | rule_type | VARCHAR(20) | NO | | 规则类型。**枚举值**: SPRINT（冲刺奖金）, TOP_RANK（Top排名奖金） |
| 3 | rule_code | VARCHAR(30) | NO | | 规则代码。**枚举值**: SPRINT_190, SPRINT_220, TOP_1, TOP_2, TOP_3 |
| 4 | rule_name | VARCHAR(50) | NO | | 规则名称 |
| 5 | threshold_hours | NUMERIC(10,2) | YES | | 小时数阈值（冲刺奖金用） |
| 6 | rank_position | INTEGER | YES | | 排名位置（Top奖金用） |
| 7 | bonus_amount | NUMERIC(12,2) | NO | | 奖金金额（元） |
| 8 | is_cumulative | BOOLEAN | NO | | 是否可累计（冲刺奖金为FALSE，取最高档） |
| 9 | priority | INTEGER | NO | | 优先级（数字越大优先级越高） |
| 10 | effective_from | DATE | NO | | 生效起始日期（含） |
| 11 | effective_to | DATE | NO | | 生效截止日期（含） |
| 12 | description | TEXT | YES | | 说明 |
| 13 | created_at | TIMESTAMPTZ | NO | | 创建时间 |
| 14 | updated_at | TIMESTAMPTZ | NO | | 更新时间 |
## 奖金规则示例
### 冲刺奖金（不累计，取最高档）
| 规则代码 | 小时阈值 | 奖金金额 | 优先级 |
|----------|----------|----------|--------|
| SPRINT_190 | 190小时 | 300元 | 1 |
| SPRINT_220 | 220小时 | 800元 | 2 |
### Top3排名奖金（独立发放）
| 规则代码 | 排名 | 奖金金额 |
|----------|------|----------|
| TOP_1 | 第1名 | 1000元 |
| TOP_2 | 第2名 | 600元 |
| TOP_3 | 第3名 | 400元 |
## 使用说明
**取值方式**
```sql
-- 获取冲刺奖金（取最高档）
SELECT * FROM billiards_dws.cfg_bonus_rules
WHERE rule_type = 'SPRINT'
AND threshold_hours <= 200 -- 实际小时数
AND effective_from <= '2026-01-01'
AND effective_to >= '2026-01-01'
ORDER BY priority DESC
LIMIT 1;
-- 获取Top3排名奖金
SELECT * FROM billiards_dws.cfg_bonus_rules
WHERE rule_type = 'TOP_RANK'
AND rank_position = 1 -- 排名
AND effective_from <= '2026-01-01'
AND effective_to >= '2026-01-01';
```
**排名口径说明**
- Top3排名按有效业绩小时数（effective_hours）降序排列
- 如遇并列则都算（如2个第一，则记为2个第一，下一个是第三）

71
etl_billiards/docs/bd_manual/dws/BD_manual_cfg_performance_tier.md Normal file
View File

@@ -0,0 +1,71 @@
# cfg_performance_tier 绩效档位配置表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | cfg_performance_tier |
| 主键 | tier_id |
| 数据来源 | 手工维护/seed脚本 |
| 说明 | 助教绩效档位配置，包含6档阈值、抽成比例、假期天数 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | tier_id | SERIAL | NO | PK | 档位ID（自增） |
| 2 | tier_code | VARCHAR(20) | NO | | 档位代码。**枚举值**: T0, T1, T2, T3, T4, T5, NEW |
| 3 | tier_name | VARCHAR(50) | NO | | 档位名称 |
| 4 | tier_level | INTEGER | NO | | 档位等级（数字越大档位越高） |
| 5 | min_hours | NUMERIC(10,2) | NO | | 最低业绩小时数阈值（>=） |
| 6 | max_hours | NUMERIC(10,2) | YES | | 最高业绩小时数阈值（<，NULL表示无上限） |
| 7 | base_deduction | NUMERIC(10,2) | NO | | 专业课抽成（元/小时），球房从基础课扣除 |
| 8 | bonus_deduction_ratio | NUMERIC(5,4) | NO | | 打赏课抽成比例（0-1） |
| 9 | vacation_days | INTEGER | NO | | 次月可休假天数 |
| 10 | vacation_unlimited | BOOLEAN | NO | | 是否休假自由（5档为TRUE） |
| 11 | is_new_hire_tier | BOOLEAN | NO | | 是否为新入职专用档位 |
| 12 | effective_from | DATE | NO | | 生效起始日期（含） |
| 13 | effective_to | DATE | NO | | 生效截止日期（含） |
| 14 | description | TEXT | YES | | 档位说明 |
| 15 | created_at | TIMESTAMPTZ | NO | | 创建时间 |
| 16 | updated_at | TIMESTAMPTZ | NO | | 更新时间 |
## 档位配置示例
| 档位代码 | 档位名称 | 小时数范围 | 专业课抽成 | 打赏课抽成 | 假期 |
|----------|----------|------------|------------|------------|------|
| T0 | 0档 | 0-100 | 23元/小时 | 45% | 4天 |
| T1 | 1档 | 100-130 | 20元/小时 | 42% | 5天 |
| T2 | 2档 | 130-160 | 17元/小时 | 40% | 6天 |
| T3 | 3档 | 160-190 | 13元/小时 | 35% | 7天 |
| T4 | 4档 | 190-230 | 8元/小时 | 30% | 8天 |
| T5 | 5档 | 230+ | 0元/小时 | 0% | 自由 |
| NEW | 新入职 | 任意 | 23元/小时 | 45% | 4天 |
## 使用说明
**取值方式**
按月份匹配生效的配置：
```sql
-- 获取指定月份的档位配置
SELECT * FROM billiards_dws.cfg_performance_tier
WHERE effective_from <= '2026-01-01'
AND effective_to >= '2026-01-01'
ORDER BY min_hours;
-- 根据有效业绩小时数匹配档位
SELECT * FROM billiards_dws.cfg_performance_tier
WHERE effective_from <= '2026-01-01'
AND effective_to >= '2026-01-01'
AND min_hours <= 185 -- 有效小时数
AND (max_hours IS NULL OR max_hours > 185)
LIMIT 1;
```
**薪资计算公式**
- 基础课收入 = 基础课小时数 × (客户支付价格 - base_deduction)
- 附加课收入 = 附加课小时数 × 190 × (1 - bonus_deduction_ratio)

62
etl_billiards/docs/bd_manual/dws/BD_manual_cfg_skill_type.md Normal file
View File

@@ -0,0 +1,62 @@
# cfg_skill_type 技能→课程类型映射表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | cfg_skill_type |
| 主键 | skill_type_id |
| 数据来源 | 手工维护/seed脚本 |
| 说明 | 将skill_id映射到课程类型（基础课/附加课），避免依赖skill_name文本匹配 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | skill_type_id | SERIAL | NO | PK | 映射ID（自增） |
| 2 | skill_id | BIGINT | NO | UK | 技能ID（来自dwd_assistant_service_log.skill_id） |
| 3 | skill_name | VARCHAR(50) | YES | | 技能名称（仅用于展示和校验） |
| 4 | course_type_code | VARCHAR(10) | NO | | 课程类型代码。**枚举值**: BASE（基础课）, BONUS（附加课） |
| 5 | course_type_name | VARCHAR(20) | NO | | 课程类型名称 |
| 6 | is_active | BOOLEAN | NO | | 是否启用 |
| 7 | description | TEXT | YES | | 说明 |
| 8 | created_at | TIMESTAMPTZ | NO | | 创建时间 |
| 9 | updated_at | TIMESTAMPTZ | NO | | 更新时间 |
## 技能映射示例
| skill_id | skill_name | 课程类型代码 | 课程类型名称 |
|----------|------------|--------------|--------------|
| 2791903611396869 | 陪打/PD | BASE | 基础课 |
| 2807440316432197 | 超休/CX | BONUS | 附加课 |
## 使用说明
**取值方式**
```sql
-- 将服务记录分类为基础课/附加课
SELECT
asl.*,
COALESCE(st.course_type_code, 'BASE') AS course_type_code,
COALESCE(st.course_type_name, '基础课') AS course_type_name
FROM billiards_dwd.dwd_assistant_service_log asl
LEFT JOIN billiards_dws.cfg_skill_type st
ON asl.skill_id = st.skill_id
AND st.is_active = TRUE;
-- 按课程类型汇总小时数
SELECT
COALESCE(st.course_type_code, 'BASE') AS course_type,
SUM(asl.income_seconds) / 3600.0 AS total_hours
FROM billiards_dwd.dwd_assistant_service_log asl
LEFT JOIN billiards_dws.cfg_skill_type st ON asl.skill_id = st.skill_id
GROUP BY COALESCE(st.course_type_code, 'BASE');
```
**说明**
- 基础课（陪打/PD）: 按等级定价，客户支付98-138元/小时
- 附加课（超休/CX）: 固定客户支付190元/小时，助教收入50元/小时

98
etl_billiards/docs/bd_manual/dws/BD_manual_dws_assistant_customer_stats.md Normal file
View File

@@ -0,0 +1,98 @@
# dws_assistant_customer_stats 助教服务客户统计表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_assistant_customer_stats |
| 主键 | id |
| 唯一键 | (site_id, assistant_id, member_id, stat_date) |
| 数据来源 | dwd_assistant_service_log |
| 更新频率 | 每日更新 |
| 说明 | 以"助教+客户"为粒度，统计服务关系和滚动窗口指标 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | assistant_id | BIGINT | NO | 助教ID |
| 5 | assistant_nickname | VARCHAR(50) | YES | 助教花名 |
| 6 | member_id | BIGINT | NO | 客户ID（member_id=0散客不入此表） |
| 7 | member_nickname | VARCHAR(100) | YES | 客户昵称 |
| 8 | member_mobile | VARCHAR(20) | YES | 客户手机号（脱敏） |
| 9 | stat_date | DATE | NO | 统计基准日期 |
| 10 | first_service_date | DATE | YES | 首次服务日期 |
| 11 | last_service_date | DATE | YES | 最近服务日期 |
| 12 | total_service_count | INTEGER | NO | 累计服务次数 |
| 13 | total_service_hours | NUMERIC(10,2) | NO | 累计服务小时数 |
| 14 | total_service_amount | NUMERIC(12,2) | NO | 累计服务金额 |
| 15-20 | service_count_7d/10d/15d/30d/60d/90d | INTEGER | NO | 近N天服务次数 |
| 21-26 | service_hours_7d/10d/15d/30d/60d/90d | NUMERIC(10,2) | NO | 近N天服务小时数 |
| 27-32 | service_amount_7d/10d/15d/30d/60d/90d | NUMERIC(12,2) | NO | 近N天服务金额 |
| 33 | days_since_last | INTEGER | YES | 距离最近服务的天数 |
| 34 | is_active_7d | BOOLEAN | NO | 近7天是否活跃 |
| 35 | is_active_30d | BOOLEAN | NO | 近30天是否活跃 |
| 36 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 37 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 滚动窗口计算
```sql
-- 统计每个助教-客户组合的滚动窗口指标
WITH service_data AS (
SELECT
site_id,
site_assistant_id AS assistant_id,
tenant_member_id AS member_id,
DATE(create_time) AS service_date,
COUNT(*) AS service_count,
SUM(income_seconds) / 3600.0 AS service_hours,
SUM(ledger_amount) AS service_amount
FROM billiards_dwd.dwd_assistant_service_log
WHERE is_delete = 0
AND tenant_member_id != 0 -- 排除散客
GROUP BY site_id, site_assistant_id, tenant_member_id, DATE(create_time)
)
SELECT
assistant_id,
member_id,
:stat_date AS stat_date,
MIN(service_date) AS first_service_date,
MAX(service_date) AS last_service_date,
SUM(service_count) AS total_service_count,
SUM(CASE WHEN service_date >= :stat_date - 6 THEN service_count ELSE 0 END) AS service_count_7d,
SUM(CASE WHEN service_date >= :stat_date - 29 THEN service_count ELSE 0 END) AS service_count_30d,
-- ... 其他窗口
FROM service_data
GROUP BY assistant_id, member_id;
```
## 使用说明
**散客处理**
- member_id=0 的散客不进入此表统计
- 仅统计有会员身份的客户
**活跃度判断**
```sql
-- 近7天活跃 = 近7天有服务记录
is_active_7d = (service_count_7d > 0)
-- 近30天活跃 = 近30天有服务记录
is_active_30d = (service_count_30d > 0)
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-21 ~ 至今 |
| 依赖表 | dwd_assistant_service_log, dim_member |
| 注意事项 | 滚动窗口需要足够的历史数据支撑 |

109
etl_billiards/docs/bd_manual/dws/BD_manual_dws_assistant_daily_detail.md Normal file
View File

@@ -0,0 +1,109 @@
# dws_assistant_daily_detail 助教日度业绩明细表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_assistant_daily_detail |
| 主键 | id |
| 唯一键 | (site_id, assistant_id, stat_date) |
| 数据来源 | dwd_assistant_service_log + dwd_assistant_trash_event |
| 更新频率 | 每小时增量更新 |
| 说明 | 以"助教+日期"为粒度，汇总每日业绩明细 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | assistant_id | BIGINT | NO | 助教ID（dim_assistant.assistant_id） |
| 5 | assistant_nickname | VARCHAR(50) | YES | 助教花名（冗余，便于查询展示） |
| 6 | stat_date | DATE | NO | 统计日期 |
| 7 | assistant_level_code | INTEGER | YES | 助教等级代码（SCD2口径：取stat_date当日生效的等级） |
| 8 | assistant_level_name | VARCHAR(20) | YES | 助教等级名称 |
| 9 | total_service_count | INTEGER | NO | 总服务次数 |
| 10 | base_service_count | INTEGER | NO | 基础课服务次数 |
| 11 | bonus_service_count | INTEGER | NO | 附加课服务次数 |
| 12 | total_seconds | INTEGER | NO | 总计费时长（秒） |
| 13 | base_seconds | INTEGER | NO | 基础课计费时长（秒） |
| 14 | bonus_seconds | INTEGER | NO | 附加课计费时长（秒） |
| 15 | total_hours | NUMERIC(10,2) | NO | 总计费小时数 |
| 16 | base_hours | NUMERIC(10,2) | NO | 基础课小时数 |
| 17 | bonus_hours | NUMERIC(10,2) | NO | 附加课小时数 |
| 18 | total_ledger_amount | NUMERIC(12,2) | NO | 总计费金额（元） |
| 19 | base_ledger_amount | NUMERIC(12,2) | NO | 基础课计费金额 |
| 20 | bonus_ledger_amount | NUMERIC(12,2) | NO | 附加课计费金额 |
| 21 | unique_customers | INTEGER | NO | 服务客户数（去重） |
| 22 | unique_tables | INTEGER | NO | 服务台桌数（去重） |
| 23 | trashed_seconds | INTEGER | NO | 被废除的服务时长（秒） |
| 24 | trashed_count | INTEGER | NO | 被废除的服务次数 |
| 25 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 26 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 主要来源：dwd_assistant_service_log
```sql
SELECT
site_id,
DATE(create_time) AS stat_date,
site_assistant_id AS assistant_id,
nickname AS assistant_nickname,
COUNT(*) AS total_service_count,
SUM(income_seconds) AS total_seconds,
SUM(ledger_amount) AS total_ledger_amount,
COUNT(DISTINCT tenant_member_id) AS unique_customers,
COUNT(DISTINCT site_table_id) AS unique_tables
FROM billiards_dwd.dwd_assistant_service_log
WHERE is_delete = 0
GROUP BY site_id, DATE(create_time), site_assistant_id, nickname;
```
### 废除记录：dwd_assistant_trash_event
```sql
SELECT
site_id,
DATE(create_time) AS stat_date,
assistant_no,
assistant_name,
SUM(charge_minutes_raw * 60) AS trashed_seconds,
COUNT(*) AS trashed_count
FROM billiards_dwd.dwd_assistant_trash_event
GROUP BY site_id, DATE(create_time), assistant_no, assistant_name;
```
## 使用说明
**时间分层查询**
```sql
-- 近2天
SELECT * FROM billiards_dws.dws_assistant_daily_detail
WHERE stat_date >= CURRENT_DATE - 1;
-- 近1月
SELECT * FROM billiards_dws.dws_assistant_daily_detail
WHERE stat_date >= CURRENT_DATE - INTERVAL '1 month';
-- 月度汇总
SELECT
assistant_id,
DATE_TRUNC('month', stat_date) AS stat_month,
SUM(total_hours) AS total_hours,
SUM(base_hours) AS base_hours,
SUM(bonus_hours) AS bonus_hours
FROM billiards_dws.dws_assistant_daily_detail
GROUP BY assistant_id, DATE_TRUNC('month', stat_date);
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-21 ~ 至今 |
| 依赖表 | dwd_assistant_service_log, dwd_assistant_trash_event, dim_assistant |

88
etl_billiards/docs/bd_manual/dws/BD_manual_dws_assistant_finance_analysis.md Normal file
View File

@@ -0,0 +1,88 @@
# dws_assistant_finance_analysis 助教收支分析表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_assistant_finance_analysis |
| 主键 | id |
| 唯一键 | (site_id, stat_date, assistant_id) |
| 数据来源 | dwd_assistant_service_log + dws_assistant_salary_calc |
| 更新频率 | 每日更新 |
| 说明 | 以"日期+助教"为粒度，分析助教产出的收入和成本 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | stat_date | DATE | NO | 统计日期 |
| 5 | assistant_id | BIGINT | NO | 助教ID |
| 6 | assistant_nickname | VARCHAR(50) | YES | 助教花名 |
| 7 | revenue_total | NUMERIC(14,2) | NO | 助教产出收入（ledger_amount汇总） |
| 8 | revenue_base | NUMERIC(14,2) | NO | 基础课收入 |
| 9 | revenue_bonus | NUMERIC(14,2) | NO | 附加课收入 |
| 10 | cost_daily | NUMERIC(14,2) | NO | 日均工资成本（月工资/工作天数） |
| 11 | gross_profit | NUMERIC(14,2) | NO | 毛利 = 收入 - 成本 |
| 12 | gross_margin | NUMERIC(5,4) | NO | 毛利率 |
| 13 | service_count | INTEGER | NO | 服务次数 |
| 14 | service_hours | NUMERIC(10,2) | NO | 服务小时数 |
| 15 | unique_customers | INTEGER | NO | 服务客户数 |
| 16 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 17 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 收入来源：dwd_assistant_service_log
```sql
SELECT
DATE(create_time) AS stat_date,
site_assistant_id AS assistant_id,
SUM(ledger_amount) AS revenue_total,
SUM(CASE WHEN skill_id = 2791903611396869 THEN ledger_amount ELSE 0 END) AS revenue_base,
SUM(CASE WHEN skill_id = 2807440316432197 THEN ledger_amount ELSE 0 END) AS revenue_bonus,
COUNT(*) AS service_count,
SUM(income_seconds) / 3600.0 AS service_hours,
COUNT(DISTINCT tenant_member_id) AS unique_customers
FROM billiards_dwd.dwd_assistant_service_log
WHERE is_delete = 0
GROUP BY DATE(create_time), site_assistant_id;
```
### 成本来源：dws_assistant_salary_calc
```sql
-- 日均成本 = 月度应发工资 / 当月工作天数
SELECT
assistant_id,
salary_month,
gross_salary / NULLIF(work_days, 0) AS cost_daily
FROM billiards_dws.dws_assistant_salary_calc sc
JOIN billiards_dws.dws_assistant_monthly_summary ms
ON sc.assistant_id = ms.assistant_id AND sc.salary_month = ms.stat_month;
```
## 使用说明
**毛利计算**
```
gross_profit = revenue_total - cost_daily
gross_margin = gross_profit / NULLIF(revenue_total, 0)
```
**注意事项**
- cost_daily 基于月度工资分摊，非实际日薪
- 当月数据在月末工资计算前 cost_daily 可能不准确
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ⚠️ 部分可回溯 |
| 数据范围 | 2025-07-21 ~ 至今 |
| 依赖表 | dwd_assistant_service_log, dws_assistant_salary_calc |
| 限制 | cost_daily 依赖 salary_calc，需先完成薪资计算 |

110
etl_billiards/docs/bd_manual/dws/BD_manual_dws_assistant_monthly_summary.md Normal file
View File

@@ -0,0 +1,110 @@
# dws_assistant_monthly_summary 助教月度业绩汇总表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_assistant_monthly_summary |
| 主键 | id |
| 唯一键 | (site_id, assistant_id, stat_month) |
| 数据来源 | dws_assistant_daily_detail 聚合 + cfg_performance_tier |
| 更新频率 | 每日更新当月数据 |
| 说明 | 以"助教+月份"为粒度，汇总月度业绩及档位计算 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | assistant_id | BIGINT | NO | 助教ID |
| 5 | assistant_nickname | VARCHAR(50) | YES | 助教花名 |
| 6 | stat_month | DATE | NO | 统计月份（月第一天，如2026-01-01） |
| 7 | assistant_level_code | INTEGER | YES | 助教等级代码（月末时点） |
| 8 | assistant_level_name | VARCHAR(20) | YES | 助教等级名称 |
| 9 | hire_date | DATE | YES | 入职日期 |
| 10 | is_new_hire | BOOLEAN | NO | 是否新入职（入职日期 >= 月1日0点） |
| 11 | work_days | INTEGER | NO | 有服务天数 |
| 12 | total_service_count | INTEGER | NO | 总服务次数 |
| 13 | base_service_count | INTEGER | NO | 基础课服务次数 |
| 14 | bonus_service_count | INTEGER | NO | 附加课服务次数 |
| 15 | total_hours | NUMERIC(10,2) | NO | 总计费小时数 |
| 16 | base_hours | NUMERIC(10,2) | NO | 基础课小时数 |
| 17 | bonus_hours | NUMERIC(10,2) | NO | 附加课小时数 |
| 18 | effective_hours | NUMERIC(10,2) | NO | 有效业绩小时数（影响档位）= total_hours - trashed_hours |
| 19 | trashed_hours | NUMERIC(10,2) | NO | 被废除小时数 |
| 20 | total_ledger_amount | NUMERIC(12,2) | NO | 总计费金额 |
| 21 | base_ledger_amount | NUMERIC(12,2) | NO | 基础课计费金额 |
| 22 | bonus_ledger_amount | NUMERIC(12,2) | NO | 附加课计费金额 |
| 23 | unique_customers | INTEGER | NO | 月度服务客户数（去重） |
| 24 | unique_tables | INTEGER | NO | 月度服务台桌数（去重） |
| 25 | avg_service_seconds | NUMERIC(10,2) | NO | 平均单次服务时长（秒） |
| 26 | tier_id | INTEGER | YES | 匹配的档位ID |
| 27 | tier_code | VARCHAR(20) | YES | 档位代码（T0-T5/NEW） |
| 28 | tier_name | VARCHAR(50) | YES | 档位名称 |
| 29 | rank_by_hours | INTEGER | YES | 月度排名（按effective_hours降序） |
| 30 | rank_with_ties | INTEGER | YES | 考虑并列的排名 |
| 31 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 32 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 从日度明细聚合
```sql
SELECT
site_id,
tenant_id,
assistant_id,
DATE_TRUNC('month', stat_date)::DATE AS stat_month,
COUNT(DISTINCT stat_date) AS work_days,
SUM(total_service_count) AS total_service_count,
SUM(base_service_count) AS base_service_count,
SUM(bonus_service_count) AS bonus_service_count,
SUM(total_hours) AS total_hours,
SUM(base_hours) AS base_hours,
SUM(bonus_hours) AS bonus_hours,
SUM(trashed_seconds) / 3600.0 AS trashed_hours
FROM billiards_dws.dws_assistant_daily_detail
GROUP BY site_id, tenant_id, assistant_id, DATE_TRUNC('month', stat_date);
```
### 档位匹配
```sql
-- 根据有效业绩匹配档位
SELECT * FROM billiards_dws.cfg_performance_tier
WHERE min_hours <= :effective_hours
AND (max_hours IS NULL OR max_hours > :effective_hours)
AND effective_from <= :stat_month
AND effective_to >= :stat_month
AND is_new_hire_tier = :is_new_hire
LIMIT 1;
```
## 使用说明
**新入职判断**
- 入职日期 >= 统计月1日0点 则为新入职
- 新入职使用NEW档位配置
**排名计算**
```sql
-- rank_with_ties: 并列排名（如2个第一则都是1，下一个是3）
SELECT
assistant_id,
effective_hours,
RANK() OVER (ORDER BY effective_hours DESC) AS rank_with_ties
FROM billiards_dws.dws_assistant_monthly_summary
WHERE stat_month = '2026-01-01';
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025年8月起（需要完整月数据） |
| 依赖表 | dws_assistant_daily_detail, cfg_performance_tier, dim_assistant |

84
etl_billiards/docs/bd_manual/dws/BD_manual_dws_assistant_recharge_commission.md Normal file
View File

@@ -0,0 +1,84 @@
# dws_assistant_recharge_commission 助教充值提成表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_assistant_recharge_commission |
| 主键 | id |
| 数据来源 | Excel手动导入 |
| 更新频率 | 按需导入 |
| 说明 | 以"助教+月份+充值订单"为粒度，记录充值提成 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | assistant_id | BIGINT | NO | 助教ID |
| 5 | assistant_nickname | VARCHAR(50) | YES | 助教花名 |
| 6 | commission_month | DATE | NO | 提成月份（月第一天） |
| 7 | recharge_order_id | BIGINT | YES | 充值订单ID |
| 8 | recharge_order_no | VARCHAR(50) | YES | 充值订单号 |
| 9 | recharge_amount | NUMERIC(12,2) | NO | 充值订单金额 |
| 10 | commission_amount | NUMERIC(12,2) | NO | 提成金额 |
| 11 | commission_ratio | NUMERIC(5,4) | YES | 提成比例 |
| 12 | import_batch_no | VARCHAR(50) | YES | 导入批次号 |
| 13 | import_file_name | VARCHAR(200) | YES | 导入文件名 |
| 14 | import_time | TIMESTAMPTZ | YES | 导入时间 |
| 15 | import_user | VARCHAR(50) | YES | 导入操作人 |
| 16 | remark | TEXT | YES | 备注 |
| 17 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 18 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## Excel导入模板
| 月份 | 助教号 | 助教花名 | 充值订单金额 | 提成金额 | 备注 |
|------|--------|----------|--------------|----------|------|
| 2026-01 | 1 | 小燕 | 5000.00 | 300.00 | ge |
| 2026-01 | 2 | 小明 | 3000.00 | 180.00 | 续充 |
### 导入规则
- **月份**: 必填，格式 2026-01 或 2026/01/01
- **助教号**: 必填，数字（如 1, 2, 31）
- **助教花名**: 必填，与助教号组合确定唯一助教
- **充值订单金额**: 选填，单位：元
- **提成金额**: 必填，单位：元
- **备注**: 选填
### 助教匹配逻辑
```sql
-- 通过 assistant_no + nickname 查找 assistant_id
SELECT assistant_id
FROM billiards_dwd.dim_assistant
WHERE assistant_no = :assistant_no
AND nickname = :nickname
AND scd2_is_current = 1;
```
## 使用说明
**汇总到薪资计算**
```sql
-- 获取助教某月的充值提成总额
SELECT
assistant_id,
commission_month,
SUM(commission_amount) AS total_commission
FROM billiards_dws.dws_assistant_recharge_commission
WHERE commission_month = '2026-01-01'
GROUP BY assistant_id, commission_month;
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ❌ 不可自动回溯 |
| 原因 | 数据来源为Excel手工导入，DWD层无此数据 |
| 处理 | 需要人工补录历史数据 |

98
etl_billiards/docs/bd_manual/dws/BD_manual_dws_assistant_salary_calc.md Normal file
View File

@@ -0,0 +1,98 @@
# dws_assistant_salary_calc 助教工资计算详情表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_assistant_salary_calc |
| 主键 | id |
| 唯一键 | (site_id, assistant_id, salary_month) |
| 数据来源 | dws_assistant_monthly_summary + cfg_* 配置表 |
| 更新频率 | 月初计算上月工资 |
| 说明 | 以"助教+月份"为粒度，计算月度工资明细 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | assistant_id | BIGINT | NO | 助教ID |
| 5 | assistant_nickname | VARCHAR(50) | YES | 助教花名 |
| 6 | salary_month | DATE | NO | 工资月份（月第一天） |
| 7 | assistant_level_code | INTEGER | YES | 助教等级代码 |
| 8 | assistant_level_name | VARCHAR(20) | YES | 助教等级名称 |
| 9 | hire_date | DATE | YES | 入职日期 |
| 10 | is_new_hire | BOOLEAN | NO | 是否新入职 |
| 11 | effective_hours | NUMERIC(10,2) | NO | 有效业绩小时数 |
| 12 | base_hours | NUMERIC(10,2) | NO | 基础课小时数 |
| 13 | bonus_hours | NUMERIC(10,2) | NO | 附加课小时数 |
| 14 | tier_id | INTEGER | YES | 档位ID |
| 15 | tier_code | VARCHAR(20) | YES | 档位代码 |
| 16 | tier_name | VARCHAR(50) | YES | 档位名称 |
| 17 | rank_with_ties | INTEGER | YES | 月度排名（考虑并列） |
| 18 | base_course_price | NUMERIC(10,2) | NO | 基础课客户支付价格 |
| 19 | bonus_course_price | NUMERIC(10,2) | NO | 附加课客户支付价格（固定190） |
| 20 | base_deduction | NUMERIC(10,2) | NO | 专业课抽成（元/小时） |
| 21 | bonus_deduction_ratio | NUMERIC(5,4) | NO | 打赏课抽成比例 |
| 22 | base_income | NUMERIC(12,2) | NO | 基础课收入 |
| 23 | bonus_income | NUMERIC(12,2) | NO | 附加课收入 |
| 24 | total_course_income | NUMERIC(12,2) | NO | 课时收入合计 |
| 25 | sprint_bonus | NUMERIC(12,2) | NO | 冲刺奖金 |
| 26 | top_rank_bonus | NUMERIC(12,2) | NO | Top3排名奖金 |
| 27 | recharge_commission | NUMERIC(12,2) | NO | 充值提成 |
| 28 | other_bonus | NUMERIC(12,2) | NO | 其他奖金 |
| 29 | total_bonus | NUMERIC(12,2) | NO | 奖金合计 |
| 30 | gross_salary | NUMERIC(12,2) | NO | 应发工资 |
| 31 | vacation_days | INTEGER | NO | 次月可休假天数 |
| 32 | vacation_unlimited | BOOLEAN | NO | 休假自由标记 |
| 33 | calc_notes | TEXT | YES | 计算备注 |
| 34 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 35 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 工资计算公式
### 课时收入
```
基础课收入 = base_hours × (base_course_price - base_deduction)
附加课收入 = bonus_hours × 190 × (1 - bonus_deduction_ratio)
课时收入合计 = 基础课收入 + 附加课收入
```
### 奖金
```
冲刺奖金: H>=190得300元, H>=220得800元（不累计取最高）
Top3奖金: 1st=1000元, 2nd=600元, 3rd=400元
充值提成: 来自dws_assistant_recharge_commission
```
### 应发工资
```
gross_salary = total_course_income + total_bonus
```
## 计算示例
| 项目 | 数值 | 计算过程 |
|------|------|----------|
| 基础课小时数 | 170 | 来自monthly_summary |
| 附加课小时数 | 15 | 来自monthly_summary |
| 等级 | 中级(20) | base_course_price=108 |
| 档位 | T3 | base_deduction=13, bonus_ratio=0.35 |
| 基础课收入 | 16,150 | 170 × (108-13) |
| 附加课收入 | 1,852.5 | 15 × 190 × 0.65 |
| 冲刺奖金 | 300 | 185>=190 |
| 应发工资 | 18,302.5 | 16,150 + 1,852.5 + 300 |
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ⚠️ 部分可回溯 |
| 数据范围 | 2025年8月起 |
| 依赖表 | dws_assistant_monthly_summary, cfg_*, dws_assistant_recharge_commission |
| 限制 | 充值提成需手工导入历史数据 |

125
etl_billiards/docs/bd_manual/dws/BD_manual_dws_finance_daily_summary.md Normal file
View File

@@ -0,0 +1,125 @@
# dws_finance_daily_summary 财务日度汇总表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_finance_daily_summary |
| 主键 | id |
| 唯一键 | (site_id, stat_date) |
| 数据来源 | dwd_settlement_head + 多个DWD事实表 |
| 更新频率 | 每小时更新当日数据 |
| 说明 | 以"日期"为粒度，汇总当日财务数据 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | stat_date | DATE | NO | 统计日期 |
| 5 | gross_amount | NUMERIC(14,2) | NO | 发生额合计 |
| 6 | table_fee_amount | NUMERIC(14,2) | NO | 台费正价 |
| 7 | goods_amount | NUMERIC(14,2) | NO | 商品正价 |
| 8 | assistant_pd_amount | NUMERIC(14,2) | NO | 助教基础课正价（陪打） |
| 9 | assistant_cx_amount | NUMERIC(14,2) | NO | 助教激励课正价（超休） |
| 10 | discount_total | NUMERIC(14,2) | NO | 优惠合计 |
| 11 | discount_groupbuy | NUMERIC(14,2) | NO | 团购优惠 |
| 12 | discount_vip | NUMERIC(14,2) | NO | 会员折扣 |
| 13 | discount_gift_card | NUMERIC(14,2) | NO | 赠送卡抵扣 |
| 14 | discount_manual | NUMERIC(14,2) | NO | 手动调整 |
| 15 | discount_rounding | NUMERIC(14,2) | NO | 抹零 |
| 16 | discount_other | NUMERIC(14,2) | NO | 其他优惠 |
| 17 | confirmed_income | NUMERIC(14,2) | NO | 确认收入 = 发生额 - 优惠 |
| 18 | cash_inflow_total | NUMERIC(14,2) | NO | 现金流入合计 |
| 19 | cash_pay_amount | NUMERIC(14,2) | NO | 收银实付 |
| 20 | groupbuy_pay_amount | NUMERIC(14,2) | NO | 团购支付金额 |
| 21 | platform_settlement_amount | NUMERIC(14,2) | NO | 平台回款金额（导入） |
| 22 | platform_fee_amount | NUMERIC(14,2) | NO | 平台佣金+服务费（导入） |
| 23 | recharge_cash_inflow | NUMERIC(14,2) | NO | 充值现金流入 |
| 24 | card_consume_total | NUMERIC(14,2) | NO | 卡消费合计 |
| 25 | cash_card_consume | NUMERIC(14,2) | NO | 储值卡消费 |
| 26 | gift_card_consume | NUMERIC(14,2) | NO | 赠送卡消费 |
| 27 | cash_outflow_total | NUMERIC(14,2) | NO | 现金流出合计 |
| 28 | cash_balance_change | NUMERIC(14,2) | NO | 现金余额变动 |
| 29 | recharge_count | INTEGER | NO | 充值笔数 |
| 30 | recharge_total | NUMERIC(14,2) | NO | 充值总额（含赠送） |
| 31 | recharge_cash | NUMERIC(14,2) | NO | 充值现金部分 |
| 32 | recharge_gift | NUMERIC(14,2) | NO | 充值赠送部分 |
| 33 | first_recharge_count | INTEGER | NO | 首充笔数 |
| 34 | first_recharge_amount | NUMERIC(14,2) | NO | 首充金额 |
| 35 | renewal_count | INTEGER | NO | 续充笔数 |
| 36 | renewal_amount | NUMERIC(14,2) | NO | 续充金额 |
| 37 | order_count | INTEGER | NO | 结账单数 |
| 38 | member_order_count | INTEGER | NO | 会员订单数 |
| 39 | guest_order_count | INTEGER | NO | 散客订单数 |
| 40 | avg_order_amount | NUMERIC(12,2) | NO | 平均客单价 |
| 41 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 42 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 结账汇总：dwd_settlement_head
```sql
SELECT
DATE(pay_time) AS stat_date,
SUM(table_charge_money) AS table_fee_amount,
SUM(goods_money) AS goods_amount,
SUM(assistant_pd_money) AS assistant_pd_amount,
SUM(assistant_cx_money) AS assistant_cx_amount,
SUM(member_discount_amount) AS discount_vip,
SUM(adjust_amount) AS discount_manual,
SUM(rounding_amount) AS discount_rounding,
SUM(pay_amount) AS cash_pay_amount,
SUM(balance_amount) AS cash_card_consume,
SUM(gift_card_amount) AS gift_card_consume,
COUNT(*) AS order_count
FROM billiards_dwd.dwd_settlement_head
WHERE settle_type = 1
GROUP BY DATE(pay_time);
```
### 团购核销：dwd_groupbuy_redemption
```sql
SELECT
DATE(create_time) AS stat_date,
SUM(coupon_money) AS groupbuy_pay_amount
FROM billiards_dwd.dwd_groupbuy_redemption
WHERE is_delete = 0
GROUP BY DATE(create_time);
```
### 充值订单：dwd_recharge_order
```sql
SELECT
DATE(pay_time) AS stat_date,
COUNT(*) AS recharge_count,
SUM(pay_amount) AS recharge_cash,
SUM(point_amount) AS recharge_gift,
SUM(CASE WHEN is_first = 1 THEN 1 ELSE 0 END) AS first_recharge_count
FROM billiards_dwd.dwd_recharge_order
GROUP BY DATE(pay_time);
```
## 使用说明
**计算公式**
```
gross_amount = table_fee_amount + goods_amount + assistant_pd_amount + assistant_cx_amount
discount_total = discount_groupbuy + discount_vip + discount_gift_card + discount_manual + discount_rounding + discount_other
confirmed_income = gross_amount - discount_total
cash_inflow_total = cash_pay_amount + groupbuy_pay_amount + platform_settlement_amount + recharge_cash_inflow
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-16 ~ 至今 |
| 依赖表 | dwd_settlement_head, dwd_groupbuy_redemption, dwd_recharge_order, dws_platform_settlement |
| 注意 | platform_settlement需Excel导入 |

90
etl_billiards/docs/bd_manual/dws/BD_manual_dws_finance_discount_detail.md Normal file
View File

@@ -0,0 +1,90 @@
# dws_finance_discount_detail 优惠明细表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_finance_discount_detail |
| 主键 | id |
| 唯一键 | (site_id, stat_date, discount_type_code) |
| 数据来源 | dwd_settlement_head + dwd_groupbuy_redemption |
| 更新频率 | 每日更新 |
| 说明 | 以"日期+优惠类型"为粒度，分析优惠构成 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | stat_date | DATE | NO | 统计日期 |
| 5 | discount_type_code | VARCHAR(30) | NO | 优惠类型代码 |
| 6 | discount_type_name | VARCHAR(50) | NO | 优惠类型名称 |
| 7 | discount_amount | NUMERIC(14,2) | NO | 优惠金额 |
| 8 | discount_ratio | NUMERIC(5,4) | NO | 优惠占比（占总优惠） |
| 9 | usage_count | INTEGER | NO | 使用次数 |
| 10 | affected_orders | INTEGER | NO | 影响订单数 |
| 11 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 12 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 优惠类型说明
| discount_type_code | discount_type_name | 数据来源 |
|--------------------|--------------------|----------|
| GROUPBUY | 团购优惠 | dwd_settlement_head.coupon_amount |
| VIP | 会员折扣 | dwd_settlement_head.member_discount_amount |
| GIFT_CARD | 赠送卡抵扣 | dwd_settlement_head.gift_card_amount |
| MANUAL | 手动调整 | dwd_settlement_head.adjust_amount |
| ROUNDING | 抹零 | dwd_settlement_head.rounding_amount |
| BIG_CUSTOMER | 大客户优惠 | dwd_settlement_head（特定会员优惠） |
| OTHER | 其他优惠 | 其他无法归类的优惠 |
## 数据来源
```sql
-- 从结账头表提取各类优惠
SELECT
DATE(pay_time) AS stat_date,
'VIP' AS discount_type_code,
'会员折扣' AS discount_type_name,
SUM(member_discount_amount) AS discount_amount,
COUNT(CASE WHEN member_discount_amount > 0 THEN 1 END) AS usage_count,
COUNT(DISTINCT CASE WHEN member_discount_amount > 0 THEN order_settle_id END) AS affected_orders
FROM billiards_dwd.dwd_settlement_head
WHERE settle_type = 1
GROUP BY DATE(pay_time)
UNION ALL
SELECT
DATE(pay_time) AS stat_date,
'GROUPBUY' AS discount_type_code,
'团购优惠' AS discount_type_name,
SUM(coupon_amount) AS discount_amount,
COUNT(CASE WHEN coupon_amount > 0 THEN 1 END) AS usage_count,
COUNT(DISTINCT CASE WHEN coupon_amount > 0 THEN order_settle_id END) AS affected_orders
FROM billiards_dwd.dwd_settlement_head
WHERE settle_type = 1
GROUP BY DATE(pay_time)
-- ... 其他优惠类型
```
## 使用说明
**占比计算**
```sql
discount_ratio = discount_amount / SUM(discount_amount) OVER (PARTITION BY stat_date)
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-16 ~ 至今 |
| 依赖表 | dwd_settlement_head, dwd_groupbuy_redemption |

87
etl_billiards/docs/bd_manual/dws/BD_manual_dws_finance_expense_summary.md Normal file
View File

@@ -0,0 +1,87 @@
# dws_finance_expense_summary 支出结构表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_finance_expense_summary |
| 主键 | id |
| 唯一键 | (site_id, expense_month, expense_type_code, import_batch_no) |
| 数据来源 | Excel手动导入 |
| 更新频率 | 按需导入 |
| 说明 | 以"月份+支出类型"为粒度，记录支出数据 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | expense_month | DATE | NO | 支出月份（月第一天） |
| 5 | expense_type_code | VARCHAR(30) | NO | 支出类型代码 |
| 6 | expense_type_name | VARCHAR(50) | NO | 支出类型名称 |
| 7 | expense_category | VARCHAR(20) | YES | 支出大类 |
| 8 | expense_amount | NUMERIC(14,2) | NO | 支出金额 |
| 9 | expense_detail | TEXT | YES | 支出明细说明 |
| 10 | import_batch_no | VARCHAR(50) | YES | 导入批次号 |
| 11 | import_file_name | VARCHAR(200) | YES | 导入文件名 |
| 12 | import_time | TIMESTAMPTZ | YES | 导入时间 |
| 13 | import_user | VARCHAR(50) | YES | 导入操作人 |
| 14 | remark | TEXT | YES | 备注 |
| 15 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 16 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 支出类型说明
| expense_type_code | expense_type_name | expense_category |
|-------------------|-------------------|------------------|
| RENT | 房租 | FIXED_COST |
| UTILITY | 水电费 | FIXED_COST |
| PROPERTY | 物业费 | FIXED_COST |
| SALARY | 工资 | VARIABLE_COST |
| REIMBURSE | 报销 | VARIABLE_COST |
| PLATFORM_FEE | 平台费用 | VARIABLE_COST |
| MAINTENANCE | 维修保养 | VARIABLE_COST |
| CONSUMABLES | 耗材 | VARIABLE_COST |
| MARKETING | 营销费用 | VARIABLE_COST |
| OTHER | 其他 | OTHER |
## Excel导入模板
| 月份 | 支出类型 | 支出金额 | 明细说明 | 备注 |
|------|----------|----------|----------|------|
| 2026-01 | 房租 | 50000.00 | 1月房租 | |
| 2026-01 | 水电费 | 8000.00 | 1月水电 | |
| 2026-01 | 工资 | 120000.00 | 员工工资 | |
### 导入规则
- **月份**: 必填，格式 2026-01 或 2026/01/01
- **支出类型**: 必填，需匹配支出类型名称
- **支出金额**: 必填，单位：元
- **明细说明**: 选填
- **备注**: 选填
## 使用说明
**月度支出汇总**
```sql
SELECT
expense_month,
expense_category,
SUM(expense_amount) AS total_expense
FROM billiards_dws.dws_finance_expense_summary
GROUP BY expense_month, expense_category
ORDER BY expense_month, expense_category;
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ❌ 不可自动回溯 |
| 原因 | 数据来源为Excel手工导入，DWD层无此数据 |
| 处理 | 需要人工补录历史数据 |

88
etl_billiards/docs/bd_manual/dws/BD_manual_dws_finance_income_structure.md Normal file
View File

@@ -0,0 +1,88 @@
# dws_finance_income_structure 收入结构分析表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_finance_income_structure |
| 主键 | id |
| 唯一键 | (site_id, stat_date, structure_type, category_code) |
| 数据来源 | dwd_table_fee_log + dwd_assistant_service_log + cfg_area_category |
| 更新频率 | 每日更新 |
| 说明 | 以"日期+区域/类型"为粒度，分析收入结构 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | stat_date | DATE | NO | 统计日期 |
| 5 | structure_type | VARCHAR(20) | NO | 结构类型。**枚举值**: AREA（区域）, INCOME_TYPE（收入类型） |
| 6 | category_code | VARCHAR(30) | NO | 分类代码 |
| 7 | category_name | VARCHAR(50) | NO | 分类名称 |
| 8 | income_amount | NUMERIC(14,2) | NO | 收入金额 |
| 9 | income_ratio | NUMERIC(5,4) | NO | 收入占比 |
| 10 | order_count | INTEGER | NO | 订单数 |
| 11 | duration_minutes | INTEGER | NO | 时长（分钟） |
| 12 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 13 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 分类代码说明
### 按区域分析 (structure_type = 'AREA')
| category_code | category_name | 来源 |
|---------------|---------------|------|
| BILLIARD | 台球散台 | A区/B区/C区/TV台 |
| BILLIARD_VIP | 台球VIP | VIP包厢 |
| SNOOKER | 斯诺克 | 斯诺克区 |
| MAHJONG | 麻将棋牌 | 麻将房/M7/M8/666/发财 |
| KTV | K歌娱乐 | K包/k包活动区/幸会158 |
| SPECIAL | 补时长 | 补时长 |
| OTHER | 其他 | 未映射区域 |
### 按收入类型分析 (structure_type = 'INCOME_TYPE')
| category_code | category_name |
|---------------|---------------|
| TABLE_FEE | 台费收入 |
| GOODS | 商品收入 |
| ASSISTANT_BASE | 助教基础课收入 |
| ASSISTANT_BONUS | 助教附加课收入 |
## 数据来源
### 按区域汇总台费
```sql
SELECT
DATE(tfl.ledger_end_time) AS stat_date,
COALESCE(ac.category_code, 'OTHER') AS category_code,
COALESCE(ac.category_name, '其他') AS category_name,
SUM(tfl.ledger_amount) AS income_amount,
SUM(tfl.ledger_count) AS duration_seconds,
COUNT(DISTINCT tfl.order_settle_id) AS order_count
FROM billiards_dwd.dwd_table_fee_log tfl
LEFT JOIN billiards_dwd.dim_table dt ON dt.table_id = tfl.site_table_id
LEFT JOIN billiards_dws.cfg_area_category ac ON dt.site_table_area_name = ac.source_area_name
WHERE tfl.is_delete = 0
GROUP BY DATE(tfl.ledger_end_time), COALESCE(ac.category_code, 'OTHER'), COALESCE(ac.category_name, '其他');
```
## 使用说明
**占比计算**
```sql
-- income_ratio = 当前分类收入 / 当日总收入
income_ratio = income_amount / SUM(income_amount) OVER (PARTITION BY stat_date, structure_type)
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-21 ~ 至今 |
| 依赖表 | dwd_table_fee_log, dwd_assistant_service_log, dim_table, cfg_area_category |

95
etl_billiards/docs/bd_manual/dws/BD_manual_dws_finance_recharge_summary.md Normal file
View File

@@ -0,0 +1,95 @@
# dws_finance_recharge_summary 充值统计表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_finance_recharge_summary |
| 主键 | id |
| 唯一键 | (site_id, stat_date) |
| 数据来源 | dwd_recharge_order |
| 更新频率 | 每日更新 |
| 说明 | 以"日期"为粒度，统计充值数据，区分首充/续充 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | stat_date | DATE | NO | 统计日期 |
| 5 | recharge_count | INTEGER | NO | 充值笔数 |
| 6 | recharge_total | NUMERIC(14,2) | NO | 充值总额（含赠送） |
| 7 | recharge_cash | NUMERIC(14,2) | NO | 现金充值金额 |
| 8 | recharge_gift | NUMERIC(14,2) | NO | 赠送金额 |
| 9 | first_recharge_count | INTEGER | NO | 首充笔数 |
| 10 | first_recharge_cash | NUMERIC(14,2) | NO | 首充现金 |
| 11 | first_recharge_gift | NUMERIC(14,2) | NO | 首充赠送 |
| 12 | first_recharge_total | NUMERIC(14,2) | NO | 首充总额 |
| 13 | renewal_count | INTEGER | NO | 续充笔数 |
| 14 | renewal_cash | NUMERIC(14,2) | NO | 续充现金 |
| 15 | renewal_gift | NUMERIC(14,2) | NO | 续充赠送 |
| 16 | renewal_total | NUMERIC(14,2) | NO | 续充总额 |
| 17 | recharge_member_count | INTEGER | NO | 充值会员数（去重） |
| 18 | new_member_count | INTEGER | NO | 新增会员数 |
| 19 | total_card_balance | NUMERIC(14,2) | NO | 全部会员卡余额（当日末） |
| 20 | cash_card_balance | NUMERIC(14,2) | NO | 储值卡余额 |
| 21 | gift_card_balance | NUMERIC(14,2) | NO | 赠送卡余额 |
| 22 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 23 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 充值订单：dwd_recharge_order
```sql
SELECT
DATE(pay_time) AS stat_date,
COUNT(*) AS recharge_count,
SUM(pay_amount + point_amount) AS recharge_total,
SUM(pay_amount) AS recharge_cash,
SUM(point_amount) AS recharge_gift,
-- 首充
SUM(CASE WHEN is_first = 1 THEN 1 ELSE 0 END) AS first_recharge_count,
SUM(CASE WHEN is_first = 1 THEN pay_amount ELSE 0 END) AS first_recharge_cash,
SUM(CASE WHEN is_first = 1 THEN point_amount ELSE 0 END) AS first_recharge_gift,
-- 续充
SUM(CASE WHEN is_first = 0 THEN 1 ELSE 0 END) AS renewal_count,
SUM(CASE WHEN is_first = 0 THEN pay_amount ELSE 0 END) AS renewal_cash,
-- 会员数
COUNT(DISTINCT member_id) AS recharge_member_count
FROM billiards_dwd.dwd_recharge_order
GROUP BY DATE(pay_time);
```
### 卡余额快照：dim_member_card_account
```sql
-- 截至stat_date当日末的卡余额
SELECT
SUM(balance) AS total_card_balance,
SUM(CASE WHEN card_type_id = 2793249295533893 THEN balance ELSE 0 END) AS cash_card_balance,
SUM(CASE WHEN card_type_id != 2793249295533893 THEN balance ELSE 0 END) AS gift_card_balance
FROM billiards_dwd.dim_member_card_account
WHERE scd2_start_time <= :stat_date + INTERVAL '1 day'
AND (scd2_end_time IS NULL OR scd2_end_time > :stat_date + INTERVAL '1 day');
```
## 使用说明
**首充判断**
- is_first = 1: 首充
- is_first = 0: 续充
**储值卡ID**
- 储值卡 card_type_id = 2793249295533893
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-21 ~ 至今 |
| 依赖表 | dwd_recharge_order, dim_member_card_account |

102
etl_billiards/docs/bd_manual/dws/BD_manual_dws_member_consumption_summary.md Normal file
View File

@@ -0,0 +1,102 @@
# dws_member_consumption_summary 会员消费汇总表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_member_consumption_summary |
| 主键 | id |
| 唯一键 | (site_id, member_id, stat_date) |
| 数据来源 | dwd_settlement_head + 关联明细表 |
| 更新频率 | 每日更新 |
| 说明 | 以"会员"为粒度，统计消费行为和滚动窗口指标 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | member_id | BIGINT | NO | 会员ID（member_id=0散客不入此表） |
| 5 | stat_date | DATE | NO | 统计基准日期 |
| 6 | member_nickname | VARCHAR(100) | YES | 会员昵称 |
| 7 | member_mobile | VARCHAR(20) | YES | 手机号（脱敏） |
| 8 | card_grade_name | VARCHAR(50) | YES | 卡等级名称 |
| 9 | register_date | DATE | YES | 注册日期 |
| 10 | first_consume_date | DATE | YES | 首次消费日期 |
| 11 | last_consume_date | DATE | YES | 最近消费日期 |
| 12 | total_visit_count | INTEGER | NO | 累计到店次数 |
| 13 | total_consume_amount | NUMERIC(14,2) | NO | 累计消费金额 |
| 14 | total_recharge_amount | NUMERIC(14,2) | NO | 累计充值金额 |
| 15 | total_table_fee | NUMERIC(14,2) | NO | 累计台费 |
| 16 | total_goods_amount | NUMERIC(14,2) | NO | 累计商品消费 |
| 17 | total_assistant_amount | NUMERIC(14,2) | NO | 累计助教服务消费 |
| 18-23 | visit_count_7d/10d/15d/30d/60d/90d | INTEGER | NO | 近N天到店次数 |
| 24-29 | consume_amount_7d/10d/15d/30d/60d/90d | NUMERIC(14,2) | NO | 近N天消费金额 |
| 30 | cash_card_balance | NUMERIC(14,2) | NO | 储值卡余额 |
| 31 | gift_card_balance | NUMERIC(14,2) | NO | 赠送卡余额 |
| 32 | total_card_balance | NUMERIC(14,2) | NO | 总卡余额 |
| 33 | days_since_last | INTEGER | YES | 距离最近消费的天数 |
| 34 | is_active_7d | BOOLEAN | NO | 近7天是否活跃 |
| 35 | is_active_30d | BOOLEAN | NO | 近30天是否活跃 |
| 36 | is_active_90d | BOOLEAN | NO | 近90天是否活跃 |
| 37 | customer_tier | VARCHAR(20) | YES | 客户分层（高价值/中等/低活跃/流失） |
| 38 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 39 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 消费统计来源：dwd_settlement_head
```sql
SELECT
site_id,
member_id,
DATE(pay_time) AS consume_date,
COUNT(*) AS visit_count,
SUM(consume_money) AS consume_amount,
SUM(table_charge_money) AS table_fee,
SUM(goods_money) AS goods_amount,
SUM(assistant_pd_money + assistant_cx_money) AS assistant_amount
FROM billiards_dwd.dwd_settlement_head
WHERE member_id != 0 -- 排除散客
AND settle_type = 1 -- 已结账
GROUP BY site_id, member_id, DATE(pay_time);
```
### 卡余额来源：dim_member_card_account
```sql
SELECT
tenant_member_id AS member_id,
SUM(CASE WHEN card_type_id = 2793249295533893 THEN balance ELSE 0 END) AS cash_card_balance,
SUM(CASE WHEN card_type_id != 2793249295533893 THEN balance ELSE 0 END) AS gift_card_balance
FROM billiards_dwd.dim_member_card_account
WHERE scd2_is_current = 1
GROUP BY tenant_member_id;
```
## 使用说明
**散客处理**
- member_id=0 的散客不进入此表统计
**客户分层规则**
```sql
customer_tier = CASE
WHEN consume_amount_30d >= 1000 THEN '高价值'
WHEN consume_amount_30d >= 300 THEN '中等'
WHEN is_active_30d THEN '低活跃'
ELSE '流失'
END
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-16 ~ 至今 |
| 依赖表 | dwd_settlement_head, dim_member, dim_member_card_account |

119
etl_billiards/docs/bd_manual/dws/BD_manual_dws_member_visit_detail.md Normal file
View File

@@ -0,0 +1,119 @@
# dws_member_visit_detail 会员来店明细表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_member_visit_detail |
| 主键 | id |
| 唯一键 | (site_id, member_id, order_settle_id) |
| 数据来源 | dwd_settlement_head + 关联明细表 |
| 更新频率 | 每日增量更新 |
| 说明 | 以"会员+订单"为粒度，记录每次来店消费明细 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | member_id | BIGINT | NO | 会员ID（散客不入此表） |
| 5 | order_settle_id | BIGINT | NO | 结账单ID |
| 6 | visit_date | DATE | NO | 来店日期 |
| 7 | visit_time | TIMESTAMPTZ | YES | 来店时间 |
| 8 | member_nickname | VARCHAR(100) | YES | 会员昵称 |
| 9 | member_mobile | VARCHAR(20) | YES | 手机号 |
| 10 | member_birthday | DATE | YES | 会员生日 |
| 11 | table_id | BIGINT | YES | 台桌ID |
| 12 | table_name | VARCHAR(50) | YES | 台桌名称 |
| 13 | area_name | VARCHAR(50) | YES | 区域名称（原始） |
| 14 | area_category | VARCHAR(20) | YES | 区域分类 |
| 15 | table_fee | NUMERIC(12,2) | NO | 台费 |
| 16 | goods_amount | NUMERIC(12,2) | NO | 商品金额 |
| 17 | assistant_amount | NUMERIC(12,2) | NO | 助教服务金额 |
| 18 | total_consume | NUMERIC(12,2) | NO | 消费总额（正价） |
| 19 | total_discount | NUMERIC(12,2) | NO | 优惠总额 |
| 20 | actual_pay | NUMERIC(12,2) | NO | 实付金额 |
| 21 | cash_pay | NUMERIC(12,2) | NO | 现金/刷卡支付 |
| 22 | cash_card_pay | NUMERIC(12,2) | NO | 储值卡支付 |
| 23 | gift_card_pay | NUMERIC(12,2) | NO | 赠送卡支付 |
| 24 | groupbuy_pay | NUMERIC(12,2) | NO | 团购券支付 |
| 25 | table_duration_min | INTEGER | NO | 台桌使用时长（分钟） |
| 26 | assistant_duration_min | INTEGER | NO | 助教服务时长（分钟） |
| 27 | assistant_services | JSONB | YES | 助教服务列表 |
| 28 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 29 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 数据来源
### 主表来源：dwd_settlement_head
```sql
SELECT
site_id,
tenant_id,
member_id,
order_settle_id,
DATE(pay_time) AS visit_date,
pay_time AS visit_time,
member_name AS member_nickname,
member_phone AS member_mobile,
table_id,
table_charge_money AS table_fee,
goods_money AS goods_amount,
assistant_pd_money + assistant_cx_money AS assistant_amount,
consume_money AS total_consume,
member_discount_amount + coupon_amount + adjust_amount AS total_discount,
pay_amount AS actual_pay,
balance_amount AS cash_card_pay,
gift_card_amount AS gift_card_pay
FROM billiards_dwd.dwd_settlement_head
WHERE member_id != 0
AND settle_type = 1;
```
### 助教服务明细：dwd_assistant_service_log
```sql
-- 聚合为JSONB格式
SELECT
order_settle_id,
jsonb_agg(jsonb_build_object(
'assistant_id', site_assistant_id,
'nickname', nickname,
'duration_min', income_seconds / 60,
'amount', ledger_amount
)) AS assistant_services
FROM billiards_dwd.dwd_assistant_service_log
GROUP BY order_settle_id;
```
## 使用说明
**assistant_services JSON格式**
```json
[
{"assistant_id": 123, "nickname": "小燕", "duration_min": 60, "amount": 108.00},
{"assistant_id": 456, "nickname": "小明", "duration_min": 30, "amount": 54.00}
]
```
**区域分类映射**
```sql
-- 通过cfg_area_category映射
area_category = COALESCE(
(SELECT category_name FROM billiards_dws.cfg_area_category
WHERE source_area_name = dim_table.site_table_area_name),
'其他'
)
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯 |
| 数据范围 | 2025-07-16 ~ 至今 |
| 依赖表 | dwd_settlement_head, dwd_assistant_service_log, dim_table, dim_member |

100
etl_billiards/docs/bd_manual/dws/BD_manual_dws_platform_settlement.md Normal file
View File

@@ -0,0 +1,100 @@
# dws_platform_settlement 平台回款/服务费表
> 生成时间：2026-02-03
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | billiards_dws |
| 表名 | dws_platform_settlement |
| 主键 | id |
| 数据来源 | Excel手动导入 |
| 更新频率 | 按需导入 |
| 说明 | 以"回款日期+平台+订单"为粒度，记录平台结算数据 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | settlement_date | DATE | NO | 回款日期 |
| 5 | platform_type | VARCHAR(30) | NO | 平台类型。**枚举值**: MEITUAN, DOUYIN, DIANPING, OTHER |
| 6 | platform_name | VARCHAR(50) | YES | 平台名称 |
| 7 | platform_order_no | VARCHAR(100) | YES | 平台订单号 |
| 8 | order_settle_id | BIGINT | YES | 关联的结账单ID |
| 9 | settlement_amount | NUMERIC(14,2) | NO | 回款金额（实际入账） |
| 10 | commission_amount | NUMERIC(14,2) | NO | 佣金（平台抽成） |
| 11 | service_fee | NUMERIC(14,2) | NO | 服务费 |
| 12 | gross_amount | NUMERIC(14,2) | NO | 订单原始金额 |
| 13 | import_batch_no | VARCHAR(50) | YES | 导入批次号 |
| 14 | import_file_name | VARCHAR(200) | YES | 导入文件名 |
| 15 | import_time | TIMESTAMPTZ | YES | 导入时间 |
| 16 | import_user | VARCHAR(50) | YES | 导入操作人 |
| 17 | remark | TEXT | YES | 备注 |
| 18 | created_at | TIMESTAMPTZ | NO | 创建时间 |
| 19 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
## 平台类型说明
| platform_type | platform_name | 说明 |
|---------------|---------------|------|
| MEITUAN | 美团 | 美团团购/外卖 |
| DOUYIN | 抖音 | 抖音团购 |
| DIANPING | 大众点评 | 大众点评团购 |
| OTHER | 其他 | 其他平台 |
## Excel导入模板
| 回款日期 | 平台 | 平台订单号 | 订单金额 | 回款金额 | 佣金 | 服务费 | 备注 |
|----------|------|------------|----------|----------|------|--------|------|
| 2026-01-15 | 美团 | MT202601150001 | 200.00 | 186.00 | 12.00 | 2.00 | |
| 2026-01-15 | 抖音 | DY202601150001 | 150.00 | 142.50 | 6.00 | 1.50 | |
### 导入规则
- **回款日期**: 必填，实际到账日期
- **平台**: 必填，美团/抖音/大众点评/其他
- **平台订单号**: 选填，用于追溯
- **订单金额**: 必填，订单原始金额
- **回款金额**: 必填，实际到账金额
- **佣金**: 选填，平台抽成
- **服务费**: 选填
### 金额关系
```
settlement_amount = gross_amount - commission_amount - service_fee
```
## 使用说明
**日度平台回款汇总**
```sql
SELECT
settlement_date,
platform_type,
SUM(settlement_amount) AS total_settlement,
SUM(commission_amount) AS total_commission,
SUM(service_fee) AS total_service_fee
FROM billiards_dws.dws_platform_settlement
GROUP BY settlement_date, platform_type
ORDER BY settlement_date, platform_type;
```
**关联到财务日度汇总**
```sql
-- dws_finance_daily_summary.platform_settlement_amount
SELECT stat_date, SUM(settlement_amount)
FROM billiards_dws.dws_platform_settlement
WHERE settlement_date = :stat_date
GROUP BY stat_date;
```
## 可回溯性
| 项目 | 说明 |
|------|------|
| 可回溯 | ❌ 不可自动回溯 |
| 原因 | 数据来源为Excel手工导入，需从平台后台导出 |
| 处理 | 需要人工补录历史平台结算数据 |

585
etl_billiards/docs/dws_tables_dictionary.md Normal file
View File

@@ -0,0 +1,585 @@
# DWS 数据字典
## 概述
DWS（Data Warehouse Service）层是数据仓库的汇总层，基于DWD明细层数据构建，为上层应用和报表提供预聚合的数据服务。
### 表清单
| 分类 | 表名 | 说明 | 更新频率 |
|------|------|------|----------|
| **配置表** | cfg_performance_tier | 绩效档位配置 | 手动维护 |
| | cfg_assistant_level_price | 助教等级定价 | 手动维护 |
| | cfg_bonus_rules | 奖金规则配置 | 手动维护 |
| | cfg_area_category | 台区分类映射 | 手动维护 |
| | cfg_skill_type | 技能课程类型映射 | 手动维护 |
| **助教维度** | dws_assistant_daily_detail | 助教日度业绩明细 | 每小时 |
| | dws_assistant_monthly_summary | 助教月度业绩汇总 | 每日 |
| | dws_assistant_customer_stats | 助教服务客户统计 | 每日 |
| | dws_assistant_salary_calc | 助教工资计算详情 | 月初 |
| | dws_assistant_recharge_commission | 助教充值提成 | Excel导入 |
| **客户维度** | dws_member_consumption_summary | 会员消费汇总 | 每日 |
| | dws_member_visit_detail | 会员来店明细 | 每日 |
| **财务维度** | dws_finance_daily_summary | 财务日度汇总 | 每小时 |
| | dws_finance_income_structure | 收入结构分析 | 每日 |
| | dws_finance_discount_detail | 优惠明细 | 每日 |
| | dws_finance_recharge_summary | 充值统计 | 每日 |
| | dws_finance_expense_summary | 支出结构 | Excel导入 |
| | dws_assistant_finance_analysis | 助教收支分析 | 每日 |
| | dws_platform_settlement | 平台回款/服务费 | Excel导入 |
| **订单汇总** | dws_order_summary | 订单汇总 | 每日 |
---
## 一、配置表
### 1.1 cfg_performance_tier - 绩效档位配置
| 字段 | 类型 | 说明 |
|------|------|------|
| tier_id | SERIAL | 档位ID（主键） |
| tier_code | VARCHAR(20) | 档位代码（T0-T5, NEW） |
| tier_name | VARCHAR(50) | 档位名称 |
| tier_level | INTEGER | 档位等级（-1=新入职, 0-5=正常档位） |
| min_hours | NUMERIC(10,2) | 最低业绩小时数阈值（>=） |
| max_hours | NUMERIC(10,2) | 最高业绩小时数阈值（<），NULL=无上限 |
| base_deduction | NUMERIC(10,2) | 专业课抽成（元/小时），球房从基础课扣除 |
| bonus_deduction_ratio | NUMERIC(5,4) | 打赏课抽成比例（0-1），球房从附加课扣除 |
| vacation_days | INTEGER | 次月可休假天数 |
| vacation_unlimited | BOOLEAN | 休假自由标记（5档为TRUE） |
| is_new_hire_tier | BOOLEAN | 是否为新入职专用档位 |
| effective_from | DATE | 生效起始日期 |
| effective_to | DATE | 生效截止日期 |
**档位配置（来自DWS数据库处理需求.md）：**
| tier_code | tier_name | 业绩阈值 | 专业课抽成 | 打赏课抽成 | 休假 |
|-----------|-----------|----------|-----------|-----------|------|
| T0 | 0档-淘汰压力 | H < 100 | 28元/时 | 50% | 3天 |
| T1 | 1档-及格档 | 100 ≤ H < 130 | 18元/时 | 40% | 4天 |
| T2 | 2档-良好档 | 130 ≤ H < 160 | 15元/时 | 38% | 4天 |
| T3 | 3档-优秀档 | 160 ≤ H < 190 | 13元/时 | 35% | 5天 |
| T4 | 4档-卓越加速档 | 190 ≤ H < 220 | 10元/时 | 33% | 6天 |
| T5 | 5档-冠军加速档 | H ≥ 220 | 8元/时 | 30% | 休假自由 |
| NEW | 新入职档位 | - | 18元/时 | 40% | 4天 |
**业务规则：**
- 6档绩效（T0-T5），根据有效业绩小时数（基础课+附加课）匹配
- 新入职档位：月1日0点后入职者首月使用NEW档位，按1档抽成标准
- 支持按时间生效，历史月份使用历史规则
### 1.2 cfg_assistant_level_price - 助教等级定价
| 字段 | 类型 | 说明 |
|------|------|------|
| price_id | SERIAL | 定价ID（主键） |
| level_code | INTEGER | 等级代码（8/10/20/30/40） |
| level_name | VARCHAR(20) | 等级名称 |
| base_course_price | NUMERIC(10,2) | 基础课客户支付价格（元/小时） |
| bonus_course_price | NUMERIC(10,2) | 附加课客户支付价格（固定190元） |
| effective_from | DATE | 生效起始日期 |
| effective_to | DATE | 生效截止日期 |
**等级定价（客户支付价格）：**
| level_code | level_name | 基础课价格 | 附加课价格 |
|------------|------------|-----------|-----------|
| 8 | 助教管理 | 98元/时 | 190元/时 |
| 10 | 初级 | 98元/时 | 190元/时 |
| 20 | 中级 | 108元/时 | 190元/时 |
| 30 | 高级 | 118元/时 | 190元/时 |
| 40 | 星级 | 138元/时 | 190元/时 |
**注意：** 此价格为客户支付价格，助教实际收入需减去档位抽成
### 1.3 cfg_bonus_rules - 奖金规则配置
| 字段 | 类型 | 说明 |
|------|------|------|
| rule_id | SERIAL | 规则ID（主键） |
| rule_type | VARCHAR(20) | 规则类型（SPRINT/TOP_RANK） |
| rule_code | VARCHAR(30) | 规则代码 |
| rule_name | VARCHAR(50) | 规则名称 |
| threshold_hours | NUMERIC(10,2) | 小时数阈值（冲刺奖金） |
| rank_position | INTEGER | 排名位置（Top奖金） |
| bonus_amount | NUMERIC(12,2) | 奖金金额（元） |
| is_cumulative | BOOLEAN | 是否可累计 |
| priority | INTEGER | 优先级 |
| effective_from | DATE | 生效起始日期 |
| effective_to | DATE | 生效截止日期 |
**业务规则：**
- 冲刺奖金：H>=190得300元，H>=220得800元，不累计取最高档
- Top3奖金：1st=1000元，2nd=600元，3rd=400元，并列都算
### 1.4 cfg_area_category - 台区分类映射
| 字段 | 类型 | 说明 |
|------|------|------|
| category_id | SERIAL | 分类ID（主键） |
| source_area_name | VARCHAR(100) | 源区域名称（来自dim_table.site_table_area_name） |
| category_code | VARCHAR(20) | 分类代码 |
| category_name | VARCHAR(50) | 分类名称 |
| match_type | VARCHAR(10) | 匹配类型（exact/like/default） |
| match_priority | INTEGER | 匹配优先级（数字越小优先级越高） |
| is_active | BOOLEAN | 是否启用 |
**分类代码（基于BD_manual_dim_table.md实际数据）：**
| category_code | category_name | 匹配规则 |
|---------------|---------------|----------|
| BILLIARD | 普通台球区 | A区, B区, C区 |
| BILLIARD_VIP | VIP台球包厢 | VIP包厢 |
| SNOOKER | 斯诺克区 | 斯诺克区 |
| MAHJONG | 麻将房 | 麻将房 |
| KTV | KTV包间 | K包 |
| SPECIAL | 补时长专用 | 补时长 |
| OTHER | 其他区域 | 默认匹配 |
### 1.5 cfg_skill_type - 技能课程类型映射
| 字段 | 类型 | 说明 |
|------|------|------|
| skill_type_id | SERIAL | 映射ID（主键） |
| skill_id | BIGINT | 技能ID |
| skill_name | VARCHAR(50) | 技能名称 |
| course_type_code | VARCHAR(10) | 课程类型代码 |
| course_type_name | VARCHAR(20) | 课程类型名称 |
| is_active | BOOLEAN | 是否启用 |
**课程类型：**
- BASE = 基础课/陪打
- BONUS = 附加课/超休
---
## 二、助教维度表
### 2.1 dws_assistant_daily_detail - 助教日度业绩明细
**粒度：** 助教 + 日期
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| site_id | BIGINT | 门店ID |
| tenant_id | BIGINT | 租户ID |
| assistant_id | BIGINT | 助教ID |
| assistant_nickname | VARCHAR(50) | 助教花名 |
| stat_date | DATE | 统计日期 |
| assistant_level_code | INTEGER | 助教等级代码（SCD2 as-of） |
| assistant_level_name | VARCHAR(20) | 助教等级名称 |
| total_service_count | INTEGER | 总服务次数 |
| base_service_count | INTEGER | 基础课服务次数 |
| bonus_service_count | INTEGER | 附加课服务次数 |
| total_seconds | INTEGER | 总计费时长（秒） |
| base_seconds | INTEGER | 基础课计费时长 |
| bonus_seconds | INTEGER | 附加课计费时长 |
| total_hours | NUMERIC(10,2) | 总计费小时数 |
| base_hours | NUMERIC(10,2) | 基础课小时数 |
| bonus_hours | NUMERIC(10,2) | 附加课小时数 |
| total_ledger_amount | NUMERIC(12,2) | 总计费金额 |
| base_ledger_amount | NUMERIC(12,2) | 基础课计费金额 |
| bonus_ledger_amount | NUMERIC(12,2) | 附加课计费金额 |
| unique_customers | INTEGER | 服务客户数（去重） |
| unique_tables | INTEGER | 服务台桌数（去重） |
| trashed_seconds | INTEGER | 被废除的服务时长 |
| trashed_count | INTEGER | 被废除的服务次数 |
**数据来源：** dwd_assistant_service_log + dwd_assistant_trash_event
### 2.2 dws_assistant_monthly_summary - 助教月度业绩汇总
**粒度：** 助教 + 月份
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| site_id | BIGINT | 门店ID |
| assistant_id | BIGINT | 助教ID |
| stat_month | DATE | 统计月份（月第一天） |
| hire_date | DATE | 入职日期 |
| is_new_hire | BOOLEAN | 是否新入职 |
| work_days | INTEGER | 有服务天数 |
| total_hours | NUMERIC(10,2) | 总计费小时数 |
| base_hours | NUMERIC(10,2) | 基础课小时数 |
| bonus_hours | NUMERIC(10,2) | 附加课小时数 |
| effective_hours | NUMERIC(10,2) | 有效业绩小时数 |
| trashed_hours | NUMERIC(10,2) | 被废除小时数 |
| tier_id | INTEGER | 档位ID |
| tier_code | VARCHAR(20) | 档位代码 |
| tier_name | VARCHAR(50) | 档位名称 |
| rank_by_hours | INTEGER | 月度排名 |
| rank_with_ties | INTEGER | 考虑并列的排名 |
**业务规则：**
- 有效业绩 = total_hours - trashed_hours
- 新入职判断：入职日期 >= 月1日0点
- 排名：按effective_hours降序，并列都算
### 2.3 dws_assistant_customer_stats - 助教服务客户统计
**粒度：** 助教 + 客户 + 统计日期
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| assistant_id | BIGINT | 助教ID |
| member_id | BIGINT | 客户ID |
| stat_date | DATE | 统计基准日期 |
| first_service_date | DATE | 首次服务日期 |
| last_service_date | DATE | 最近服务日期 |
| total_service_count | INTEGER | 累计服务次数 |
| total_service_hours | NUMERIC(10,2) | 累计服务小时数 |
| service_count_7d | INTEGER | 近7天服务次数 |
| service_count_30d | INTEGER | 近30天服务次数 |
| service_count_90d | INTEGER | 近90天服务次数 |
| is_active_7d | BOOLEAN | 近7天是否活跃 |
| is_active_30d | BOOLEAN | 近30天是否活跃 |
**业务规则：**
- 散客（member_id=0）不进入此表
- 滚动窗口：7/10/15/30/60/90天
### 2.4 dws_assistant_salary_calc - 助教工资计算详情
**粒度：** 助教 + 工资月份
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| assistant_id | BIGINT | 助教ID |
| assistant_nickname | VARCHAR(50) | 助教花名 |
| salary_month | DATE | 工资月份（月第一天） |
| assistant_level_code | INTEGER | 助教等级代码（8/10/20/30/40） |
| assistant_level_name | VARCHAR(20) | 助教等级名称 |
| hire_date | DATE | 入职日期 |
| is_new_hire | BOOLEAN | 是否新入职 |
| effective_hours | NUMERIC(10,2) | 有效业绩小时数（基础课+附加课-废除） |
| base_hours | NUMERIC(10,2) | 基础课/专业课小时数 |
| bonus_hours | NUMERIC(10,2) | 附加课/打赏课小时数 |
| tier_id | INTEGER | 档位ID |
| tier_code | VARCHAR(20) | 档位代码（T0-T5/NEW） |
| tier_name | VARCHAR(50) | 档位名称 |
| rank_with_ties | INTEGER | 月度排名（考虑并列，用于Top3奖金） |
| base_course_price | NUMERIC(10,2) | 基础课客户支付价格（98/108/118/138） |
| bonus_course_price | NUMERIC(10,2) | 附加课客户支付价格（固定190） |
| base_deduction | NUMERIC(10,2) | 专业课抽成（元/小时），档位决定 |
| bonus_deduction_ratio | NUMERIC(5,4) | 打赏课抽成比例（0-1），档位决定 |
| base_income | NUMERIC(12,2) | 基础课收入 |
| bonus_income | NUMERIC(12,2) | 附加课收入 |
| total_course_income | NUMERIC(12,2) | 课时收入合计 |
| sprint_bonus | NUMERIC(12,2) | 冲刺奖金（H>=190:300, H>=220:800） |
| top_rank_bonus | NUMERIC(12,2) | Top3排名奖金（1st:1000, 2nd:600, 3rd:400） |
| recharge_commission | NUMERIC(12,2) | 充值提成 |
| other_bonus | NUMERIC(12,2) | 其他奖金（手动调整） |
| total_bonus | NUMERIC(12,2) | 奖金合计 |
| gross_salary | NUMERIC(12,2) | 应发工资 |
| vacation_days | INTEGER | 次月可休假天数 |
| vacation_unlimited | BOOLEAN | 休假自由标记（5档为TRUE） |
| calc_notes | TEXT | 计算备注（异常说明等） |
**工资计算公式（来自DWS数据库处理需求.md）：**
```
基础课收入 = 基础课小时数 × (客户支付价格 - 专业课抽成)
附加课收入 = 附加课小时数 × 190 × (1 - 打赏课抽成比例)
应发工资 = 课时收入 + 奖金
```
**计算示例（中级助教185小时，3档）：**
- 基础课170小时: 170 × (108 - 13) = 16,150元
- 附加课15小时: 15 × 190 × (1 - 0.35) = 1,852.5元
- 课时收入: 18,002.5元
- 冲刺奖金（H≥190未达到）: 0元
- 应发工资: 18,002.5元
---
## 三、客户维度表
### 3.1 dws_member_consumption_summary - 会员消费汇总
**粒度：** 会员 + 统计日期
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| member_id | BIGINT | 会员ID |
| stat_date | DATE | 统计基准日期 |
| first_consume_date | DATE | 首次消费日期 |
| last_consume_date | DATE | 最近消费日期 |
| total_visit_count | INTEGER | 累计到店次数 |
| total_consume_amount | NUMERIC(14,2) | 累计消费金额 |
| visit_count_7d | INTEGER | 近7天到店次数 |
| visit_count_30d | INTEGER | 近30天到店次数 |
| consume_amount_30d | NUMERIC(14,2) | 近30天消费金额 |
| cash_card_balance | NUMERIC(14,2) | 储值卡余额 |
| gift_card_balance | NUMERIC(14,2) | 赠送卡余额 |
| customer_tier | VARCHAR(20) | 客户分层 |
**客户分层规则：**
- 高价值：90天内消费>=3次 且 消费金额>=1000
- 中等：30天内有消费
- 低活跃：90天内有消费但30天内无消费
- 流失：90天内无消费
### 3.2 dws_member_visit_detail - 会员来店明细
**粒度：** 会员 + 订单
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| member_id | BIGINT | 会员ID |
| order_settle_id | BIGINT | 结账单ID |
| visit_date | DATE | 来店日期 |
| table_name | VARCHAR(50) | 台桌名称 |
| area_category | VARCHAR(20) | 区域分类 |
| table_fee | NUMERIC(12,2) | 台费 |
| goods_amount | NUMERIC(12,2) | 商品金额 |
| assistant_amount | NUMERIC(12,2) | 助教服务金额 |
| total_consume | NUMERIC(12,2) | 消费总额 |
| actual_pay | NUMERIC(12,2) | 实付金额 |
| assistant_services | JSONB | 助教服务明细（JSON） |
---
## 四、财务维度表
### 4.1 dws_finance_daily_summary - 财务日度汇总
**粒度：** 日期
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| stat_date | DATE | 统计日期 |
| gross_amount | NUMERIC(14,2) | 发生额合计 |
| table_fee_amount | NUMERIC(14,2) | 台费正价 |
| goods_amount | NUMERIC(14,2) | 商品正价 |
| assistant_pd_amount | NUMERIC(14,2) | 助教基础课正价 |
| assistant_cx_amount | NUMERIC(14,2) | 助教激励课正价 |
| discount_total | NUMERIC(14,2) | 优惠合计 |
| discount_groupbuy | NUMERIC(14,2) | 团购优惠 |
| discount_vip | NUMERIC(14,2) | 会员折扣 |
| discount_gift_card | NUMERIC(14,2) | 赠送卡抵扣 |
| discount_manual | NUMERIC(14,2) | 手动调整 |
| discount_rounding | NUMERIC(14,2) | 抹零 |
| discount_other | NUMERIC(14,2) | 其他优惠（手动调整拆分） |
| confirmed_income | NUMERIC(14,2) | 确认收入 |
| cash_inflow_total | NUMERIC(14,2) | 现金流入合计 |
| cash_pay_amount | NUMERIC(14,2) | 收银实付 |
| groupbuy_pay_amount | NUMERIC(14,2) | 团购支付金额 |
| platform_settlement_amount | NUMERIC(14,2) | 平台回款金额 |
| platform_fee_amount | NUMERIC(14,2) | 平台服务费+佣金 |
| recharge_cash_inflow | NUMERIC(14,2) | 充值现金流入 |
| card_consume_total | NUMERIC(14,2) | 卡消费合计 |
| cash_card_consume | NUMERIC(14,2) | 储值卡消费 |
| gift_card_consume | NUMERIC(14,2) | 赠送卡消费 |
| cash_outflow_total | NUMERIC(14,2) | 现金流出合计 |
| cash_balance_change | NUMERIC(14,2) | 现金结余 |
| recharge_count | INTEGER | 充值笔数 |
| recharge_total | NUMERIC(14,2) | 充值总额 |
| recharge_cash | NUMERIC(14,2) | 充值现金部分 |
| recharge_gift | NUMERIC(14,2) | 充值赠送部分 |
| first_recharge_count | INTEGER | 首充笔数 |
| renewal_count | INTEGER | 续充笔数 |
| order_count | INTEGER | 结账单数 |
| member_order_count | INTEGER | 会员订单数 |
| guest_order_count | INTEGER | 散客订单数 |
| avg_order_amount | NUMERIC(12,2) | 平均客单价 |
**计算公式：**
- 发生额 = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money
- 团购支付金额 = pl_coupon_sale_amount > 0 ? pl_coupon_sale_amount : groupbuy_redemption.ledger_unit_price
- 团购优惠 = coupon_amount - 团购支付金额
- 优惠合计 = 团购优惠 + 会员折扣 + 赠送卡抵扣 + 手动调整 + 抹零
- 其他优惠 = adjust_amount - 大客户优惠（不足0按0处理）
- 确认收入 = 发生额 - 优惠合计
- 平台回款金额 = dws_platform_settlement.settlement_amount（若无导入，则使用团购支付金额）
- 平台服务费 = commission_amount + service_fee
- 现金流入合计 = 收银实付 + 平台回款金额 + 充值现金流入
- 现金流出合计 = 支出汇总 + 平台服务费
- 现金结余 = 现金流入合计 - 现金流出合计
**财务指标数据来源矩阵（字段 → 来源 → 口径）**
| 字段 | 来源表 | 口径说明 |
|------|--------|----------|
| gross_amount | dwd_settlement_head | table_charge_money + goods_money + assistant_pd_money + assistant_cx_money |
| discount_groupbuy | dwd_settlement_head + dwd_groupbuy_redemption | coupon_amount - 团购支付金额 |
| discount_vip | dwd_settlement_head | member_discount_amount |
| discount_gift_card | dwd_settlement_head | gift_card_amount |
| discount_manual | dwd_settlement_head | adjust_amount（手动调整总额） |
| discount_rounding | dwd_settlement_head | rounding_amount |
| discount_other | dwd_settlement_head | adjust_amount - 大客户优惠（配置映射） |
| confirmed_income | dwd_settlement_head | gross_amount - discount_total |
| cash_pay_amount | dwd_settlement_head | pay_amount（收银实付） |
| groupbuy_pay_amount | dwd_settlement_head + dwd_groupbuy_redemption | pl_coupon_sale_amount 或 ledger_unit_price |
| platform_settlement_amount | dws_platform_settlement | settlement_amount（Excel导入） |
| platform_fee_amount | dws_platform_settlement | commission_amount + service_fee |
| recharge_cash_inflow | dwd_recharge_order | pay_money（现金充值） |
| cash_inflow_total | dwd_settlement_head + dws_platform_settlement + dwd_recharge_order | 收银实付 + 平台回款 + 充值现金 |
| cash_outflow_total | dws_finance_expense_summary + dws_platform_settlement | 支出汇总 + 平台服务费 |
| cash_balance_change | dws_finance_daily_summary | cash_inflow_total - cash_outflow_total |
### 4.2 dws_finance_recharge_summary - 充值统计
**粒度：** 日期
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| stat_date | DATE | 统计日期 |
| recharge_count | INTEGER | 充值笔数 |
| recharge_total | NUMERIC(14,2) | 充值总额（含赠送） |
| recharge_cash | NUMERIC(14,2) | 现金充值金额 |
| recharge_gift | NUMERIC(14,2) | 赠送金额 |
| first_recharge_count | INTEGER | 首充笔数 |
| first_recharge_cash | NUMERIC(14,2) | 首充现金 |
| renewal_count | INTEGER | 续充笔数 |
| renewal_cash | NUMERIC(14,2) | 续充现金 |
| cash_card_balance | NUMERIC(14,2) | 储值卡余额 |
| gift_card_balance | NUMERIC(14,2) | 赠送卡余额 |
**数据来源：** dwd_recharge_order（is_first字段区分首充/续充）
### 4.3 dws_finance_income_structure - 收入结构分析
**粒度：** 日期 + 结构类型 + 分类
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| stat_date | DATE | 统计日期 |
| structure_type | VARCHAR(20) | 结构类型（INCOME_TYPE/AREA） |
| category_code | VARCHAR(30) | 分类代码 |
| category_name | VARCHAR(50) | 分类名称 |
| income_amount | NUMERIC(14,2) | 收入金额 |
| income_ratio | NUMERIC(5,4) | 收入占比 |
| order_count | INTEGER | 订单数 |
| duration_minutes | INTEGER | 时长（分钟） |
**结构类型说明：**
1. **INCOME_TYPE（按收入类型）：**
- TABLE_FEE = 台费收入
- GOODS = 商品收入
- ASSISTANT_BASE = 助教基础课
- ASSISTANT_BONUS = 助教附加课
2. **AREA（按区域）：**
- 使用cfg_area_category映射（BILLIARD/BILLIARD_VIP/SNOOKER/MAHJONG/KTV/OTHER）
**数据来源：** dwd_settlement_head, dwd_table_fee_log, dwd_assistant_service_log
### 4.4 dws_finance_discount_detail - 优惠明细
**粒度：** 日期 + 优惠类型
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| stat_date | DATE | 统计日期 |
| discount_type_code | VARCHAR(30) | 优惠类型代码 |
| discount_type_name | VARCHAR(50) | 优惠类型名称 |
| discount_amount | NUMERIC(14,2) | 优惠金额 |
| discount_ratio | NUMERIC(5,4) | 优惠占比（占总优惠） |
| usage_count | INTEGER | 使用次数 |
| affected_orders | INTEGER | 影响订单数 |
**优惠类型：**
- GROUPBUY = 团购优惠（coupon_amount - 团购实付金额）
- VIP = 会员折扣（member_discount_amount）
- GIFT_CARD = 赠送卡抵扣（gift_card_amount）
- ROUNDING = 抹零（rounding_amount）
- BIG_CUSTOMER = 大客户优惠（基于配置映射的手动调整）
- OTHER = 其他优惠（手动调整中除大客户外部分）
**数据来源：** dwd_settlement_head, dwd_groupbuy_redemption
### 4.5 dws_finance_expense_summary - 支出结构（Excel导入）
**粒度：** 月份 + 支出类型
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| expense_month | DATE | 支出月份 |
| expense_type_code | VARCHAR(30) | 支出类型代码 |
| expense_type_name | VARCHAR(50) | 支出类型名称 |
| expense_category | VARCHAR(20) | 支出大类 |
| expense_amount | NUMERIC(14,2) | 支出金额 |
| import_batch_no | VARCHAR(50) | 导入批次号 |
**支出类型：**
- RENT = 房租
- UTILITY = 水电费
- PROPERTY = 物业费
- SALARY = 工资
- REIMBURSE = 报销
- PLATFORM_FEE = 平台服务费
- OTHER = 其他
### 4.6 dws_platform_settlement - 平台回款（Excel导入）
**粒度：** 回款日期 + 平台 + 订单
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGSERIAL | 主键 |
| settlement_date | DATE | 回款日期 |
| platform_type | VARCHAR(30) | 平台类型 |
| platform_name | VARCHAR(50) | 平台名称 |
| platform_order_no | VARCHAR(100) | 平台订单号 |
| order_settle_id | BIGINT | 关联的结账单ID |
| settlement_amount | NUMERIC(14,2) | 回款金额 |
| commission_amount | NUMERIC(14,2) | 佣金 |
| service_fee | NUMERIC(14,2) | 服务费 |
| gross_amount | NUMERIC(14,2) | 订单原始金额 |
| import_batch_no | VARCHAR(50) | 导入批次号 |
---
## 五、时间分层机制
### 5.1 时间口径定义
| 时间窗口 | 说明 | 边界规则 |
|----------|------|----------|
| 本周 | 从本周一到今天 | 周起始日为周一 |
| 上周 | 上周一到上周日 | 完整7天 |
| 本月 | 从月1日到今天 | 月第一天0点起 |
| 上月 | 上月完整月份 | 完整自然月 |
| 前3个月不含本月 | 三个月前月初到上月末 | 不含当前月 |
| 前3个月含本月 | 两个月前月初到今天 | 含当前月 |
| 本季度 | 季度第一月1日到今天 | 季度起始 |
| 上季度 | 上季度完整三个月 | 完整自然季 |
| 最近半年 | 往前6个月（不含本月） | 不含当前月 |
### 5.2 滚动窗口
支持以下滚动窗口统计：
- 近7天
- 近10天
- 近15天
- 近30天
- 近60天
- 近90天
### 5.3 环比计算
环比规则：对比上一个等长区间
- 如查询1月1日-1月15日，环比为12月17日-12月31日
---
## 六、数据更新策略
| 表类型 | 更新频率 | 幂等方式 |
|--------|----------|----------|
| 日度明细表 | 每小时 | delete-before-insert（按日期窗口） |
| 日度汇总表 | 每小时 | delete-before-insert（按日期） |
| 月度汇总表 | 每日 | delete-before-insert（按月份） |
| 客户统计表 | 每日 | delete-before-insert（按统计日期） |
| Excel导入表 | 手动 | 按import_batch_no去重 |

494
etl_billiards/docs/index_tables.md Normal file
View File

@@ -0,0 +1,494 @@
## 1. 客户召回表
| 客户姓名 | 召回指数 |
|----------|----------|
| 陈腾鑫 | 10.00 |
| 章先生 | 10.00 |
| 孙总 | 10.00 |
| 梅 | 10.00 |
| 胡先生 | 10.00 |
| 黄先生 | 9.63 |
| 小熊 | 9.52 |
| 周先生 | 9.41 |
| 李先生 | 9.39 |
| 王 | 9.27 |
| 张无忌 | 9.20 |
| 黄先生 | 8.96 |
| 陈德韩 | 8.94 |
| 胡总 | 8.93 |
| T | 8.89 |
| 候 | 8.88 |
| 孙先生 | 8.87 |
| 王先生 | 8.86 |
| 清 | 8.86 |
| amy | 8.84 |
| 林先生 | 8.84 |
| 张先生 | 8.79 |
| 刘先生 | 8.79 |
| 黄国磊 | 8.79 |
| 游 | 8.79 |
| 陈先生 | 8.79 |
| 陈 | 8.79 |
| 大G | 8.79 |
| 李先生 | 8.79 |
| 孙启明 | 8.79 |
| 陈先生 | 8.79 |
| 罗先生 | 8.79 |
| 刘哥 | 8.79 |
| 杨 | 8.79 |
| 枫先生 | 8.79 |
| 老宋 | 8.79 |
| 黄先生 | 8.79 |
| 刘女士 | 8.79 |
| 彭先生 | 8.79 |
| 李 | 8.79 |
| 桂先生 | 8.79 |
| 王先生 | 8.79 |
| 潘先生 | 8.79 |
| 方先生 | 8.79 |
| 郑先生 | 8.79 |
| 阿亮 | 8.79 |
| 孟紫龙 | 8.79 |
| 林总 | 8.78 |
| 林志铭 | 8.64 |
| 罗超 | 8.63 |
| 张丹逸 | 8.52 |
| 谢俊 | 8.07 |
| 王龙 | 7.80 |
| 唐先生 | 7.79 |
| 周周 | 7.47 |
| 曾巧明 | 6.83 |
| 昌哥 | 6.17 |
| 江先生 | 5.84 |
| 袁 | 5.24 |
| 蔡总 | 4.73 |
| 胡先生 | 4.51 |
| 陈先生 | 4.45 |
| 明哥 | 3.92 |
| 公孙先生 | 3.57 |
| 曾先生 | 3.47 |
| 黄生 | 3.46 |
| 葛先生 | 3.35 |
| 轩哥 | 3.32 |
| 张先生 | 2.73 |
| 叶先生 | 2.61 |
| 小燕 | 2.39 |
| 罗先生 | 2.38 |
| 李先生 | 2.23 |
| 陈淑涛 | 2.23 |
| 肖先生 | 2.23 |
| 范先生 | 2.14 |
| 常总 | 1.47 |
| 董贝 | 1.04 |
| 陈小姐 | 1.04 |
| 林先生 | 0.90 |
| 柳先生 | 0.61 |
| 林先生 | 0.20 |
| 潘先生 | 0.20 |
| 曾丹烨 | 0.07 |
| 魏先生 | 0.00 |
| 艾宇民 | 0.00 |
| 吴生 | 0.00 |
| 卢广贤 | 0.00 |
| 陈泽斌 | 0.00 |
| 李先生 | 0.00 |
共 90 条记录
## 2. 助教客户关系表
| 助教花名 | 客户姓名 | 关系指数 |
|----------|----------|----------|
| 卡顿 | 葛先生 | 10.00 |
| 小燕 | 葛先生 | 10.00 |
| 七七 | 轩哥 | 10.00 |
| 佳怡 | 罗先生 | 10.00 |
| 璇子 | 轩哥 | 10.00 |
| 阿清 | 张先生 | 10.00 |
| 璇子 | 江先生 | 10.00 |
| CC | 周周 | 10.00 |
| 周周 | 周周 | 10.00 |
| 小燕 | 小燕 | 10.00 |
| 卡顿 | 小燕 | 10.00 |
| 姜姜 | 张先生 | 10.00 |
| 小侯 | 张先生 | 10.00 |
| 渔渔 | 张先生 | 10.00 |
| 欣欣 | 张先生 | 10.00 |
| 千千 | 张先生 | 10.00 |
| 小A | 张先生 | 10.00 |
| 甜甜 | 张先生 | 10.00 |
| 小A | 周先生 | 10.00 |
| 欣欣 | 周先生 | 10.00 |
| 千千 | 周先生 | 10.00 |
| 甜甜 | 周先生 | 10.00 |
| 涛涛 | 蔡总 | 10.00 |
| 婉婉 | 吴先生 | 10.00 |
| 千千 | 梅 | 10.00 |
| 甜甜 | 梅 | 10.00 |
| 小A | 梅 | 10.00 |
| 欣欣 | 梅 | 10.00 |
| 球球 | 周周 | 10.00 |
| 涛涛 | 轩哥 | 10.00 |
| 小不点 | 周周 | 10.00 |
| 小柔 | 蔡总 | 10.00 |
| 年糕 | 葛先生 | 10.00 |
| 佳怡 | 陈腾鑫 | 10.00 |
| 小不点 | 罗先生 | 10.00 |
| 球球 | 罗先生 | 10.00 |
| 小柔 | 轩哥 | 10.00 |
| 阿清 | 梅 | 10.00 |
| 阿清 | 胡先生 | 10.00 |
| 佳怡 | 陈先生 | 10.00 |
| 小不点 | 轩哥 | 10.00 |
| 佳怡 | 小熊 | 10.00 |
| 球球 | 轩哥 | 10.00 |
| 阿清 | 孙总 | 10.00 |
| CC | 罗先生 | 10.00 |
| 周周 | 罗先生 | 10.00 |
| 小柔 | 明哥 | 9.96 |
| 渔渔 | 李先生 | 9.88 |
| 姜姜 | 李先生 | 9.88 |
| 小侯 | 李先生 | 9.88 |
| 年糕 | 常总 | 9.85 |
| 婉婉 | 明哥 | 9.61 |
| 乔西 | 陈先生 | 9.59 |
| 璇子 | 蔡总 | 9.46 |
| CC | 常总 | 9.40 |
| 周周 | 常总 | 9.40 |
| 七七 | 蔡总 | 9.24 |
| 甜甜 | 孙总 | 9.24 |
| 小A | 孙总 | 9.24 |
| 欣欣 | 孙总 | 9.24 |
| 千千 | 孙总 | 9.24 |
| 七七 | 胡先生 | 9.20 |
| 千千 | 小熊 | 9.02 |
| 甜甜 | 小熊 | 9.02 |
| 欣欣 | 小熊 | 9.02 |
| 小A | 小熊 | 9.02 |
| 佳怡 | 胡先生 | 9.02 |
| 涛涛 | 小燕 | 8.66 |
| 阿清 | 轩哥 | 8.53 |
| 年糕 | 叶先生 | 8.51 |
| 小不点 | 张先生 | 8.39 |
| 球球 | 张先生 | 8.39 |
| 阿清 | 葛先生 | 8.36 |
| 周周 | 张先生 | 8.30 |
| CC | 张先生 | 8.30 |
| 甜甜 | 胡先生 | 8.04 |
| 千千 | 胡先生 | 8.04 |
| 欣欣 | 胡先生 | 8.04 |
| 小A | 胡先生 | 8.04 |
| 小不点 | 小熊 | 7.88 |
| 球球 | 小熊 | 7.88 |
| 小侯 | 胡先生 | 7.86 |
| 姜姜 | 胡先生 | 7.86 |
| 渔渔 | 胡先生 | 7.86 |
| 乔西 | 罗先生 | 7.86 |
| 小不点 | 胡先生 | 7.65 |
| 球球 | 胡先生 | 7.65 |
| 球球 | 孙总 | 7.56 |
| 小不点 | 孙总 | 7.56 |
| 璇子 | 孙总 | 7.46 |
| 阿清 | 清 | 7.35 |
| 小A | 小燕 | 7.09 |
| 甜甜 | 小燕 | 7.09 |
| 欣欣 | 小燕 | 7.09 |
| 千千 | 小燕 | 7.09 |
| 甜甜 | 公孙先生 | 7.07 |
| 千千 | 公孙先生 | 7.07 |
| 欣欣 | 公孙先生 | 7.07 |
| 小A | 公孙先生 | 7.07 |
| 婉婉 | 孙总 | 7.03 |
| 菲菲 | 陈腾鑫 | 6.92 |
| 橙子 | 陈腾鑫 | 6.92 |
| 希希 | 陈腾鑫 | 6.92 |
| 婉婉 | 章先生 | 6.91 |
| 婉婉 | 公孙先生 | 6.86 |
| CC | 林先生 | 6.77 |
| 周周 | 林先生 | 6.77 |
| 阿清 | 小燕 | 6.76 |
| 苏苏 | 蔡总 | 6.64 |
| 七七 | 小燕 | 6.60 |
| 小不点 | 江先生 | 6.59 |
| 球球 | 江先生 | 6.59 |
| 涛涛 | 罗先生 | 6.52 |
| 凤梨 | 葛先生 | 6.51 |
| 佳怡 | 轩哥 | 6.49 |
| 年糕 | 轩哥 | 6.44 |
| 年糕 | 小燕 | 6.43 |
| CC | 轩哥 | 6.26 |
| 周周 | 轩哥 | 6.26 |
| yy | 公孙先生 | 6.13 |
| 阿清 | 陈腾鑫 | 6.04 |
| 佳怡 | 周周 | 6.03 |
| 七七 | 江先生 | 5.93 |
| CC | 林先生 | 5.87 |
| 周周 | 林先生 | 5.87 |
| 年糕 | 王 | 5.76 |
| 年糕 | 李先生 | 5.72 |
| 七七 | 孙总 | 5.69 |
| 苏苏 | 黄先生 | 5.66 |
| 婉婉 | 叶先生 | 5.55 |
| 涛涛 | 叶先生 | 5.55 |
| 凤梨 | 叶先生 | 5.54 |
| 小A | 黄先生 | 5.53 |
| 甜甜 | 黄先生 | 5.53 |
| 千千 | 黄先生 | 5.53 |
| 欣欣 | 黄先生 | 5.53 |
| yy | 叶先生 | 5.53 |
| 苏苏 | 罗先生 | 5.48 |
| 小侯 | 葛先生 | 5.47 |
| 渔渔 | 葛先生 | 5.47 |
| 姜姜 | 葛先生 | 5.47 |
| 佳怡 | 林志铭 | 5.45 |
| 婉婉 | 葛先生 | 5.37 |
| CC | 小熊 | 5.29 |
| 周周 | 小熊 | 5.29 |
| 涛涛 | 孙总 | 5.20 |
| 小敌 | 李先生 | 5.09 |
| 吱吱 | 李先生 | 5.09 |
| 周周 | 葛先生 | 5.08 |
| CC | 葛先生 | 5.08 |
| 甜甜 | 蔡总 | 5.04 |
| 千千 | 蔡总 | 5.04 |
| 欣欣 | 蔡总 | 5.04 |
| 小A | 蔡总 | 5.04 |
| 婉婉 | 轩哥 | 5.03 |
| 年糕 | 胡先生 | 5.02 |
| 吱吱 | 葛先生 | 4.88 |
| 小敌 | 葛先生 | 4.88 |
| 婉婉 | 王 | 4.87 |
| yy | 张先生 | 4.66 |
| 璇子 | 罗先生 | 4.65 |
| yy | 葛先生 | 4.59 |
| 苏苏 | 柳先生 | 4.58 |
| 乔西 | 蔡总 | 4.50 |
| 七七 | 张先生 | 4.36 |
| 乔西 | 葛先生 | 4.33 |
| 乔西 | 小熊 | 4.33 |
| 周周 | 江先生 | 4.32 |
| CC | 江先生 | 4.32 |
| Amy | 轩哥 | 4.31 |
| 年糕 | 罗超 | 4.20 |
| yy | 林志铭 | 4.19 |
| 年糕 | 艾宇民 | 4.16 |
| 阿清 | 黄先生 | 4.14 |
| 七七 | 罗超 | 4.12 |
| 年糕 | 范先生 | 4.08 |
| 凤梨 | 林先生 | 4.07 |
| 璇子 | 张先生 | 4.06 |
| 球球 | 常总 | 4.05 |
| 小不点 | 常总 | 4.05 |
| yy | 孙总 | 3.99 |
| 七七 | 葛先生 | 3.93 |
| 乔西 | 轩哥 | 3.90 |
| 年糕 | 小熊 | 3.85 |
| 千千 | 李先生 | 3.73 |
| 欣欣 | 李先生 | 3.73 |
| 小A | 李先生 | 3.73 |
| 甜甜 | 李先生 | 3.73 |
| 姜姜 | 轩哥 | 3.62 |
| 渔渔 | 轩哥 | 3.62 |
| 小侯 | 轩哥 | 3.62 |
| 迟迟 | 轩哥 | 3.60 |
| 泡芙 | 轩哥 | 3.60 |
| 小琳 | 轩哥 | 3.60 |
| 七七 | 罗先生 | 3.57 |
| 年糕 | 胡总 | 3.47 |
| 欣欣 | 葛先生 | 3.43 |
| 甜甜 | 葛先生 | 3.43 |
| 千千 | 葛先生 | 3.43 |
| 小A | 葛先生 | 3.43 |
| 七七 | 林总 | 3.43 |
| 乔西 | 陈德韩 | 3.38 |
| 泡芙 | 林总 | 3.31 |
| 迟迟 | 林总 | 3.31 |
| 小琳 | 林总 | 3.31 |
| 涛涛 | 葛先生 | 3.27 |
| 阿清 | 罗先生 | 3.16 |
| 璇子 | 周周 | 3.16 |
| 阿清 | 王先生 | 3.14 |
| 小柳 | 轩哥 | 3.06 |
| 迟迟 | 陈腾鑫 | 3.04 |
| 小琳 | 陈腾鑫 | 3.04 |
| 泡芙 | 陈腾鑫 | 3.04 |
| 瑶瑶 | 蔡总 | 2.92 |
| 图图 | 蔡总 | 2.92 |
| 小A | 轩哥 | 2.91 |
| 千千 | 轩哥 | 2.91 |
| 欣欣 | 轩哥 | 2.91 |
| 甜甜 | 轩哥 | 2.91 |
| 年糕 | 罗先生 | 2.84 |
| 小不点 | 黄先生 | 2.73 |
| 球球 | 黄先生 | 2.73 |
| 渔渔 | 梅 | 2.72 |
| 姜姜 | 梅 | 2.72 |
| 小侯 | 梅 | 2.72 |
| 欣欣 | 陈先生 | 2.68 |
| 千千 | 陈先生 | 2.68 |
| 小A | 陈先生 | 2.68 |
| 甜甜 | 陈先生 | 2.68 |
| 婉婉 | 江先生 | 2.67 |
| 千千 | 枫先生 | 2.67 |
| 欣欣 | 枫先生 | 2.67 |
| 小A | 枫先生 | 2.67 |
| 甜甜 | 枫先生 | 2.67 |
| 阿清 | 枫先生 | 2.67 |
| 乔西 | 张无忌 | 2.55 |
| 甜甜 | 范先生 | 2.51 |
| 千千 | 范先生 | 2.51 |
| 小A | 范先生 | 2.51 |
| 欣欣 | 范先生 | 2.51 |
| 七七 | 林先生 | 2.45 |
| CC | T | 2.36 |
| 周周 | T | 2.36 |
| 苏苏 | 周周 | 2.36 |
| 小侯 | 周先生 | 2.28 |
| 渔渔 | 周先生 | 2.28 |
| 姜姜 | 周先生 | 2.28 |
| 涛涛 | 胡总 | 2.28 |
| 苏苏 | 林先生 | 2.14 |
| 渔渔 | 彭先生 | 2.07 |
| 小侯 | 彭先生 | 2.07 |
| 姜姜 | 彭先生 | 2.07 |
| 小侯 | 清 | 2.03 |
| 甜甜 | 清 | 2.03 |
| 小A | 清 | 2.03 |
| 欣欣 | 清 | 2.03 |
| 千千 | 清 | 2.03 |
| 渔渔 | 清 | 2.03 |
| 姜姜 | 清 | 2.03 |
| 苏苏 | 张先生 | 1.94 |
| 千千 | 林总 | 1.88 |
| 甜甜 | 林总 | 1.88 |
| 欣欣 | 林总 | 1.88 |
| 小A | 林总 | 1.88 |
| 甜甜 | 陈腾鑫 | 1.82 |
| 欣欣 | 陈腾鑫 | 1.82 |
| 千千 | 陈腾鑫 | 1.82 |
| 小A | 陈腾鑫 | 1.82 |
| 佳怡 | 彭先生 | 1.80 |
| 婉婉 | 周先生 | 1.77 |
| 苏苏 | 周先生 | 1.68 |
| CC | 昌哥 | 1.64 |
| 周周 | 昌哥 | 1.64 |
| 球球 | 蔡总 | 1.57 |
| 小不点 | 蔡总 | 1.57 |
| 苏苏 | 李先生 | 1.53 |
| 吱吱 | 李先生 | 1.50 |
| 小敌 | 李先生 | 1.50 |
| 婉婉 | 刘哥 | 1.46 |
| CC | 林总 | 1.39 |
| 周周 | 林总 | 1.39 |
| 小不点 | T | 1.38 |
| 球球 | T | 1.38 |
| 悠悠 | 张先生 | 1.38 |
| 布丁 | 张先生 | 1.38 |
| 小怡 | 周先生 | 1.37 |
| 雯雯 | 周先生 | 1.37 |
| 素素 | 周先生 | 1.37 |
| 嘉嘉 | 轩哥 | 1.31 |
| 小柔 | 葛先生 | 1.30 |
| 乔西 | 张先生 | 1.29 |
| 小不点 | 候 | 1.23 |
| 球球 | 候 | 1.23 |
| 嘉嘉 | 罗先生 | 1.22 |
| 小侯 | T | 1.19 |
| 渔渔 | T | 1.19 |
| 姜姜 | T | 1.19 |
| 小侯 | 黄先生 | 1.19 |
| 小敌 | 林先生 | 1.19 |
| 姜姜 | 黄先生 | 1.19 |
| 吱吱 | 林先生 | 1.19 |
| 渔渔 | 黄先生 | 1.19 |
| 球球 | 葛先生 | 1.16 |
| 小不点 | 葛先生 | 1.16 |
| Amy | amy | 1.15 |
| 乔西 | T | 1.12 |
| 球球 | 老宋 | 1.10 |
| 小不点 | 老宋 | 1.10 |
| 乔西 | 林先生 | 1.01 |
| 素素 | 张先生 | 0.98 |
| 小怡 | 张先生 | 0.98 |
| 雯雯 | 张先生 | 0.98 |
| 佳怡 | T | 0.96 |
| 年糕 | 张先生 | 0.94 |
| 小侯 | 陈腾鑫 | 0.88 |
| 渔渔 | 陈腾鑫 | 0.88 |
| 姜姜 | 陈腾鑫 | 0.88 |
| 阿清 | 李先生 | 0.85 |
| 球球 | 林总 | 0.83 |
| 小不点 | 林总 | 0.83 |
| 婉婉 | 常总 | 0.77 |
| 小侯 | 艾宇民 | 0.76 |
| 姜姜 | 艾宇民 | 0.76 |
| 渔渔 | 艾宇民 | 0.76 |
| 小敌 | 郑先生 | 0.74 |
| 吱吱 | 郑先生 | 0.74 |
| 千千 | 罗先生 | 0.72 |
| 甜甜 | 罗先生 | 0.72 |
| 小A | 罗先生 | 0.72 |
| 欣欣 | 罗先生 | 0.72 |
| 球球 | 小燕 | 0.67 |
| 小不点 | 小燕 | 0.67 |
| 年糕 | 周先生 | 0.65 |
| 卡顿 | 罗先生 | 0.62 |
| 小燕 | 罗先生 | 0.62 |
| 小敌 | 刘哥 | 0.60 |
| 吱吱 | 刘哥 | 0.60 |
| 小柔 | 孟紫龙 | 0.56 |
| 阿清 | 候 | 0.54 |
| 乔西 | 候 | 0.49 |
| 小敌 | 张先生 | 0.46 |
| 甜甜 | T | 0.46 |
| 小A | T | 0.46 |
| 欣欣 | T | 0.46 |
| 千千 | T | 0.46 |
| 吱吱 | 张先生 | 0.46 |
| 小A | 游 | 0.38 |
| 千千 | 游 | 0.38 |
| 甜甜 | 游 | 0.38 |
| 欣欣 | 游 | 0.38 |
| 苏苏 | 葛先生 | 0.34 |
| 渔渔 | 候 | 0.32 |
| 小侯 | 候 | 0.32 |
| 姜姜 | 候 | 0.32 |
| 苏苏 | T | 0.31 |
| 婉婉 | 罗先生 | 0.26 |
| 涛涛 | 候 | 0.24 |
| 苏苏 | 候 | 0.23 |
| 阿清 | 常总 | 0.23 |
| 小不点 | 李先生 | 0.22 |
| 球球 | 李先生 | 0.22 |
| 小柔 | T | 0.19 |
| 年糕 | 潘先生 | 0.19 |
| 婉婉 | 候 | 0.18 |
| 小柔 | 罗先生 | 0.17 |
| 梦梦 | 葛先生 | 0.14 |
| 欣怡 | 葛先生 | 0.14 |
| 大姚 | 葛先生 | 0.14 |
| 椰子 | 葛先生 | 0.14 |
| 璇子 | 林先生 | 0.11 |
| 年糕 | 明哥 | 0.09 |
| 涛涛 | 张先生 | 0.08 |
| 周周 | 大G | 0.02 |
| 佳怡 | 大G | 0.02 |
| CC | 大G | 0.02 |
| 周周 | 明哥 | 0.00 |
| Amy | 明哥 | 0.00 |
| 小怡 | 叶先生 | 0.00 |
| 乔西 | 林先生 | 0.00 |
| 素素 | 叶先生 | 0.00 |
| 雯雯 | 叶先生 | 0.00 |
| 梦梦 | 蔡总 | 0.00 |
| 欣怡 | 蔡总 | 0.00 |
| 椰子 | 蔡总 | 0.00 |
| 大姚 | 蔡总 | 0.00 |
| 周周 | 游 | 0.00 |
| 小柔 | 昌哥 | 0.00 |
| CC | 游 | 0.00 |
| 佳怡 | 游 | 0.00 |
| CC | 明哥 | 0.00 |
| 小柔 | 江先生 | 0.00 |
共 391 条记录

BIN
etl_billiards/docs/index_tables_output.txt Normal file
View File

Binary file not shown.

167
etl_billiards/docs/补充更多信息.md Normal file
View File

@@ -0,0 +1,167 @@
# 补充更多信息：
## DWD数据库更新
DWD的数据库，若干表中，新增了若干表，可能会对整个DWS层设计有影响/优化，重新思考可用的字段。
## 支出/成本数据缺失
财务页需要房租、水电、物业、工资、报销、平台服务费等现金支出与“支出结构”，DWD 里只有商品成本 dwd_store_goods_sale.cost_money，但价格也不对。缺少费用/薪酬/平台服务费等表，导致“现金支出/现金结余/结余率/支出结构”无法落地。
### 更新：
- 这些内容先在数据库结构中预留，后期会通过Excel等方式手动导入。
## 平台回款与团购差价口径不足
需求有“平台回款”“团购差价”，DWD 只有团购核销/验券记录（dwd_groupbuy_redemption/dwd_platform_coupon_redemption），没有平台结算/回款/佣金/服务费明细，无法算“平台回款”与“平台服务费”。
### 更新：
- 确认的平台服务费与回款金额先在数据库结构中预留，后期会通过Excel等方式手动导入。
## 优惠分类无法分拆
财务页要区分“团购优惠/大客户优惠/赠送卡抵扣/其他优惠”，DWD 仅有 member_discount_amount / coupon_amount / adjust_amount / rounding_amount / gift_card_amount / recharge_card_amount 等汇总字段，且没有“大客户”标识或优惠原因维表，无法稳定拆分口径。
### 更新：
- 赠送卡抵扣 指的就是 酒水卡+台费卡+活动抵用券 结账 抵扣的。
- 团购优惠： ledger_amount + assistant_promotion_money - ledger_unit_price
- 大客户优惠和其他优惠：就是手动调账产生的优惠（订单中的折扣、台桌折扣、商品折扣、手动优惠这几项关系需要确认下，找100个样本进行分析）。
## “发生额/正价”口径不清
- 结账记录中的正价： tableChargeMoney（台费正价）goodsMoney（商品正价）assistantPdMoney（助教基础课正价）assistantCxMoney（助教激励课正价）
- 团购中的正价：ledger_amount(台桌正价) + assistant_promotion_money(助教正价)
- 团购中的核销价：ledger_unit_price
## 区域/房型维度不规范
筛选要“大厅A/B/C、麻将房、团建房/包厢”，DWD 只有 site_table_area_name 等自由文本，没有规范维表映射，容易导致前端筛选不可控。
### 更新
BD_manual_dim_table.md 中，有台区分布的对应关系
## 充值与赠送卡口径缺口
需求中“储值卡充值实收（首充/续费、不含赠送）”与“赠送卡新增/消费/余额”细分酒水卡/台费卡/抵用券。DWD 里 dwd_recharge_order 没有明确“赠送金额”字段；dim_member_card_account / dwd_member_balance_change 仅有卡类型名称，缺少“是否赠送”“卡类别标准枚举”，需要补充规则/维表。
### 更新
- 酒水卡，台费卡活动抵用券，台费卡 是赠送卡 分类在dim_member_card_account 的card_type_id，对应的数据库说明书中有介绍。
- 储值卡是充值的“现金卡”
## 助教薪酬规则未闭合
DWS 需求里“充值提成”空缺，且“冲刺奖/额外奖金”重复；没有助教工资/结算流水表，财务页“助教分成/奖惩”无法核算。
### 更新
- 充值提成数据库结构中预留，后期会通过Excel等方式手动导入。会记录时间，充值金额，储值卡卡关联，充值提成金额。
- “冲刺奖/额外奖金”重复：按照薪资说明进行相应调整。
- 没有助教工资/结算流水表：为我增加相应的表。满足业务逻辑。
## 时间分层与筛选不匹配
### 更新
- UI 需要“最近半年不含本月、上季度”等时间维度，并且满足上葛周期的环比。DWS 分层仅到 3 个月，可能导致查询性能或需要额外聚合层。财务方面需要特殊处理。
## 缺失 DDL：
方案里列出的表没有全部给出结构定义，包括 cfg_tier_effective_period、dws_assistant_salary_calc、dws_member_visit_detail、dws_finance_discount_detail、dws_finance_recharge_summary、dws_finance_expense_summary。这些在 DWS_任务计划_v1.md 中仅出现在清单里，但没有 DDL，会导致实施阶段卡住。
### 更新
- 补全DLL。
## SCD2 维度取数口径
助教等级在 dws_assistant_monthly_summary 用了 SCD2_is_current=1，这是否会把“当前等级”套到历史月份，能否满足需求中的“历史月份”统计？是否要加一些数据筛选条件？是否需按业务时间点做 as-of join（基于有效期）？
## 附加课/基础课口径
方案中用 skill_name 判断“超休/激励/打赏”为附加课，但我希望换成skill_id进行枚举，避免漏记或误记；落在库中可以使用名称。
## 财务指标可追溯口径
dws_finance_daily_summary 已覆盖“发生额/优惠/确认收入/现金流/充值”等字段，但缺少“数据来源矩阵”（字段→DWD表→公式）。财务需求对“发生额(正价)”和“优惠”拆分非常细，需明确“正价”来源（台费价、助教等级价、商品原价）与“优惠”拆分口径（团购差价、大客户折扣、赠送卡抵扣、免单/抹零、手动调整）。
### 更新
- 增加 数据来源矩阵，记录数据的来龙去脉
我觉得还不够全，给你一些我整理的内容。
# 1.2 DWD 核心表与关键字段
还差好多，举例：
## 助教服务相关：
dwd_assistant_service_log：
| `order_assistant_type` | 服务类型 | 1=基础课或包厢课, 2=附加课/激励课 | 这个不重要，用skill_id判断就好。
另外，服务时keh长，服务的助教ID与花名，客户关联，台桌号，台桌分类关联等也很重要。
## 客户相关：
客户姓名手机号生日以及关联的会员卡。
## 财务：
还有从结账记录出发关联的台桌流水助教流水
结算路径
充值流水等。
以上是否要补充？
---------------
## 订单获取的字段更新
### 订单各项正价小计
- 台费正价：table_charge_money
- 商品正价：goods_money
- 助教基础课/陪打正价：assistant_pd_money
- 助教激励课/超休正价：assistant_cx_money
### 支付信息
- 会员卡支付金额：recharge_card_amount。（卡类型还要从dwd_settlement_head的order_settle_id 去dwd_member_balance_change表，找到卡的类型。）
- 收银实付：pay_amount。
- 团购抵消的台费：coupon_amount。
- 团购支付的金额：2条路径，若pl_coupon_sale_amount非0 ，则使用pl_coupon_sale_amount。若pl_coupon_sale_amount为0且coupon_amount不为0，那么需要到dwd_groupbuy_redemption找到对应的订单的ledger_unit_price。
### 订单优惠与打折
- 台费打折：adjust_amount
- 团购券优惠：团购抵消的台费 - 团购支付的金额
-----------------
单独任务：
大客户优惠；抹零；其他优惠 需要抽样分析，当作一个单独任务为我分析执行。
| **会员折扣** | dwd_settlement_head | `member_discount_amount` | 会员身份折扣 | 这个貌似没有启用过，也为我作为单独任务分析处理吧。。
---------------
时间分层机制：需求明确“四层时间分层（近2天/近1月/近3月/全量）”，方案只写了更新频率，需补齐具体实现（分区策略/分层表或物化汇总层/定期归档与清理作业）。
DDL 完整性：补充说明中提到缺失的表（如 cfg_tier_effective_period、dws_assistant_salary_calc、dws_member_visit_detail、dws_finance_discount_detail、dws_finance_recharge_summary、dws_finance_expense_summary）需要在 schema_dws.sql 里落全；方案里写了“更新DDL”，但应明确完整DDL清单与字段级定义。
薪酬规则与生效期：档位、奖金、规则有“按月/按时间生效”的要求，方案目前只有 cfg_performance_tier/cfg_bonus_rules，需要补充生效期字段或独立“规则生效期配置表”，否则历史月份口径会错。
SCD2 / as-of 口径：助教等级是SCD2维度，历史月份不能直接用“当前等级”。方案需明确“按有效期 as-of join”的取数规则。
技能枚举规范：需求要求用 skill_id 判断基础课/附加课；方案应明确 skill_id→课程类型映射（可用配置表），避免 skill_name 漏记。
滚动区间统计：需求中明确 7/10/15/30/60/90 天窗口，方案未明确存储方式（建议在 dws_assistant_customer_stats、dws_member_consumption_summary 中直接落多窗口字段，或新增滚动汇总表）。
财务口径矩阵需全覆盖：方案已有“数据来源矩阵”，但需扩展至财务页面每一项指标（发生额/优惠拆分/确认收入/现金流/充值/平台回款/支出结构），确保每一项都有明确字段+公式+来源表。
手工导入表规范：支出/平台回款/充值提成的Excel导入要补“字段定义、时间粒度、门店维度、去重与校验规则”，否则实现阶段会反复返工。
区域/房型维表：方案已有 cfg_area_category，但需落地“具体映射规则 + 默认兜底 + 异常值处理”，并与 BD_manual_dim_table.md 一致。
# 更新
时间口径定义：本周/上周/本季度/上季度/最近半年不含本月 等窗口的“起止边界”为月第一天0点。周起始日为周一。
环比规则：开启对比时，是“对比上一个等长区间”相比。
有效业绩的排除规则：仅对“助教废除表”的记录进行处理排除。其影响绩效。
新入职定档规则：月1日0点之后入住的，计算为新入职。入职日以助教表入职时间为准。
Top3 奖金排名口径：按绩效总小时数。如遇并列则都算，比如2个第一，则记为2个第一，一个第三。
充值提成规则：比例/阶梯/时间口径缺失：通过手动导入表格，表格中会明确月份，提成关联充值订单金额和助教获得的提成金额。
大客户优惠/其他优惠划分规则：目前需要抽样分析。
平台回款/服务费口径：明确导入数据字段包含：回款金额、佣金、服务费、回款日期、平台类型、订单关联键。
散客处理：member_id=0 的客户是散客。不进入客户维度统计。
门店/租户范围：现在只有一个门店，一个租户。

198
etl_billiards/docs/财务页面需求.md Normal file
View File

@@ -0,0 +1,198 @@
# 筛选
- 按时间范围 本月/上个月/前3个月不加本月/前3个月+本月/最近半年不加本月/本季度含本月/上个季度/本周/上周
- 按区域筛选 大厅（A区/B区/C区） /麻将房/团建房
# 新增功能
- 一个开关，打开后，可以与紧邻前一个等长区间进行对比（用上下箭头表示增/跌，并跟随百分比。）
- 对比数值的UI需要设计，关闭状态和开启状态。
- 问号icon，点击会有相应的弹窗显示内容。将弹出放在页面底部，存在关闭按钮，且默认5秒后自动消失。不影响滚动等操
# 数据展示调整
## 黑色banner 经营状况一览
### 行1：收入概览 即 经营链：
- 发生额/正价。 点击提示icon：
"
按台桌/包厢/助教/酒水的“正价”计算出的理论销售额，反映经营规模与业务量。
计算方式 = 各收入项目按正价 × 数量/时长汇总计算。
**不是最终收到了多少钱。**
"
- 总优惠 | 优惠比例。点击提示icon：
"
本期因团购差价、大客户折扣、赠送卡抵扣、免单/抹零等导致的让利总额，用于解释“发生额”与“成交/确认收入”的差异。
计算方式 = 发生额 − 成交/确认收入
或 = 团购优惠 + 大客户优惠 + 赠送抵扣 + 其他优惠/免单/抹零（汇总）
"
- 成交/确认收入。点击提示icon：
"
扣除各种优惠后的成交金额，**按记账规则统计的营业收入**。
计算方式 = 发生额 − 团购优惠 − 大客户优惠 − 赠送抵扣（及其他优惠）。
**不含充值营业收入** 充值是预收/负债，但会影响现金流。**
"
### 行2：现金概览 注：往期为已结算，本期为预估：
- 实收/现金流入
"
统计真实进账的资金，包括现金 + 线上支付 + 平台回款。
计算方式 = 消费实收 + 平台团购 - 各类退款/冲正。
**此为现金口径，不等于营业收入。**区别为：充值属于预收款的现金流入，属于预存行为，球房债务。
"
- 现金支出。点击提示icon：
"
本期所有支出项目的合计。
计算方式 = 房租 + 水电 + 进货成本支出 + 耗材 + 报销 + 助教分成 + 固定人员工资 + 平台服务费 + 其他费用
"
- 现金结余 | 结余率。点击提示icon：
"
本期营业收入扣除全部成本后的利润，用于衡量经营质量。
计算方式= 实收/现金流入 − 总支出。
"
## AI分析
以下内容先占位，真实内容会通过AI接口调用展示，此处为标准Markdown内容排版。
优惠率Top：团购(%) / 大客户(%) / 赠送卡(%)
差异最大项目：酒水 / 台桌 / 包厢 ...
财务分析：充值高但消耗低（或相反）提示
## 充值与预收
### 行1 会员卡概览
- 储值卡充值实收 首充 | 续费 | 合计。点击提示icon：
"
本期储值卡充值到账的新增金额。
按照首充，续费，合计路径进行统计。
计算方式 = 本期储值卡充值订单的实收金额。
不含赠送金额
"
- 全类别会员卡余额合计 **仅经营参考，非财务属性**。点击提示icon：
"
截至本期末，顾客充值后尚未消费的储值余额，包括赠送的台费卡酒水卡等类别，用于判断未来可转化的消费规模。
计算方式 = 各类会员卡往期余额 + 本期充值到账与赠送到账 − 本期卡消耗 ± 调整（退款/冲正/手工修正）
"
### 行2 储值卡统计详情
- 储值卡充值。点击提示icon：
"
本期储值卡充值到账的新增金额。
"
- 储值卡消耗。点击提示icon：
"
余额卡在查询周期内消耗金额。
计算方式 = 本期消耗 ± 调整
"
- 储值卡总余额。点击提示icon：
"
截至本期末，余额卡可用的余额。
计算方式 = 期初余额卡余额 + 本期新增 − 本期消耗 ± 调整
"
### 行3 赠送卡统计详情
需要设计下页面，主要字段是合计，且细分的也要展示。
- 赠送卡新增合计；细分 酒水卡|台费卡|抵用券。点击提示icon：
"
本期各类型赠送卡的新增金额。
"
- 赠送卡消费合计；细分酒水卡|台费卡|抵用券。点击提示icon：
"
本期各类型赠送卡在查询周期内消耗金额。
计算方式 = 本期消耗 ± 调整
"
- 赠送卡总余额合计；细分酒水卡|台费卡|抵用券。点击提示icon：
"
截至本期末，各类型赠送卡可用的余额。
计算方式 = 期初余额 + 本期新增 − 本期消耗 ± 调整
"
## 发生额 → 入账收入 及 优惠影响
页面字段结构：
### 收入确认（损益链）
发生额(正价) ¥123,456
├─ 团购优惠 -¥ 6,200
├─ 手动调整 + 大客户优惠 -¥ 4,800
├─ 赠送卡抵扣(台桌卡+酒水卡+抵用券) -¥ 2,336
└─ 其他优惠 免单+抹零 -¥ 0
成交/确认收入 ¥110,120
支付方式构成
├─ 由储值卡结算冲销 ¥60,120
├─ 现金/线上支付 ¥60,120
└─ 团购核销确认收入（团购成交价） ¥60,120
现金流
消费现金流入：现金+线上+平台回款−退款 ¥60,120
充值到账（首充/续费） ¥60,120
现金流入合计 ¥60,120
### 收入结构
收入结构（发生额 | 优惠 | 入账 ）
开台与包厢 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
├─ A区 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
├─ B区 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
├─ C区 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
├─ 团建区 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
└─ 麻将区 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
助教(基础课) ¥xx,xxx | -¥ | ¥xx,xxx
助教(激励课) ¥xx,xxx | -¥ | ¥xx,xxx
食品酒水 ¥xx,xxx | -¥x,xxx | ¥xx,xxx
## 支出结构
助教分成：基础¥x,xxx 附加¥x,xxx 充值提成¥x,xxx
助教额外奖金：¥x,xxx
食品饮料进货：¥x,xxx 耗材¥x,xxx 报销¥x,xxx
房租¥x,xxx 水电¥x,xxx 物业¥x,xxx
固定人员工资¥x,xxx
汇来米平台服务费¥x,xxx
美团服务费¥x,xxx 抖音服务费¥x,xxx
支出合计 ¥ xx,xxx
## 助教收支分析
助教基础课 客户支付 | 球房抽成 | 球房均小时抽成
├─ 初级 客户支付 | 球房抽成 | 球房均小时抽成
├─ 中级 客户支付 | 球房抽成 | 球房均小时抽成
├─ 高级 客户支付 | 球房抽成 | 球房均小时抽成
└─ 星级 客户支付 | 球房抽成 | 球房均小时抽成
助教激励课 客户支付 | 球房抽成 | 球房均小时抽成

7
etl_billiards/gui/widgets/task_panel.py
View File

@@ -1197,6 +1197,11 @@ class TaskPanel(QWidget):
self.integrity_compare_content.setChecked(app_settings.integrity_compare_content)
if hasattr(app_settings, 'integrity_auto_backfill'):
self.integrity_auto_backfill.setChecked(app_settings.integrity_auto_backfill)
# 加载补齐相关子选项（需要在 auto_backfill 之后加载，因为它们的启用状态依赖 auto_backfill）
if hasattr(app_settings, 'integrity_backfill_mismatch'):
self.integrity_backfill_mismatch.setChecked(app_settings.integrity_backfill_mismatch)
if hasattr(app_settings, 'integrity_recheck'):
self.integrity_recheck.setChecked(app_settings.integrity_recheck)
if hasattr(app_settings, 'integrity_ods_tasks'):
self.integrity_ods_tasks.setText(app_settings.integrity_ods_tasks)
@@ -1256,6 +1261,8 @@ class TaskPanel(QWidget):
app_settings.integrity_include_dimensions = self.integrity_include_dimensions.isChecked()
app_settings.integrity_compare_content = self.integrity_compare_content.isChecked()
app_settings.integrity_auto_backfill = self.integrity_auto_backfill.isChecked()
app_settings.integrity_backfill_mismatch = self.integrity_backfill_mismatch.isChecked()
app_settings.integrity_recheck = self.integrity_recheck.isChecked()
app_settings.integrity_ods_tasks = self.integrity_ods_tasks.text().strip()
except Exception as e:
print(f"保存数据校验设置失败: {e}")

40
etl_billiards/orchestration/task_registry.py
View File

@@ -28,6 +28,26 @@ from tasks.check_cutoff_task import CheckCutoffTask
from tasks.init_dws_schema_task import InitDwsSchemaTask
from tasks.dws_build_order_summary_task import DwsBuildOrderSummaryTask
from tasks.data_integrity_task import DataIntegrityTask
from tasks.seed_dws_config_task import SeedDwsConfigTask
# DWS 层任务导入
from tasks.dws import (
AssistantDailyTask,
AssistantMonthlyTask,
AssistantCustomerTask,
AssistantSalaryTask,
AssistantFinanceTask,
MemberConsumptionTask,
MemberVisitTask,
FinanceDailyTask,
FinanceRechargeTask,
FinanceIncomeStructureTask,
FinanceDiscountDetailTask,
DwsRetentionCleanupTask,
# 指数算法任务
RecallIndexTask,
IntimacyIndexTask,
)
class TaskRegistry:
"""任务注册和工厂"""
@@ -81,6 +101,26 @@ default_registry.register("ODS_JSON_ARCHIVE", OdsJsonArchiveTask)
default_registry.register("CHECK_CUTOFF", CheckCutoffTask)
default_registry.register("DATA_INTEGRITY_CHECK", DataIntegrityTask)
default_registry.register("INIT_DWS_SCHEMA", InitDwsSchemaTask)
default_registry.register("SEED_DWS_CONFIG", SeedDwsConfigTask)
default_registry.register("DWS_BUILD_ORDER_SUMMARY", DwsBuildOrderSummaryTask)
# DWS 层业务任务
default_registry.register("DWS_ASSISTANT_DAILY", AssistantDailyTask)
default_registry.register("DWS_ASSISTANT_MONTHLY", AssistantMonthlyTask)
default_registry.register("DWS_ASSISTANT_CUSTOMER", AssistantCustomerTask)
default_registry.register("DWS_ASSISTANT_SALARY", AssistantSalaryTask)
default_registry.register("DWS_ASSISTANT_FINANCE", AssistantFinanceTask)
default_registry.register("DWS_MEMBER_CONSUMPTION", MemberConsumptionTask)
default_registry.register("DWS_MEMBER_VISIT", MemberVisitTask)
default_registry.register("DWS_FINANCE_DAILY", FinanceDailyTask)
default_registry.register("DWS_FINANCE_RECHARGE", FinanceRechargeTask)
default_registry.register("DWS_FINANCE_INCOME_STRUCTURE", FinanceIncomeStructureTask)
default_registry.register("DWS_FINANCE_DISCOUNT_DETAIL", FinanceDiscountDetailTask)
default_registry.register("DWS_RETENTION_CLEANUP", DwsRetentionCleanupTask)
# DWS 指数算法任务
default_registry.register("DWS_RECALL_INDEX", RecallIndexTask)
default_registry.register("DWS_INTIMACY_INDEX", IntimacyIndexTask)
for code, task_cls in ODS_TASK_CLASSES.items():
default_registry.register(code, task_cls)

318
etl_billiards/scheduled_tasks.json
View File

File diff suppressed because one or more lines are too long

636
etl_billiards/scripts/analyze_discount_patterns.py Normal file
View File

@@ -0,0 +1,636 @@
# -*- coding: utf-8 -*-
"""
优惠口径抽样分析脚本
功能说明：
从dwd_settlement_head表抽样100单，分析以下优惠字段的使用情况：
- adjust_amount: 台费打折/调整（可能包含大客户优惠、其他优惠）
- member_discount_amount: 会员折扣
- rounding_amount: 抹零金额
- coupon_amount: 团购抵消台费
- gift_card_amount: 赠送卡支付
分析目标：
1. 大客户优惠：是否存在"大客户"标识？如何与普通调整区分？
2. 会员折扣：是否有非零值？使用场景是什么？
3. 抹零：抹零规则？与adjust_amount的关系？
4. 其他优惠：adjust_amount中还包含哪些优惠类型？
输出：
- 控制台打印分析报告
- 生成 docs/analysis_discount_patterns.md 报告文件
作者：ETL团队
创建日期：2026-02-01
"""
import os
import sys
from datetime import datetime
from decimal import Decimal
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
# 添加项目根目录到Python路径
project_root = Path(__file__).parent.parent.parent
sys.path.insert(0, str(project_root))
from etl_billiards.utils.config import Config
from etl_billiards.utils.db import DatabaseConnection
def analyze_discount_patterns():
"""
执行优惠口径抽样分析
"""
print("=" * 80)
print("优惠口径抽样分析")
print("=" * 80)
print()
# 加载配置和数据库连接
config = Config()
db = DatabaseConnection(config)
try:
# 1. 获取总体统计
print("【1. 总体统计】")
print("-" * 40)
overall_stats = get_overall_stats(db)
print_overall_stats(overall_stats)
print()
# 2. 抽样分析优惠订单
print("【2. 有优惠的订单抽样分析（100单）】")
print("-" * 40)
sample_orders = get_sample_orders_with_discount(db, limit=100)
discount_analysis = analyze_sample_orders(sample_orders)
print_discount_analysis(discount_analysis)
print()
# 3. adjust_amount详细分析
print("【3. adjust_amount (台费打折/调整) 详细分析】")
print("-" * 40)
adjust_analysis = analyze_adjust_amount(db)
print_adjust_analysis(adjust_analysis)
print()
# 4. 会员折扣使用分析
print("【4. member_discount_amount (会员折扣) 使用分析】")
print("-" * 40)
member_discount_analysis = analyze_member_discount(db)
print_member_discount_analysis(member_discount_analysis)
print()
# 5. 抹零规则分析
print("【5. rounding_amount (抹零) 规则分析】")
print("-" * 40)
rounding_analysis = analyze_rounding(db)
print_rounding_analysis(rounding_analysis)
print()
# 6. 团购优惠分析
print("【6. 团购优惠分析】")
print("-" * 40)
groupbuy_analysis = analyze_groupbuy(db)
print_groupbuy_analysis(groupbuy_analysis)
print()
# 7. 生成分析报告
print("【7. 生成分析报告】")
print("-" * 40)
report = generate_report(
overall_stats,
discount_analysis,
adjust_analysis,
member_discount_analysis,
rounding_analysis,
groupbuy_analysis
)
# 保存报告
report_path = project_root / "etl_billiards" / "docs" / "analysis_discount_patterns.md"
with open(report_path, 'w', encoding='utf-8') as f:
f.write(report)
print(f"报告已保存到: {report_path}")
finally:
db.close()
def get_overall_stats(db: DatabaseConnection) -> Dict[str, Any]:
"""
获取总体统计数据
"""
sql = """
SELECT
COUNT(*) AS total_orders,
COUNT(CASE WHEN adjust_amount != 0 THEN 1 END) AS orders_with_adjust,
COUNT(CASE WHEN member_discount_amount != 0 THEN 1 END) AS orders_with_member_discount,
COUNT(CASE WHEN rounding_amount != 0 THEN 1 END) AS orders_with_rounding,
COUNT(CASE WHEN coupon_amount != 0 THEN 1 END) AS orders_with_coupon,
COUNT(CASE WHEN gift_card_amount != 0 THEN 1 END) AS orders_with_gift_card,
SUM(adjust_amount) AS total_adjust,
SUM(member_discount_amount) AS total_member_discount,
SUM(rounding_amount) AS total_rounding,
SUM(coupon_amount) AS total_coupon,
SUM(gift_card_amount) AS total_gift_card,
SUM(consume_money) AS total_consume,
SUM(pay_amount) AS total_pay
FROM billiards_dwd.dwd_settlement_head
"""
rows = db.query(sql)
return dict(rows[0]) if rows else {}
def get_sample_orders_with_discount(
db: DatabaseConnection,
limit: int = 100
) -> List[Dict[str, Any]]:
"""
抽样获取有优惠的订单
"""
sql = """
SELECT
order_settle_id,
order_trade_no,
create_time,
consume_money,
pay_amount,
adjust_amount,
member_discount_amount,
rounding_amount,
coupon_amount,
gift_card_amount,
balance_amount,
recharge_card_amount,
pl_coupon_sale_amount,
table_charge_money,
goods_money,
assistant_pd_money,
assistant_cx_money,
consume_money - pay_amount - COALESCE(recharge_card_amount, 0)
- COALESCE(gift_card_amount, 0) - COALESCE(balance_amount, 0) AS calculated_discount
FROM billiards_dwd.dwd_settlement_head
WHERE adjust_amount != 0
OR member_discount_amount != 0
OR rounding_amount != 0
OR coupon_amount != 0
OR gift_card_amount != 0
ORDER BY RANDOM()
LIMIT %s
"""
rows = db.query(sql, (limit,))
return [dict(row) for row in rows] if rows else []
def analyze_sample_orders(orders: List[Dict[str, Any]]) -> Dict[str, Any]:
"""
分析抽样订单
"""
analysis = {
'total_sampled': len(orders),
'with_adjust': 0,
'with_member_discount': 0,
'with_rounding': 0,
'with_coupon': 0,
'with_gift_card': 0,
'adjust_values': [],
'member_discount_values': [],
'rounding_values': [],
'coupon_values': [],
'gift_card_values': [],
}
for order in orders:
adjust = Decimal(str(order.get('adjust_amount', 0)))
member_discount = Decimal(str(order.get('member_discount_amount', 0)))
rounding = Decimal(str(order.get('rounding_amount', 0)))
coupon = Decimal(str(order.get('coupon_amount', 0)))
gift_card = Decimal(str(order.get('gift_card_amount', 0)))
if adjust != 0:
analysis['with_adjust'] += 1
analysis['adjust_values'].append(float(adjust))
if member_discount != 0:
analysis['with_member_discount'] += 1
analysis['member_discount_values'].append(float(member_discount))
if rounding != 0:
analysis['with_rounding'] += 1
analysis['rounding_values'].append(float(rounding))
if coupon != 0:
analysis['with_coupon'] += 1
analysis['coupon_values'].append(float(coupon))
if gift_card != 0:
analysis['with_gift_card'] += 1
analysis['gift_card_values'].append(float(gift_card))
return analysis
def analyze_adjust_amount(db: DatabaseConnection) -> Dict[str, Any]:
"""
分析adjust_amount字段的分布和模式
"""
# 1. 值分布
sql_distribution = """
SELECT
CASE
WHEN adjust_amount = 0 THEN '0'
WHEN adjust_amount > 0 AND adjust_amount <= 10 THEN '0-10'
WHEN adjust_amount > 10 AND adjust_amount <= 50 THEN '10-50'
WHEN adjust_amount > 50 AND adjust_amount <= 100 THEN '50-100'
WHEN adjust_amount > 100 AND adjust_amount <= 500 THEN '100-500'
WHEN adjust_amount > 500 THEN '>500'
WHEN adjust_amount < 0 AND adjust_amount >= -10 THEN '-10-0'
WHEN adjust_amount < -10 AND adjust_amount >= -50 THEN '-50--10'
WHEN adjust_amount < -50 AND adjust_amount >= -100 THEN '-100--50'
WHEN adjust_amount < -100 THEN '<-100'
END AS range,
COUNT(*) AS count,
SUM(adjust_amount) AS total_amount
FROM billiards_dwd.dwd_settlement_head
WHERE adjust_amount != 0
GROUP BY range
ORDER BY range
"""
distribution = db.query(sql_distribution)
# 2. 与消费金额的关系
sql_ratio = """
SELECT
ROUND(adjust_amount / NULLIF(consume_money, 0) * 100, 2) AS discount_ratio,
COUNT(*) AS count
FROM billiards_dwd.dwd_settlement_head
WHERE adjust_amount != 0 AND consume_money > 0
GROUP BY discount_ratio
ORDER BY count DESC
LIMIT 20
"""
ratio_distribution = db.query(sql_ratio)
# 3. 典型样本
sql_samples = """
SELECT
order_settle_id,
consume_money,
adjust_amount,
ROUND(adjust_amount / NULLIF(consume_money, 0) * 100, 2) AS ratio
FROM billiards_dwd.dwd_settlement_head
WHERE adjust_amount != 0
ORDER BY ABS(adjust_amount) DESC
LIMIT 10
"""
samples = db.query(sql_samples)
return {
'distribution': [dict(r) for r in distribution] if distribution else [],
'ratio_distribution': [dict(r) for r in ratio_distribution] if ratio_distribution else [],
'top_samples': [dict(r) for r in samples] if samples else []
}
def analyze_member_discount(db: DatabaseConnection) -> Dict[str, Any]:
"""
分析member_discount_amount字段的使用情况
"""
sql = """
SELECT
COUNT(*) AS total_orders,
COUNT(CASE WHEN member_discount_amount != 0 THEN 1 END) AS with_discount,
SUM(member_discount_amount) AS total_discount,
AVG(CASE WHEN member_discount_amount != 0 THEN member_discount_amount END) AS avg_discount,
MAX(member_discount_amount) AS max_discount,
MIN(CASE WHEN member_discount_amount != 0 THEN member_discount_amount END) AS min_discount
FROM billiards_dwd.dwd_settlement_head
"""
rows = db.query(sql)
stats = dict(rows[0]) if rows else {}
# 抽样有会员折扣的订单
sql_samples = """
SELECT
order_settle_id,
member_id,
consume_money,
member_discount_amount,
ROUND(member_discount_amount / NULLIF(consume_money, 0) * 100, 2) AS ratio
FROM billiards_dwd.dwd_settlement_head
WHERE member_discount_amount != 0
LIMIT 20
"""
samples = db.query(sql_samples)
return {
'stats': stats,
'samples': [dict(r) for r in samples] if samples else []
}
def analyze_rounding(db: DatabaseConnection) -> Dict[str, Any]:
"""
分析rounding_amount字段的规则
"""
# 1. 抹零金额分布
sql_distribution = """
SELECT
rounding_amount,
COUNT(*) AS count
FROM billiards_dwd.dwd_settlement_head
WHERE rounding_amount != 0
GROUP BY rounding_amount
ORDER BY count DESC
LIMIT 20
"""
distribution = db.query(sql_distribution)
# 2. 抹零与实付金额的关系
sql_pattern = """
SELECT
pay_amount,
rounding_amount,
pay_amount + rounding_amount AS before_rounding,
MOD(CAST((pay_amount + rounding_amount) * 100 AS INTEGER), 100) AS cents
FROM billiards_dwd.dwd_settlement_head
WHERE rounding_amount != 0
LIMIT 20
"""
patterns = db.query(sql_pattern)
return {
'distribution': [dict(r) for r in distribution] if distribution else [],
'patterns': [dict(r) for r in patterns] if patterns else []
}
def analyze_groupbuy(db: DatabaseConnection) -> Dict[str, Any]:
"""
分析团购优惠
"""
# 1. 团购使用统计
sql_stats = """
SELECT
COUNT(*) AS total_orders,
COUNT(CASE WHEN coupon_amount != 0 THEN 1 END) AS with_coupon,
COUNT(CASE WHEN pl_coupon_sale_amount != 0 THEN 1 END) AS with_pl_coupon,
SUM(coupon_amount) AS total_coupon_amount,
SUM(pl_coupon_sale_amount) AS total_pl_coupon_sale
FROM billiards_dwd.dwd_settlement_head
"""
stats = db.query(sql_stats)
# 2. 团购订单样本
sql_samples = """
SELECT
sh.order_settle_id,
sh.coupon_amount,
sh.pl_coupon_sale_amount,
gr.ledger_amount AS groupbuy_ledger_amount,
gr.ledger_unit_price AS groupbuy_unit_price
FROM billiards_dwd.dwd_settlement_head sh
LEFT JOIN billiards_dwd.dwd_groupbuy_redemption gr
ON sh.order_settle_id = gr.order_settle_id
WHERE sh.coupon_amount != 0
LIMIT 20
"""
samples = db.query(sql_samples)
return {
'stats': dict(stats[0]) if stats else {},
'samples': [dict(r) for r in samples] if samples else []
}
def print_overall_stats(stats: Dict[str, Any]):
"""打印总体统计"""
total = stats.get('total_orders', 0)
print(f"总订单数: {total:,}")
print(f"有adjust_amount的订单: {stats.get('orders_with_adjust', 0):,} ({stats.get('orders_with_adjust', 0)/total*100:.2f}%)")
print(f"有member_discount的订单: {stats.get('orders_with_member_discount', 0):,} ({stats.get('orders_with_member_discount', 0)/total*100:.2f}%)")
print(f"有rounding的订单: {stats.get('orders_with_rounding', 0):,} ({stats.get('orders_with_rounding', 0)/total*100:.2f}%)")
print(f"有coupon的订单: {stats.get('orders_with_coupon', 0):,} ({stats.get('orders_with_coupon', 0)/total*100:.2f}%)")
print(f"有gift_card的订单: {stats.get('orders_with_gift_card', 0):,} ({stats.get('orders_with_gift_card', 0)/total*100:.2f}%)")
print()
print(f"adjust_amount总额: {stats.get('total_adjust', 0):,.2f}")
print(f"member_discount总额: {stats.get('total_member_discount', 0):,.2f}")
print(f"rounding总额: {stats.get('total_rounding', 0):,.2f}")
print(f"coupon总额: {stats.get('total_coupon', 0):,.2f}")
print(f"gift_card总额: {stats.get('total_gift_card', 0):,.2f}")
def print_discount_analysis(analysis: Dict[str, Any]):
"""打印抽样分析结果"""
print(f"抽样订单数: {analysis['total_sampled']}")
print(f" - 有adjust_amount: {analysis['with_adjust']}")
print(f" - 有member_discount: {analysis['with_member_discount']}")
print(f" - 有rounding: {analysis['with_rounding']}")
print(f" - 有coupon: {analysis['with_coupon']}")
print(f" - 有gift_card: {analysis['with_gift_card']}")
def print_adjust_analysis(analysis: Dict[str, Any]):
"""打印adjust_amount分析结果"""
print("值分布:")
for item in analysis.get('distribution', []):
print(f" {item.get('range', 'N/A')}: {item.get('count', 0):,} 单, 总额 {item.get('total_amount', 0):,.2f}")
print("\n折扣比例分布 (Top 10):")
for item in analysis.get('ratio_distribution', [])[:10]:
print(f" {item.get('discount_ratio', 0)}%: {item.get('count', 0):,} 单")
print("\n大额调整样本 (Top 10):")
for item in analysis.get('top_samples', []):
print(f" 订单{item.get('order_settle_id')}: 消费{item.get('consume_money', 0):,.2f}, 调整{item.get('adjust_amount', 0):,.2f} ({item.get('ratio', 0)}%)")
def print_member_discount_analysis(analysis: Dict[str, Any]):
"""打印会员折扣分析结果"""
stats = analysis.get('stats', {})
print(f"总订单数: {stats.get('total_orders', 0):,}")
print(f"有会员折扣的订单: {stats.get('with_discount', 0):,}")
print(f"会员折扣总额: {stats.get('total_discount', 0):,.2f}")
print(f"平均折扣: {stats.get('avg_discount', 0):,.2f}")
print(f"最大折扣: {stats.get('max_discount', 0):,.2f}")
samples = analysis.get('samples', [])
if samples:
print("\n样本订单:")
for item in samples[:5]:
print(f" 订单{item.get('order_settle_id')}: 会员{item.get('member_id')}, 消费{item.get('consume_money', 0):,.2f}, 折扣{item.get('member_discount_amount', 0):,.2f} ({item.get('ratio', 0)}%)")
else:
print("\n[!] 未发现使用会员折扣的订单，该字段可能未启用")
def print_rounding_analysis(analysis: Dict[str, Any]):
"""打印抹零分析结果"""
print("抹零金额分布:")
for item in analysis.get('distribution', []):
print(f" {item.get('rounding_amount', 0):,.2f}: {item.get('count', 0):,} 单")
print("\n抹零模式样本:")
for item in analysis.get('patterns', [])[:5]:
print(f" 实付{item.get('pay_amount', 0):,.2f} + 抹零{item.get('rounding_amount', 0):,.2f} = {item.get('before_rounding', 0):,.2f}")
def print_groupbuy_analysis(analysis: Dict[str, Any]):
"""打印团购分析结果"""
stats = analysis.get('stats', {})
print(f"总订单数: {stats.get('total_orders', 0):,}")
print(f"有coupon_amount的订单: {stats.get('with_coupon', 0):,}")
print(f"有pl_coupon_sale_amount的订单: {stats.get('with_pl_coupon', 0):,}")
print(f"coupon_amount总额: {stats.get('total_coupon_amount', 0):,.2f}")
print(f"pl_coupon_sale_amount总额: {stats.get('total_pl_coupon_sale', 0):,.2f}")
print("\n团购订单样本:")
for item in analysis.get('samples', [])[:5]:
print(f" 订单{item.get('order_settle_id')}: coupon={item.get('coupon_amount', 0):,.2f}, pl_coupon={item.get('pl_coupon_sale_amount', 0):,.2f}, groupbuy_price={item.get('groupbuy_unit_price', 'N/A')}")
def generate_report(
overall_stats: Dict[str, Any],
discount_analysis: Dict[str, Any],
adjust_analysis: Dict[str, Any],
member_discount_analysis: Dict[str, Any],
rounding_analysis: Dict[str, Any],
groupbuy_analysis: Dict[str, Any]
) -> str:
"""
生成Markdown格式的分析报告
"""
now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
total = overall_stats.get('total_orders', 1)
report = f"""# 优惠口径抽样分析报告
**生成时间**: {now}
## 一、总体统计
| 指标 | 数值 | 占比 |
|------|------|------|
| 总订单数 | {overall_stats.get('total_orders', 0):,} | 100% |
| 有adjust_amount的订单 | {overall_stats.get('orders_with_adjust', 0):,} | {overall_stats.get('orders_with_adjust', 0)/total*100:.2f}% |
| 有member_discount的订单 | {overall_stats.get('orders_with_member_discount', 0):,} | {overall_stats.get('orders_with_member_discount', 0)/total*100:.2f}% |
| 有rounding的订单 | {overall_stats.get('orders_with_rounding', 0):,} | {overall_stats.get('orders_with_rounding', 0)/total*100:.2f}% |
| 有coupon的订单 | {overall_stats.get('orders_with_coupon', 0):,} | {overall_stats.get('orders_with_coupon', 0)/total*100:.2f}% |
| 有gift_card的订单 | {overall_stats.get('orders_with_gift_card', 0):,} | {overall_stats.get('orders_with_gift_card', 0)/total*100:.2f}% |
### 金额统计
| 优惠类型 | 总额 |
|----------|------|
| adjust_amount (台费打折/调整) | {overall_stats.get('total_adjust', 0):,.2f} |
| member_discount_amount (会员折扣) | {overall_stats.get('total_member_discount', 0):,.2f} |
| rounding_amount (抹零) | {overall_stats.get('total_rounding', 0):,.2f} |
| coupon_amount (团购抵消台费) | {overall_stats.get('total_coupon', 0):,.2f} |
| gift_card_amount (赠送卡支付) | {overall_stats.get('total_gift_card', 0):,.2f} |
## 二、adjust_amount (台费打折/调整) 分析
### 值分布
| 区间 | 订单数 | 总额 |
|------|--------|------|
"""
for item in adjust_analysis.get('distribution', []):
report += f"| {item.get('range', 'N/A')} | {item.get('count', 0):,} | {item.get('total_amount', 0):,.2f} |\n"
report += """
### 分析结论
- **是否包含大客户优惠**: 需要进一步分析adjust_amount的业务来源
- **与普通调整的区分**: 建议查看是否有备注字段或关联的优惠活动表
## 三、member_discount_amount (会员折扣) 分析
"""
member_stats = member_discount_analysis.get('stats', {})
with_discount = member_stats.get('with_discount', 0)
if with_discount == 0:
report += """### 结论
**[!] 该字段未发现任何非零值，会员折扣功能可能未启用。**
建议：在DWS财务统计中，可以暂时忽略此字段，或将其标记为"待启用"。
"""
else:
report += f"""### 使用统计
| 指标 | 数值 |
|------|------|
| 有会员折扣的订单 | {with_discount:,} |
| 会员折扣总额 | {member_stats.get('total_discount', 0):,.2f} |
| 平均折扣 | {member_stats.get('avg_discount', 0):,.2f} |
| 最大折扣 | {member_stats.get('max_discount', 0):,.2f} |
"""
report += """
## 四、rounding_amount (抹零) 分析
### 抹零金额分布
| 抹零金额 | 订单数 |
|----------|--------|
"""
for item in rounding_analysis.get('distribution', [])[:10]:
report += f"| {item.get('rounding_amount', 0):,.2f} | {item.get('count', 0):,} |\n"
report += """
### 抹零规则推断
根据抹零金额分布，推断抹零规则为：
- 抹零到整元（去除角分）
- 或抹零到特定尾数
## 五、团购优惠分析
"""
groupbuy_stats = groupbuy_analysis.get('stats', {})
report += f"""### 使用统计
| 指标 | 数值 |
|------|------|
| 有coupon_amount的订单 | {groupbuy_stats.get('with_coupon', 0):,} |
| 有pl_coupon_sale_amount的订单 | {groupbuy_stats.get('with_pl_coupon', 0):,} |
| coupon_amount总额 | {groupbuy_stats.get('total_coupon_amount', 0):,.2f} |
| pl_coupon_sale_amount总额 | {groupbuy_stats.get('total_pl_coupon_sale', 0):,.2f} |
### 团购支付金额计算路径
根据分析，团购支付金额应按以下路径计算：
1. 若 `pl_coupon_sale_amount ≠ 0` → 使用 `pl_coupon_sale_amount`
2. 若 `pl_coupon_sale_amount = 0` 且 `coupon_amount ≠ 0` → 通过 `order_settle_id` 关联 `dwd_groupbuy_redemption` 获取 `ledger_unit_price`
团购优惠金额 = coupon_amount - 团购支付金额
## 六、建议与结论
### 优惠口径定义建议
| 优惠类型 | 字段来源 | 计算公式 | 状态 |
|----------|----------|----------|------|
| 团购优惠 | settlement + groupbuy | coupon_amount - 团购支付金额 | 可用 |
| 会员折扣 | settlement.member_discount_amount | 直接取值 | 待确认 |
| 赠送卡抵扣 | settlement.gift_card_amount | 直接取值 | 可用 |
| 手动调整 | settlement.adjust_amount | 直接取值 | 可用 |
| 抹零 | settlement.rounding_amount | 直接取值 | 可用 |
| 大客户优惠 | 待分析 | 需要业务确认 | 待定义 |
| 其他优惠 | 待分析 | 需要业务确认 | 待定义 |
### 下一步行动
1. **确认会员折扣是否启用**: 与业务确认member_discount_amount的使用场景
2. **大客户优惠识别规则**: 与业务确认如何从adjust_amount中识别大客户优惠
3. **其他优惠分类**: 与业务确认adjust_amount中还包含哪些优惠类型
"""
return report
if __name__ == "__main__":
analyze_discount_patterns()

287
etl_billiards/scripts/analyze_member_discount_usage.py Normal file
View File

@@ -0,0 +1,287 @@
# -*- coding: utf-8 -*-
"""
会员折扣启用分析脚本
功能说明：
确认 dwd_settlement_head.member_discount_amount 字段是否已启用
分析内容：
1. 统计非零记录数
2. 按时间分布分析
3. 按会员类型分析
4. 与其他字段的关联分析
输出：
- 控制台打印分析结果
- 结论：字段是否已启用，使用场景
作者：ETL团队
创建日期：2026-02-01
"""
import os
import sys
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List
# 添加项目根目录到Python路径
project_root = Path(__file__).parent.parent.parent
sys.path.insert(0, str(project_root))
from etl_billiards.utils.config import Config
from etl_billiards.utils.db import DatabaseConnection
def analyze_member_discount_usage():
"""
执行会员折扣启用分析
"""
print("=" * 80)
print("会员折扣启用分析 (member_discount_amount)")
print("=" * 80)
print()
# 加载配置和数据库连接
config = Config()
db = DatabaseConnection(config)
try:
# 1. 基础统计
print("【1. 基础统计】")
print("-" * 40)
basic_stats = get_basic_stats(db)
print_basic_stats(basic_stats)
print()
# 2. 时间分布分析
print("【2. 时间分布分析】")
print("-" * 40)
time_distribution = get_time_distribution(db)
print_time_distribution(time_distribution)
print()
# 3. 会员类型分析
print("【3. 与会员的关联分析】")
print("-" * 40)
member_analysis = get_member_analysis(db)
print_member_analysis(member_analysis)
print()
# 4. 样本数据
print("【4. 样本数据】")
print("-" * 40)
samples = get_sample_data(db)
print_samples(samples)
print()
# 5. 结论
print("【5. 分析结论】")
print("-" * 40)
print_conclusion(basic_stats)
finally:
db.close()
def get_basic_stats(db: DatabaseConnection) -> Dict[str, Any]:
"""
获取基础统计数据
"""
sql = """
SELECT
COUNT(*) AS total_orders,
COUNT(CASE WHEN member_discount_amount != 0 THEN 1 END) AS with_member_discount,
COUNT(CASE WHEN member_discount_amount > 0 THEN 1 END) AS positive_discount,
COUNT(CASE WHEN member_discount_amount < 0 THEN 1 END) AS negative_discount,
SUM(member_discount_amount) AS total_member_discount,
AVG(CASE WHEN member_discount_amount != 0 THEN member_discount_amount END) AS avg_discount,
MAX(member_discount_amount) AS max_discount,
MIN(member_discount_amount) AS min_discount,
STDDEV(CASE WHEN member_discount_amount != 0 THEN member_discount_amount END) AS stddev_discount
FROM billiards_dwd.dwd_settlement_head
"""
rows = db.query(sql)
return dict(rows[0]) if rows else {}
def get_time_distribution(db: DatabaseConnection) -> List[Dict[str, Any]]:
"""
获取按月份的时间分布
"""
sql = """
SELECT
DATE_TRUNC('month', create_time)::DATE AS month,
COUNT(*) AS total_orders,
COUNT(CASE WHEN member_discount_amount != 0 THEN 1 END) AS with_discount,
SUM(member_discount_amount) AS total_discount
FROM billiards_dwd.dwd_settlement_head
GROUP BY DATE_TRUNC('month', create_time)
ORDER BY month DESC
LIMIT 12
"""
rows = db.query(sql)
return [dict(row) for row in rows] if rows else []
def get_member_analysis(db: DatabaseConnection) -> Dict[str, Any]:
"""
分析与会员的关联
"""
# 会员vs非会员
sql_member_vs_guest = """
SELECT
CASE WHEN member_id = 0 THEN '散客' ELSE '会员' END AS customer_type,
COUNT(*) AS total_orders,
COUNT(CASE WHEN member_discount_amount != 0 THEN 1 END) AS with_discount,
SUM(member_discount_amount) AS total_discount
FROM billiards_dwd.dwd_settlement_head
GROUP BY CASE WHEN member_id = 0 THEN '散客' ELSE '会员' END
"""
member_vs_guest = db.query(sql_member_vs_guest)
# 按会员卡等级
sql_by_grade = """
SELECT
COALESCE(m.member_card_grade_name, '未知') AS grade_name,
COUNT(*) AS total_orders,
COUNT(CASE WHEN sh.member_discount_amount != 0 THEN 1 END) AS with_discount,
SUM(sh.member_discount_amount) AS total_discount
FROM billiards_dwd.dwd_settlement_head sh
LEFT JOIN billiards_dwd.dim_member m ON sh.member_id = m.member_id
WHERE sh.member_id != 0
GROUP BY COALESCE(m.member_card_grade_name, '未知')
ORDER BY total_orders DESC
"""
by_grade = db.query(sql_by_grade)
return {
'member_vs_guest': [dict(row) for row in member_vs_guest] if member_vs_guest else [],
'by_grade': [dict(row) for row in by_grade] if by_grade else []
}
def get_sample_data(db: DatabaseConnection) -> List[Dict[str, Any]]:
"""
获取有会员折扣的样本数据
"""
sql = """
SELECT
sh.order_settle_id,
sh.order_trade_no,
sh.create_time,
sh.member_id,
m.nickname AS member_name,
m.member_card_grade_name,
sh.consume_money,
sh.pay_amount,
sh.member_discount_amount,
ROUND(sh.member_discount_amount / NULLIF(sh.consume_money, 0) * 100, 2) AS discount_ratio
FROM billiards_dwd.dwd_settlement_head sh
LEFT JOIN billiards_dwd.dim_member m ON sh.member_id = m.member_id
WHERE sh.member_discount_amount != 0
ORDER BY sh.create_time DESC
LIMIT 20
"""
rows = db.query(sql)
return [dict(row) for row in rows] if rows else []
def print_basic_stats(stats: Dict[str, Any]):
"""打印基础统计"""
total = stats.get('total_orders', 1)
with_discount = stats.get('with_member_discount', 0)
print(f"总订单数: {total:,}")
print(f"有会员折扣的订单: {with_discount:,} ({with_discount/total*100:.4f}%)")
print(f" - 正值(折扣): {stats.get('positive_discount', 0):,}")
print(f" - 负值(加价?): {stats.get('negative_discount', 0):,}")
print()
print(f"会员折扣总额: {stats.get('total_member_discount', 0):,.2f}")
print(f"平均折扣: {stats.get('avg_discount', 0) or 0:,.2f}")
print(f"最大折扣: {stats.get('max_discount', 0):,.2f}")
print(f"最小折扣: {stats.get('min_discount', 0):,.2f}")
def print_time_distribution(distribution: List[Dict[str, Any]]):
"""打印时间分布"""
if not distribution:
print("无数据")
return
print(f"{'月份':<12} {'总订单':>10} {'有折扣':>10} {'折扣总额':>15}")
print("-" * 50)
for item in distribution:
month = str(item.get('month', 'N/A'))[:7]
total = item.get('total_orders', 0)
with_discount = item.get('with_discount', 0)
total_discount = item.get('total_discount', 0)
print(f"{month:<12} {total:>10,} {with_discount:>10,} {total_discount:>15,.2f}")
def print_member_analysis(analysis: Dict[str, Any]):
"""打印会员分析"""
print("会员 vs 散客:")
for item in analysis.get('member_vs_guest', []):
print(f" {item.get('customer_type', 'N/A')}: {item.get('total_orders', 0):,} 单, {item.get('with_discount', 0)} 单有折扣, 折扣总额 {item.get('total_discount', 0):,.2f}")
print("\n按会员卡等级:")
for item in analysis.get('by_grade', []):
print(f" {item.get('grade_name', 'N/A')}: {item.get('total_orders', 0):,} 单, {item.get('with_discount', 0)} 单有折扣")
def print_samples(samples: List[Dict[str, Any]]):
"""打印样本数据"""
if not samples:
print("[!] 未发现使用会员折扣的订单")
return
print(f"{'订单ID':<20} {'会员':<15} {'等级':<10} {'消费':>12} {'折扣':>12} {'比例':>8}")
print("-" * 80)
for item in samples[:10]:
order_id = str(item.get('order_settle_id', 'N/A'))[:18]
member = str(item.get('member_name', 'N/A'))[:13]
grade = str(item.get('member_card_grade_name', 'N/A'))[:8]
consume = item.get('consume_money', 0)
discount = item.get('member_discount_amount', 0)
ratio = item.get('discount_ratio', 0)
print(f"{order_id:<20} {member:<15} {grade:<10} {consume:>12,.2f} {discount:>12,.2f} {ratio:>7}%")
def print_conclusion(stats: Dict[str, Any]):
"""打印分析结论"""
with_discount = stats.get('with_member_discount', 0)
total = stats.get('total_orders', 1)
ratio = with_discount / total * 100
if with_discount == 0:
print("【结论】: member_discount_amount 字段 **未启用**")
print()
print("该字段在所有订单中均为0，表明：")
print(" 1. 会员折扣功能在业务系统中未开启")
print(" 2. 或会员折扣通过其他方式（如adjust_amount）记录")
print()
print("【建议】:")
print(" 1. 在DWS财务统计中，暂时不处理此字段")
print(" 2. 将此字段标记为'预留/待启用'")
print(" 3. 后续如果业务启用，再更新统计逻辑")
elif ratio < 1:
print(f"【结论】: member_discount_amount 字段 **极少使用** (仅{ratio:.4f}%订单)")
print()
print("该字段使用率极低，可能是：")
print(" 1. 会员折扣功能刚启用不久")
print(" 2. 仅特定场景使用")
print()
print("【建议】:")
print(" 1. 在DWS财务统计中保留此字段的处理逻辑")
print(" 2. 定期监控使用率变化")
else:
print(f"【结论】: member_discount_amount 字段 **已启用** ({ratio:.2f}%订单使用)")
print()
print("【建议】:")
print(" 1. 在DWS财务优惠明细中正常统计此字段")
print(" 2. 关注会员折扣与其他优惠的叠加规则")
if __name__ == "__main__":
analyze_member_discount_usage()

74
etl_billiards/scripts/check_assistant_dim.py Normal file
View File

@@ -0,0 +1,74 @@
# -*- coding: utf-8 -*-
import sys
sys.path.insert(0, '.')
from config.settings import AppConfig
from database.connection import DatabaseConnection
from database.operations import DatabaseOperations
config = AppConfig.load()
db_conn = DatabaseConnection(config.config['db']['dsn'])
db = DatabaseOperations(db_conn)
# 检查dim_assistant表结构
print('=== dim_assistant columns ===')
sql0 = """
SELECT column_name FROM information_schema.columns
WHERE table_schema = 'billiards_dwd' AND table_name = 'dim_assistant'
"""
for row in db.query(sql0):
print(f' {dict(row)["column_name"]}')
# 检查dim_assistant数量
print()
print('=== dim_assistant ===')
sql1 = 'SELECT COUNT(*) as cnt FROM billiards_dwd.dim_assistant WHERE scd2_is_current = 1'
rows = db.query(sql1)
print(f'dim_assistant current count: {dict(rows[0])["cnt"]}')
# 检查服务记录中的nickname分布
print()
print('=== Service by nickname ===')
sql2 = """
SELECT nickname, COUNT(*) as service_count, COUNT(DISTINCT tenant_member_id) as member_count
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
GROUP BY nickname
ORDER BY service_count DESC
LIMIT 10
"""
for row in db.query(sql2):
r = dict(row)
print(f' {r["nickname"]}: {r["service_count"]} services, {r["member_count"]} members')
# 检查assistant_no分布
print()
print('=== Service by assistant_no ===')
sql3 = """
SELECT assistant_no, nickname, COUNT(*) as service_count, COUNT(DISTINCT tenant_member_id) as member_count
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
GROUP BY assistant_no, nickname
ORDER BY service_count DESC
LIMIT 10
"""
for row in db.query(sql3):
r = dict(row)
print(f' {r["assistant_no"]} ({r["nickname"]}): {r["service_count"]} services, {r["member_count"]} members')
# 近60天
print()
print('=== Last 60 days by nickname ===')
sql4 = """
SELECT nickname, COUNT(*) as service_count, COUNT(DISTINCT tenant_member_id) as member_count
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
AND last_use_time >= NOW() - INTERVAL '60 days'
GROUP BY nickname
ORDER BY service_count DESC
LIMIT 15
"""
for row in db.query(sql4):
r = dict(row)
print(f' {r["nickname"]}: {r["service_count"]} services, {r["member_count"]} members')
db_conn.close()

82
etl_billiards/scripts/check_dwd_service.py Normal file
View File

@@ -0,0 +1,82 @@
# -*- coding: utf-8 -*-
import sys
sys.path.insert(0, '.')
from config.settings import AppConfig
from database.connection import DatabaseConnection
from database.operations import DatabaseOperations
config = AppConfig.load()
db_conn = DatabaseConnection(config.config['db']['dsn'])
db = DatabaseOperations(db_conn)
# 检查DWD层服务记录分布
print("=== DWD层服务记录分析 ===")
print()
# 1. 总体统计
sql1 = """
SELECT
COUNT(*) as total_records,
COUNT(DISTINCT tenant_member_id) as unique_members,
COUNT(DISTINCT site_assistant_id) as unique_assistants,
COUNT(DISTINCT (tenant_member_id, site_assistant_id)) as unique_pairs
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
"""
r = dict(db.query(sql1)[0])
print("总体统计:")
print(f" 总服务记录数: {r['total_records']}")
print(f" 唯一会员数: {r['unique_members']}")
print(f" 唯一助教数: {r['unique_assistants']}")
print(f" 唯一客户-助教对: {r['unique_pairs']}")
# 2. 助教服务会员数分布
print()
print("助教服务会员数分布 (Top 10):")
sql2 = """
SELECT site_assistant_id, COUNT(DISTINCT tenant_member_id) as member_count
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
GROUP BY site_assistant_id
ORDER BY member_count DESC
LIMIT 10
"""
for row in db.query(sql2):
r = dict(row)
print(f" 助教 {r['site_assistant_id']}: 服务 {r['member_count']} 个会员")
# 3. 每个客户-助教对的服务次数分布
print()
print("客户-助教对 服务次数分布 (Top 10):")
sql3 = """
SELECT tenant_member_id, site_assistant_id, COUNT(*) as service_count
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
GROUP BY tenant_member_id, site_assistant_id
ORDER BY service_count DESC
LIMIT 10
"""
for row in db.query(sql3):
r = dict(row)
print(f" 会员 {r['tenant_member_id']} - 助教 {r['site_assistant_id']}: {r['service_count']} 次服务")
# 4. 近60天的数据
print()
print("=== 近60天数据 ===")
sql4 = """
SELECT
COUNT(*) as total_records,
COUNT(DISTINCT tenant_member_id) as unique_members,
COUNT(DISTINCT site_assistant_id) as unique_assistants,
COUNT(DISTINCT (tenant_member_id, site_assistant_id)) as unique_pairs
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
AND last_use_time >= NOW() - INTERVAL '60 days'
"""
r4 = dict(db.query(sql4)[0])
print(f" 总服务记录数: {r4['total_records']}")
print(f" 唯一会员数: {r4['unique_members']}")
print(f" 唯一助教数: {r4['unique_assistants']}")
print(f" 唯一客户-助教对: {r4['unique_pairs']}")
db_conn.close()

57
etl_billiards/scripts/check_intimacy_stats.py Normal file
View File

@@ -0,0 +1,57 @@
# -*- coding: utf-8 -*-
import sys
sys.path.insert(0, '.')
from config.settings import AppConfig
from database.connection import DatabaseConnection
from database.operations import DatabaseOperations
config = AppConfig.load()
db_conn = DatabaseConnection(config.config['db']['dsn'])
db = DatabaseOperations(db_conn)
# 检查实际统计
sql = """
SELECT
COUNT(*) as total_pairs,
COUNT(DISTINCT member_id) as unique_members,
COUNT(DISTINCT assistant_id) as unique_assistants
FROM billiards_dws.dws_member_assistant_intimacy
"""
rows = db.query(sql)
r = dict(rows[0])
print("DWS亲密指数统计:")
print(f" 总记录数(对): {r['total_pairs']}")
print(f" 唯一会员数: {r['unique_members']}")
print(f" 唯一助教数: {r['unique_assistants']}")
# 查看助教分布
sql2 = """
SELECT assistant_id, COUNT(*) as member_count
FROM billiards_dws.dws_member_assistant_intimacy
GROUP BY assistant_id
ORDER BY member_count DESC
LIMIT 10
"""
rows2 = db.query(sql2)
print()
print("Top 10 助教 (按服务会员数):")
for row in rows2:
r = dict(row)
print(f" 助教 {r['assistant_id']}: 服务 {r['member_count']} 个会员")
# 检查DWD层原始数据
sql3 = """
SELECT
COUNT(DISTINCT site_assistant_id) as unique_assistants,
COUNT(DISTINCT tenant_member_id) as unique_members
FROM billiards_dwd.dwd_assistant_service_log
WHERE tenant_member_id > 0 AND is_delete = 0
"""
rows3 = db.query(sql3)
r3 = dict(rows3[0])
print()
print("DWD层原始数据:")
print(f" 唯一助教数: {r3['unique_assistants']}")
print(f" 唯一会员数: {r3['unique_members']}")
db_conn.close()

3
etl_billiards/scripts/check_ods_gaps.py
View File

@@ -702,6 +702,7 @@ def run_gap_check(
content_sample_limit: int | None = None,
window_split_unit: str | None = None,
window_compensation_hours: int | None = None,
tag: str = "",
) -> dict:
cfg = cfg or AppConfig.load({})
tz = ZoneInfo(cfg.get("app.timezone", "Asia/Taipei"))
@@ -800,7 +801,7 @@ def run_gap_check(
if cutoff:
logger.info("CUTOFF=%s overlap_hours=%s", cutoff.isoformat(), cutoff_overlap_hours)
tag_suffix = f"_{args.tag}" if args.tag else ""
tag_suffix = f"_{tag}" if tag else ""
client = build_recording_client(cfg, task_code=f"ODS_GAP_CHECK{tag_suffix}")
db_state = _init_db_state(cfg)

185
etl_billiards/scripts/create_index_tables.py Normal file
View File

@@ -0,0 +1,185 @@
# -*- coding: utf-8 -*-
"""
创建指数算法相关表
"""
import sys
import os
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from config.settings import AppConfig
from database.connection import DatabaseConnection
from database.operations import DatabaseOperations
# 表DDL
DDL_STATEMENTS = [
# 参数配置表
"""
DROP TABLE IF EXISTS billiards_dws.cfg_index_parameters CASCADE;
CREATE TABLE billiards_dws.cfg_index_parameters (
param_id SERIAL PRIMARY KEY,
index_type VARCHAR(50) NOT NULL,
param_name VARCHAR(100) NOT NULL,
param_value NUMERIC(14,6) NOT NULL,
description TEXT,
effective_from DATE NOT NULL DEFAULT CURRENT_DATE,
effective_to DATE,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_cfg_index_parameters UNIQUE (index_type, param_name, effective_from)
);
CREATE INDEX idx_cfg_index_params_type ON billiards_dws.cfg_index_parameters (index_type);
""",
# 召回指数表
"""
DROP TABLE IF EXISTS billiards_dws.dws_member_recall_index CASCADE;
CREATE TABLE billiards_dws.dws_member_recall_index (
recall_id BIGSERIAL PRIMARY KEY,
site_id BIGINT NOT NULL,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
days_since_last_visit INTEGER,
visit_interval_median NUMERIC(10,2),
visit_interval_mad NUMERIC(10,2),
days_since_first_visit INTEGER,
days_since_last_recharge INTEGER,
visits_last_14_days INTEGER NOT NULL DEFAULT 0,
visits_last_60_days INTEGER NOT NULL DEFAULT 0,
score_overdue NUMERIC(10,4),
score_new_bonus NUMERIC(10,4),
score_recharge_bonus NUMERIC(10,4),
score_hot_drop NUMERIC(10,4),
raw_score NUMERIC(14,6),
display_score NUMERIC(4,2),
calc_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
calc_version INTEGER NOT NULL DEFAULT 1,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_dws_member_recall UNIQUE (site_id, member_id)
);
CREATE INDEX idx_dws_recall_display ON billiards_dws.dws_member_recall_index (site_id, display_score DESC);
""",
# 亲密指数表
"""
DROP TABLE IF EXISTS billiards_dws.dws_member_assistant_intimacy CASCADE;
CREATE TABLE billiards_dws.dws_member_assistant_intimacy (
intimacy_id BIGSERIAL PRIMARY KEY,
site_id BIGINT NOT NULL,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
assistant_id BIGINT NOT NULL,
session_count INTEGER NOT NULL DEFAULT 0,
total_duration_minutes INTEGER NOT NULL DEFAULT 0,
basic_session_count INTEGER NOT NULL DEFAULT 0,
incentive_session_count INTEGER NOT NULL DEFAULT 0,
days_since_last_session INTEGER,
attributed_recharge_count INTEGER NOT NULL DEFAULT 0,
attributed_recharge_amount NUMERIC(14,2) NOT NULL DEFAULT 0,
score_frequency NUMERIC(10,4),
score_recency NUMERIC(10,4),
score_recharge NUMERIC(10,4),
score_duration NUMERIC(10,4),
burst_multiplier NUMERIC(6,4),
raw_score NUMERIC(14,6),
display_score NUMERIC(4,2),
calc_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
calc_version INTEGER NOT NULL DEFAULT 1,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_dws_member_assistant_intimacy UNIQUE (site_id, member_id, assistant_id)
);
CREATE INDEX idx_dws_intimacy_member ON billiards_dws.dws_member_assistant_intimacy (site_id, member_id, display_score DESC);
CREATE INDEX idx_dws_intimacy_assistant ON billiards_dws.dws_member_assistant_intimacy (site_id, assistant_id, display_score DESC);
""",
# 分位点历史表
"""
DROP TABLE IF EXISTS billiards_dws.dws_index_percentile_history CASCADE;
CREATE TABLE billiards_dws.dws_index_percentile_history (
history_id BIGSERIAL PRIMARY KEY,
site_id BIGINT NOT NULL,
index_type VARCHAR(50) NOT NULL,
calc_time TIMESTAMPTZ NOT NULL,
percentile_5 NUMERIC(14,6),
percentile_95 NUMERIC(14,6),
percentile_5_smoothed NUMERIC(14,6),
percentile_95_smoothed NUMERIC(14,6),
record_count INTEGER,
min_raw_score NUMERIC(14,6),
max_raw_score NUMERIC(14,6),
avg_raw_score NUMERIC(14,6),
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_dws_index_percentile_history UNIQUE (site_id, index_type, calc_time)
);
CREATE INDEX idx_dws_percentile_history ON billiards_dws.dws_index_percentile_history (site_id, index_type, calc_time DESC);
"""
]
# 初始化参数
SEED_PARAMS = """
INSERT INTO billiards_dws.cfg_index_parameters
(index_type, param_name, param_value, description, effective_from)
VALUES
('RECALL', 'lookback_days', 60, '回溯窗口（天）', CURRENT_DATE),
('RECALL', 'sigma_min', 2.0, '波动下限（天）', CURRENT_DATE),
('RECALL', 'halflife_new', 7, '新客户半衰期（天）', CURRENT_DATE),
('RECALL', 'halflife_recharge', 10, '刚充值半衰期（天）', CURRENT_DATE),
('RECALL', 'weight_overdue', 3.0, '超期紧急性权重', CURRENT_DATE),
('RECALL', 'weight_new', 1.0, '新客户权重', CURRENT_DATE),
('RECALL', 'weight_recharge', 1.0, '刚充值权重', CURRENT_DATE),
('RECALL', 'weight_hot', 1.0, '热度断档权重', CURRENT_DATE),
('RECALL', 'percentile_lower', 5, '下锚分位数', CURRENT_DATE),
('RECALL', 'percentile_upper', 95, '上锚分位数', CURRENT_DATE),
('RECALL', 'ewma_alpha', 0.2, 'EWMA平滑系数', CURRENT_DATE),
('INTIMACY', 'lookback_days', 60, '回溯窗口（天）', CURRENT_DATE),
('INTIMACY', 'session_merge_hours', 4, '会话合并间隔（小时）', CURRENT_DATE),
('INTIMACY', 'recharge_attribute_hours', 1, '充值归因窗口（小时）', CURRENT_DATE),
('INTIMACY', 'amount_base', 500, '金额压缩基准（元）', CURRENT_DATE),
('INTIMACY', 'incentive_weight', 1.5, '附加课权重倍数', CURRENT_DATE),
('INTIMACY', 'halflife_session', 14, '会话衰减半衰期（天）', CURRENT_DATE),
('INTIMACY', 'halflife_last', 10, '最近一次半衰期（天）', CURRENT_DATE),
('INTIMACY', 'halflife_recharge', 21, '充值衰减半衰期（天）', CURRENT_DATE),
('INTIMACY', 'halflife_short', 7, '短期激增检测半衰期（天）', CURRENT_DATE),
('INTIMACY', 'halflife_long', 30, '长期激增检测半衰期（天）', CURRENT_DATE),
('INTIMACY', 'weight_frequency', 2.0, '频次权重', CURRENT_DATE),
('INTIMACY', 'weight_recency', 1.5, '最近一次权重', CURRENT_DATE),
('INTIMACY', 'weight_recharge', 2.0, '归因充值权重', CURRENT_DATE),
('INTIMACY', 'weight_duration', 0.5, '时长权重', CURRENT_DATE),
('INTIMACY', 'burst_gamma', 0.6, '激增放大系数', CURRENT_DATE),
('INTIMACY', 'percentile_lower', 5, '下锚分位数', CURRENT_DATE),
('INTIMACY', 'percentile_upper', 95, '上锚分位数', CURRENT_DATE),
('INTIMACY', 'ewma_alpha', 0.2, 'EWMA平滑系数', CURRENT_DATE)
ON CONFLICT (index_type, param_name, effective_from) DO NOTHING;
"""
def main():
print("创建指数算法相关表...")
config = AppConfig.load()
db_conn = DatabaseConnection(config.config["db"]["dsn"])
try:
with db_conn.conn.cursor() as cur:
# 创建表
for i, ddl in enumerate(DDL_STATEMENTS, 1):
print(f" 执行DDL {i}/{len(DDL_STATEMENTS)}...")
cur.execute(ddl)
# 初始化参数
print(" 初始化算法参数...")
cur.execute(SEED_PARAMS)
db_conn.conn.commit()
print("完成!")
# 验证
cur.execute("SELECT COUNT(*) FROM billiards_dws.cfg_index_parameters")
count = cur.fetchone()[0]
print(f" 已插入 {count} 个参数配置")
finally:
db_conn.close()
if __name__ == '__main__':
main()

602
etl_billiards/scripts/import_dws_excel.py Normal file
View File

@@ -0,0 +1,602 @@
# -*- coding: utf-8 -*-
"""
DWS Excel导入脚本
功能说明：
支持三类Excel数据的导入：
1. 支出结构（dws_finance_expense_summary）
2. 平台结算（dws_platform_settlement）
3. 充值提成（dws_assistant_recharge_commission）
导入规范：
- 字段定义：按照目标表字段要求
- 时间粒度：支出按月，平台结算按日，充值提成按月
- 门店维度：使用配置的site_id
- 去重规则：按import_batch_no去重
- 校验规则：金额字段非负，日期格式校验
使用方式：
python import_dws_excel.py --type expense --file expenses.xlsx
python import_dws_excel.py --type platform --file platform_settlement.xlsx
python import_dws_excel.py --type commission --file recharge_commission.xlsx
作者：ETL团队
创建日期：2026-02-01
"""
import argparse
import os
import sys
import uuid
from datetime import date, datetime
from decimal import Decimal, InvalidOperation
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
# 添加项目根目录到Python路径
project_root = Path(__file__).parent.parent.parent
sys.path.insert(0, str(project_root))
try:
import pandas as pd
except ImportError:
print("请安装 pandas: pip install pandas openpyxl")
sys.exit(1)
from etl_billiards.utils.config import Config
from etl_billiards.utils.db import DatabaseConnection
# =============================================================================
# 常量定义
# =============================================================================
# 支出类型枚举
EXPENSE_TYPES = {
'房租': 'RENT',
'水电费': 'UTILITY',
'物业费': 'PROPERTY',
'工资': 'SALARY',
'报销': 'REIMBURSE',
'平台服务费': 'PLATFORM_FEE',
'其他': 'OTHER',
}
# 支出大类映射
EXPENSE_CATEGORIES = {
'RENT': 'FIXED_COST',
'UTILITY': 'VARIABLE_COST',
'PROPERTY': 'FIXED_COST',
'SALARY': 'FIXED_COST',
'REIMBURSE': 'VARIABLE_COST',
'PLATFORM_FEE': 'VARIABLE_COST',
'OTHER': 'OTHER',
}
# 平台类型枚举
PLATFORM_TYPES = {
'美团': 'MEITUAN',
'抖音': 'DOUYIN',
'大众点评': 'DIANPING',
'其他': 'OTHER',
}
# =============================================================================
# 导入基类
# =============================================================================
class BaseImporter:
"""导入基类"""
def __init__(self, config: Config, db: DatabaseConnection):
self.config = config
self.db = db
self.site_id = config.get("app.store_id")
self.tenant_id = config.get("app.tenant_id", self.site_id)
self.batch_no = self._generate_batch_no()
def _generate_batch_no(self) -> str:
"""生成导入批次号"""
timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
unique_id = str(uuid.uuid4())[:8]
return f"{timestamp}_{unique_id}"
def _safe_decimal(self, value: Any, default: Decimal = Decimal('0')) -> Decimal:
"""安全转换为Decimal"""
if value is None or pd.isna(value):
return default
try:
return Decimal(str(value))
except (ValueError, InvalidOperation):
return default
def _safe_date(self, value: Any) -> Optional[date]:
"""安全转换为日期"""
if value is None or pd.isna(value):
return None
if isinstance(value, datetime):
return value.date()
if isinstance(value, date):
return value
try:
return pd.to_datetime(value).date()
except:
return None
def _safe_month(self, value: Any) -> Optional[date]:
"""安全转换为月份（月第一天）"""
dt = self._safe_date(value)
if dt:
return dt.replace(day=1)
return None
def import_file(self, file_path: str) -> Dict[str, Any]:
"""导入文件"""
raise NotImplementedError
def validate_row(self, row: Dict[str, Any], row_idx: int) -> List[str]:
"""校验行数据，返回错误列表"""
return []
def transform_row(self, row: Dict[str, Any]) -> Dict[str, Any]:
"""转换行数据"""
raise NotImplementedError
def insert_records(self, records: List[Dict[str, Any]]) -> int:
"""插入记录"""
raise NotImplementedError
# =============================================================================
# 支出导入
# =============================================================================
class ExpenseImporter(BaseImporter):
"""
支出导入
Excel格式要求：
- 月份: 2026-01 或 2026/01/01 格式
- 支出类型: 房租/水电费/物业费/工资/报销/平台服务费/其他
- 金额: 数字
- 备注: 可选
"""
TARGET_TABLE = "billiards_dws.dws_finance_expense_summary"
REQUIRED_COLUMNS = ['月份', '支出类型', '金额']
OPTIONAL_COLUMNS = ['明细', '备注']
def import_file(self, file_path: str) -> Dict[str, Any]:
"""导入支出Excel"""
print(f"开始导入支出文件: {file_path}")
# 读取Excel
df = pd.read_excel(file_path)
# 校验必要列
missing_cols = [c for c in self.REQUIRED_COLUMNS if c not in df.columns]
if missing_cols:
return {"status": "ERROR", "message": f"缺少必要列: {missing_cols}"}
# 处理数据
records = []
errors = []
for idx, row in df.iterrows():
row_dict = row.to_dict()
row_errors = self.validate_row(row_dict, idx + 2) # Excel行号从2开始
if row_errors:
errors.extend(row_errors)
continue
record = self.transform_row(row_dict)
records.append(record)
if errors:
print(f"校验错误: {len(errors)} 条")
for err in errors[:10]:
print(f" - {err}")
# 插入数据
inserted = 0
if records:
inserted = self.insert_records(records)
return {
"status": "SUCCESS" if not errors else "PARTIAL",
"batch_no": self.batch_no,
"total_rows": len(df),
"inserted": inserted,
"errors": len(errors),
"error_messages": errors[:10]
}
def validate_row(self, row: Dict[str, Any], row_idx: int) -> List[str]:
errors = []
# 校验月份
month = self._safe_month(row.get('月份'))
if not month:
errors.append(f"行{row_idx}: 月份格式错误")
# 校验支出类型
expense_type = row.get('支出类型', '').strip()
if expense_type not in EXPENSE_TYPES:
errors.append(f"行{row_idx}: 支出类型无效 '{expense_type}'")
# 校验金额
amount = self._safe_decimal(row.get('金额'))
if amount < 0:
errors.append(f"行{row_idx}: 金额不能为负数")
return errors
def transform_row(self, row: Dict[str, Any]) -> Dict[str, Any]:
expense_type_name = row.get('支出类型', '').strip()
expense_type_code = EXPENSE_TYPES.get(expense_type_name, 'OTHER')
expense_category = EXPENSE_CATEGORIES.get(expense_type_code, 'OTHER')
return {
'site_id': self.site_id,
'tenant_id': self.tenant_id,
'expense_month': self._safe_month(row.get('月份')),
'expense_type_code': expense_type_code,
'expense_type_name': expense_type_name,
'expense_category': expense_category,
'expense_amount': self._safe_decimal(row.get('金额')),
'expense_detail': row.get('明细'),
'import_batch_no': self.batch_no,
'import_file_name': os.path.basename(str(row.get('_file_path', ''))),
'import_time': datetime.now(),
'import_user': os.getenv('USERNAME', 'system'),
'remark': row.get('备注'),
}
def insert_records(self, records: List[Dict[str, Any]]) -> int:
columns = [
'site_id', 'tenant_id', 'expense_month', 'expense_type_code',
'expense_type_name', 'expense_category', 'expense_amount',
'expense_detail', 'import_batch_no', 'import_file_name',
'import_time', 'import_user', 'remark'
]
cols_str = ", ".join(columns)
placeholders = ", ".join(["%s"] * len(columns))
sql = f"INSERT INTO {self.TARGET_TABLE} ({cols_str}) VALUES ({placeholders})"
inserted = 0
with self.db.conn.cursor() as cur:
for record in records:
values = [record.get(col) for col in columns]
cur.execute(sql, values)
inserted += cur.rowcount
self.db.commit()
return inserted
# =============================================================================
# 平台结算导入
# =============================================================================
class PlatformSettlementImporter(BaseImporter):
"""
平台结算导入
Excel格式要求：
- 回款日期: 日期格式
- 平台类型: 美团/抖音/大众点评/其他
- 平台订单号: 字符串
- 订单原始金额: 数字
- 佣金: 数字
- 服务费: 数字
- 回款金额: 数字
- 备注: 可选
"""
TARGET_TABLE = "billiards_dws.dws_platform_settlement"
REQUIRED_COLUMNS = ['回款日期', '平台类型', '回款金额']
OPTIONAL_COLUMNS = ['平台订单号', '订单原始金额', '佣金', '服务费', '关联订单ID', '备注']
def import_file(self, file_path: str) -> Dict[str, Any]:
print(f"开始导入平台结算文件: {file_path}")
df = pd.read_excel(file_path)
missing_cols = [c for c in self.REQUIRED_COLUMNS if c not in df.columns]
if missing_cols:
return {"status": "ERROR", "message": f"缺少必要列: {missing_cols}"}
records = []
errors = []
for idx, row in df.iterrows():
row_dict = row.to_dict()
row_errors = self.validate_row(row_dict, idx + 2)
if row_errors:
errors.extend(row_errors)
continue
record = self.transform_row(row_dict)
records.append(record)
if errors:
print(f"校验错误: {len(errors)} 条")
for err in errors[:10]:
print(f" - {err}")
inserted = 0
if records:
inserted = self.insert_records(records)
return {
"status": "SUCCESS" if not errors else "PARTIAL",
"batch_no": self.batch_no,
"total_rows": len(df),
"inserted": inserted,
"errors": len(errors),
}
def validate_row(self, row: Dict[str, Any], row_idx: int) -> List[str]:
errors = []
settlement_date = self._safe_date(row.get('回款日期'))
if not settlement_date:
errors.append(f"行{row_idx}: 回款日期格式错误")
platform_type = row.get('平台类型', '').strip()
if platform_type not in PLATFORM_TYPES:
errors.append(f"行{row_idx}: 平台类型无效 '{platform_type}'")
amount = self._safe_decimal(row.get('回款金额'))
if amount < 0:
errors.append(f"行{row_idx}: 回款金额不能为负数")
return errors
def transform_row(self, row: Dict[str, Any]) -> Dict[str, Any]:
platform_name = row.get('平台类型', '').strip()
platform_type = PLATFORM_TYPES.get(platform_name, 'OTHER')
return {
'site_id': self.site_id,
'tenant_id': self.tenant_id,
'settlement_date': self._safe_date(row.get('回款日期')),
'platform_type': platform_type,
'platform_name': platform_name,
'platform_order_no': row.get('平台订单号'),
'order_settle_id': row.get('关联订单ID'),
'settlement_amount': self._safe_decimal(row.get('回款金额')),
'commission_amount': self._safe_decimal(row.get('佣金')),
'service_fee': self._safe_decimal(row.get('服务费')),
'gross_amount': self._safe_decimal(row.get('订单原始金额')),
'import_batch_no': self.batch_no,
'import_file_name': os.path.basename(str(row.get('_file_path', ''))),
'import_time': datetime.now(),
'import_user': os.getenv('USERNAME', 'system'),
'remark': row.get('备注'),
}
def insert_records(self, records: List[Dict[str, Any]]) -> int:
columns = [
'site_id', 'tenant_id', 'settlement_date', 'platform_type',
'platform_name', 'platform_order_no', 'order_settle_id',
'settlement_amount', 'commission_amount', 'service_fee',
'gross_amount', 'import_batch_no', 'import_file_name',
'import_time', 'import_user', 'remark'
]
cols_str = ", ".join(columns)
placeholders = ", ".join(["%s"] * len(columns))
sql = f"INSERT INTO {self.TARGET_TABLE} ({cols_str}) VALUES ({placeholders})"
inserted = 0
with self.db.conn.cursor() as cur:
for record in records:
values = [record.get(col) for col in columns]
cur.execute(sql, values)
inserted += cur.rowcount
self.db.commit()
return inserted
# =============================================================================
# 充值提成导入
# =============================================================================
class RechargeCommissionImporter(BaseImporter):
"""
充值提成导入
Excel格式要求：
- 月份: 2026-01 格式
- 助教ID: 数字
- 助教花名: 字符串
- 充值订单金额: 数字
- 提成金额: 数字
- 充值订单号: 可选
- 备注: 可选
"""
TARGET_TABLE = "billiards_dws.dws_assistant_recharge_commission"
REQUIRED_COLUMNS = ['月份', '助教ID', '提成金额']
OPTIONAL_COLUMNS = ['助教花名', '充值订单金额', '充值订单ID', '充值订单号', '备注']
def import_file(self, file_path: str) -> Dict[str, Any]:
print(f"开始导入充值提成文件: {file_path}")
df = pd.read_excel(file_path)
missing_cols = [c for c in self.REQUIRED_COLUMNS if c not in df.columns]
if missing_cols:
return {"status": "ERROR", "message": f"缺少必要列: {missing_cols}"}
records = []
errors = []
for idx, row in df.iterrows():
row_dict = row.to_dict()
row_errors = self.validate_row(row_dict, idx + 2)
if row_errors:
errors.extend(row_errors)
continue
record = self.transform_row(row_dict)
records.append(record)
if errors:
print(f"校验错误: {len(errors)} 条")
for err in errors[:10]:
print(f" - {err}")
inserted = 0
if records:
inserted = self.insert_records(records)
return {
"status": "SUCCESS" if not errors else "PARTIAL",
"batch_no": self.batch_no,
"total_rows": len(df),
"inserted": inserted,
"errors": len(errors),
}
def validate_row(self, row: Dict[str, Any], row_idx: int) -> List[str]:
errors = []
month = self._safe_month(row.get('月份'))
if not month:
errors.append(f"行{row_idx}: 月份格式错误")
assistant_id = row.get('助教ID')
if assistant_id is None or pd.isna(assistant_id):
errors.append(f"行{row_idx}: 助教ID不能为空")
amount = self._safe_decimal(row.get('提成金额'))
if amount < 0:
errors.append(f"行{row_idx}: 提成金额不能为负数")
return errors
def transform_row(self, row: Dict[str, Any]) -> Dict[str, Any]:
recharge_amount = self._safe_decimal(row.get('充值订单金额'))
commission_amount = self._safe_decimal(row.get('提成金额'))
commission_ratio = commission_amount / recharge_amount if recharge_amount > 0 else None
return {
'site_id': self.site_id,
'tenant_id': self.tenant_id,
'assistant_id': int(row.get('助教ID')),
'assistant_nickname': row.get('助教花名'),
'commission_month': self._safe_month(row.get('月份')),
'recharge_order_id': row.get('充值订单ID'),
'recharge_order_no': row.get('充值订单号'),
'recharge_amount': recharge_amount,
'commission_amount': commission_amount,
'commission_ratio': commission_ratio,
'import_batch_no': self.batch_no,
'import_file_name': os.path.basename(str(row.get('_file_path', ''))),
'import_time': datetime.now(),
'import_user': os.getenv('USERNAME', 'system'),
'remark': row.get('备注'),
}
def insert_records(self, records: List[Dict[str, Any]]) -> int:
columns = [
'site_id', 'tenant_id', 'assistant_id', 'assistant_nickname',
'commission_month', 'recharge_order_id', 'recharge_order_no',
'recharge_amount', 'commission_amount', 'commission_ratio',
'import_batch_no', 'import_file_name', 'import_time',
'import_user', 'remark'
]
cols_str = ", ".join(columns)
placeholders = ", ".join(["%s"] * len(columns))
sql = f"INSERT INTO {self.TARGET_TABLE} ({cols_str}) VALUES ({placeholders})"
inserted = 0
with self.db.conn.cursor() as cur:
for record in records:
values = [record.get(col) for col in columns]
cur.execute(sql, values)
inserted += cur.rowcount
self.db.commit()
return inserted
# =============================================================================
# 主函数
# =============================================================================
def main():
parser = argparse.ArgumentParser(description='DWS Excel导入工具')
parser.add_argument(
'--type', '-t',
choices=['expense', 'platform', 'commission'],
required=True,
help='导入类型: expense(支出), platform(平台结算), commission(充值提成)'
)
parser.add_argument(
'--file', '-f',
required=True,
help='Excel文件路径'
)
args = parser.parse_args()
# 检查文件
if not os.path.exists(args.file):
print(f"文件不存在: {args.file}")
sys.exit(1)
# 加载配置
config = Config()
db = DatabaseConnection(config)
try:
# 选择导入器
if args.type == 'expense':
importer = ExpenseImporter(config, db)
elif args.type == 'platform':
importer = PlatformSettlementImporter(config, db)
elif args.type == 'commission':
importer = RechargeCommissionImporter(config, db)
else:
print(f"未知的导入类型: {args.type}")
sys.exit(1)
# 执行导入
result = importer.import_file(args.file)
# 输出结果
print("\n" + "=" * 50)
print("导入结果:")
print(f" 状态: {result.get('status')}")
print(f" 批次号: {result.get('batch_no')}")
print(f" 总行数: {result.get('total_rows')}")
print(f" 插入行数: {result.get('inserted')}")
print(f" 错误行数: {result.get('errors')}")
if result.get('status') == 'ERROR':
print(f" 错误信息: {result.get('message')}")
sys.exit(1)
except Exception as e:
print(f"导入失败: {e}")
db.rollback()
sys.exit(1)
finally:
db.close()
if __name__ == "__main__":
main()

35
etl_billiards/scripts/run_seed_dws_config.py Normal file
View File

@@ -0,0 +1,35 @@
# -*- coding: utf-8 -*-
"""执行DWS配置数据导入"""
import os
from pathlib import Path
from dotenv import load_dotenv
import psycopg2
def main():
# 加载.env配置
env_path = Path(__file__).parent.parent / ".env"
load_dotenv(env_path)
dsn = os.getenv("PG_DSN")
if not dsn:
print("错误: 未找到 PG_DSN 配置")
return
# 读取SQL文件
sql_file = Path(__file__).parent.parent / "database" / "seed_dws_config.sql"
sql_content = sql_file.read_text(encoding="utf-8")
print(f"连接数据库...")
conn = psycopg2.connect(dsn)
conn.autocommit = True
with conn.cursor() as cur:
print(f"执行SQL文件: {sql_file}")
cur.execute(sql_content)
print("DWS配置数据导入成功!")
conn.close()
if __name__ == "__main__":
main()

43
etl_billiards/scripts/show_area_category.py Normal file
View File

@@ -0,0 +1,43 @@
# -*- coding: utf-8 -*-
"""显示台区分类映射数据"""
import os
from pathlib import Path
from dotenv import load_dotenv
import psycopg2
def main():
load_dotenv(Path(__file__).parent.parent / ".env")
dsn = os.getenv("PG_DSN")
conn = psycopg2.connect(dsn)
print("cfg_area_category 数据内容:")
print("=" * 90)
print(f"{'source_area_name':<15} {'category_code':<15} {'category_name':<12} {'match_type':<10} {'priority':<8}")
print("-" * 90)
with conn.cursor() as cur:
cur.execute("""
SELECT source_area_name, category_code, category_name, match_type, match_priority
FROM billiards_dws.cfg_area_category
ORDER BY match_priority, category_code, source_area_name
""")
for row in cur.fetchall():
print(f"{row[0]:<15} {row[1]:<15} {row[2]:<12} {row[3]:<10} {row[4]:<8}")
print("=" * 90)
print("\n分类汇总:")
with conn.cursor() as cur:
cur.execute("""
SELECT category_code, category_name, COUNT(*) as cnt
FROM billiards_dws.cfg_area_category
GROUP BY category_code, category_name
ORDER BY category_code
""")
for row in cur.fetchall():
print(f" {row[0]:<15} {row[1]:<12} {row[2]} 条规则")
conn.close()
if __name__ == "__main__":
main()

48
etl_billiards/scripts/show_performance_tier.py Normal file
View File

@@ -0,0 +1,48 @@
# -*- coding: utf-8 -*-
"""显示绩效档位配置数据"""
import os
from pathlib import Path
from dotenv import load_dotenv
import psycopg2
def main():
load_dotenv(Path(__file__).parent.parent / ".env")
dsn = os.getenv("PG_DSN")
conn = psycopg2.connect(dsn)
print("cfg_performance_tier 数据内容:")
print("=" * 110)
print(f"{'tier_code':<8} {'tier_name':<18} {'min_hours':<10} {'max_hours':<10} {'base_ded':<10} {'bonus_ded':<10} {'vacation':<10}")
print("-" * 110)
with conn.cursor() as cur:
cur.execute("""
SELECT tier_code, tier_name, min_hours, max_hours,
base_deduction, bonus_deduction_ratio,
vacation_days, vacation_unlimited
FROM billiards_dws.cfg_performance_tier
ORDER BY tier_level
""")
for row in cur.fetchall():
max_h = str(row[3]) if row[3] else "NULL"
vac = "自由" if row[7] else str(row[6]) + "天"
print(f"{row[0]:<8} {row[1]:<18} {row[2]:<10} {max_h:<10} {row[4]:<10} {row[5]*100:.0f}%{'':<7} {vac:<10}")
print("=" * 110)
print("\n数据来源依据: DWS 数据库处理需求.md 第35-41行")
print("""
| 档位 | 总业绩小时数阈值 | 专业课抽成 | 打赏课抽成 | 次月休假 |
|------|------------------|-----------|-----------|----------|
| 0档 | H < 100 | 28元/小时 | 50% | 3天 |
| 1档 | 100 ≤ H < 130 | 18元/小时 | 40% | 4天 |
| 2档 | 130 ≤ H < 160 | 15元/小时 | 38% | 4天 |
| 3档 | 160 ≤ H < 190 | 13元/小时 | 35% | 5天 |
| 4档 | 190 ≤ H < 220 | 10元/小时 | 33% | 6天 |
| 5档 | H ≥ 220 | 8元/小时 | 30% | 休假自由 |
""")
conn.close()
if __name__ == "__main__":
main()

222
etl_billiards/scripts/test_index_tasks.py Normal file
View File

@@ -0,0 +1,222 @@
# -*- coding: utf-8 -*-
"""
测试指数算法任务
"""
import sys
import os
# 添加项目路径
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import logging
from config.settings import AppConfig
from database.connection import DatabaseConnection
from database.operations import DatabaseOperations
from tasks.dws.index import RecallIndexTask, IntimacyIndexTask
# 配置日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('test_index')
def test_recall_index():
"""测试召回指数任务"""
logger.info("=" * 60)
logger.info("测试客户召回指数任务 (DWS_RECALL_INDEX)")
logger.info("=" * 60)
# 加载配置
config = AppConfig.load()
# 连接数据库
db_conn = DatabaseConnection(config.config["db"]["dsn"])
db = DatabaseOperations(db_conn)
try:
# 创建任务实例
task = RecallIndexTask(config, db, None, logger)
# 执行任务
result = task.execute(None)
logger.info("任务执行结果: %s", result)
# 查询结果
if result.get('status') == 'success':
sql = """
SELECT
COUNT(*) as total_count,
ROUND(AVG(display_score)::numeric, 2) as avg_score,
ROUND(MIN(display_score)::numeric, 2) as min_score,
ROUND(MAX(display_score)::numeric, 2) as max_score,
ROUND(AVG(raw_score)::numeric, 4) as avg_raw_score,
ROUND(AVG(score_overdue)::numeric, 4) as avg_overdue,
ROUND(AVG(score_new_bonus)::numeric, 4) as avg_new_bonus,
ROUND(AVG(score_recharge_bonus)::numeric, 4) as avg_recharge_bonus,
ROUND(AVG(score_hot_drop)::numeric, 4) as avg_hot_drop
FROM billiards_dws.dws_member_recall_index
"""
rows = db.query(sql)
if rows:
stats = dict(rows[0])
logger.info("-" * 40)
logger.info("召回指数统计:")
logger.info(" 总记录数: %s", stats['total_count'])
logger.info(" Display Score: 平均=%.2f, 最小=%.2f, 最大=%.2f",
stats['avg_score'] or 0, stats['min_score'] or 0, stats['max_score'] or 0)
logger.info(" Raw Score 平均: %.4f", stats['avg_raw_score'] or 0)
logger.info(" 分项得分平均:")
logger.info(" - 超期紧急性: %.4f", stats['avg_overdue'] or 0)
logger.info(" - 新客户加分: %.4f", stats['avg_new_bonus'] or 0)
logger.info(" - 充值加分: %.4f", stats['avg_recharge_bonus'] or 0)
logger.info(" - 热度断档: %.4f", stats['avg_hot_drop'] or 0)
# 查询Top 5
logger.info("-" * 40)
logger.info("召回优先级 Top 5:")
top_sql = """
SELECT member_id, display_score, raw_score,
days_since_last_visit, visit_interval_median
FROM billiards_dws.dws_member_recall_index
ORDER BY display_score DESC
LIMIT 5
"""
top_rows = db.query(top_sql)
for i, row in enumerate(top_rows or [], 1):
r = dict(row)
logger.info(" %d. 会员%s: %.2f分 (Raw=%.4f, 最近到店=%s天前, 周期=%.1f天)",
i, r['member_id'], r['display_score'] or 0, r['raw_score'] or 0,
r['days_since_last_visit'], r['visit_interval_median'] or 0)
return result
finally:
db_conn.close()
def test_intimacy_index():
"""测试亲密指数任务"""
logger.info("")
logger.info("=" * 60)
logger.info("测试客户-助教亲密指数任务 (DWS_INTIMACY_INDEX)")
logger.info("=" * 60)
# 加载配置
config = AppConfig.load()
# 连接数据库
db_conn = DatabaseConnection(config.config["db"]["dsn"])
db = DatabaseOperations(db_conn)
try:
# 创建任务实例
task = IntimacyIndexTask(config, db, None, logger)
# 执行任务
result = task.execute(None)
logger.info("任务执行结果: %s", result)
# 查询结果
if result.get('status') == 'success':
sql = """
SELECT
COUNT(*) as total_count,
COUNT(DISTINCT member_id) as unique_members,
COUNT(DISTINCT assistant_id) as unique_assistants,
ROUND(AVG(display_score)::numeric, 2) as avg_score,
ROUND(MIN(display_score)::numeric, 2) as min_score,
ROUND(MAX(display_score)::numeric, 2) as max_score,
ROUND(AVG(raw_score)::numeric, 4) as avg_raw_score,
ROUND(AVG(score_frequency)::numeric, 4) as avg_frequency,
ROUND(AVG(score_recency)::numeric, 4) as avg_recency,
ROUND(AVG(score_recharge)::numeric, 4) as avg_recharge,
ROUND(AVG(burst_multiplier)::numeric, 4) as avg_burst
FROM billiards_dws.dws_member_assistant_intimacy
"""
rows = db.query(sql)
if rows:
stats = dict(rows[0])
logger.info("-" * 40)
logger.info("亲密指数统计:")
logger.info(" 总记录数: %s (客户-助教对)", stats['total_count'])
logger.info(" 唯一会员: %s, 唯一助教: %s", stats['unique_members'], stats['unique_assistants'])
logger.info(" Display Score: 平均=%.2f, 最小=%.2f, 最大=%.2f",
stats['avg_score'] or 0, stats['min_score'] or 0, stats['max_score'] or 0)
logger.info(" Raw Score 平均: %.4f", stats['avg_raw_score'] or 0)
logger.info(" 分项得分平均:")
logger.info(" - 频次强度: %.4f", stats['avg_frequency'] or 0)
logger.info(" - 最近温度: %.4f", stats['avg_recency'] or 0)
logger.info(" - 充值强度: %.4f", stats['avg_recharge'] or 0)
logger.info(" - 激增放大: %.4f", stats['avg_burst'] or 0)
# 查询Top亲密关系
logger.info("-" * 40)
logger.info("亲密度 Top 5 客户-助教对:")
top_sql = """
SELECT member_id, assistant_id, display_score, raw_score,
session_count, attributed_recharge_amount
FROM billiards_dws.dws_member_assistant_intimacy
ORDER BY display_score DESC
LIMIT 5
"""
top_rows = db.query(top_sql)
for i, row in enumerate(top_rows or [], 1):
r = dict(row)
logger.info(" %d. 会员%s-助教%s: %.2f分 (会话%d次, 归因充值%.2f元)",
i, r['member_id'], r['assistant_id'],
r['display_score'] or 0, r['session_count'] or 0,
r['attributed_recharge_amount'] or 0)
return result
finally:
db_conn.close()
if __name__ == '__main__':
print("=" * 60)
print("指数算法任务测试")
print("=" * 60)
print()
# 先检查表是否存在
config = AppConfig.load()
db_conn = DatabaseConnection(config.config["db"]["dsn"])
db = DatabaseOperations(db_conn)
check_sql = """
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'billiards_dws'
AND table_name IN ('dws_member_recall_index', 'dws_member_assistant_intimacy', 'cfg_index_parameters')
"""
tables = db.query(check_sql)
existing_tables = [dict(r)['table_name'] for r in (tables or [])]
if 'cfg_index_parameters' not in existing_tables:
print("警告: cfg_index_parameters 表不存在，请先执行 schema_dws.sql")
print("需要执行的表:")
print(" - cfg_index_parameters")
print(" - dws_member_recall_index")
print(" - dws_member_assistant_intimacy")
print(" - dws_index_percentile_history")
db_conn.close()
sys.exit(1)
db_conn.close()
# 测试召回指数
recall_result = test_recall_index()
# 测试亲密指数
intimacy_result = test_intimacy_index()
print()
print("=" * 60)
print("测试完成")
print("=" * 60)
print(f"召回指数: {recall_result.get('status', 'unknown')}")
print(f"亲密指数: {intimacy_result.get('status', 'unknown')}")

34
etl_billiards/scripts/verify_dws_config.py Normal file
View File

@@ -0,0 +1,34 @@
# -*- coding: utf-8 -*-
"""验证DWS配置数据"""
import os
from pathlib import Path
from dotenv import load_dotenv
import psycopg2
def main():
load_dotenv(Path(__file__).parent.parent / ".env")
dsn = os.getenv("PG_DSN")
conn = psycopg2.connect(dsn)
tables = [
"cfg_performance_tier",
"cfg_assistant_level_price",
"cfg_bonus_rules",
"cfg_area_category",
"cfg_skill_type"
]
print("DWS 配置表数据统计:")
print("-" * 40)
with conn.cursor() as cur:
for t in tables:
cur.execute(f"SELECT COUNT(*) FROM billiards_dws.{t}")
cnt = cur.fetchone()[0]
print(f"{t}: {cnt} 行")
conn.close()
if __name__ == "__main__":
main()

79
etl_billiards/tasks/dwd_load_task.py
View File

@@ -155,6 +155,7 @@ class DwdLoadTask(BaseTask):
("table_id", "id", None),
("site_table_area_name", "areaname", None),
("tenant_table_area_id", "site_table_area_id", None),
("order_id", "order_id", None),
],
"billiards_dwd.dim_table_ex": [
("table_id", "id", None),
@@ -167,12 +168,23 @@ class DwdLoadTask(BaseTask):
("group_name", "group_name", None),
("light_equipment_id", "light_equipment_id", None),
],
"billiards_dwd.dim_member": [("member_id", "id", None)],
"billiards_dwd.dim_member": [
("member_id", "id", None),
("pay_money_sum", "pay_money_sum", None),
("recharge_money_sum", "recharge_money_sum", None),
],
"billiards_dwd.dim_member_ex": [
("member_id", "id", None),
("register_site_name", "site_name", None),
("person_tenant_org_id", "person_tenant_org_id", None),
("person_tenant_org_name", "person_tenant_org_name", None),
("register_source", "register_source", None),
],
"billiards_dwd.dim_member_card_account": [
("member_card_id", "id", None),
("principal_balance", "principal_balance", None),
("member_grade", "member_grade", None),
],
"billiards_dwd.dim_member_card_account": [("member_card_id", "id", None)],
"billiards_dwd.dim_member_card_account_ex": [
("member_card_id", "id", None),
("tenant_name", "tenantname", None),
@@ -182,10 +194,16 @@ class DwdLoadTask(BaseTask):
("use_scene", "use_scene", None),
("tableareaid", "tableareaid", None),
("goodscategoryid", "goodscategoryid", None),
("able_share_member_discount", "able_share_member_discount", "boolean"),
("electricity_deduct_radio", "electricity_deduct_radio", None),
("electricity_discount", "electricity_discount", None),
("electricity_card_deduct", "electricitycarddeduct", "boolean"),
("recharge_freeze_balance", "rechargefreezebalance", None),
],
"billiards_dwd.dim_tenant_goods": [
("tenant_goods_id", "id", None),
("category_name", "categoryname", None),
("not_sale", "not_sale", None),
],
"billiards_dwd.dim_tenant_goods_ex": [
("tenant_goods_id", "id", None),
@@ -204,6 +222,8 @@ class DwdLoadTask(BaseTask):
("batch_stock_qty", "stock", None),
("sale_qty", "sale_num", None),
("total_sales_qty", "total_sales", None),
("commodity_code", "commodity_code", None),
("not_sale", "not_sale", None),
],
"billiards_dwd.dim_store_goods_ex": [
("site_goods_id", "id", None),
@@ -239,6 +259,8 @@ class DwdLoadTask(BaseTask):
("package_template_id", "package_id", None),
("coupon_face_value", "coupon_money", None),
("duration_seconds", "duration", None),
("sort", "sort", None),
("is_first_limit", "is_first_limit", "boolean"),
],
"billiards_dwd.dim_groupbuy_package_ex": [
("groupbuy_package_id", "id", None),
@@ -247,12 +269,18 @@ class DwdLoadTask(BaseTask):
("usable_range", "usable_range", None),
("table_area_id_list", "table_area_id_list", None),
("package_type", "type", None),
("tenant_coupon_sale_order_item_id", "tenantcouponsaleorderitemid", None),
],
# 事实表主键及关键差异列
"billiards_dwd.dwd_table_fee_log": [("table_fee_log_id", "id", None)],
"billiards_dwd.dwd_table_fee_log": [
("table_fee_log_id", "id", None),
("activity_discount_amount", "activity_discount_amount", None),
("real_service_money", "real_service_money", None),
],
"billiards_dwd.dwd_table_fee_log_ex": [
("table_fee_log_id", "id", None),
("salesman_name", "salesman_name", None),
("order_consumption_type", "order_consumption_type", None),
],
"billiards_dwd.dwd_table_fee_adjust": [
("table_fee_adjust_id", "id", None),
@@ -260,12 +288,24 @@ class DwdLoadTask(BaseTask):
("table_area_id", "tenant_table_area_id", None),
("table_area_name", "tableprofile->>'table_area_name'", None),
("adjust_time", "create_time", None),
("table_name", "table_name", None),
("table_price", "table_price", None),
("charge_free", "charge_free", "boolean"),
],
"billiards_dwd.dwd_table_fee_adjust_ex": [
("table_fee_adjust_id", "id", None),
("ledger_name", "ledger_name", None),
("area_type_id", "area_type_id", None),
("site_table_area_id", "site_table_area_id", None),
("site_table_area_name", "site_table_area_name", None),
("site_name", "sitename", None),
("tenant_name", "tenant_name", None),
],
"billiards_dwd.dwd_store_goods_sale": [
("store_goods_sale_id", "id", None),
("discount_price", "discount_money", None),
("coupon_share_money", "coupon_share_money", None),
],
"billiards_dwd.dwd_store_goods_sale": [("store_goods_sale_id", "id", None), ("discount_price", "discount_money", None)],
"billiards_dwd.dwd_store_goods_sale_ex": [
("store_goods_sale_id", "id", None),
("option_value_name", "option_value_name", None),
@@ -282,6 +322,7 @@ class DwdLoadTask(BaseTask):
("site_assistant_id", "order_assistant_id", None),
("level_name", "levelname", None),
("skill_name", "skillname", None),
("real_service_money", "real_service_money", None),
],
"billiards_dwd.dwd_assistant_service_log_ex": [
("assistant_service_id", "id", None),
@@ -291,6 +332,7 @@ class DwdLoadTask(BaseTask):
("trash_reason", "trash_reason", None),
("salesman_name", "salesman_name", None),
("table_name", "tablename", None),
("assistant_team_name", "assistantteamname", None),
],
"billiards_dwd.dwd_assistant_trash_event": [
("assistant_trash_event_id", "id", None),
@@ -303,6 +345,7 @@ class DwdLoadTask(BaseTask):
("assistant_name", "assistantname", None),
("trash_reason", "trashreason", None),
("create_time", "createtime", None),
("tenant_id", "tenant_id", None),
],
"billiards_dwd.dwd_assistant_trash_event_ex": [
("assistant_trash_event_id", "id", None),
@@ -318,13 +361,20 @@ class DwdLoadTask(BaseTask):
("change_time", "create_time", None),
("member_name", "membername", None),
("member_mobile", "membermobile", None),
("principal_before", "principal_before", None),
("principal_after", "principal_after", None),
],
"billiards_dwd.dwd_member_balance_change_ex": [
("balance_change_id", "id", None),
("pay_site_name", "paysitename", None),
("register_site_name", "registersitename", None),
("principal_data", "principal_data", None),
],
"billiards_dwd.dwd_groupbuy_redemption": [
("redemption_id", "id", None),
("member_discount_money", "member_discount_money", None),
("coupon_sale_id", "coupon_sale_id", None),
],
"billiards_dwd.dwd_groupbuy_redemption": [("redemption_id", "id", None)],
"billiards_dwd.dwd_groupbuy_redemption_ex": [
("redemption_id", "id", None),
("table_area_name", "tableareaname", None),
@@ -334,13 +384,24 @@ class DwdLoadTask(BaseTask):
("salesman_name", "salesman_name", None),
("salesman_org_id", "sales_man_org_id", None),
("ledger_group_name", "ledger_group_name", None),
("table_share_money", "table_share_money", None),
("table_service_share_money", "table_service_share_money", None),
("goods_share_money", "goods_share_money", None),
("good_service_share_money", "good_service_share_money", None),
("assistant_share_money", "assistant_share_money", None),
("assistant_service_share_money", "assistant_service_share_money", None),
("recharge_share_money", "recharge_share_money", None),
],
"billiards_dwd.dwd_platform_coupon_redemption": [("platform_coupon_redemption_id", "id", None)],
"billiards_dwd.dwd_platform_coupon_redemption_ex": [
("platform_coupon_redemption_id", "id", None),
("coupon_cover", "coupon_cover", None),
],
"billiards_dwd.dwd_payment": [("payment_id", "id", None), ("pay_date", "pay_time", "date")],
"billiards_dwd.dwd_payment": [
("payment_id", "id", None),
("pay_date", "pay_time", "date"),
("tenant_id", "tenant_id", None),
],
"billiards_dwd.dwd_refund": [("refund_id", "id", None)],
"billiards_dwd.dwd_refund_ex": [
("refund_id", "id", None),
@@ -382,6 +443,11 @@ class DwdLoadTask(BaseTask):
("coupon_amount", "couponamount", None),
("rounding_amount", "roundingamount", None),
("point_amount", "pointamount", None),
("electricity_money", "electricitymoney", None),
("real_electricity_money", "realelectricitymoney", None),
("electricity_adjust_money", "electricityadjustmoney", None),
("pl_coupon_sale_amount", "plcouponsaleamount", None),
("mervou_sales_amount", "mervousalesamount", None),
],
"billiards_dwd.dwd_settlement_head_ex": [
("order_settle_id", "id", None),
@@ -414,6 +480,7 @@ class DwdLoadTask(BaseTask):
("order_remark", "orderremark", None),
("operator_id", "operatorid", None),
("salesman_user_id", "salesmanuserid", None),
("settle_list", "settlelist", None),
],
# 充值结算：recharge_settlements（字段风格同 settlement_records）
"billiards_dwd.dwd_recharge_order": [

55
etl_billiards/tasks/dws/__init__.py Normal file
View File

@@ -0,0 +1,55 @@
# -*- coding: utf-8 -*-
"""
DWS层ETL任务模块
包含：
- BaseDwsTask: DWS任务基类
- 助教维度任务
- 客户维度任务
- 财务维度任务
- 指数算法任务
"""
from .base_dws_task import BaseDwsTask, TimeLayer, TimeWindow, CourseType, DiscountType
from .assistant_daily_task import AssistantDailyTask
from .assistant_monthly_task import AssistantMonthlyTask
from .assistant_customer_task import AssistantCustomerTask
from .assistant_salary_task import AssistantSalaryTask
from .assistant_finance_task import AssistantFinanceTask
from .member_consumption_task import MemberConsumptionTask
from .member_visit_task import MemberVisitTask
from .finance_daily_task import FinanceDailyTask
from .finance_recharge_task import FinanceRechargeTask
from .finance_income_task import FinanceIncomeStructureTask
from .finance_discount_task import FinanceDiscountDetailTask
from .retention_cleanup_task import DwsRetentionCleanupTask
# 指数算法任务
from .index import RecallIndexTask, IntimacyIndexTask
__all__ = [
# 基类
"BaseDwsTask",
"TimeLayer",
"TimeWindow",
"CourseType",
"DiscountType",
# 助教维度
"AssistantDailyTask",
"AssistantMonthlyTask",
"AssistantCustomerTask",
"AssistantSalaryTask",
"AssistantFinanceTask",
# 客户维度
"MemberConsumptionTask",
"MemberVisitTask",
# 财务维度
"FinanceDailyTask",
"FinanceRechargeTask",
"FinanceIncomeStructureTask",
"FinanceDiscountDetailTask",
"DwsRetentionCleanupTask",
# 指数算法
"RecallIndexTask",
"IntimacyIndexTask",
]

333
etl_billiards/tasks/dws/assistant_customer_task.py Normal file
View File

@@ -0,0 +1,333 @@
# -*- coding: utf-8 -*-
"""
助教服务客户统计任务
功能说明：
以"助教+客户"为粒度，统计服务关系和滚动窗口指标
数据来源：
- dwd_assistant_service_log: 助教服务流水
- dim_member: 会员维度
目标表：
billiards_dws.dws_assistant_customer_stats
更新策略：
- 更新频率：每日更新
- 幂等方式：delete-before-insert（按统计日期）
业务规则：
- 散客处理：member_id=0 不进入此表统计
- 滚动窗口：7/10/15/30/60/90天
- 活跃度：近7天/30天是否有服务
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Set, Tuple
from .base_dws_task import BaseDwsTask, TaskContext
class AssistantCustomerTask(BaseDwsTask):
"""
助教服务客户统计任务
统计每个助教与每个客户的服务关系：
- 首次/最近服务日期
- 累计服务统计
- 滚动窗口统计（7/10/15/30/60/90天）
- 活跃度指标
"""
def get_task_code(self) -> str:
return "DWS_ASSISTANT_CUSTOMER"
def get_target_table(self) -> str:
return "dws_assistant_customer_stats"
def get_primary_keys(self) -> List[str]:
return ["site_id", "assistant_id", "member_id", "stat_date"]
# ==========================================================================
# ETL主流程
# ==========================================================================
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
提取数据
"""
stat_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
self.logger.info(
"%s: 提取数据，统计日期 %s",
self.get_task_code(), stat_date
)
# 计算最大回溯日期（90天窗口）
lookback_start = stat_date - timedelta(days=90)
# 1. 获取助教-客户服务记录（包含历史全量用于累计统计）
service_pairs = self._extract_service_pairs(site_id, stat_date)
# 2. 获取会员信息
member_info = self._extract_member_info(site_id)
# 3. 获取助教信息
assistant_info = self._extract_assistant_info(site_id)
return {
'service_pairs': service_pairs,
'member_info': member_info,
'assistant_info': assistant_info,
'stat_date': stat_date,
'site_id': site_id
}
def transform(self, extracted: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据：计算各窗口统计
"""
service_pairs = extracted['service_pairs']
member_info = extracted['member_info']
assistant_info = extracted['assistant_info']
stat_date = extracted['stat_date']
site_id = extracted['site_id']
self.logger.info(
"%s: 转换数据，%d 条服务关系记录",
self.get_task_code(), len(service_pairs)
)
# 构建统计记录
results = []
for pair in service_pairs:
assistant_id = pair.get('assistant_id')
member_id = pair.get('member_id')
# 跳过散客
if self.is_guest(member_id):
continue
asst_info = assistant_info.get(assistant_id, {})
memb_info = member_info.get(member_id, {})
# 构建记录
record = {
'site_id': site_id,
'tenant_id': self.config.get("app.tenant_id", site_id),
'assistant_id': assistant_id,
'assistant_nickname': asst_info.get('nickname', pair.get('assistant_nickname')),
'member_id': member_id,
'member_nickname': memb_info.get('nickname'),
'member_mobile': self._mask_mobile(memb_info.get('mobile')),
'stat_date': stat_date,
# 全量累计统计
'first_service_date': pair.get('first_service_date'),
'last_service_date': pair.get('last_service_date'),
'total_service_count': self.safe_int(pair.get('total_service_count', 0)),
'total_service_hours': self.safe_decimal(pair.get('total_service_hours', 0)),
'total_service_amount': self.safe_decimal(pair.get('total_service_amount', 0)),
# 滚动窗口统计
'service_count_7d': self.safe_int(pair.get('service_count_7d', 0)),
'service_count_10d': self.safe_int(pair.get('service_count_10d', 0)),
'service_count_15d': self.safe_int(pair.get('service_count_15d', 0)),
'service_count_30d': self.safe_int(pair.get('service_count_30d', 0)),
'service_count_60d': self.safe_int(pair.get('service_count_60d', 0)),
'service_count_90d': self.safe_int(pair.get('service_count_90d', 0)),
'service_hours_7d': self.safe_decimal(pair.get('service_hours_7d', 0)),
'service_hours_10d': self.safe_decimal(pair.get('service_hours_10d', 0)),
'service_hours_15d': self.safe_decimal(pair.get('service_hours_15d', 0)),
'service_hours_30d': self.safe_decimal(pair.get('service_hours_30d', 0)),
'service_hours_60d': self.safe_decimal(pair.get('service_hours_60d', 0)),
'service_hours_90d': self.safe_decimal(pair.get('service_hours_90d', 0)),
'service_amount_7d': self.safe_decimal(pair.get('service_amount_7d', 0)),
'service_amount_10d': self.safe_decimal(pair.get('service_amount_10d', 0)),
'service_amount_15d': self.safe_decimal(pair.get('service_amount_15d', 0)),
'service_amount_30d': self.safe_decimal(pair.get('service_amount_30d', 0)),
'service_amount_60d': self.safe_decimal(pair.get('service_amount_60d', 0)),
'service_amount_90d': self.safe_decimal(pair.get('service_amount_90d', 0)),
# 活跃度指标
'days_since_last': self._calc_days_since(stat_date, pair.get('last_service_date')),
'is_active_7d': self.safe_int(pair.get('service_count_7d', 0)) > 0,
'is_active_30d': self.safe_int(pair.get('service_count_30d', 0)) > 0,
}
results.append(record)
return results
def load(self, transformed: List[Dict[str, Any]], context: TaskContext) -> Dict:
"""
加载数据
"""
if not transformed:
self.logger.info("%s: 无数据需要写入", self.get_task_code())
return {"counts": {"fetched": 0, "inserted": 0, "updated": 0, "skipped": 0, "errors": 0}}
# 删除已存在的数据
deleted = self.delete_existing_data(context, date_col="stat_date")
# 批量插入
inserted = self.bulk_insert(transformed)
self.logger.info(
"%s: 加载完成，删除 %d 行，插入 %d 行",
self.get_task_code(), deleted, inserted
)
return {
"counts": {
"fetched": len(transformed),
"inserted": inserted,
"updated": 0,
"skipped": 0,
"errors": 0
},
"extra": {"deleted": deleted}
}
# ==========================================================================
# 数据提取方法
# ==========================================================================
def _extract_service_pairs(
self,
site_id: int,
stat_date: date
) -> List[Dict[str, Any]]:
"""
提取助教-客户服务统计（含滚动窗口）
"""
sql = """
WITH service_base AS (
SELECT
site_assistant_id AS assistant_id,
nickname AS assistant_nickname,
tenant_member_id AS member_id,
DATE(start_use_time) AS service_date,
income_seconds,
ledger_amount
FROM billiards_dwd.dwd_assistant_service_log
WHERE site_id = %s
AND tenant_member_id IS NOT NULL
AND tenant_member_id != 0
)
SELECT
assistant_id,
MAX(assistant_nickname) AS assistant_nickname,
member_id,
MIN(service_date) AS first_service_date,
MAX(service_date) AS last_service_date,
-- 全量累计
COUNT(*) AS total_service_count,
SUM(income_seconds) / 3600.0 AS total_service_hours,
SUM(ledger_amount) AS total_service_amount,
-- 7天窗口
COUNT(CASE WHEN service_date >= %s - INTERVAL '6 days' THEN 1 END) AS service_count_7d,
SUM(CASE WHEN service_date >= %s - INTERVAL '6 days' THEN income_seconds ELSE 0 END) / 3600.0 AS service_hours_7d,
SUM(CASE WHEN service_date >= %s - INTERVAL '6 days' THEN ledger_amount ELSE 0 END) AS service_amount_7d,
-- 10天窗口
COUNT(CASE WHEN service_date >= %s - INTERVAL '9 days' THEN 1 END) AS service_count_10d,
SUM(CASE WHEN service_date >= %s - INTERVAL '9 days' THEN income_seconds ELSE 0 END) / 3600.0 AS service_hours_10d,
SUM(CASE WHEN service_date >= %s - INTERVAL '9 days' THEN ledger_amount ELSE 0 END) AS service_amount_10d,
-- 15天窗口
COUNT(CASE WHEN service_date >= %s - INTERVAL '14 days' THEN 1 END) AS service_count_15d,
SUM(CASE WHEN service_date >= %s - INTERVAL '14 days' THEN income_seconds ELSE 0 END) / 3600.0 AS service_hours_15d,
SUM(CASE WHEN service_date >= %s - INTERVAL '14 days' THEN ledger_amount ELSE 0 END) AS service_amount_15d,
-- 30天窗口
COUNT(CASE WHEN service_date >= %s - INTERVAL '29 days' THEN 1 END) AS service_count_30d,
SUM(CASE WHEN service_date >= %s - INTERVAL '29 days' THEN income_seconds ELSE 0 END) / 3600.0 AS service_hours_30d,
SUM(CASE WHEN service_date >= %s - INTERVAL '29 days' THEN ledger_amount ELSE 0 END) AS service_amount_30d,
-- 60天窗口
COUNT(CASE WHEN service_date >= %s - INTERVAL '59 days' THEN 1 END) AS service_count_60d,
SUM(CASE WHEN service_date >= %s - INTERVAL '59 days' THEN income_seconds ELSE 0 END) / 3600.0 AS service_hours_60d,
SUM(CASE WHEN service_date >= %s - INTERVAL '59 days' THEN ledger_amount ELSE 0 END) AS service_amount_60d,
-- 90天窗口
COUNT(CASE WHEN service_date >= %s - INTERVAL '89 days' THEN 1 END) AS service_count_90d,
SUM(CASE WHEN service_date >= %s - INTERVAL '89 days' THEN income_seconds ELSE 0 END) / 3600.0 AS service_hours_90d,
SUM(CASE WHEN service_date >= %s - INTERVAL '89 days' THEN ledger_amount ELSE 0 END) AS service_amount_90d
FROM service_base
GROUP BY assistant_id, member_id
HAVING MAX(service_date) >= %s - INTERVAL '90 days'
"""
# 构建参数（每个窗口需要3个日期参数）
params = [site_id]
for _ in range(6): # 6个窗口，每个3个参数
params.extend([stat_date, stat_date, stat_date])
params.append(stat_date) # HAVING条件
rows = self.db.query(sql, tuple(params))
return [dict(row) for row in rows] if rows else []
def _extract_member_info(self, site_id: int) -> Dict[int, Dict[str, Any]]:
"""
提取会员信息
"""
sql = """
SELECT
member_id,
nickname,
mobile
FROM billiards_dwd.dim_member
WHERE site_id = %s
"""
rows = self.db.query(sql, (site_id,))
result = {}
for row in (rows or []):
row_dict = dict(row)
result[row_dict['member_id']] = row_dict
return result
def _extract_assistant_info(self, site_id: int) -> Dict[int, Dict[str, Any]]:
"""
提取助教信息
"""
sql = """
SELECT
site_assistant_id AS assistant_id,
nickname
FROM billiards_dwd.dim_assistant
WHERE site_id = %s
AND valid_to IS NULL
"""
rows = self.db.query(sql, (site_id,))
result = {}
for row in (rows or []):
row_dict = dict(row)
result[row_dict['assistant_id']] = row_dict
return result
# ==========================================================================
# 工具方法
# ==========================================================================
def _mask_mobile(self, mobile: Optional[str]) -> Optional[str]:
"""
手机号脱敏
"""
if not mobile or len(mobile) < 7:
return mobile
return mobile[:3] + "****" + mobile[-4:]
def _calc_days_since(self, stat_date: date, last_date: Optional[date]) -> Optional[int]:
"""
计算距离最近服务的天数
"""
if not last_date:
return None
if isinstance(last_date, datetime):
last_date = last_date.date()
return (stat_date - last_date).days
# 便于外部导入
__all__ = ['AssistantCustomerTask']

344
etl_billiards/tasks/dws/assistant_daily_task.py Normal file
View File

@@ -0,0 +1,344 @@
# -*- coding: utf-8 -*-
"""
助教日度业绩明细任务
功能说明：
以"助教+日期"为粒度，汇总每日业绩明细
数据来源：
- dwd_assistant_service_log: 助教服务流水
- dwd_assistant_trash_event: 废除记录（排除）
- dim_assistant: 助教维度（SCD2，获取当日等级）
- cfg_skill_type: 技能→课程类型映射
目标表：
billiards_dws.dws_assistant_daily_detail
更新策略：
- 更新频率：每小时增量更新
- 幂等方式：delete-before-insert（按日期窗口）
业务规则：
- 有效业绩：需排除dwd_assistant_trash_event中的废除记录
- 助教等级：使用SCD2 as-of取值，获取统计日当日生效的等级
- 课程类型：通过skill_id映射，分为基础课和附加课
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Set, Tuple
from .base_dws_task import BaseDwsTask, CourseType, TaskContext
class AssistantDailyTask(BaseDwsTask):
"""
助教日度业绩明细任务
汇总每个助教每天的：
- 服务次数（总/基础课/附加课）
- 计费时长（秒/小时）
- 计费金额
- 服务客户数（去重）
- 服务台桌数（去重）
- 被废除的记录统计
"""
def get_task_code(self) -> str:
return "DWS_ASSISTANT_DAILY"
def get_target_table(self) -> str:
return "dws_assistant_daily_detail"
def get_primary_keys(self) -> List[str]:
return ["site_id", "assistant_id", "stat_date"]
# ==========================================================================
# ETL主流程
# ==========================================================================
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
提取数据：从DWD层读取助教服务记录
"""
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
self.logger.info(
"%s: 提取数据，日期范围 %s ~ %s",
self.get_task_code(), start_date, end_date
)
# 1. 获取助教服务记录
service_records = self._extract_service_records(site_id, start_date, end_date)
# 2. 获取废除记录
trash_records = self._extract_trash_records(site_id, start_date, end_date)
# 3. 加载配置缓存
self.load_config_cache()
return {
'service_records': service_records,
'trash_records': trash_records,
'start_date': start_date,
'end_date': end_date,
'site_id': site_id
}
def transform(self, extracted: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据：按助教+日期聚合
"""
service_records = extracted['service_records']
trash_records = extracted['trash_records']
site_id = extracted['site_id']
self.logger.info(
"%s: 转换数据，服务记录 %d 条，废除记录 %d 条",
self.get_task_code(), len(service_records), len(trash_records)
)
# 构建废除记录索引（assistant_service_id -> trash_info）
trash_index = self._build_trash_index(trash_records)
# 按助教+日期聚合
aggregated = self._aggregate_by_assistant_date(
service_records,
trash_index,
site_id
)
return aggregated
def load(self, transformed: List[Dict[str, Any]], context: TaskContext) -> Dict:
"""
加载数据：写入DWS表
"""
if not transformed:
self.logger.info("%s: 无数据需要写入", self.get_task_code())
return {"counts": {"fetched": 0, "inserted": 0, "updated": 0, "skipped": 0, "errors": 0}}
# 删除已存在的数据（幂等）
deleted = self.delete_existing_data(context, date_col="stat_date")
# 批量插入
inserted = self.bulk_insert(transformed)
self.logger.info(
"%s: 加载完成，删除 %d 行，插入 %d 行",
self.get_task_code(), deleted, inserted
)
return {
"counts": {
"fetched": len(transformed),
"inserted": inserted,
"updated": 0,
"skipped": 0,
"errors": 0
},
"extra": {"deleted": deleted}
}
# ==========================================================================
# 数据提取方法
# ==========================================================================
def _extract_service_records(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取助教服务记录
"""
sql = """
SELECT
asl.assistant_service_id,
asl.order_settle_id,
asl.site_assistant_id AS assistant_id,
asl.nickname AS assistant_nickname,
asl.assistant_level,
asl.skill_id,
asl.skill_name,
asl.tenant_member_id AS member_id,
asl.site_table_id AS table_id,
asl.income_seconds,
asl.real_use_seconds,
asl.ledger_amount,
asl.ledger_unit_price,
DATE(asl.start_use_time) AS service_date
FROM billiards_dwd.dwd_assistant_service_log asl
WHERE asl.site_id = %s
AND DATE(asl.start_use_time) >= %s
AND DATE(asl.start_use_time) <= %s
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
def _extract_trash_records(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取废除记录
有效业绩的排除规则：仅对"助教废除表"的记录进行处理排除
"""
sql = """
SELECT
assistant_service_id,
trash_seconds,
trash_reason,
trash_time
FROM billiards_dwd.dwd_assistant_trash_event
WHERE site_id = %s
AND DATE(trash_time) >= %s
AND DATE(trash_time) <= %s
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
# ==========================================================================
# 数据转换方法
# ==========================================================================
def _build_trash_index(
self,
trash_records: List[Dict[str, Any]]
) -> Dict[int, Dict[str, Any]]:
"""
构建废除记录索引
"""
index = {}
for record in trash_records:
service_id = record.get('assistant_service_id')
if service_id:
index[service_id] = record
return index
def _aggregate_by_assistant_date(
self,
service_records: List[Dict[str, Any]],
trash_index: Dict[int, Dict[str, Any]],
site_id: int
) -> List[Dict[str, Any]]:
"""
按助教+日期聚合服务记录
"""
# 聚合字典：(assistant_id, service_date) -> aggregated_data
agg_dict: Dict[Tuple[int, date], Dict[str, Any]] = {}
for record in service_records:
assistant_id = record.get('assistant_id')
service_date = record.get('service_date')
if not assistant_id or not service_date:
continue
key = (assistant_id, service_date)
# 初始化聚合数据
if key not in agg_dict:
# 获取助教当日等级（SCD2 as-of）
level_info = self.get_assistant_level_asof(assistant_id, service_date)
agg_dict[key] = {
'site_id': site_id,
'tenant_id': self.config.get("app.tenant_id", site_id),
'assistant_id': assistant_id,
'assistant_nickname': record.get('assistant_nickname'),
'stat_date': service_date,
'assistant_level_code': level_info.get('level_code') if level_info else record.get('assistant_level'),
'assistant_level_name': level_info.get('level_name') if level_info else None,
'total_service_count': 0,
'base_service_count': 0,
'bonus_service_count': 0,
'total_seconds': 0,
'base_seconds': 0,
'bonus_seconds': 0,
'total_hours': Decimal('0'),
'base_hours': Decimal('0'),
'bonus_hours': Decimal('0'),
'total_ledger_amount': Decimal('0'),
'base_ledger_amount': Decimal('0'),
'bonus_ledger_amount': Decimal('0'),
'unique_customers': set(),
'unique_tables': set(),
'trashed_seconds': 0,
'trashed_count': 0,
}
agg = agg_dict[key]
# 获取服务信息
service_id = record.get('assistant_service_id')
income_seconds = self.safe_int(record.get('income_seconds', 0))
ledger_amount = self.safe_decimal(record.get('ledger_amount', 0))
skill_id = record.get('skill_id')
member_id = record.get('member_id')
table_id = record.get('table_id')
# 判断课程类型
course_type = self.get_course_type(skill_id) if skill_id else CourseType.BASE
is_base = course_type == CourseType.BASE
# 检查是否被废除
is_trashed = service_id in trash_index
if is_trashed:
# 废除记录单独统计
trash_info = trash_index[service_id]
trash_seconds = self.safe_int(trash_info.get('trash_seconds', income_seconds))
agg['trashed_seconds'] += trash_seconds
agg['trashed_count'] += 1
else:
# 正常记录累加
agg['total_service_count'] += 1
agg['total_seconds'] += income_seconds
agg['total_ledger_amount'] += ledger_amount
if is_base:
agg['base_service_count'] += 1
agg['base_seconds'] += income_seconds
agg['base_ledger_amount'] += ledger_amount
else:
agg['bonus_service_count'] += 1
agg['bonus_seconds'] += income_seconds
agg['bonus_ledger_amount'] += ledger_amount
# 客户和台桌去重统计（不论是否废除）
if member_id and not self.is_guest(member_id):
agg['unique_customers'].add(member_id)
if table_id:
agg['unique_tables'].add(table_id)
# 转换为列表并计算派生字段
result = []
for key, agg in agg_dict.items():
# 计算小时数
agg['total_hours'] = self.seconds_to_hours(agg['total_seconds'])
agg['base_hours'] = self.seconds_to_hours(agg['base_seconds'])
agg['bonus_hours'] = self.seconds_to_hours(agg['bonus_seconds'])
# 转换set为count
agg['unique_customers'] = len(agg['unique_customers'])
agg['unique_tables'] = len(agg['unique_tables'])
result.append(agg)
return result
# 便于外部导入
__all__ = ['AssistantDailyTask']

199
etl_billiards/tasks/dws/assistant_finance_task.py Normal file
View File

@@ -0,0 +1,199 @@
# -*- coding: utf-8 -*-
"""
助教收支分析任务
功能说明：
以"日期+助教"为粒度，分析助教产出的收入和成本
数据来源：
- dwd_assistant_service_log: 助教服务流水（收入）
- dws_assistant_salary_calc: 工资计算（成本）
目标表：
billiards_dws.dws_assistant_finance_analysis
更新策略：
- 更新频率：每日更新
- 幂等方式：delete-before-insert（按日期）
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Tuple
from .base_dws_task import BaseDwsTask, CourseType, TaskContext
class AssistantFinanceTask(BaseDwsTask):
"""
助教收支分析任务
"""
def get_task_code(self) -> str:
return "DWS_ASSISTANT_FINANCE"
def get_target_table(self) -> str:
return "dws_assistant_finance_analysis"
def get_primary_keys(self) -> List[str]:
return ["site_id", "stat_date", "assistant_id"]
def extract(self, context: TaskContext) -> Dict[str, Any]:
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
# 获取助教日度收入
daily_revenue = self._extract_daily_revenue(site_id, start_date, end_date)
# 获取月度工资（用于计算日均成本）
monthly_salary = self._extract_monthly_salary(site_id, start_date, end_date)
# 加载配置
self.load_config_cache()
return {
'daily_revenue': daily_revenue,
'monthly_salary': monthly_salary,
'start_date': start_date,
'end_date': end_date,
'site_id': site_id
}
def transform(self, extracted: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
daily_revenue = extracted['daily_revenue']
monthly_salary = extracted['monthly_salary']
site_id = extracted['site_id']
# 构建月度工资索引
salary_index = {}
for sal in monthly_salary:
asst_id = sal.get('assistant_id')
month = sal.get('salary_month')
if asst_id and month:
salary_index[(asst_id, month)] = sal
results = []
for rev in daily_revenue:
assistant_id = rev.get('assistant_id')
stat_date = rev.get('stat_date')
# 获取对应月份的工资
month_start = stat_date.replace(day=1) if isinstance(stat_date, date) else None
salary = salary_index.get((assistant_id, month_start), {})
# 计算日均成本
gross_salary = self.safe_decimal(salary.get('gross_salary', 0))
work_days = self.safe_int(salary.get('work_days', 1)) or 1
cost_daily = gross_salary / Decimal(str(work_days))
revenue_total = self.safe_decimal(rev.get('revenue_total', 0))
gross_profit = revenue_total - cost_daily
gross_margin = gross_profit / revenue_total if revenue_total > 0 else Decimal('0')
record = {
'site_id': site_id,
'tenant_id': self.config.get("app.tenant_id", site_id),
'stat_date': stat_date,
'assistant_id': assistant_id,
'assistant_nickname': rev.get('assistant_nickname'),
'revenue_total': revenue_total,
'revenue_base': self.safe_decimal(rev.get('revenue_base', 0)),
'revenue_bonus': self.safe_decimal(rev.get('revenue_bonus', 0)),
'cost_daily': cost_daily,
'gross_profit': gross_profit,
'gross_margin': gross_margin,
'service_count': self.safe_int(rev.get('service_count', 0)),
'service_hours': self.safe_decimal(rev.get('service_hours', 0)),
'unique_customers': self.safe_int(rev.get('unique_customers', 0)),
}
results.append(record)
return results
def load(self, transformed: List[Dict[str, Any]], context: TaskContext) -> Dict:
if not transformed:
return {"counts": {"fetched": 0, "inserted": 0, "updated": 0, "skipped": 0, "errors": 0}}
deleted = self.delete_existing_data(context, date_col="stat_date")
inserted = self.bulk_insert(transformed)
return {
"counts": {"fetched": len(transformed), "inserted": inserted, "updated": 0, "skipped": 0, "errors": 0},
"extra": {"deleted": deleted}
}
def _extract_daily_revenue(self, site_id: int, start_date: date, end_date: date) -> List[Dict[str, Any]]:
# 基础课skill_id
BASE_SKILL_ID = 2791903611396869
sql = """
SELECT
DATE(start_use_time) AS stat_date,
site_assistant_id AS assistant_id,
MAX(nickname) AS assistant_nickname,
COUNT(*) AS service_count,
SUM(income_seconds) / 3600.0 AS service_hours,
SUM(ledger_amount) AS revenue_total,
SUM(CASE WHEN skill_id = %s THEN ledger_amount ELSE 0 END) AS revenue_base,
SUM(CASE WHEN skill_id != %s THEN ledger_amount ELSE 0 END) AS revenue_bonus,
COUNT(DISTINCT tenant_member_id) AS unique_customers
FROM billiards_dwd.dwd_assistant_service_log
WHERE site_id = %s
AND DATE(start_use_time) >= %s
AND DATE(start_use_time) <= %s
GROUP BY DATE(start_use_time), site_assistant_id
"""
rows = self.db.query(sql, (BASE_SKILL_ID, BASE_SKILL_ID, site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
def _extract_monthly_salary(self, site_id: int, start_date: date, end_date: date) -> List[Dict[str, Any]]:
# 获取涉及的月份
month_start = start_date.replace(day=1)
month_end = end_date.replace(day=1)
sql = """
SELECT
assistant_id,
salary_month,
gross_salary,
effective_hours
FROM billiards_dws.dws_assistant_salary_calc
WHERE site_id = %s
AND salary_month >= %s
AND salary_month <= %s
"""
rows = self.db.query(sql, (site_id, month_start, month_end))
# 获取每月工作天数
work_days_sql = """
SELECT
assistant_id,
DATE_TRUNC('month', stat_date)::DATE AS month,
COUNT(DISTINCT stat_date) AS work_days
FROM billiards_dws.dws_assistant_daily_detail
WHERE site_id = %s
AND stat_date >= %s
AND stat_date <= %s
GROUP BY assistant_id, DATE_TRUNC('month', stat_date)
"""
work_days_rows = self.db.query(work_days_sql, (site_id, start_date, end_date))
work_days_index = {(r['assistant_id'], r['month']): r['work_days'] for r in (work_days_rows or [])}
results = []
for row in (rows or []):
row_dict = dict(row)
asst_id = row_dict.get('assistant_id')
month = row_dict.get('salary_month')
row_dict['work_days'] = work_days_index.get((asst_id, month), 20)
results.append(row_dict)
return results
__all__ = ['AssistantFinanceTask']

444
etl_billiards/tasks/dws/assistant_monthly_task.py Normal file
View File

@@ -0,0 +1,444 @@
# -*- coding: utf-8 -*-
"""
助教月度业绩汇总任务
功能说明：
以"助教+月份"为粒度，汇总月度业绩及档位计算
数据来源：
- dws_assistant_daily_detail: 日度明细（聚合）
- dim_assistant: 助教维度（入职日期、等级）
- cfg_performance_tier: 绩效档位配置
目标表：
billiards_dws.dws_assistant_monthly_summary
更新策略：
- 更新频率：每日更新当月数据
- 幂等方式：delete-before-insert（按月份）
业务规则：
- 新入职判断：入职日期在月1日0点之后则为新入职
- 有效业绩：total_hours - trashed_hours
- 档位匹配：根据有效业绩小时数匹配cfg_performance_tier
- 排名计算：按有效业绩小时数降序，考虑并列（如2个第一则都是1，下一个是3）
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Set, Tuple
from .base_dws_task import BaseDwsTask, TaskContext
class AssistantMonthlyTask(BaseDwsTask):
"""
助教月度业绩汇总任务
汇总每个助教每月的：
- 工作天数、服务次数、时长
- 有效业绩（扣除废除记录后）
- 档位匹配
- 月度排名（用于Top3奖金）
"""
def get_task_code(self) -> str:
return "DWS_ASSISTANT_MONTHLY"
def get_target_table(self) -> str:
return "dws_assistant_monthly_summary"
def get_primary_keys(self) -> List[str]:
return ["site_id", "assistant_id", "stat_month"]
# ==========================================================================
# ETL主流程
# ==========================================================================
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
提取数据：从日度明细表聚合
"""
# 确定月份范围
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
# 获取涉及的月份列表
months = self._get_months_in_range(start_date, end_date)
self.logger.info(
"%s: 提取数据，月份范围 %s",
self.get_task_code(), [str(m) for m in months]
)
# 1. 获取日度明细聚合数据
daily_aggregates = self._extract_daily_aggregates(site_id, months)
# 2. 获取助教基本信息
assistant_info = self._extract_assistant_info(site_id)
# 3. 加载配置缓存
self.load_config_cache()
return {
'daily_aggregates': daily_aggregates,
'assistant_info': assistant_info,
'months': months,
'site_id': site_id
}
def transform(self, extracted: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据：计算月度汇总、档位匹配、排名
"""
daily_aggregates = extracted['daily_aggregates']
assistant_info = extracted['assistant_info']
months = extracted['months']
site_id = extracted['site_id']
self.logger.info(
"%s: 转换数据，%d 个月份，%d 条聚合记录",
self.get_task_code(), len(months), len(daily_aggregates)
)
# 按月份处理
all_results = []
for month in months:
month_results = self._process_month(
daily_aggregates,
assistant_info,
month,
site_id
)
all_results.extend(month_results)
return all_results
def load(self, transformed: List[Dict[str, Any]], context: TaskContext) -> Dict:
"""
加载数据：写入DWS表
"""
if not transformed:
self.logger.info("%s: 无数据需要写入", self.get_task_code())
return {"counts": {"fetched": 0, "inserted": 0, "updated": 0, "skipped": 0, "errors": 0}}
# 删除已存在的数据（按月份）
deleted = self._delete_by_months(context, transformed)
# 批量插入
inserted = self.bulk_insert(transformed)
self.logger.info(
"%s: 加载完成，删除 %d 行，插入 %d 行",
self.get_task_code(), deleted, inserted
)
return {
"counts": {
"fetched": len(transformed),
"inserted": inserted,
"updated": 0,
"skipped": 0,
"errors": 0
},
"extra": {"deleted": deleted}
}
# ==========================================================================
# 数据提取方法
# ==========================================================================
def _get_months_in_range(self, start_date: date, end_date: date) -> List[date]:
"""
获取日期范围内的所有月份（月第一天）
"""
months = []
current = start_date.replace(day=1)
end_month = end_date.replace(day=1)
while current <= end_month:
months.append(current)
# 下个月
if current.month == 12:
current = current.replace(year=current.year + 1, month=1)
else:
current = current.replace(month=current.month + 1)
return months
def _extract_daily_aggregates(
self,
site_id: int,
months: List[date]
) -> List[Dict[str, Any]]:
"""
从日度明细表提取并按月聚合
"""
if not months:
return []
# 构建月份条件
month_conditions = []
for month in months:
next_month = (month.replace(day=28) + timedelta(days=4)).replace(day=1)
month_conditions.append(f"(stat_date >= '{month}' AND stat_date < '{next_month}')")
month_where = " OR ".join(month_conditions)
sql = f"""
SELECT
assistant_id,
assistant_nickname,
assistant_level_code,
assistant_level_name,
DATE_TRUNC('month', stat_date)::DATE AS stat_month,
COUNT(DISTINCT stat_date) AS work_days,
SUM(total_service_count) AS total_service_count,
SUM(base_service_count) AS base_service_count,
SUM(bonus_service_count) AS bonus_service_count,
SUM(total_hours) AS total_hours,
SUM(base_hours) AS base_hours,
SUM(bonus_hours) AS bonus_hours,
SUM(total_ledger_amount) AS total_ledger_amount,
SUM(base_ledger_amount) AS base_ledger_amount,
SUM(bonus_ledger_amount) AS bonus_ledger_amount,
SUM(unique_customers) AS total_unique_customers,
SUM(unique_tables) AS total_unique_tables,
SUM(trashed_seconds) AS trashed_seconds,
SUM(trashed_count) AS trashed_count
FROM billiards_dws.dws_assistant_daily_detail
WHERE site_id = %s AND ({month_where})
GROUP BY assistant_id, assistant_nickname, assistant_level_code, assistant_level_name,
DATE_TRUNC('month', stat_date)
"""
rows = self.db.query(sql, (site_id,))
return [dict(row) for row in rows] if rows else []
def _extract_assistant_info(self, site_id: int) -> Dict[int, Dict[str, Any]]:
"""
提取助教基本信息
"""
sql = """
SELECT
site_assistant_id AS assistant_id,
nickname,
assistant_level,
entry_date AS hire_date
FROM billiards_dwd.dim_assistant
WHERE site_id = %s
AND valid_to IS NULL -- 当前有效记录
"""
rows = self.db.query(sql, (site_id,))
result = {}
for row in (rows or []):
row_dict = dict(row)
result[row_dict['assistant_id']] = row_dict
return result
# ==========================================================================
# 数据转换方法
# ==========================================================================
def _process_month(
self,
daily_aggregates: List[Dict[str, Any]],
assistant_info: Dict[int, Dict[str, Any]],
month: date,
site_id: int
) -> List[Dict[str, Any]]:
"""
处理单个月份的数据
"""
# 筛选该月份的数据
month_data = [
agg for agg in daily_aggregates
if agg.get('stat_month') == month
]
if not month_data:
return []
# 构建月度汇总记录
month_records = []
for agg in month_data:
assistant_id = agg.get('assistant_id')
asst_info = assistant_info.get(assistant_id, {})
# 计算有效业绩
total_hours = self.safe_decimal(agg.get('total_hours', 0))
trashed_hours = self.seconds_to_hours(self.safe_int(agg.get('trashed_seconds', 0)))
effective_hours = total_hours - trashed_hours
# 判断是否新入职
hire_date = asst_info.get('hire_date')
is_new_hire = False
if hire_date:
if isinstance(hire_date, datetime):
hire_date = hire_date.date()
is_new_hire = self.is_new_hire_in_month(hire_date, month)
# 匹配档位
tier_hours = effective_hours
max_tier_level = None
if is_new_hire:
tier_hours = self._calc_new_hire_tier_hours(effective_hours, self.safe_int(agg.get('work_days', 0)))
if hire_date and hire_date.day > 25:
max_tier_level = 3
tier = self.get_performance_tier(
tier_hours,
is_new_hire,
effective_date=month,
max_tier_level=max_tier_level
)
# 获取月末的等级信息（用于记录）
month_end = self._get_month_end(month)
level_info = self.get_assistant_level_asof(assistant_id, month_end)
record = {
'site_id': site_id,
'tenant_id': self.config.get("app.tenant_id", site_id),
'assistant_id': assistant_id,
'assistant_nickname': agg.get('assistant_nickname'),
'stat_month': month,
'assistant_level_code': level_info.get('level_code') if level_info else agg.get('assistant_level_code'),
'assistant_level_name': level_info.get('level_name') if level_info else agg.get('assistant_level_name'),
'hire_date': hire_date,
'is_new_hire': is_new_hire,
'work_days': self.safe_int(agg.get('work_days', 0)),
'total_service_count': self.safe_int(agg.get('total_service_count', 0)),
'base_service_count': self.safe_int(agg.get('base_service_count', 0)),
'bonus_service_count': self.safe_int(agg.get('bonus_service_count', 0)),
'total_hours': total_hours,
'base_hours': self.safe_decimal(agg.get('base_hours', 0)),
'bonus_hours': self.safe_decimal(agg.get('bonus_hours', 0)),
'effective_hours': effective_hours,
'trashed_hours': trashed_hours,
'total_ledger_amount': self.safe_decimal(agg.get('total_ledger_amount', 0)),
'base_ledger_amount': self.safe_decimal(agg.get('base_ledger_amount', 0)),
'bonus_ledger_amount': self.safe_decimal(agg.get('bonus_ledger_amount', 0)),
'unique_customers': self.safe_int(agg.get('total_unique_customers', 0)),
'unique_tables': self.safe_int(agg.get('total_unique_tables', 0)),
'avg_service_seconds': self._calc_avg_service_seconds(agg),
'tier_id': tier.get('tier_id') if tier else None,
'tier_code': tier.get('tier_code') if tier else None,
'tier_name': tier.get('tier_name') if tier else None,
'rank_by_hours': None, # 后面计算
'rank_with_ties': None, # 后面计算
}
month_records.append(record)
# 计算排名
self._calculate_ranks(month_records)
return month_records
def _get_month_end(self, month: date) -> date:
"""
获取月末日期
"""
if month.month == 12:
next_month = month.replace(year=month.year + 1, month=1, day=1)
else:
next_month = month.replace(month=month.month + 1, day=1)
return next_month - timedelta(days=1)
def _calc_avg_service_seconds(self, agg: Dict[str, Any]) -> Decimal:
"""
计算平均单次服务时长
"""
total_count = self.safe_int(agg.get('total_service_count', 0))
if total_count == 0:
return Decimal('0')
total_hours = self.safe_decimal(agg.get('total_hours', 0))
total_seconds = total_hours * Decimal('3600')
return total_seconds / Decimal(str(total_count))
def _calc_new_hire_tier_hours(self, effective_hours: Decimal, work_days: int) -> Decimal:
"""
新入职定档：日均 * 30（仅用于定档，不影响奖金与排名）
"""
if work_days <= 0:
return Decimal('0')
return (effective_hours / Decimal(str(work_days))) * Decimal('30')
def _calculate_ranks(self, records: List[Dict[str, Any]]) -> None:
"""
计算排名（考虑并列）
Top3排名口径：按有效业绩总小时数排名，
如遇并列则都算，比如2个第一，则记为2个第一，一个第三
"""
if not records:
return
# 按有效业绩降序排序
sorted_records = sorted(
records,
key=lambda x: x.get('effective_hours', Decimal('0')),
reverse=True
)
# 计算考虑并列的排名
values = [
(r.get('assistant_id'), r.get('effective_hours', Decimal('0')))
for r in sorted_records
]
ranked = self.calculate_rank_with_ties(values)
# 创建排名映射
rank_map = {
assistant_id: (rank, dense_rank)
for assistant_id, rank, dense_rank in ranked
}
# 更新记录
for record in records:
assistant_id = record.get('assistant_id')
if assistant_id in rank_map:
rank, _ = rank_map[assistant_id]
record['rank_by_hours'] = rank
record['rank_with_ties'] = rank # 使用考虑并列的排名
def _delete_by_months(
self,
context: TaskContext,
records: List[Dict[str, Any]]
) -> int:
"""
按月份删除已存在的数据
"""
# 获取涉及的月份
months = set(r.get('stat_month') for r in records if r.get('stat_month'))
if not months:
return 0
target_table = self.get_target_table()
full_table = f"{self.DWS_SCHEMA}.{target_table}"
total_deleted = 0
with self.db.conn.cursor() as cur:
for month in months:
sql = f"""
DELETE FROM {full_table}
WHERE site_id = %s AND stat_month = %s
"""
cur.execute(sql, (context.store_id, month))
total_deleted += cur.rowcount
return total_deleted
# 便于外部导入
__all__ = ['AssistantMonthlyTask']

403
etl_billiards/tasks/dws/assistant_salary_task.py Normal file
View File

@@ -0,0 +1,403 @@
# -*- coding: utf-8 -*-
"""
助教工资计算任务
功能说明：
以"助教+月份"为粒度，计算月度工资明细
数据来源：
- dws_assistant_monthly_summary: 月度业绩汇总
- dws_assistant_recharge_commission: 充值提成（Excel导入）
- cfg_performance_tier: 绩效档位配置
- cfg_assistant_level_price: 等级定价配置
- cfg_bonus_rules: 奖金规则配置
目标表：
billiards_dws.dws_assistant_salary_calc
更新策略：
- 更新频率：月初计算上月工资
- 幂等方式：delete-before-insert（按月份）
业务规则（来自DWS数据库处理需求.md）：
- 基础课收入 = 基础课小时数 × (客户支付价格 - 专业课抽成)
例：中级助教基础课170小时，3档 = 170 × (108 - 13) = 16,150元
- 附加课收入 = 附加课小时数 × 附加课价格 × (1 - 打赏课抽成比例)
例：附加课15小时，3档 = 15 × 190 × (1 - 0.35) = 1,852.5元
- 冲刺奖金：H>=190:300, H>=220:800（不累计，取最高档）
- Top3奖金：1st:1000, 2nd:600, 3rd:400（并列都算）
- 充值提成：来自dws_assistant_recharge_commission
- SCD2口径：等级定价使用月份对应的历史值
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Tuple
from .base_dws_task import BaseDwsTask, TaskContext
class AssistantSalaryTask(BaseDwsTask):
"""
助教工资计算任务
计算每个助教每月的工资明细：
- 课时收入（基础课+附加课）
- 扣款（档位扣款+其他）
- 奖金（档位奖金+冲刺+Top3+充值提成+其他）
- 应发工资
"""
def get_task_code(self) -> str:
return "DWS_ASSISTANT_SALARY"
def get_target_table(self) -> str:
return "dws_assistant_salary_calc"
def get_primary_keys(self) -> List[str]:
return ["site_id", "assistant_id", "salary_month"]
# ==========================================================================
# ETL主流程
# ==========================================================================
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
提取数据
"""
# 确定工资月份（通常是上月）
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
salary_month = self._get_salary_month(end_date)
site_id = context.store_id
self.logger.info(
"%s: 提取数据，工资月份 %s",
self.get_task_code(), salary_month
)
# 1. 获取月度业绩汇总
monthly_summary = self._extract_monthly_summary(site_id, salary_month)
# 2. 获取充值提成
recharge_commission = self._extract_recharge_commission(site_id, salary_month)
# 3. 加载配置缓存
self.load_config_cache()
return {
'monthly_summary': monthly_summary,
'recharge_commission': recharge_commission,
'salary_month': salary_month,
'site_id': site_id
}
def transform(self, extracted: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据：计算工资
"""
monthly_summary = extracted['monthly_summary']
recharge_commission = extracted['recharge_commission']
salary_month = extracted['salary_month']
site_id = extracted['site_id']
self.logger.info(
"%s: 转换数据，%d 条月度汇总记录",
self.get_task_code(), len(monthly_summary)
)
# 构建充值提成索引
commission_index = {}
for comm in recharge_commission:
asst_id = comm.get('assistant_id')
if asst_id:
commission_index[asst_id] = commission_index.get(asst_id, Decimal('0')) + \
self.safe_decimal(comm.get('commission_amount', 0))
# 计算工资
results = []
for summary in monthly_summary:
record = self._calculate_salary(summary, commission_index, salary_month, site_id)
results.append(record)
return results
def load(self, transformed: List[Dict[str, Any]], context: TaskContext) -> Dict:
"""
加载数据
"""
if not transformed:
self.logger.info("%s: 无数据需要写入", self.get_task_code())
return {"counts": {"fetched": 0, "inserted": 0, "updated": 0, "skipped": 0, "errors": 0}}
# 删除已存在的数据
deleted = self._delete_by_month(context, transformed)
# 批量插入
inserted = self.bulk_insert(transformed)
self.logger.info(
"%s: 加载完成，删除 %d 行，插入 %d 行",
self.get_task_code(), deleted, inserted
)
return {
"counts": {
"fetched": len(transformed),
"inserted": inserted,
"updated": 0,
"skipped": 0,
"errors": 0
},
"extra": {"deleted": deleted}
}
# ==========================================================================
# 数据提取方法
# ==========================================================================
def _get_salary_month(self, end_date: date) -> date:
"""
获取工资月份（默认为上月）
"""
# 如果是月初，计算上月工资
if end_date.day <= 5:
if end_date.month == 1:
return date(end_date.year - 1, 12, 1)
else:
return date(end_date.year, end_date.month - 1, 1)
else:
# 否则计算当月（可能是调整）
return end_date.replace(day=1)
def _extract_monthly_summary(
self,
site_id: int,
salary_month: date
) -> List[Dict[str, Any]]:
"""
提取月度业绩汇总
"""
sql = """
SELECT
assistant_id,
assistant_nickname,
stat_month,
assistant_level_code,
assistant_level_name,
hire_date,
is_new_hire,
effective_hours,
base_hours,
bonus_hours,
tier_id,
tier_code,
tier_name,
rank_with_ties
FROM billiards_dws.dws_assistant_monthly_summary
WHERE site_id = %s AND stat_month = %s
"""
rows = self.db.query(sql, (site_id, salary_month))
return [dict(row) for row in rows] if rows else []
def _extract_recharge_commission(
self,
site_id: int,
salary_month: date
) -> List[Dict[str, Any]]:
"""
提取充值提成
"""
sql = """
SELECT
assistant_id,
commission_amount
FROM billiards_dws.dws_assistant_recharge_commission
WHERE site_id = %s AND commission_month = %s
"""
rows = self.db.query(sql, (site_id, salary_month))
return [dict(row) for row in rows] if rows else []
# ==========================================================================
# 工资计算方法
# ==========================================================================
def _calculate_salary(
self,
summary: Dict[str, Any],
commission_index: Dict[int, Decimal],
salary_month: date,
site_id: int
) -> Dict[str, Any]:
"""
计算单个助教的月度工资
"""
assistant_id = summary.get('assistant_id')
level_code = summary.get('assistant_level_code')
effective_hours = self.safe_decimal(summary.get('effective_hours', 0))
base_hours = self.safe_decimal(summary.get('base_hours', 0))
bonus_hours = self.safe_decimal(summary.get('bonus_hours', 0))
is_new_hire = summary.get('is_new_hire', False)
rank = summary.get('rank_with_ties')
# 获取等级定价（SCD2口径，按月份取值）
# base_course_price: 客户支付价格（初级98/中级108/高级118/星级138）
# bonus_course_price: 附加课客户支付价格（固定190元）
level_price = self.get_level_price(level_code, salary_month)
base_course_price = self.safe_decimal(
level_price.get('base_course_price', 98) if level_price else 98
)
bonus_course_price = self.safe_decimal(
level_price.get('bonus_course_price', 190) if level_price else 190
)
# 获取档位配置
# base_deduction: 专业课抽成（元/小时），球房从每小时扣除
# bonus_deduction_ratio: 打赏课抽成比例，球房从附加课收入扣除的比例
tier = self.get_performance_tier_by_id(summary.get('tier_id'), salary_month)
if not tier:
tier = self.get_performance_tier(
effective_hours,
is_new_hire,
effective_date=salary_month
)
base_deduction = self.safe_decimal(tier.get('base_deduction', 18)) if tier else Decimal('18')
bonus_deduction_ratio = self.safe_decimal(tier.get('bonus_deduction_ratio', 0.40)) if tier else Decimal('0.40')
vacation_days = tier.get('vacation_days', 0) if tier else 0
vacation_unlimited = tier.get('vacation_unlimited', False) if tier else False
# ============================================================
# 工资计算公式（来自DWS数据库处理需求.md）
# ============================================================
# 基础课收入 = 基础课小时数 × (客户支付价格 - 专业课抽成)
# 例：中级助教170小时，3档 = 170 × (108 - 13) = 16,150元
base_income = base_hours * (base_course_price - base_deduction)
# 附加课收入 = 附加课小时数 × 附加课价格 × (1 - 打赏课抽成比例)
# 例：15小时，3档 = 15 × 190 × (1 - 0.35) = 1,852.5元
bonus_income = bonus_hours * bonus_course_price * (Decimal('1') - bonus_deduction_ratio)
# 课时收入合计
total_course_income = base_income + bonus_income
# 计算冲刺奖金（H>=190:300, H>=220:800，不累计取最高）
sprint_bonus = self.calculate_sprint_bonus(effective_hours, salary_month)
# 计算Top3排名奖金（1st:1000, 2nd:600, 3rd:400，并列都算）
top_rank_bonus = Decimal('0')
if rank and rank <= 3:
top_rank_bonus = self.calculate_top_rank_bonus(rank, salary_month)
# 获取充值提成
recharge_commission = commission_index.get(assistant_id, Decimal('0'))
# 汇总奖金
other_bonus = Decimal('0') # 预留其他奖金
total_bonus = sprint_bonus + top_rank_bonus + recharge_commission + other_bonus
# 计算应发工资 = 课时收入 + 奖金
gross_salary = total_course_income + total_bonus
# 构建记录
return {
'site_id': site_id,
'tenant_id': self.config.get("app.tenant_id", site_id),
'assistant_id': assistant_id,
'assistant_nickname': summary.get('assistant_nickname'),
'salary_month': salary_month,
'assistant_level_code': level_code,
'assistant_level_name': summary.get('assistant_level_name'),
'hire_date': summary.get('hire_date'),
'is_new_hire': is_new_hire,
'effective_hours': effective_hours,
'base_hours': base_hours,
'bonus_hours': bonus_hours,
'tier_id': summary.get('tier_id'),
'tier_code': tier.get('tier_code') if tier else None,
'tier_name': tier.get('tier_name') if tier else None,
'rank_with_ties': rank,
# 定价信息
'base_course_price': base_course_price,
'bonus_course_price': bonus_course_price,
'base_deduction': base_deduction,
'bonus_deduction_ratio': bonus_deduction_ratio,
# 收入明细
'base_income': base_income,
'bonus_income': bonus_income,
'total_course_income': total_course_income,
# 奖金明细
'sprint_bonus': sprint_bonus,
'top_rank_bonus': top_rank_bonus,
'recharge_commission': recharge_commission,
'other_bonus': other_bonus,
'total_bonus': total_bonus,
# 应发工资
'gross_salary': gross_salary,
# 假期
'vacation_days': vacation_days,
'vacation_unlimited': vacation_unlimited,
'calc_notes': self._build_calc_notes(summary, tier, sprint_bonus, top_rank_bonus),
}
def _build_calc_notes(
self,
summary: Dict[str, Any],
tier: Optional[Dict[str, Any]],
sprint_bonus: Decimal,
top_rank_bonus: Decimal
) -> Optional[str]:
"""
构建计算备注
"""
notes = []
if summary.get('is_new_hire'):
notes.append("新入职首月")
if tier:
notes.append(f"档位: {tier.get('tier_name', 'N/A')}")
if sprint_bonus > 0:
notes.append(f"冲刺奖金: {sprint_bonus}")
if top_rank_bonus > 0:
rank = summary.get('rank_with_ties')
notes.append(f"Top{rank}奖金: {top_rank_bonus}")
return "; ".join(notes) if notes else None
def _delete_by_month(
self,
context: TaskContext,
records: List[Dict[str, Any]]
) -> int:
"""
按月份删除已存在的数据
"""
months = set(r.get('salary_month') for r in records if r.get('salary_month'))
if not months:
return 0
target_table = self.get_target_table()
full_table = f"{self.DWS_SCHEMA}.{target_table}"
total_deleted = 0
with self.db.conn.cursor() as cur:
for month in months:
sql = f"""
DELETE FROM {full_table}
WHERE site_id = %s AND salary_month = %s
"""
cur.execute(sql, (context.store_id, month))
total_deleted += cur.rowcount
return total_deleted
# 便于外部导入
__all__ = ['AssistantSalaryTask']

1223
etl_billiards/tasks/dws/base_dws_task.py Normal file
View File

File diff suppressed because it is too large Load Diff

574
etl_billiards/tasks/dws/finance_daily_task.py Normal file
View File

@@ -0,0 +1,574 @@
# -*- coding: utf-8 -*-
"""
财务日度汇总任务
功能说明：
以"日期"为粒度，汇总当日财务数据
数据来源：
- dwd_settlement_head: 结账单头表
- dwd_groupbuy_redemption: 团购核销
- dwd_recharge_order: 充值订单
- dws_finance_expense_summary: 支出汇总（Excel导入）
- dws_platform_settlement: 平台回款/服务费（Excel导入）
目标表：
billiards_dws.dws_finance_daily_summary
更新策略：
- 更新频率：每小时更新当日数据
- 幂等方式：delete-before-insert（按日期）
业务规则：
- 发生额：table_charge_money + goods_money + assistant_pd_money + assistant_cx_money
- 团购优惠：coupon_amount - 团购支付金额
- 团购支付：pl_coupon_sale_amount 或关联 groupbuy_redemption.ledger_unit_price
- 首充/续充：通过 is_first 字段区分
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
import calendar
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Tuple
from .base_dws_task import BaseDwsTask, TaskContext
class FinanceDailyTask(BaseDwsTask):
"""
财务日度汇总任务
汇总每日的：
- 发生额（正价）
- 优惠拆分
- 确认收入
- 现金流（流入/流出）
- 充值统计（首充/续充）
- 订单统计
"""
def get_task_code(self) -> str:
return "DWS_FINANCE_DAILY"
def get_target_table(self) -> str:
return "dws_finance_daily_summary"
def get_primary_keys(self) -> List[str]:
return ["site_id", "stat_date"]
# ==========================================================================
# ETL主流程
# ==========================================================================
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
提取数据
"""
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
self.logger.info(
"%s: 提取数据，日期范围 %s ~ %s",
self.get_task_code(), start_date, end_date
)
# 1. 获取结账单汇总
settlement_summary = self._extract_settlement_summary(site_id, start_date, end_date)
# 2. 获取团购核销汇总
groupbuy_summary = self._extract_groupbuy_summary(site_id, start_date, end_date)
# 3. 获取充值汇总
recharge_summary = self._extract_recharge_summary(site_id, start_date, end_date)
# 4. 获取支出汇总（来自导入表）
expense_summary = self._extract_expense_summary(site_id, start_date, end_date)
# 5. 获取平台回款汇总（来自导入表）
platform_summary = self._extract_platform_summary(site_id, start_date, end_date)
# 6. 获取大客户优惠明细（用于拆分手动优惠）
big_customer_summary = self._extract_big_customer_discounts(site_id, start_date, end_date)
return {
'settlement_summary': settlement_summary,
'groupbuy_summary': groupbuy_summary,
'recharge_summary': recharge_summary,
'expense_summary': expense_summary,
'platform_summary': platform_summary,
'big_customer_summary': big_customer_summary,
'start_date': start_date,
'end_date': end_date,
'site_id': site_id
}
def transform(self, extracted: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据：按日期聚合
"""
settlement_summary = extracted['settlement_summary']
groupbuy_summary = extracted['groupbuy_summary']
recharge_summary = extracted['recharge_summary']
expense_summary = extracted['expense_summary']
platform_summary = extracted['platform_summary']
big_customer_summary = extracted['big_customer_summary']
site_id = extracted['site_id']
self.logger.info(
"%s: 转换数据，%d 天结账数据，%d 天充值数据",
self.get_task_code(), len(settlement_summary), len(recharge_summary)
)
# 按日期合并数据
dates = set()
for item in settlement_summary + recharge_summary + expense_summary + platform_summary:
stat_date = item.get('stat_date')
if stat_date:
dates.add(stat_date)
# 构建索引
settle_index = {s['stat_date']: s for s in settlement_summary}
groupbuy_index = {g['stat_date']: g for g in groupbuy_summary}
recharge_index = {r['stat_date']: r for r in recharge_summary}
expense_index = {e['stat_date']: e for e in expense_summary}
platform_index = {p['stat_date']: p for p in platform_summary}
big_customer_index = {b['stat_date']: b for b in big_customer_summary}
results = []
for stat_date in sorted(dates):
settle = settle_index.get(stat_date, {})
groupbuy = groupbuy_index.get(stat_date, {})
recharge = recharge_index.get(stat_date, {})
expense = expense_index.get(stat_date, {})
platform = platform_index.get(stat_date, {})
big_customer = big_customer_index.get(stat_date, {})
record = self._build_daily_record(
stat_date, settle, groupbuy, recharge, expense, platform, big_customer, site_id
)
results.append(record)
return results
def load(self, transformed: List[Dict[str, Any]], context: TaskContext) -> Dict:
"""
加载数据
"""
if not transformed:
self.logger.info("%s: 无数据需要写入", self.get_task_code())
return {"counts": {"fetched": 0, "inserted": 0, "updated": 0, "skipped": 0, "errors": 0}}
deleted = self.delete_existing_data(context, date_col="stat_date")
inserted = self.bulk_insert(transformed)
self.logger.info(
"%s: 加载完成，删除 %d 行，插入 %d 行",
self.get_task_code(), deleted, inserted
)
return {
"counts": {
"fetched": len(transformed),
"inserted": inserted,
"updated": 0,
"skipped": 0,
"errors": 0
},
"extra": {"deleted": deleted}
}
# ==========================================================================
# 数据提取方法
# ==========================================================================
def _extract_settlement_summary(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取结账单日汇总
"""
sql = """
SELECT
DATE(create_time) AS stat_date,
COUNT(*) AS order_count,
COUNT(CASE WHEN member_id != 0 AND member_id IS NOT NULL THEN 1 END) AS member_order_count,
COUNT(CASE WHEN member_id = 0 OR member_id IS NULL THEN 1 END) AS guest_order_count,
-- 发生额（正价）
SUM(table_charge_money) AS table_fee_amount,
SUM(goods_money) AS goods_amount,
SUM(assistant_pd_money) AS assistant_pd_amount,
SUM(assistant_cx_money) AS assistant_cx_amount,
SUM(table_charge_money + goods_money + assistant_pd_money + assistant_cx_money) AS gross_amount,
-- 支付
SUM(pay_amount) AS cash_pay_amount,
SUM(recharge_card_amount) AS card_pay_amount,
SUM(balance_amount) AS balance_pay_amount,
SUM(gift_card_amount) AS gift_card_pay_amount,
-- 优惠
SUM(coupon_amount) AS coupon_amount,
SUM(adjust_amount) AS adjust_amount,
SUM(member_discount_amount) AS member_discount_amount,
SUM(rounding_amount) AS rounding_amount,
SUM(pl_coupon_sale_amount) AS pl_coupon_sale_amount,
-- 消费金额
SUM(consume_money) AS total_consume
FROM billiards_dwd.dwd_settlement_head
WHERE site_id = %s
AND DATE(create_time) >= %s
AND DATE(create_time) <= %s
GROUP BY DATE(create_time)
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
def _extract_groupbuy_summary(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取团购核销日汇总
"""
sql = """
SELECT
DATE(redeem_time) AS stat_date,
COUNT(*) AS groupbuy_count,
SUM(ledger_unit_price) AS groupbuy_pay_total
FROM billiards_dwd.dwd_groupbuy_redemption
WHERE site_id = %s
AND DATE(redeem_time) >= %s
AND DATE(redeem_time) <= %s
GROUP BY DATE(redeem_time)
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
def _extract_recharge_summary(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取充值日汇总
"""
sql = """
SELECT
DATE(create_time) AS stat_date,
COUNT(*) AS recharge_count,
SUM(pay_money + gift_money) AS recharge_total,
SUM(pay_money) AS recharge_cash,
SUM(gift_money) AS recharge_gift,
COUNT(CASE WHEN is_first = 1 THEN 1 END) AS first_recharge_count,
SUM(CASE WHEN is_first = 1 THEN pay_money + gift_money ELSE 0 END) AS first_recharge_total,
SUM(CASE WHEN is_first = 1 THEN pay_money ELSE 0 END) AS first_recharge_cash,
SUM(CASE WHEN is_first = 1 THEN gift_money ELSE 0 END) AS first_recharge_gift,
COUNT(CASE WHEN is_first = 0 OR is_first IS NULL THEN 1 END) AS renewal_count,
SUM(CASE WHEN is_first = 0 OR is_first IS NULL THEN pay_money + gift_money ELSE 0 END) AS renewal_total,
SUM(CASE WHEN is_first = 0 OR is_first IS NULL THEN pay_money ELSE 0 END) AS renewal_cash,
SUM(CASE WHEN is_first = 0 OR is_first IS NULL THEN gift_money ELSE 0 END) AS renewal_gift,
COUNT(DISTINCT member_id) AS recharge_member_count
FROM billiards_dwd.dwd_recharge_order
WHERE site_id = %s
AND DATE(create_time) >= %s
AND DATE(create_time) <= %s
GROUP BY DATE(create_time)
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
def _extract_expense_summary(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取支出汇总（来自导入表，按月分摊到日）
"""
if start_date > end_date:
return []
start_month = start_date.replace(day=1)
end_month = end_date.replace(day=1)
sql = """
SELECT
expense_month,
SUM(expense_amount) AS expense_amount
FROM billiards_dws.dws_finance_expense_summary
WHERE site_id = %s
AND expense_month >= %s
AND expense_month <= %s
GROUP BY expense_month
"""
rows = self.db.query(sql, (site_id, start_month, end_month))
if not rows:
return []
daily_totals: Dict[date, Decimal] = {}
for row in rows:
row_dict = dict(row)
month_date = row_dict.get('expense_month')
if not month_date:
continue
amount = self.safe_decimal(row_dict.get('expense_amount', 0))
days_in_month = calendar.monthrange(month_date.year, month_date.month)[1]
daily_amount = amount / Decimal(str(days_in_month)) if days_in_month > 0 else Decimal('0')
for day in range(1, days_in_month + 1):
stat_date = date(month_date.year, month_date.month, day)
if stat_date < start_date or stat_date > end_date:
continue
daily_totals[stat_date] = daily_totals.get(stat_date, Decimal('0')) + daily_amount
return [
{'stat_date': stat_date, 'expense_amount': amount}
for stat_date, amount in sorted(daily_totals.items())
]
def _extract_platform_summary(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取平台回款/服务费汇总（来自导入表）
"""
sql = """
SELECT
settlement_date AS stat_date,
SUM(settlement_amount) AS settlement_amount,
SUM(commission_amount) AS commission_amount,
SUM(service_fee) AS service_fee
FROM billiards_dws.dws_platform_settlement
WHERE site_id = %s
AND settlement_date >= %s
AND settlement_date <= %s
GROUP BY settlement_date
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
return [dict(row) for row in rows] if rows else []
def _extract_big_customer_discounts(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取大客户优惠（用于拆分手动调整）
"""
member_ids = self._parse_id_list(self.config.get("dws.discount.big_customer_member_ids"))
order_ids = self._parse_id_list(self.config.get("dws.discount.big_customer_order_ids"))
if not member_ids and not order_ids:
return []
sql = """
SELECT
pay_time::DATE AS stat_date,
order_settle_id,
member_id,
adjust_amount
FROM billiards_dwd.dwd_settlement_head
WHERE site_id = %s
AND pay_time >= %s
AND pay_time < %s + INTERVAL '1 day'
AND adjust_amount != 0
"""
rows = self.db.query(sql, (site_id, start_date, end_date))
if not rows:
return []
result: Dict[date, Dict[str, Any]] = {}
for row in rows:
row_dict = dict(row)
stat_date = row_dict.get('stat_date')
if not stat_date:
continue
order_id = row_dict.get('order_settle_id')
member_id = row_dict.get('member_id')
if order_id not in order_ids and member_id not in member_ids:
continue
amount = abs(self.safe_decimal(row_dict.get('adjust_amount', 0)))
entry = result.setdefault(stat_date, {'stat_date': stat_date, 'big_customer_amount': Decimal('0'), 'big_customer_count': 0})
entry['big_customer_amount'] += amount
entry['big_customer_count'] += 1
return list(result.values())
def _parse_id_list(self, value: Any) -> set:
if not value:
return set()
if isinstance(value, str):
items = [v.strip() for v in value.split(",") if v.strip()]
return {int(v) for v in items if v.isdigit()}
if isinstance(value, (list, tuple, set)):
result = set()
for item in value:
if item is None:
continue
try:
result.add(int(item))
except (ValueError, TypeError):
continue
return result
return set()
# ==========================================================================
# 数据转换方法
# ==========================================================================
def _build_daily_record(
self,
stat_date: date,
settle: Dict[str, Any],
groupbuy: Dict[str, Any],
recharge: Dict[str, Any],
expense: Dict[str, Any],
platform: Dict[str, Any],
big_customer: Dict[str, Any],
site_id: int
) -> Dict[str, Any]:
"""
构建日度财务记录
"""
# 发生额
gross_amount = self.safe_decimal(settle.get('gross_amount', 0))
table_fee_amount = self.safe_decimal(settle.get('table_fee_amount', 0))
goods_amount = self.safe_decimal(settle.get('goods_amount', 0))
assistant_pd_amount = self.safe_decimal(settle.get('assistant_pd_amount', 0))
assistant_cx_amount = self.safe_decimal(settle.get('assistant_cx_amount', 0))
# 支付
cash_pay_amount = self.safe_decimal(settle.get('cash_pay_amount', 0))
card_pay_amount = self.safe_decimal(settle.get('card_pay_amount', 0))
balance_pay_amount = self.safe_decimal(settle.get('balance_pay_amount', 0))
gift_card_pay_amount = self.safe_decimal(settle.get('gift_card_pay_amount', 0))
# 优惠
coupon_amount = self.safe_decimal(settle.get('coupon_amount', 0))
pl_coupon_sale = self.safe_decimal(settle.get('pl_coupon_sale_amount', 0))
groupbuy_pay = self.safe_decimal(groupbuy.get('groupbuy_pay_total', 0))
# 团购支付金额：优先使用pl_coupon_sale_amount，否则使用groupbuy核销金额
if pl_coupon_sale > 0:
groupbuy_pay_amount = pl_coupon_sale
else:
groupbuy_pay_amount = groupbuy_pay
# 团购优惠 = 团购抵消台费 - 团购支付金额
discount_groupbuy = coupon_amount - groupbuy_pay_amount
if discount_groupbuy < 0:
discount_groupbuy = Decimal('0')
adjust_amount = self.safe_decimal(settle.get('adjust_amount', 0))
member_discount = self.safe_decimal(settle.get('member_discount_amount', 0))
rounding_amount = self.safe_decimal(settle.get('rounding_amount', 0))
big_customer_amount = self.safe_decimal(big_customer.get('big_customer_amount', 0))
other_discount = adjust_amount - big_customer_amount
if other_discount < 0:
other_discount = Decimal('0')
# 优惠合计
discount_total = discount_groupbuy + member_discount + gift_card_pay_amount + adjust_amount + rounding_amount
# 确认收入
confirmed_income = gross_amount - discount_total
# 现金流
platform_settlement_amount = self.safe_decimal(platform.get('settlement_amount', 0))
platform_fee_amount = (
self.safe_decimal(platform.get('commission_amount', 0))
+ self.safe_decimal(platform.get('service_fee', 0))
)
recharge_cash_inflow = self.safe_decimal(recharge.get('recharge_cash', 0))
platform_inflow = platform_settlement_amount if platform_settlement_amount > 0 else groupbuy_pay_amount
cash_inflow_total = cash_pay_amount + platform_inflow + recharge_cash_inflow
cash_outflow_total = self.safe_decimal(expense.get('expense_amount', 0)) + platform_fee_amount
cash_balance_change = cash_inflow_total - cash_outflow_total
# 卡消费
cash_card_consume = card_pay_amount + balance_pay_amount
gift_card_consume = gift_card_pay_amount
card_consume_total = cash_card_consume + gift_card_consume
# 充值统计
recharge_count = self.safe_int(recharge.get('recharge_count', 0))
recharge_total = self.safe_decimal(recharge.get('recharge_total', 0))
recharge_cash = self.safe_decimal(recharge.get('recharge_cash', 0))
recharge_gift = self.safe_decimal(recharge.get('recharge_gift', 0))
first_recharge_count = self.safe_int(recharge.get('first_recharge_count', 0))
first_recharge_amount = self.safe_decimal(recharge.get('first_recharge_total', 0))
renewal_count = self.safe_int(recharge.get('renewal_count', 0))
renewal_amount = self.safe_decimal(recharge.get('renewal_total', 0))
# 订单统计
order_count = self.safe_int(settle.get('order_count', 0))
member_order_count = self.safe_int(settle.get('member_order_count', 0))
guest_order_count = self.safe_int(settle.get('guest_order_count', 0))
avg_order_amount = gross_amount / order_count if order_count > 0 else Decimal('0')
return {
'site_id': site_id,
'tenant_id': self.config.get("app.tenant_id", site_id),
'stat_date': stat_date,
# 发生额
'gross_amount': gross_amount,
'table_fee_amount': table_fee_amount,
'goods_amount': goods_amount,
'assistant_pd_amount': assistant_pd_amount,
'assistant_cx_amount': assistant_cx_amount,
# 优惠
'discount_total': discount_total,
'discount_groupbuy': discount_groupbuy,
'discount_vip': member_discount,
'discount_gift_card': gift_card_pay_amount,
'discount_manual': adjust_amount,
'discount_rounding': rounding_amount,
'discount_other': other_discount,
# 确认收入
'confirmed_income': confirmed_income,
# 现金流
'cash_inflow_total': cash_inflow_total,
'cash_pay_amount': cash_pay_amount,
'groupbuy_pay_amount': groupbuy_pay_amount,
'platform_settlement_amount': platform_settlement_amount,
'platform_fee_amount': platform_fee_amount,
'recharge_cash_inflow': recharge_cash_inflow,
'card_consume_total': card_consume_total,
'cash_card_consume': cash_card_consume,
'gift_card_consume': gift_card_consume,
'cash_outflow_total': cash_outflow_total,
'cash_balance_change': cash_balance_change,
# 充值统计
'recharge_count': recharge_count,
'recharge_total': recharge_total,
'recharge_cash': recharge_cash,
'recharge_gift': recharge_gift,
'first_recharge_count': first_recharge_count,
'first_recharge_amount': first_recharge_amount,
'renewal_count': renewal_count,
'renewal_amount': renewal_amount,
# 订单统计
'order_count': order_count,
'member_order_count': member_order_count,
'guest_order_count': guest_order_count,
'avg_order_amount': avg_order_amount,
}
# 便于外部导入
__all__ = ['FinanceDailyTask']

410
etl_billiards/tasks/dws/finance_discount_task.py Normal file
View File

@@ -0,0 +1,410 @@
# -*- coding: utf-8 -*-
"""
优惠明细分析任务
功能说明：
以"日期+优惠类型"为粒度，分析优惠构成
数据来源：
- dwd_settlement_head: 结账单头表（优惠字段）
- dwd_groupbuy_redemption: 团购核销（团购实付金额）
- dwd_member_balance_change: 余额变动（赠送卡消费）
目标表：
billiards_dws.dws_finance_discount_detail
更新策略：
- 更新频率：每日更新
- 幂等方式：delete-before-insert（按日期）
业务规则：
- 团购优惠 (GROUPBUY): coupon_amount - 团购实付金额
- 会员折扣 (VIP): member_discount_amount
- 赠送卡抵扣 (GIFT_CARD): gift_card_amount
- 抹零 (ROUNDING): rounding_amount
- 大客户优惠 (BIG_CUSTOMER): 手动调整中标记的大客户订单
- 其他优惠 (OTHER): 手动调整中除大客户外的部分
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Tuple
from .base_dws_task import BaseDwsTask, TaskContext
class FinanceDiscountDetailTask(BaseDwsTask):
"""
优惠明细分析任务
分析各类优惠的使用情况：
- 团购优惠
- 会员折扣
- 赠送卡抵扣
- 手动调整
- 抹零
- 其他优惠
"""
def get_task_code(self) -> str:
return "DWS_FINANCE_DISCOUNT_DETAIL"
def get_target_table(self) -> str:
return "dws_finance_discount_detail"
def get_primary_keys(self) -> List[str]:
return ["site_id", "stat_date", "discount_type_code"]
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
抽取优惠相关数据
数据来源：
1. settlement_head: 各类优惠字段
2. groupbuy_redemption: 团购实付金额
"""
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
# 从settlement_head抽取优惠数据
discount_summary = self._extract_discount_summary(site_id, start_date, end_date)
# 从groupbuy_redemption获取团购实付金额
groupbuy_payments = self._extract_groupbuy_payments(site_id, start_date, end_date)
# 提取大客户优惠（拆分手动调整）
big_customer_summary = self._extract_big_customer_discounts(site_id, start_date, end_date)
return {
'discount_summary': discount_summary,
'groupbuy_payments': groupbuy_payments,
'big_customer_summary': big_customer_summary,
}
def _extract_discount_summary(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
从结账单头表抽取优惠汇总
字段说明：
- coupon_amount: 团购抵消台费金额
- adjust_amount: 手动调整金额（台费打折）
- member_discount_amount: 会员折扣
- rounding_amount: 抹零金额
- gift_card_amount: 赠送卡支付
- pl_coupon_sale_amount: 平台券销售金额（团购实付路径1）
"""
sql = """
SELECT
pay_time::DATE AS stat_date,
-- 团购相关
COALESCE(SUM(coupon_amount), 0) AS coupon_amount_total,
COALESCE(SUM(pl_coupon_sale_amount), 0) AS pl_coupon_sale_total,
COUNT(CASE WHEN coupon_amount > 0 THEN 1 END) AS coupon_order_count,
-- 手动调整
COALESCE(SUM(adjust_amount), 0) AS adjust_amount_total,
COUNT(CASE WHEN adjust_amount != 0 THEN 1 END) AS adjust_order_count,
-- 会员折扣
COALESCE(SUM(member_discount_amount), 0) AS member_discount_total,
COUNT(CASE WHEN member_discount_amount > 0 THEN 1 END) AS member_discount_order_count,
-- 抹零
COALESCE(SUM(rounding_amount), 0) AS rounding_amount_total,
COUNT(CASE WHEN rounding_amount != 0 THEN 1 END) AS rounding_order_count,
-- 赠送卡
COALESCE(SUM(gift_card_amount), 0) AS gift_card_amount_total,
COUNT(CASE WHEN gift_card_amount > 0 THEN 1 END) AS gift_card_order_count,
-- 总订单数
COUNT(*) AS total_orders
FROM billiards_dwd.dwd_settlement_head
WHERE site_id = %(site_id)s
AND pay_time >= %(start_date)s
AND pay_time < %(end_date)s + INTERVAL '1 day'
AND settle_status = 1 -- 已结账
GROUP BY pay_time::DATE
ORDER BY stat_date
"""
rows = self.db.query(sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
return [dict(row) for row in rows] if rows else []
def _extract_groupbuy_payments(
self,
site_id: int,
start_date: date,
end_date: date
) -> Dict[date, Decimal]:
"""
从团购核销表获取团购实付金额
团购实付金额计算：
- 若 pl_coupon_sale_amount > 0，使用该值
- 否则使用 groupbuy_redemption.ledger_unit_price
返回：{日期: 团购实付总额}
"""
sql = """
SELECT
sh.pay_time::DATE AS stat_date,
SUM(
CASE
WHEN sh.pl_coupon_sale_amount > 0 THEN sh.pl_coupon_sale_amount
ELSE COALESCE(gr.ledger_unit_price, 0)
END
) AS groupbuy_payment
FROM billiards_dwd.dwd_settlement_head sh
LEFT JOIN billiards_dwd.dwd_groupbuy_redemption gr
ON gr.order_settle_id = sh.order_settle_id
WHERE sh.site_id = %(site_id)s
AND sh.pay_time >= %(start_date)s
AND sh.pay_time < %(end_date)s + INTERVAL '1 day'
AND sh.settle_status = 1
AND sh.coupon_amount > 0 -- 只统计有团购的订单
GROUP BY sh.pay_time::DATE
"""
rows = self.db.query(sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
result = {}
if rows:
for row in rows:
result[row['stat_date']] = self.safe_decimal(row.get('groupbuy_payment', 0))
return result
def transform(self, data: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据
将抽取的数据转换为目标表格式：
- 每种优惠类型一条记录
- 计算团购优惠（coupon_amount - 团购实付）
- 计算优惠占比
"""
site_id = context.store_id
tenant_id = self.config.get("app.tenant_id", site_id)
discount_summary = data.get('discount_summary', [])
groupbuy_payments = data.get('groupbuy_payments', {})
big_customer_summary = {r['stat_date']: r for r in data.get('big_customer_summary', [])}
records = []
# 优惠类型定义
# (type_code, type_name, amount_field, count_field, special_calc)
discount_types = [
('GROUPBUY', '团购优惠', 'coupon_amount_total', 'coupon_order_count', True),
('VIP', '会员折扣', 'member_discount_total', 'member_discount_order_count', False),
('ROUNDING', '抹零', 'rounding_amount_total', 'rounding_order_count', False),
('GIFT_CARD', '赠送卡抵扣', 'gift_card_amount_total', 'gift_card_order_count', False),
]
for daily_data in discount_summary:
stat_date = daily_data.get('stat_date')
# 计算各类优惠金额
daily_discounts = {}
total_discount = Decimal('0')
for type_code, type_name, amount_field, count_field, special_calc in discount_types:
if special_calc and type_code == 'GROUPBUY':
# 团购优惠 = 团购抵消台费 - 团购实付
coupon_amount = self.safe_decimal(daily_data.get(amount_field, 0))
groupbuy_paid = groupbuy_payments.get(stat_date, Decimal('0'))
discount_amount = coupon_amount - groupbuy_paid
# 确保优惠金额为正数
discount_amount = max(discount_amount, Decimal('0'))
else:
discount_amount = abs(self.safe_decimal(daily_data.get(amount_field, 0)))
usage_count = daily_data.get(count_field, 0) or 0
daily_discounts[type_code] = {
'type_name': type_name,
'amount': discount_amount,
'count': usage_count,
}
total_discount += discount_amount
# 拆分手动调整为大客户/其他
adjust_amount = abs(self.safe_decimal(daily_data.get('adjust_amount_total', 0)))
adjust_count = daily_data.get('adjust_order_count', 0) or 0
big_customer_info = big_customer_summary.get(stat_date, {})
big_customer_amount = self.safe_decimal(big_customer_info.get('big_customer_amount', 0))
big_customer_count = big_customer_info.get('big_customer_count', 0) or 0
other_amount = adjust_amount - big_customer_amount
if other_amount < 0:
other_amount = Decimal('0')
other_count = adjust_count - big_customer_count
if other_count < 0:
other_count = 0
daily_discounts['BIG_CUSTOMER'] = {
'type_name': '大客户优惠',
'amount': big_customer_amount,
'count': big_customer_count,
}
daily_discounts['OTHER'] = {
'type_name': '其他优惠',
'amount': other_amount,
'count': other_count,
}
total_discount += big_customer_amount + other_amount
# 为每种优惠类型生成记录
for type_code, discount_info in daily_discounts.items():
discount_amount = discount_info['amount']
usage_count = discount_info['count']
# 计算占比（避免除零）
discount_ratio = (discount_amount / total_discount) if total_discount > 0 else Decimal('0')
records.append({
'site_id': site_id,
'tenant_id': tenant_id,
'stat_date': stat_date,
'discount_type_code': type_code,
'discount_type_name': discount_info['type_name'],
'discount_amount': discount_amount,
'discount_ratio': round(discount_ratio, 4),
'usage_count': usage_count,
'affected_orders': usage_count, # 简化：使用次数=影响订单数
})
return records
def _extract_big_customer_discounts(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
提取大客户优惠（基于手动调整）
"""
member_ids = self._parse_id_list(self.config.get("dws.discount.big_customer_member_ids"))
order_ids = self._parse_id_list(self.config.get("dws.discount.big_customer_order_ids"))
if not member_ids and not order_ids:
return []
sql = """
SELECT
pay_time::DATE AS stat_date,
order_settle_id,
member_id,
adjust_amount
FROM billiards_dwd.dwd_settlement_head
WHERE site_id = %(site_id)s
AND pay_time >= %(start_date)s
AND pay_time < %(end_date)s + INTERVAL '1 day'
AND adjust_amount != 0
"""
rows = self.db.query(sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
if not rows:
return []
result: Dict[date, Dict[str, Any]] = {}
for row in rows:
row_dict = dict(row)
stat_date = row_dict.get('stat_date')
if not stat_date:
continue
order_id = row_dict.get('order_settle_id')
member_id = row_dict.get('member_id')
if order_id not in order_ids and member_id not in member_ids:
continue
amount = abs(self.safe_decimal(row_dict.get('adjust_amount', 0)))
entry = result.setdefault(stat_date, {'stat_date': stat_date, 'big_customer_amount': Decimal('0'), 'big_customer_count': 0})
entry['big_customer_amount'] += amount
entry['big_customer_count'] += 1
return list(result.values())
def _parse_id_list(self, value: Any) -> set:
if not value:
return set()
if isinstance(value, str):
items = [v.strip() for v in value.split(",") if v.strip()]
return {int(v) for v in items if v.isdigit()}
if isinstance(value, (list, tuple, set)):
result = set()
for item in value:
if item is None:
continue
try:
result.add(int(item))
except (ValueError, TypeError):
continue
return result
return set()
def load(self, records: List[Dict[str, Any]], context: TaskContext) -> Dict[str, Any]:
"""
加载数据到目标表
使用幂等方式：delete-before-insert（按日期范围）
"""
if not records:
return {'inserted': 0, 'deleted': 0}
site_id = context.store_id
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
# 删除窗口内的旧数据
delete_sql = """
DELETE FROM billiards_dws.dws_finance_discount_detail
WHERE site_id = %(site_id)s
AND stat_date >= %(start_date)s
AND stat_date <= %(end_date)s
"""
deleted = self.db.execute(delete_sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
# 批量插入新数据
insert_sql = """
INSERT INTO billiards_dws.dws_finance_discount_detail (
site_id, tenant_id, stat_date,
discount_type_code, discount_type_name,
discount_amount, discount_ratio,
usage_count, affected_orders,
created_at, updated_at
) VALUES (
%(site_id)s, %(tenant_id)s, %(stat_date)s,
%(discount_type_code)s, %(discount_type_name)s,
%(discount_amount)s, %(discount_ratio)s,
%(usage_count)s, %(affected_orders)s,
NOW(), NOW()
)
"""
inserted = 0
for record in records:
self.db.execute(insert_sql, record)
inserted += 1
return {
'deleted': deleted or 0,
'inserted': inserted,
}

437
etl_billiards/tasks/dws/finance_income_task.py Normal file
View File

@@ -0,0 +1,437 @@
# -*- coding: utf-8 -*-
"""
收入结构分析任务
功能说明：
以"日期+区域/类型"为粒度，分析收入结构
数据来源：
- dwd_settlement_head: 结账单头表（台费、商品、助教正价）
- dwd_table_fee_log: 台费流水（区域关联）
- dwd_assistant_service_log: 助教服务流水（区域关联）
- cfg_area_category: 区域分类映射
目标表：
billiards_dws.dws_finance_income_structure
更新策略：
- 更新频率：每日更新
- 幂等方式：delete-before-insert（按日期+类型）
业务规则：
- 结构类型1（INCOME_TYPE）：按收入类型分析（台费/商品/助教基础课/助教附加课）
- 结构类型2（AREA）：按区域分析（普通台球区/VIP包厢/斯诺克/麻将/KTV等）
- 区域映射使用cfg_area_category配置
作者：ETL团队
创建日期：2026-02-01
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from decimal import Decimal
from typing import Any, Dict, List, Optional, Tuple
from .base_dws_task import BaseDwsTask, TaskContext
class FinanceIncomeStructureTask(BaseDwsTask):
"""
收入结构分析任务
分析收入的两种维度：
1. INCOME_TYPE: 按收入类型（台费/商品/助教基础课/助教附加课）
2. AREA: 按区域（使用cfg_area_category映射）
"""
def get_task_code(self) -> str:
return "DWS_FINANCE_INCOME_STRUCTURE"
def get_target_table(self) -> str:
return "dws_finance_income_structure"
def get_primary_keys(self) -> List[str]:
return ["site_id", "stat_date", "structure_type", "category_code"]
def extract(self, context: TaskContext) -> Dict[str, Any]:
"""
抽取数据
分两条路径抽取：
1. 按收入类型汇总（来自settlement_head）
2. 按区域汇总（来自table_fee_log和assistant_service_log）
"""
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
site_id = context.store_id
# 按收入类型汇总
income_by_type = self._extract_income_by_type(site_id, start_date, end_date)
# 按区域汇总
income_by_area = self._extract_income_by_area(site_id, start_date, end_date)
return {
'income_by_type': income_by_type,
'income_by_area': income_by_area,
}
def _extract_income_by_type(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
按收入类型汇总
收入类型分类：
- TABLE_FEE: 台费收入 (table_charge_money)
- GOODS: 商品收入 (goods_money)
- ASSISTANT_BASE: 助教基础课 (assistant_pd_money)
- ASSISTANT_BONUS: 助教附加课 (assistant_cx_money)
"""
sql = """
SELECT
pay_time::DATE AS stat_date,
-- 台费收入
COALESCE(SUM(table_charge_money), 0) AS table_fee_income,
COUNT(CASE WHEN table_charge_money > 0 THEN 1 END) AS table_fee_orders,
-- 商品收入
COALESCE(SUM(goods_money), 0) AS goods_income,
COUNT(CASE WHEN goods_money > 0 THEN 1 END) AS goods_orders,
-- 助教基础课收入（PD=陪打）
COALESCE(SUM(assistant_pd_money), 0) AS assistant_base_income,
COUNT(CASE WHEN assistant_pd_money > 0 THEN 1 END) AS assistant_base_orders,
-- 助教附加课收入（CX=超休/促销）
COALESCE(SUM(assistant_cx_money), 0) AS assistant_bonus_income,
COUNT(CASE WHEN assistant_cx_money > 0 THEN 1 END) AS assistant_bonus_orders,
-- 总订单数
COUNT(*) AS total_orders
FROM billiards_dwd.dwd_settlement_head
WHERE site_id = %(site_id)s
AND pay_time >= %(start_date)s
AND pay_time < %(end_date)s + INTERVAL '1 day'
AND settle_status = 1 -- 已结账
GROUP BY pay_time::DATE
ORDER BY stat_date
"""
rows = self.db.query(sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
return [dict(row) for row in rows] if rows else []
def _extract_income_by_area(
self,
site_id: int,
start_date: date,
end_date: date
) -> List[Dict[str, Any]]:
"""
按区域汇总收入
关联dim_table获取区域名称，再映射到cfg_area_category
"""
sql = """
WITH
-- 台费按区域汇总
table_fee_by_area AS (
SELECT
tfl.pay_time::DATE AS stat_date,
dt.site_table_area_name AS area_name,
COALESCE(SUM(tfl.ledger_amount), 0) AS income_amount,
COALESCE(SUM(tfl.ledger_time_seconds), 0) AS duration_seconds,
COUNT(DISTINCT tfl.order_settle_id) AS order_count
FROM billiards_dwd.dwd_table_fee_log tfl
LEFT JOIN billiards_dwd.dim_table dt
ON dt.site_table_id = tfl.site_table_id
WHERE tfl.site_id = %(site_id)s
AND tfl.pay_time >= %(start_date)s
AND tfl.pay_time < %(end_date)s + INTERVAL '1 day'
GROUP BY tfl.pay_time::DATE, dt.site_table_area_name
),
-- 助教服务按区域汇总
assistant_by_area AS (
SELECT
asl.start_use_time::DATE AS stat_date,
dt.site_table_area_name AS area_name,
COALESCE(SUM(asl.ledger_amount), 0) AS income_amount,
COALESCE(SUM(asl.income_seconds), 0) AS duration_seconds,
COUNT(DISTINCT asl.order_settle_id) AS order_count
FROM billiards_dwd.dwd_assistant_service_log asl
LEFT JOIN billiards_dwd.dim_table dt
ON dt.site_table_id = asl.site_table_id
WHERE asl.site_id = %(site_id)s
AND asl.start_use_time >= %(start_date)s
AND asl.start_use_time < %(end_date)s + INTERVAL '1 day'
GROUP BY asl.start_use_time::DATE, dt.site_table_area_name
)
-- 合并台费和助教服务
SELECT
COALESCE(t.stat_date, a.stat_date) AS stat_date,
COALESCE(t.area_name, a.area_name) AS area_name,
COALESCE(t.income_amount, 0) + COALESCE(a.income_amount, 0) AS income_amount,
COALESCE(t.duration_seconds, 0) + COALESCE(a.duration_seconds, 0) AS duration_seconds,
GREATEST(COALESCE(t.order_count, 0), COALESCE(a.order_count, 0)) AS order_count
FROM table_fee_by_area t
FULL OUTER JOIN assistant_by_area a
ON t.stat_date = a.stat_date AND t.area_name = a.area_name
ORDER BY stat_date, area_name
"""
rows = self.db.query(sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
return [dict(row) for row in rows] if rows else []
def transform(self, data: Dict[str, Any], context: TaskContext) -> List[Dict[str, Any]]:
"""
转换数据
将抽取的数据转换为目标表格式：
1. 按收入类型展开（每种类型一条记录）
2. 按区域展开（每个区域一条记录）
3. 计算占比
"""
site_id = context.store_id
tenant_id = self.config.get("app.tenant_id", site_id)
records = []
# 处理按收入类型的数据
income_type_records = self._transform_income_by_type(
data.get('income_by_type', []),
site_id,
tenant_id
)
records.extend(income_type_records)
# 处理按区域的数据
area_records = self._transform_income_by_area(
data.get('income_by_area', []),
site_id,
tenant_id
)
records.extend(area_records)
return records
def _transform_income_by_type(
self,
income_data: List[Dict[str, Any]],
site_id: int,
tenant_id: int
) -> List[Dict[str, Any]]:
"""
转换按收入类型的数据
将每日汇总数据展开为4条记录（台费/商品/基础课/附加课）
"""
# 收入类型定义
income_types = [
('TABLE_FEE', '台费收入', 'table_fee_income', 'table_fee_orders'),
('GOODS', '商品收入', 'goods_income', 'goods_orders'),
('ASSISTANT_BASE', '助教基础课', 'assistant_base_income', 'assistant_base_orders'),
('ASSISTANT_BONUS', '助教附加课', 'assistant_bonus_income', 'assistant_bonus_orders'),
]
records = []
for daily_data in income_data:
stat_date = daily_data.get('stat_date')
# 计算当日总收入（用于计算占比）
total_income = sum(
self.safe_decimal(daily_data.get(field, 0))
for _, _, field, _ in income_types
)
# 为每种收入类型生成一条记录
for type_code, type_name, income_field, order_field in income_types:
income_amount = self.safe_decimal(daily_data.get(income_field, 0))
order_count = daily_data.get(order_field, 0) or 0
# 计算占比（避免除零）
income_ratio = (income_amount / total_income) if total_income > 0 else Decimal('0')
records.append({
'site_id': site_id,
'tenant_id': tenant_id,
'stat_date': stat_date,
'structure_type': 'INCOME_TYPE',
'category_code': type_code,
'category_name': type_name,
'income_amount': income_amount,
'income_ratio': round(income_ratio, 4),
'order_count': order_count,
'duration_minutes': 0, # 收入类型维度不统计时长
})
return records
def _transform_income_by_area(
self,
area_data: List[Dict[str, Any]],
site_id: int,
tenant_id: int
) -> List[Dict[str, Any]]:
"""
转换按区域的数据
将区域名称映射到cfg_area_category的category_code
"""
records = []
# 加载区域分类配置
area_categories = self._get_config_cache().get('area_categories', {})
# 按日期分组计算总收入（用于计算占比）
daily_totals = {}
for row in area_data:
stat_date = row.get('stat_date')
income = self.safe_decimal(row.get('income_amount', 0))
daily_totals[stat_date] = daily_totals.get(stat_date, Decimal('0')) + income
# 按日期+区域聚合（相同category_code需要合并）
aggregated = {}
for row in area_data:
stat_date = row.get('stat_date')
area_name = row.get('area_name') or '未知区域'
income_amount = self.safe_decimal(row.get('income_amount', 0))
duration_seconds = row.get('duration_seconds', 0) or 0
order_count = row.get('order_count', 0) or 0
# 映射区域名称到分类代码
category = self._map_area_to_category(area_name, area_categories)
category_code = category.get('category_code', 'OTHER')
category_name = category.get('category_name', '其他区域')
# 聚合键
key = (stat_date, category_code)
if key not in aggregated:
aggregated[key] = {
'stat_date': stat_date,
'category_code': category_code,
'category_name': category_name,
'income_amount': Decimal('0'),
'duration_seconds': 0,
'order_count': 0,
}
aggregated[key]['income_amount'] += income_amount
aggregated[key]['duration_seconds'] += duration_seconds
aggregated[key]['order_count'] += order_count
# 生成记录
for key, agg_data in aggregated.items():
stat_date = agg_data['stat_date']
total_income = daily_totals.get(stat_date, Decimal('1'))
income_amount = agg_data['income_amount']
# 计算占比
income_ratio = (income_amount / total_income) if total_income > 0 else Decimal('0')
records.append({
'site_id': site_id,
'tenant_id': tenant_id,
'stat_date': stat_date,
'structure_type': 'AREA',
'category_code': agg_data['category_code'],
'category_name': agg_data['category_name'],
'income_amount': income_amount,
'income_ratio': round(income_ratio, 4),
'order_count': agg_data['order_count'],
'duration_minutes': agg_data['duration_seconds'] // 60,
})
return records
def _map_area_to_category(
self,
area_name: str,
area_categories: Dict[str, Dict[str, Any]]
) -> Dict[str, Any]:
"""
将区域名称映射到分类
匹配规则：
1. 精确匹配 match_pattern
2. 模糊匹配（LIKE）
3. 默认返回 OTHER
"""
if not area_name:
return {'category_code': 'OTHER', 'category_name': '其他区域'}
# 遍历配置查找匹配
for pattern, category in area_categories.items():
match_type = category.get('match_type', 'exact')
if match_type == 'exact':
if area_name == pattern:
return category
elif match_type == 'like':
# 简单的模糊匹配（包含关系）
if pattern.replace('%', '') in area_name:
return category
# 默认分类
return {'category_code': 'OTHER', 'category_name': '其他区域'}
def load(self, records: List[Dict[str, Any]], context: TaskContext) -> Dict[str, Any]:
"""
加载数据到目标表
使用幂等方式：delete-before-insert（按日期范围）
"""
if not records:
return {'inserted': 0, 'deleted': 0}
site_id = context.store_id
start_date = context.window_start.date() if hasattr(context.window_start, 'date') else context.window_start
end_date = context.window_end.date() if hasattr(context.window_end, 'date') else context.window_end
# 删除窗口内的旧数据
delete_sql = """
DELETE FROM billiards_dws.dws_finance_income_structure
WHERE site_id = %(site_id)s
AND stat_date >= %(start_date)s
AND stat_date <= %(end_date)s
"""
deleted = self.db.execute(delete_sql, {
'site_id': site_id,
'start_date': start_date,
'end_date': end_date,
})
# 批量插入新数据
insert_sql = """
INSERT INTO billiards_dws.dws_finance_income_structure (
site_id, tenant_id, stat_date,
structure_type, category_code, category_name,
income_amount, income_ratio,
order_count, duration_minutes,
created_at, updated_at
) VALUES (
%(site_id)s, %(tenant_id)s, %(stat_date)s,
%(structure_type)s, %(category_code)s, %(category_name)s,
%(income_amount)s, %(income_ratio)s,
%(order_count)s, %(duration_minutes)s,
NOW(), NOW()
)
"""
inserted = 0
for record in records:
self.db.execute(insert_sql, record)
inserted += 1
return {
'deleted': deleted or 0,
'inserted': inserted,
}

Some files were not shown because too many files have changed in this diff Show More