1123 lines
47 KiB
Markdown
1123 lines
47 KiB
Markdown
# DWS 数据层实施任务计划 v1.0
|
||
|
||
> **版本**: 1.0
|
||
> **创建日期**: 2026-02-01
|
||
> **项目路径**: `C:\dev\LLTQ\ETL\feiqiu-ETL`
|
||
> **目标**: 在已完成的 DWD 层数据基础上，完成 DWS（数据汇总层）的数据库设计与 ETL 实现
|
||
|
||
---
|
||
|
||
## 一、项目背景与现状分析
|
||
|
||
### 1.1 已有基础设施
|
||
|
||
| 层级 | 状态 | Schema | 说明 |
|
||
|------|------|--------|------|
|
||
| ODS（操作数据层） | ✅ 完成 | `billiards_ods` | 原始数据落地，20+ 张表 |
|
||
| DWD（明细数据层） | ✅ 完成 | `billiards_dwd` | 维度表 9 张 + 事实表 12 张 |
|
||
| DWS（汇总数据层） | 🔄 部分完成 | `billiards_dws` | 仅有 `dws_order_summary` 1 张 |
|
||
|
||
### 1.2 现有代码架构
|
||
|
||
```
|
||
etl_billiards/
|
||
├── tasks/
|
||
│ ├── base_task.py # BaseTask 基类（E/T/L 模板方法）
|
||
│ ├── init_dws_schema_task.py # DWS Schema 初始化任务
|
||
│ └── dws_build_order_summary_task.py # 订单汇总表构建任务
|
||
├── database/
|
||
│ └── schema_dws.sql # DWS DDL（当前仅 dws_order_summary）
|
||
├── scripts/
|
||
│ └── build_dws_order_summary.py # 订单汇总构建脚本
|
||
└── docs/
|
||
├── dwd_main_tables_dictionary.md # DWD 数据字典
|
||
└── 财务页面需求.md # 财务需求原型
|
||
```
|
||
|
||
### 1.3 核心 DWD 表依赖关系
|
||
|
||
**维度表**:
|
||
- `dim_assistant`: 助教维度（level 字段标识等级：初级/中级/高级/星级）
|
||
- `dim_member`: 会员维度
|
||
- `dim_table`: 台桌维度
|
||
- `dim_site`: 门店维度
|
||
|
||
**事实表**:
|
||
- `dwd_assistant_service_log`: 助教服务记录（核心：基础课+附加课统计）
|
||
- `dwd_assistant_trash_event`: 助教废除记录（影响业绩有效性）
|
||
- `dwd_settlement_head`: 结算单头表
|
||
- `dwd_table_fee_log`: 台费流水
|
||
- `dwd_store_goods_sale`: 商品销售
|
||
- `dwd_recharge_order`: 充值订单
|
||
- `dwd_member_balance_change`: 会员余额变动
|
||
- `dwd_payment`: 支付记录
|
||
- `dwd_refund`: 退款记录
|
||
|
||
---
|
||
|
||
## 二、需求分析与表设计
|
||
|
||
### 2.1 数据分层策略（时间分区）
|
||
|
||
根据需求，将数据按更新时间分为 4 层以优化查询效率：
|
||
|
||
| 分层 | 时间范围 | 用途 | 实现方式 |
|
||
|------|----------|------|----------|
|
||
| L1（热数据） | 最近 2 天 | 实时监控/当日报表 | 物化视图 + 定时刷新 |
|
||
| L2（近期数据） | 最近 1 个月 | 周报/月报 | 分区表 |
|
||
| L3（中期数据） | 最近 3 个月 | 季度分析 | 分区表 |
|
||
| L4（全量数据） | 历史全部 | 年度汇总/深度分析 | 原始表 |
|
||
|
||
**实现机制**:
|
||
1. 使用 PostgreSQL 表分区（Range Partition by 月份）
|
||
2. 通过视图自动路由到对应时间层
|
||
3. 配套清理任务定期归档/删除过期数据
|
||
|
||
### 2.2 DWS 表清单（完整设计）
|
||
|
||
#### 2.2.1 配置表（系统设置）
|
||
|
||
| 表名 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `cfg_performance_tier` | 配置 | 助教绩效档位配置（6档：0-5档） |
|
||
| `cfg_assistant_level_price` | 配置 | 助教等级定价（初级/中级/高级/星级） |
|
||
| `cfg_bonus_rules` | 配置 | 奖金规则配置（冲刺奖/Top3奖） |
|
||
| `cfg_tier_effective_period` | 配置 | 档位配置生效时间范围 |
|
||
|
||
#### 2.2.2 助教维度汇总表
|
||
|
||
| 表名 | 类型 | 主要维度 | 说明 |
|
||
|------|------|----------|------|
|
||
| `dws_assistant_monthly_summary` | 汇总 | 助教×月份 | 月度业绩汇总（课时/收入/档位） |
|
||
| `dws_assistant_daily_detail` | 明细 | 助教×日期 | 日度业绩明细（便于月中进度追踪） |
|
||
| `dws_assistant_customer_stats` | 汇总 | 助教×时间窗口 | 服务客户统计（7/10/15/30/60/90天） |
|
||
| `dws_assistant_salary_calc` | 计算 | 助教×月份 | 月度工资计算结果 |
|
||
|
||
#### 2.2.3 客户维度汇总表
|
||
|
||
| 表名 | 类型 | 主要维度 | 说明 |
|
||
|------|------|----------|------|
|
||
| `dws_member_consumption_summary` | 汇总 | 会员×时间窗口 | 消费情况统计（7/10/15/30/60/90天） |
|
||
| `dws_member_visit_detail` | 明细 | 会员×订单 | 来店消费明细（含服务详情） |
|
||
|
||
#### 2.2.4 财务维度汇总表
|
||
|
||
| 表名 | 类型 | 主要维度 | 说明 |
|
||
|------|------|----------|------|
|
||
| `dws_finance_daily_summary` | 汇总 | 门店×日期 | 日度财务汇总 |
|
||
| `dws_finance_income_structure` | 汇总 | 门店×日期×区域 | 收入结构（按区域/类型） |
|
||
| `dws_finance_discount_detail` | 明细 | 门店×日期 | 优惠明细（团购/大客户/赠送卡等） |
|
||
| `dws_finance_recharge_summary` | 汇总 | 门店×日期 | 充值与预收汇总 |
|
||
| `dws_finance_expense_summary` | 汇总 | 门店×日期 | 支出结构汇总 |
|
||
| `dws_assistant_finance_analysis` | 汇总 | 门店×日期×等级 | 助教收支分析 |
|
||
|
||
#### 2.2.5 现有表保留
|
||
|
||
| 表名 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| `dws_order_summary` | ✅ 保留 | 订单级汇总（已实现） |
|
||
|
||
---
|
||
|
||
## 三、表结构详细设计
|
||
|
||
### 3.1 配置表 DDL
|
||
|
||
#### 3.1.1 `cfg_performance_tier` - 绩效档位配置
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: cfg_performance_tier
|
||
-- 用途: 助教绩效档位配置表，定义6个档位的阈值与分成规则
|
||
-- 业务规则:
|
||
-- - 过档后，所有时长按新档位进行计算
|
||
-- - 总业绩小时数 = 基础课 + 附加课
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.cfg_performance_tier (
|
||
tier_id SERIAL PRIMARY KEY, -- 档位主键
|
||
tier_code INTEGER NOT NULL UNIQUE, -- 档位代码：0-5
|
||
tier_name VARCHAR(50) NOT NULL, -- 档位名称
|
||
tier_reason VARCHAR(100), -- 档位设计原因
|
||
min_hours NUMERIC(10,2) NOT NULL, -- 最小小时数阈值（含）
|
||
max_hours NUMERIC(10,2), -- 最大小时数阈值（不含），NULL表示无上限
|
||
base_deduction NUMERIC(10,2) NOT NULL, -- 基础课抽成（元/小时）
|
||
bonus_ratio NUMERIC(5,4) NOT NULL, -- 附加课/打赏课抽成比例（如0.50表示50%）
|
||
vacation_days INTEGER, -- 次月休假天数，NULL表示休假自由
|
||
effective_from DATE NOT NULL DEFAULT '2026-01-01', -- 生效开始日期
|
||
effective_to DATE DEFAULT '9999-12-31', -- 生效结束日期
|
||
is_active BOOLEAN DEFAULT TRUE, -- 是否启用
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now()
|
||
);
|
||
|
||
-- 初始化默认档位配置（2026年标准）
|
||
COMMENT ON TABLE billiards_dws.cfg_performance_tier IS '助教绩效档位配置表：定义各档位的业绩阈值与分成规则';
|
||
COMMENT ON COLUMN billiards_dws.cfg_performance_tier.tier_code IS '档位代码：0=淘汰压力，1=及格档，2=良好档，3=优秀档，4=卓越加速档，5=冠军加速档';
|
||
COMMENT ON COLUMN billiards_dws.cfg_performance_tier.base_deduction IS '基础课球房抽成金额（元/小时），助教实得=客户单价-此值';
|
||
COMMENT ON COLUMN billiards_dws.cfg_performance_tier.bonus_ratio IS '附加课/打赏课球房抽成比例，助教实得=收费*(1-此值)';
|
||
```
|
||
|
||
#### 3.1.2 `cfg_assistant_level_price` - 助教等级定价
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: cfg_assistant_level_price
|
||
-- 用途: 助教等级对应的客户收费标准
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.cfg_assistant_level_price (
|
||
price_id SERIAL PRIMARY KEY,
|
||
level_code INTEGER NOT NULL, -- 等级代码（对应dim_assistant.level）
|
||
level_name VARCHAR(20) NOT NULL, -- 等级名称：初级/中级/高级/星级
|
||
base_price NUMERIC(10,2) NOT NULL, -- 基础课客户收费（元/小时）
|
||
bonus_price NUMERIC(10,2) NOT NULL DEFAULT 190, -- 附加课客户收费（元/小时），统一190
|
||
effective_from DATE NOT NULL DEFAULT '2026-01-01',
|
||
effective_to DATE DEFAULT '9999-12-31',
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
UNIQUE(level_code, effective_from)
|
||
);
|
||
|
||
COMMENT ON TABLE billiards_dws.cfg_assistant_level_price IS '助教等级定价表：定义各等级对客户的收费标准';
|
||
COMMENT ON COLUMN billiards_dws.cfg_assistant_level_price.level_code IS '等级代码：1=初级，2=中级，3=高级，4=星级，8=助教管理';
|
||
```
|
||
|
||
#### 3.1.3 `cfg_bonus_rules` - 奖金规则配置
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: cfg_bonus_rules
|
||
-- 用途: 冲刺奖、Top3奖等额外奖金规则配置
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.cfg_bonus_rules (
|
||
rule_id SERIAL PRIMARY KEY,
|
||
rule_type VARCHAR(20) NOT NULL, -- 规则类型：SPRINT(冲刺奖)/TOP_RANK(排名奖)
|
||
rule_name VARCHAR(50) NOT NULL, -- 规则名称
|
||
condition_type VARCHAR(20) NOT NULL, -- 条件类型：HOURS_GTE(时长>=)/RANK_EQ(排名=)
|
||
condition_value NUMERIC(10,2) NOT NULL, -- 条件值
|
||
bonus_amount NUMERIC(10,2) NOT NULL, -- 奖金金额（元）
|
||
priority INTEGER DEFAULT 0, -- 优先级（同类型取高优先级）
|
||
is_stackable BOOLEAN DEFAULT FALSE, -- 是否可叠加
|
||
effective_from DATE NOT NULL DEFAULT '2026-01-01',
|
||
effective_to DATE DEFAULT '9999-12-31',
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now()
|
||
);
|
||
|
||
COMMENT ON TABLE billiards_dws.cfg_bonus_rules IS '奖金规则配置表：定义冲刺奖和Top3排名奖';
|
||
COMMENT ON COLUMN billiards_dws.cfg_bonus_rules.is_stackable IS '是否可叠加：FALSE表示同类型奖金取高不叠加';
|
||
```
|
||
|
||
### 3.2 助教维度汇总表 DDL
|
||
|
||
#### 3.2.1 `dws_assistant_monthly_summary` - 月度业绩汇总
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_assistant_monthly_summary
|
||
-- 用途: 助教月度业绩汇总表，核心统计表
|
||
-- 更新策略: 每日增量更新当月数据，月初全量刷新上月
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_assistant_monthly_summary (
|
||
summary_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL, -- 门店ID
|
||
assistant_id BIGINT NOT NULL, -- 助教ID
|
||
stat_month DATE NOT NULL, -- 统计月份（每月1日）
|
||
|
||
-- 基础课统计
|
||
base_service_count INTEGER DEFAULT 0, -- 基础课服务次数
|
||
base_service_seconds INTEGER DEFAULT 0, -- 基础课服务秒数
|
||
base_service_hours NUMERIC(10,2) DEFAULT 0, -- 基础课服务小时数（精确到分钟）
|
||
base_income_original NUMERIC(12,2) DEFAULT 0, -- 基础课原始收入（客户支付）
|
||
base_income_deduction NUMERIC(12,2) DEFAULT 0, -- 基础课球房抽成
|
||
base_income_actual NUMERIC(12,2) DEFAULT 0, -- 基础课助教实得
|
||
|
||
-- 附加课统计
|
||
bonus_service_count INTEGER DEFAULT 0, -- 附加课服务次数
|
||
bonus_service_seconds INTEGER DEFAULT 0, -- 附加课服务秒数
|
||
bonus_service_hours NUMERIC(10,2) DEFAULT 0, -- 附加课服务小时数
|
||
bonus_income_original NUMERIC(12,2) DEFAULT 0, -- 附加课原始收入
|
||
bonus_income_ratio_ded NUMERIC(12,2) DEFAULT 0, -- 附加课球房按比例抽成
|
||
bonus_income_actual NUMERIC(12,2) DEFAULT 0, -- 附加课助教实得
|
||
|
||
-- 汇总统计
|
||
total_service_count INTEGER DEFAULT 0, -- 总服务次数
|
||
total_service_hours NUMERIC(10,2) DEFAULT 0, -- 总服务小时数
|
||
total_income_original NUMERIC(12,2) DEFAULT 0, -- 总原始收入
|
||
total_income_actual NUMERIC(12,2) DEFAULT 0, -- 总助教实得
|
||
|
||
-- 废除影响
|
||
trashed_service_count INTEGER DEFAULT 0, -- 被废除服务次数
|
||
trashed_service_seconds INTEGER DEFAULT 0, -- 被废除服务秒数
|
||
trashed_amount NUMERIC(12,2) DEFAULT 0, -- 被废除金额
|
||
|
||
-- 档位信息
|
||
tier_code INTEGER, -- 当前档位代码（0-5）
|
||
tier_name VARCHAR(50), -- 档位名称
|
||
tier_base_deduction NUMERIC(10,2), -- 档位基础课抽成
|
||
tier_bonus_ratio NUMERIC(5,4), -- 档位附加课抽成比例
|
||
|
||
-- 奖金
|
||
sprint_bonus NUMERIC(10,2) DEFAULT 0, -- 冲刺奖金额
|
||
rank_bonus NUMERIC(10,2) DEFAULT 0, -- 排名奖金额
|
||
other_bonus NUMERIC(10,2) DEFAULT 0, -- 其他奖金
|
||
total_bonus NUMERIC(10,2) DEFAULT 0, -- 奖金合计
|
||
|
||
-- 最终工资
|
||
final_salary NUMERIC(12,2) DEFAULT 0, -- 最终应发工资
|
||
|
||
-- 助教快照信息
|
||
assistant_level INTEGER, -- 助教等级
|
||
assistant_level_name VARCHAR(20), -- 等级名称
|
||
entry_date DATE, -- 入职日期
|
||
is_new_employee BOOLEAN DEFAULT FALSE, -- 是否本月新入职
|
||
work_days_in_month INTEGER, -- 本月在职天数
|
||
|
||
-- 排名信息
|
||
monthly_rank INTEGER, -- 当月排名
|
||
|
||
-- 元数据
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, assistant_id, stat_month)
|
||
);
|
||
|
||
-- 索引优化
|
||
CREATE INDEX IF NOT EXISTS idx_dws_asst_monthly_site_month
|
||
ON billiards_dws.dws_assistant_monthly_summary(site_id, stat_month);
|
||
CREATE INDEX IF NOT EXISTS idx_dws_asst_monthly_assistant
|
||
ON billiards_dws.dws_assistant_monthly_summary(assistant_id, stat_month);
|
||
CREATE INDEX IF NOT EXISTS idx_dws_asst_monthly_month
|
||
ON billiards_dws.dws_assistant_monthly_summary(stat_month);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_assistant_monthly_summary IS '助教月度业绩汇总表：统计每位助教每月的业绩、收入、档位、工资';
|
||
COMMENT ON COLUMN billiards_dws.dws_assistant_monthly_summary.base_service_hours IS '基础课服务小时数，精确到分钟（秒数/3600）';
|
||
COMMENT ON COLUMN billiards_dws.dws_assistant_monthly_summary.tier_code IS '根据total_service_hours计算的档位，参照cfg_performance_tier';
|
||
```
|
||
|
||
#### 3.2.2 `dws_assistant_daily_detail` - 日度业绩明细
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_assistant_daily_detail
|
||
-- 用途: 助教日度业绩明细，用于月中进度追踪
|
||
-- 更新策略: 每小时增量更新
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_assistant_daily_detail (
|
||
detail_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL,
|
||
assistant_id BIGINT NOT NULL,
|
||
stat_date DATE NOT NULL, -- 统计日期
|
||
|
||
-- 基础课日统计
|
||
base_service_count INTEGER DEFAULT 0,
|
||
base_service_seconds INTEGER DEFAULT 0,
|
||
base_service_hours NUMERIC(10,4) DEFAULT 0,
|
||
base_income_original NUMERIC(12,2) DEFAULT 0,
|
||
|
||
-- 附加课日统计
|
||
bonus_service_count INTEGER DEFAULT 0,
|
||
bonus_service_seconds INTEGER DEFAULT 0,
|
||
bonus_service_hours NUMERIC(10,4) DEFAULT 0,
|
||
bonus_income_original NUMERIC(12,2) DEFAULT 0,
|
||
|
||
-- 汇总
|
||
total_service_count INTEGER DEFAULT 0,
|
||
total_service_hours NUMERIC(10,4) DEFAULT 0,
|
||
total_income_original NUMERIC(12,2) DEFAULT 0,
|
||
|
||
-- 废除
|
||
trashed_count INTEGER DEFAULT 0,
|
||
trashed_seconds INTEGER DEFAULT 0,
|
||
trashed_amount NUMERIC(12,2) DEFAULT 0,
|
||
|
||
-- 累计（当月至今）
|
||
mtd_total_hours NUMERIC(10,2) DEFAULT 0, -- Month-To-Date 累计小时数
|
||
mtd_tier_code INTEGER, -- 累计后档位
|
||
|
||
-- 服务客户统计
|
||
unique_customers INTEGER DEFAULT 0, -- 当日服务不同客户数
|
||
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, assistant_id, stat_date)
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_dws_asst_daily_site_date
|
||
ON billiards_dws.dws_assistant_daily_detail(site_id, stat_date);
|
||
CREATE INDEX IF NOT EXISTS idx_dws_asst_daily_assistant
|
||
ON billiards_dws.dws_assistant_daily_detail(assistant_id, stat_date);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_assistant_daily_detail IS '助教日度业绩明细表：便于实时追踪月中业绩进度';
|
||
```
|
||
|
||
#### 3.2.3 `dws_assistant_customer_stats` - 服务客户统计
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_assistant_customer_stats
|
||
-- 用途: 助教服务客户统计（多时间窗口）
|
||
-- 更新策略: 每日凌晨全量刷新
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_assistant_customer_stats (
|
||
stats_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL,
|
||
assistant_id BIGINT NOT NULL,
|
||
stat_date DATE NOT NULL, -- 统计基准日期
|
||
window_days INTEGER NOT NULL, -- 时间窗口天数：7/10/15/30/60/90
|
||
|
||
-- 客户统计
|
||
unique_customers INTEGER DEFAULT 0, -- 服务不同客户数
|
||
total_service_count INTEGER DEFAULT 0, -- 总服务次数
|
||
total_service_hours NUMERIC(10,2) DEFAULT 0, -- 总服务小时数
|
||
|
||
-- 按课程类型
|
||
base_customers INTEGER DEFAULT 0, -- 基础课客户数
|
||
base_service_count INTEGER DEFAULT 0,
|
||
bonus_customers INTEGER DEFAULT 0, -- 附加课客户数
|
||
bonus_service_count INTEGER DEFAULT 0,
|
||
|
||
-- 收入
|
||
total_income NUMERIC(12,2) DEFAULT 0,
|
||
|
||
-- 客户复购
|
||
repeat_customers INTEGER DEFAULT 0, -- 复购客户数（服务>=2次）
|
||
repeat_rate NUMERIC(5,4) DEFAULT 0, -- 复购率
|
||
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, assistant_id, stat_date, window_days)
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_dws_asst_cust_window
|
||
ON billiards_dws.dws_assistant_customer_stats(assistant_id, stat_date, window_days);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_assistant_customer_stats IS '助教服务客户统计表：支持7/10/15/30/60/90天多时间窗口';
|
||
```
|
||
|
||
### 3.3 客户维度汇总表 DDL
|
||
|
||
#### 3.3.1 `dws_member_consumption_summary` - 消费情况统计
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_member_consumption_summary
|
||
-- 用途: 会员消费情况统计（多时间窗口）
|
||
-- 更新策略: 每日凌晨全量刷新
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_member_consumption_summary (
|
||
summary_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL,
|
||
member_id BIGINT NOT NULL,
|
||
stat_date DATE NOT NULL,
|
||
window_days INTEGER NOT NULL, -- 7/10/15/30/60/90
|
||
|
||
-- 到店统计
|
||
visit_count INTEGER DEFAULT 0, -- 到店次数
|
||
visit_days INTEGER DEFAULT 0, -- 到店天数
|
||
|
||
-- 台费消费
|
||
table_fee_count INTEGER DEFAULT 0, -- 开台次数
|
||
table_fee_seconds INTEGER DEFAULT 0, -- 台费时长（秒）
|
||
table_fee_hours NUMERIC(10,2) DEFAULT 0, -- 台费小时数
|
||
table_fee_amount NUMERIC(12,2) DEFAULT 0, -- 台费金额
|
||
|
||
-- 助教服务
|
||
assistant_service_count INTEGER DEFAULT 0, -- 助教服务次数
|
||
assistant_service_hours NUMERIC(10,2) DEFAULT 0, -- 助教服务小时数
|
||
assistant_service_amt NUMERIC(12,2) DEFAULT 0, -- 助教服务金额
|
||
unique_assistants INTEGER DEFAULT 0, -- 服务过的不同助教数
|
||
|
||
-- 商品消费
|
||
goods_order_count INTEGER DEFAULT 0, -- 商品订单数
|
||
goods_item_count INTEGER DEFAULT 0, -- 商品项数
|
||
goods_amount NUMERIC(12,2) DEFAULT 0, -- 商品金额
|
||
|
||
-- 汇总金额
|
||
total_original_amount NUMERIC(12,2) DEFAULT 0, -- 原始消费总额
|
||
total_discount_amount NUMERIC(12,2) DEFAULT 0, -- 优惠总额
|
||
total_actual_amount NUMERIC(12,2) DEFAULT 0, -- 实际支付总额
|
||
|
||
-- 支付方式
|
||
cash_payment NUMERIC(12,2) DEFAULT 0, -- 现金支付
|
||
online_payment NUMERIC(12,2) DEFAULT 0, -- 线上支付
|
||
card_payment NUMERIC(12,2) DEFAULT 0, -- 储值卡支付
|
||
coupon_payment NUMERIC(12,2) DEFAULT 0, -- 团购券支付
|
||
|
||
-- 客户价值指标
|
||
avg_visit_amount NUMERIC(10,2) DEFAULT 0, -- 单次到店平均消费
|
||
avg_visit_duration_min INTEGER DEFAULT 0, -- 单次平均停留时长（分钟）
|
||
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, member_id, stat_date, window_days)
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_dws_member_cons_window
|
||
ON billiards_dws.dws_member_consumption_summary(member_id, stat_date, window_days);
|
||
CREATE INDEX IF NOT EXISTS idx_dws_member_cons_site
|
||
ON billiards_dws.dws_member_consumption_summary(site_id, stat_date, window_days);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_member_consumption_summary IS '会员消费汇总表：支持7/10/15/30/60/90天多时间窗口';
|
||
```
|
||
|
||
### 3.4 财务维度汇总表 DDL
|
||
|
||
#### 3.4.1 `dws_finance_daily_summary` - 日度财务汇总
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_finance_daily_summary
|
||
-- 用途: 门店日度财务汇总（核心财务报表数据源）
|
||
-- 更新策略: 每小时增量更新
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_finance_daily_summary (
|
||
summary_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL,
|
||
stat_date DATE NOT NULL,
|
||
|
||
-- ========== 经营链：发生额 → 优惠 → 确认收入 ==========
|
||
-- 发生额（正价）
|
||
gross_revenue NUMERIC(14,2) DEFAULT 0, -- 发生额/正价总计
|
||
gross_table_fee NUMERIC(14,2) DEFAULT 0, -- 台费发生额
|
||
gross_assistant_base NUMERIC(14,2) DEFAULT 0, -- 助教基础课发生额
|
||
gross_assistant_bonus NUMERIC(14,2) DEFAULT 0, -- 助教激励课发生额
|
||
gross_goods NUMERIC(14,2) DEFAULT 0, -- 食品酒水发生额
|
||
|
||
-- 优惠明细
|
||
discount_total NUMERIC(14,2) DEFAULT 0, -- 优惠总额
|
||
discount_groupbuy NUMERIC(14,2) DEFAULT 0, -- 团购优惠
|
||
discount_vip NUMERIC(14,2) DEFAULT 0, -- 大客户优惠
|
||
discount_gift_card NUMERIC(14,2) DEFAULT 0, -- 赠送卡抵扣（台桌卡+酒水卡+抵用券）
|
||
discount_manual NUMERIC(14,2) DEFAULT 0, -- 手动调整
|
||
discount_free NUMERIC(14,2) DEFAULT 0, -- 免单
|
||
discount_rounding NUMERIC(14,2) DEFAULT 0, -- 抹零
|
||
|
||
-- 成交/确认收入
|
||
confirmed_revenue NUMERIC(14,2) DEFAULT 0, -- 成交/确认收入（不含充值）
|
||
|
||
-- ========== 支付方式构成 ==========
|
||
payment_stored_card NUMERIC(14,2) DEFAULT 0, -- 储值卡结算冲销
|
||
payment_cash_online NUMERIC(14,2) DEFAULT 0, -- 现金/线上支付
|
||
payment_groupbuy_deal NUMERIC(14,2) DEFAULT 0, -- 团购核销确认收入（成交价）
|
||
|
||
-- ========== 现金流 ==========
|
||
-- 现金流入
|
||
cash_inflow_consume NUMERIC(14,2) DEFAULT 0, -- 消费现金流入（现金+线上+平台回款-退款）
|
||
cash_inflow_recharge NUMERIC(14,2) DEFAULT 0, -- 充值到账（首充+续费）
|
||
cash_inflow_total NUMERIC(14,2) DEFAULT 0, -- 现金流入合计
|
||
|
||
-- 现金支出（需外部输入或其他系统对接）
|
||
cash_outflow_total NUMERIC(14,2) DEFAULT 0, -- 现金支出合计
|
||
cash_outflow_rent NUMERIC(14,2) DEFAULT 0, -- 房租
|
||
cash_outflow_utility NUMERIC(14,2) DEFAULT 0, -- 水电
|
||
cash_outflow_purchase NUMERIC(14,2) DEFAULT 0, -- 进货成本
|
||
cash_outflow_assistant NUMERIC(14,2) DEFAULT 0, -- 助教分成
|
||
cash_outflow_salary NUMERIC(14,2) DEFAULT 0, -- 固定人员工资
|
||
cash_outflow_platform NUMERIC(14,2) DEFAULT 0, -- 平台服务费
|
||
cash_outflow_other NUMERIC(14,2) DEFAULT 0, -- 其他费用
|
||
|
||
-- 现金结余
|
||
cash_balance NUMERIC(14,2) DEFAULT 0, -- 现金结余
|
||
cash_balance_rate NUMERIC(5,4) DEFAULT 0, -- 结余率
|
||
|
||
-- ========== 充值与预收 ==========
|
||
recharge_first NUMERIC(14,2) DEFAULT 0, -- 首充金额
|
||
recharge_renew NUMERIC(14,2) DEFAULT 0, -- 续费金额
|
||
recharge_total NUMERIC(14,2) DEFAULT 0, -- 充值合计
|
||
recharge_gift NUMERIC(14,2) DEFAULT 0, -- 充值赠送金额
|
||
|
||
-- 储值卡
|
||
stored_card_consume NUMERIC(14,2) DEFAULT 0, -- 储值卡消耗
|
||
stored_card_balance NUMERIC(14,2) DEFAULT 0, -- 储值卡余额（截止当日）
|
||
|
||
-- 赠送卡
|
||
gift_card_new NUMERIC(14,2) DEFAULT 0, -- 赠送卡新增
|
||
gift_card_consume NUMERIC(14,2) DEFAULT 0, -- 赠送卡消耗
|
||
gift_card_balance NUMERIC(14,2) DEFAULT 0, -- 赠送卡余额
|
||
|
||
-- ========== 订单统计 ==========
|
||
order_count INTEGER DEFAULT 0, -- 订单数
|
||
order_avg_amount NUMERIC(10,2) DEFAULT 0, -- 客单价
|
||
member_order_count INTEGER DEFAULT 0, -- 会员订单数
|
||
member_order_rate NUMERIC(5,4) DEFAULT 0, -- 会员订单占比
|
||
|
||
-- ========== 退款统计 ==========
|
||
refund_count INTEGER DEFAULT 0, -- 退款笔数
|
||
refund_amount NUMERIC(14,2) DEFAULT 0, -- 退款金额
|
||
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, stat_date)
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_dws_finance_daily_site_date
|
||
ON billiards_dws.dws_finance_daily_summary(site_id, stat_date);
|
||
CREATE INDEX IF NOT EXISTS idx_dws_finance_daily_date
|
||
ON billiards_dws.dws_finance_daily_summary(stat_date);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_finance_daily_summary IS '门店日度财务汇总表：核心财务报表数据源';
|
||
COMMENT ON COLUMN billiards_dws.dws_finance_daily_summary.gross_revenue IS '发生额/正价：按各项目正价计算的理论销售额';
|
||
COMMENT ON COLUMN billiards_dws.dws_finance_daily_summary.confirmed_revenue IS '成交/确认收入：扣除优惠后的营业收入，不含充值';
|
||
```
|
||
|
||
#### 3.4.2 `dws_finance_income_structure` - 收入结构（按区域）
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_finance_income_structure
|
||
-- 用途: 收入结构按区域/类型细分
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_finance_income_structure (
|
||
structure_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL,
|
||
stat_date DATE NOT NULL,
|
||
|
||
-- 分类维度
|
||
income_category VARCHAR(20) NOT NULL, -- 收入大类：TABLE/ASSISTANT_BASE/ASSISTANT_BONUS/GOODS
|
||
area_name VARCHAR(50), -- 区域名称：A区/B区/C区/团建区/麻将区/NULL(不分区)
|
||
|
||
-- 金额
|
||
gross_amount NUMERIC(14,2) DEFAULT 0, -- 发生额
|
||
discount_amount NUMERIC(14,2) DEFAULT 0, -- 优惠金额
|
||
confirmed_amount NUMERIC(14,2) DEFAULT 0, -- 确认收入
|
||
|
||
-- 数量/时长
|
||
item_count INTEGER DEFAULT 0, -- 项目数/次数
|
||
duration_seconds INTEGER DEFAULT 0, -- 时长（秒）
|
||
duration_hours NUMERIC(10,2) DEFAULT 0, -- 时长（小时）
|
||
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, stat_date, income_category, area_name)
|
||
);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_finance_income_structure IS '收入结构表：按大类和区域细分的收入明细';
|
||
```
|
||
|
||
#### 3.4.3 `dws_assistant_finance_analysis` - 助教收支分析
|
||
|
||
```sql
|
||
-- ============================================================
|
||
-- 表名: dws_assistant_finance_analysis
|
||
-- 用途: 助教收支分析（财务视角）
|
||
-- ============================================================
|
||
CREATE TABLE IF NOT EXISTS billiards_dws.dws_assistant_finance_analysis (
|
||
analysis_id BIGSERIAL PRIMARY KEY,
|
||
site_id BIGINT NOT NULL,
|
||
stat_date DATE NOT NULL,
|
||
assistant_level INTEGER, -- 助教等级（NULL表示全部）
|
||
assistant_level_name VARCHAR(20),
|
||
|
||
-- 基础课
|
||
base_customer_payment NUMERIC(14,2) DEFAULT 0, -- 客户支付
|
||
base_shop_commission NUMERIC(14,2) DEFAULT 0, -- 球房抽成
|
||
base_hours NUMERIC(10,2) DEFAULT 0, -- 小时数
|
||
base_avg_commission NUMERIC(10,2) DEFAULT 0, -- 均小时抽成
|
||
|
||
-- 激励课
|
||
bonus_customer_payment NUMERIC(14,2) DEFAULT 0,
|
||
bonus_shop_commission NUMERIC(14,2) DEFAULT 0,
|
||
bonus_hours NUMERIC(10,2) DEFAULT 0,
|
||
bonus_avg_commission NUMERIC(10,2) DEFAULT 0,
|
||
|
||
-- 汇总
|
||
total_customer_payment NUMERIC(14,2) DEFAULT 0,
|
||
total_shop_commission NUMERIC(14,2) DEFAULT 0,
|
||
total_hours NUMERIC(10,2) DEFAULT 0,
|
||
|
||
-- 助教数量
|
||
assistant_count INTEGER DEFAULT 0,
|
||
|
||
created_at TIMESTAMPTZ DEFAULT now(),
|
||
updated_at TIMESTAMPTZ DEFAULT now(),
|
||
|
||
UNIQUE(site_id, stat_date, assistant_level)
|
||
);
|
||
|
||
COMMENT ON TABLE billiards_dws.dws_assistant_finance_analysis IS '助教收支分析表：财务视角的助教业绩与抽成统计';
|
||
```
|
||
|
||
---
|
||
|
||
## 四、技术实现方案
|
||
|
||
### 4.1 代码架构设计
|
||
|
||
```
|
||
etl_billiards/
|
||
├── tasks/
|
||
│ ├── dws/ # DWS 任务模块（新增）
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base_dws_task.py # DWS任务基类
|
||
│ │ ├── cfg_init_task.py # 配置表初始化任务
|
||
│ │ ├── assistant_monthly_task.py # 助教月度汇总任务
|
||
│ │ ├── assistant_daily_task.py # 助教日度明细任务
|
||
│ │ ├── assistant_customer_task.py # 助教客户统计任务
|
||
│ │ ├── member_consumption_task.py # 会员消费统计任务
|
||
│ │ ├── finance_daily_task.py # 财务日度汇总任务
|
||
│ │ ├── finance_structure_task.py # 收入结构任务
|
||
│ │ └── assistant_finance_task.py # 助教收支分析任务
|
||
│ └── init_dws_schema_task.py # 更新：执行完整DWS DDL
|
||
├── database/
|
||
│ ├── schema_dws.sql # 更新：完整DWS DDL
|
||
│ └── seed_dws_config.sql # 新增：配置表初始数据
|
||
├── scripts/
|
||
│ └── build_dws_*.py # DWS 构建脚本
|
||
└── docs/
|
||
└── dws_tables_dictionary.md # 新增：DWS 数据字典
|
||
```
|
||
|
||
### 4.2 类设计（OOP）
|
||
|
||
```python
|
||
# ============================================================
|
||
# 文件: tasks/dws/base_dws_task.py
|
||
# 用途: DWS 任务基类，封装通用逻辑
|
||
# ============================================================
|
||
|
||
class BaseDwsTask(BaseTask):
|
||
"""
|
||
DWS 层任务基类
|
||
|
||
特性：
|
||
1. 支持增量/全量两种刷新模式
|
||
2. 支持 delete-before-insert 策略（幂等性保障）
|
||
3. 内置时间窗口处理逻辑
|
||
"""
|
||
|
||
def __init__(self, config, db_connection, api_client, logger):
|
||
super().__init__(config, db_connection, api_client, logger)
|
||
self.target_schema = "billiards_dws"
|
||
self.source_schema = "billiards_dwd"
|
||
|
||
@property
|
||
def target_table(self) -> str:
|
||
"""子类需实现：返回目标表名"""
|
||
raise NotImplementedError
|
||
|
||
@property
|
||
def delete_before_insert(self) -> bool:
|
||
"""是否在插入前删除同范围数据，默认True"""
|
||
return True
|
||
|
||
def get_delete_sql(self, context: TaskContext) -> tuple[str, list]:
|
||
"""生成删除SQL，子类可覆盖"""
|
||
raise NotImplementedError
|
||
|
||
def get_insert_sql(self, context: TaskContext) -> tuple[str, dict]:
|
||
"""生成插入SQL，子类需实现"""
|
||
raise NotImplementedError
|
||
```
|
||
|
||
### 4.3 核心算法实现
|
||
|
||
#### 4.3.1 档位计算算法
|
||
|
||
```python
|
||
def calculate_tier(total_hours: float, is_new_employee: bool,
|
||
entry_date: date, stat_month: date,
|
||
work_days: int) -> dict:
|
||
"""
|
||
计算助教档位
|
||
|
||
规则：
|
||
1. 过档后，所有时长按新档位计算
|
||
2. 新入职助教按 日均*30 折算定档
|
||
3. 25日后入职最高定3档
|
||
|
||
Args:
|
||
total_hours: 总业绩小时数
|
||
is_new_employee: 是否本月新入职
|
||
entry_date: 入职日期
|
||
stat_month: 统计月份
|
||
work_days: 本月在职天数
|
||
|
||
Returns:
|
||
{tier_code, tier_name, base_deduction, bonus_ratio}
|
||
"""
|
||
effective_hours = total_hours
|
||
max_tier = 5
|
||
|
||
if is_new_employee and work_days < 30:
|
||
# 新入职折算：日均 * 30
|
||
daily_avg = total_hours / max(work_days, 1)
|
||
effective_hours = daily_avg * 30
|
||
|
||
# 25日后入职最高3档
|
||
if entry_date.day >= 25:
|
||
max_tier = 3
|
||
|
||
# 查询档位配置
|
||
tier = query_tier_config(effective_hours, max_tier)
|
||
return tier
|
||
```
|
||
|
||
#### 4.3.2 工资计算算法
|
||
|
||
```python
|
||
def calculate_salary(assistant_data: dict, tier: dict,
|
||
level_price: dict, bonus_rules: list) -> dict:
|
||
"""
|
||
计算助教月度工资
|
||
|
||
公式（以中级助教185小时为例）：
|
||
基础课收入 = 基础课时 * (客户单价 - 档位抽成)
|
||
附加课收入 = 附加课原价 * (1 - 档位抽成比例)
|
||
冲刺奖 = 达到阈值取最高
|
||
排名奖 = 按排名取值
|
||
|
||
最终工资 = 基础课收入 + 附加课收入 + 冲刺奖 + 排名奖
|
||
"""
|
||
# 基础课收入
|
||
base_income = (
|
||
assistant_data['base_hours'] *
|
||
(level_price['base_price'] - tier['base_deduction'])
|
||
)
|
||
|
||
# 附加课收入
|
||
bonus_income = (
|
||
assistant_data['bonus_income_original'] *
|
||
(1 - tier['bonus_ratio'])
|
||
)
|
||
|
||
# 冲刺奖（取高不叠加）
|
||
sprint_bonus = calculate_sprint_bonus(
|
||
assistant_data['total_hours'], bonus_rules
|
||
)
|
||
|
||
# 排名奖
|
||
rank_bonus = calculate_rank_bonus(
|
||
assistant_data['monthly_rank'], bonus_rules
|
||
)
|
||
|
||
final_salary = base_income + bonus_income + sprint_bonus + rank_bonus
|
||
|
||
return {
|
||
'base_income': base_income,
|
||
'bonus_income': bonus_income,
|
||
'sprint_bonus': sprint_bonus,
|
||
'rank_bonus': rank_bonus,
|
||
'final_salary': final_salary
|
||
}
|
||
```
|
||
|
||
### 4.4 SQL 构建示例
|
||
|
||
#### 4.4.1 助教月度汇总 SQL
|
||
|
||
```sql
|
||
-- 助教月度业绩汇总构建SQL
|
||
WITH
|
||
-- 1. 有效服务记录（排除废除）
|
||
valid_services AS (
|
||
SELECT
|
||
asl.site_id,
|
||
asl.site_assistant_id AS assistant_id,
|
||
DATE_TRUNC('month', asl.start_use_time)::date AS stat_month,
|
||
asl.skill_name,
|
||
-- 判断课程类型：基础课/附加课
|
||
CASE
|
||
WHEN asl.skill_name IN ('超休', '激励', '打赏') THEN 'BONUS'
|
||
ELSE 'BASE'
|
||
END AS service_type,
|
||
asl.income_seconds,
|
||
asl.ledger_amount,
|
||
asl.projected_income,
|
||
asl.tenant_member_id
|
||
FROM billiards_dwd.dwd_assistant_service_log asl
|
||
WHERE COALESCE(asl.is_delete, 0) = 0
|
||
AND asl.start_use_time >= %(start_date)s
|
||
AND asl.start_use_time < %(end_date)s
|
||
-- 排除已废除的记录
|
||
AND NOT EXISTS (
|
||
SELECT 1 FROM billiards_dwd.dwd_assistant_trash_event ate
|
||
WHERE ate.assistant_service_id = asl.assistant_service_id
|
||
)
|
||
),
|
||
|
||
-- 2. 按助教+月份+类型汇总
|
||
service_summary AS (
|
||
SELECT
|
||
site_id,
|
||
assistant_id,
|
||
stat_month,
|
||
service_type,
|
||
COUNT(*) AS service_count,
|
||
SUM(income_seconds) AS service_seconds,
|
||
SUM(income_seconds) / 3600.0 AS service_hours,
|
||
SUM(ledger_amount) AS income_original,
|
||
COUNT(DISTINCT tenant_member_id) AS unique_customers
|
||
FROM valid_services
|
||
GROUP BY site_id, assistant_id, stat_month, service_type
|
||
),
|
||
|
||
-- 3. 废除统计
|
||
trash_summary AS (
|
||
SELECT
|
||
site_id,
|
||
assistant_id, -- 需要从关联表获取
|
||
DATE_TRUNC('month', create_time)::date AS stat_month,
|
||
COUNT(*) AS trashed_count,
|
||
SUM(charge_minutes_raw * 60) AS trashed_seconds,
|
||
SUM(abolish_amount) AS trashed_amount
|
||
FROM billiards_dwd.dwd_assistant_trash_event
|
||
WHERE create_time >= %(start_date)s
|
||
AND create_time < %(end_date)s
|
||
GROUP BY site_id, assistant_id, DATE_TRUNC('month', create_time)
|
||
),
|
||
|
||
-- 4. 助教维度信息
|
||
assistant_info AS (
|
||
SELECT
|
||
assistant_id,
|
||
site_id,
|
||
level,
|
||
CASE level
|
||
WHEN 1 THEN '初级'
|
||
WHEN 2 THEN '中级'
|
||
WHEN 3 THEN '高级'
|
||
WHEN 4 THEN '星级'
|
||
WHEN 8 THEN '助教管理'
|
||
ELSE '未知'
|
||
END AS level_name,
|
||
entry_time::date AS entry_date
|
||
FROM billiards_dwd.dim_assistant
|
||
WHERE SCD2_is_current = 1
|
||
)
|
||
|
||
-- 5. 最终汇总
|
||
SELECT
|
||
ss_base.site_id,
|
||
ss_base.assistant_id,
|
||
ss_base.stat_month,
|
||
-- 基础课
|
||
COALESCE(ss_base.service_count, 0) AS base_service_count,
|
||
COALESCE(ss_base.service_seconds, 0) AS base_service_seconds,
|
||
COALESCE(ss_base.service_hours, 0) AS base_service_hours,
|
||
COALESCE(ss_base.income_original, 0) AS base_income_original,
|
||
-- 附加课
|
||
COALESCE(ss_bonus.service_count, 0) AS bonus_service_count,
|
||
COALESCE(ss_bonus.service_seconds, 0) AS bonus_service_seconds,
|
||
COALESCE(ss_bonus.service_hours, 0) AS bonus_service_hours,
|
||
COALESCE(ss_bonus.income_original, 0) AS bonus_income_original,
|
||
-- 汇总
|
||
COALESCE(ss_base.service_count, 0) + COALESCE(ss_bonus.service_count, 0) AS total_service_count,
|
||
COALESCE(ss_base.service_hours, 0) + COALESCE(ss_bonus.service_hours, 0) AS total_service_hours,
|
||
COALESCE(ss_base.income_original, 0) + COALESCE(ss_bonus.income_original, 0) AS total_income_original,
|
||
-- 废除
|
||
COALESCE(ts.trashed_count, 0) AS trashed_service_count,
|
||
COALESCE(ts.trashed_seconds, 0) AS trashed_service_seconds,
|
||
COALESCE(ts.trashed_amount, 0) AS trashed_amount,
|
||
-- 助教信息
|
||
ai.level AS assistant_level,
|
||
ai.level_name AS assistant_level_name,
|
||
ai.entry_date
|
||
FROM service_summary ss_base
|
||
LEFT JOIN service_summary ss_bonus
|
||
ON ss_base.site_id = ss_bonus.site_id
|
||
AND ss_base.assistant_id = ss_bonus.assistant_id
|
||
AND ss_base.stat_month = ss_bonus.stat_month
|
||
AND ss_bonus.service_type = 'BONUS'
|
||
LEFT JOIN trash_summary ts
|
||
ON ss_base.site_id = ts.site_id
|
||
AND ss_base.assistant_id = ts.assistant_id
|
||
AND ss_base.stat_month = ts.stat_month
|
||
LEFT JOIN assistant_info ai
|
||
ON ss_base.assistant_id = ai.assistant_id
|
||
WHERE ss_base.service_type = 'BASE'
|
||
;
|
||
```
|
||
|
||
---
|
||
|
||
## 五、实施任务清单
|
||
|
||
### 5.1 阶段一：基础设施（预计 1-2 天）
|
||
|
||
| 序号 | 任务 | 优先级 | 依赖 | 产出物 |
|
||
|------|------|--------|------|--------|
|
||
| 1.1 | 更新 `schema_dws.sql` DDL | P0 | - | DDL 文件 |
|
||
| 1.2 | 创建 `seed_dws_config.sql` 初始数据 | P0 | 1.1 | 种子数据文件 |
|
||
| 1.3 | 更新 `InitDwsSchemaTask` | P0 | 1.1,1.2 | 任务代码 |
|
||
| 1.4 | 创建 `BaseDwsTask` 基类 | P0 | - | 基类代码 |
|
||
| 1.5 | 注册新任务到 `task_registry.py` | P0 | 1.3,1.4 | 注册代码 |
|
||
|
||
### 5.2 阶段二：配置表与助教维度（预计 2-3 天）
|
||
|
||
| 序号 | 任务 | 优先级 | 依赖 | 产出物 |
|
||
|------|------|--------|------|--------|
|
||
| 2.1 | 实现 `CfgInitTask` 配置初始化 | P0 | 1.* | 任务代码 |
|
||
| 2.2 | 实现 `AssistantDailyTask` 日度明细 | P0 | 1.4 | 任务代码 |
|
||
| 2.3 | 实现 `AssistantMonthlyTask` 月度汇总 | P0 | 2.2 | 任务代码 |
|
||
| 2.4 | 实现档位计算与工资计算模块 | P0 | 2.3 | 算法模块 |
|
||
| 2.5 | 实现 `AssistantCustomerTask` 客户统计 | P1 | 2.2 | 任务代码 |
|
||
|
||
### 5.3 阶段三：客户维度（预计 1-2 天）
|
||
|
||
| 序号 | 任务 | 优先级 | 依赖 | 产出物 |
|
||
|------|------|--------|------|--------|
|
||
| 3.1 | 实现 `MemberConsumptionTask` | P0 | 1.4 | 任务代码 |
|
||
| 3.2 | 实现多时间窗口查询视图 | P1 | 3.1 | SQL 视图 |
|
||
|
||
### 5.4 阶段四：财务维度（预计 2-3 天）
|
||
|
||
| 序号 | 任务 | 优先级 | 依赖 | 产出物 |
|
||
|------|------|--------|------|--------|
|
||
| 4.1 | 实现 `FinanceDailySummaryTask` | P0 | 1.4 | 任务代码 |
|
||
| 4.2 | 实现 `FinanceIncomeStructureTask` | P0 | 4.1 | 任务代码 |
|
||
| 4.3 | 实现 `AssistantFinanceTask` | P0 | 2.3 | 任务代码 |
|
||
| 4.4 | 实现充值与预收统计逻辑 | P1 | 4.1 | 模块代码 |
|
||
|
||
### 5.5 阶段五：数据分层与维护（预计 1-2 天）
|
||
|
||
| 序号 | 任务 | 优先级 | 依赖 | 产出物 |
|
||
|------|------|--------|------|--------|
|
||
| 5.1 | 实现分区表管理任务 | P1 | 1.1 | 任务代码 |
|
||
| 5.2 | 实现数据清理/归档任务 | P1 | 5.1 | 任务代码 |
|
||
| 5.3 | 配置定时调度 | P1 | 2-4.* | 调度配置 |
|
||
|
||
### 5.6 阶段六：文档与测试（预计 1-2 天）
|
||
|
||
| 序号 | 任务 | 优先级 | 依赖 | 产出物 |
|
||
|------|------|--------|------|--------|
|
||
| 6.1 | 编写 `dws_tables_dictionary.md` | P0 | 1-5.* | 数据字典 |
|
||
| 6.2 | 更新 `README.md` | P0 | 1-5.* | README |
|
||
| 6.3 | 编写单元测试 | P1 | 2-4.* | 测试代码 |
|
||
| 6.4 | 编写集成测试 | P1 | 6.3 | 测试代码 |
|
||
|
||
---
|
||
|
||
## 六、风险与注意事项
|
||
|
||
### 6.1 数据一致性
|
||
|
||
1. **废除记录处理**：计算助教业绩时必须排除已废除的服务记录
|
||
2. **课程类型判断**：根据 `skill_name` 字段区分基础课和附加课，需确认枚举值完整性
|
||
3. **新入职折算**：需要准确获取入职日期和在职天数
|
||
|
||
### 6.2 性能优化
|
||
|
||
1. **索引设计**：所有汇总表按常用查询维度建立复合索引
|
||
2. **增量更新**：日常运行采用增量模式，仅全量刷新月初或异常恢复场景
|
||
3. **分区策略**：大表按月份分区，历史数据可归档
|
||
|
||
### 6.3 编码注意
|
||
|
||
1. **中文注释**：所有 SQL 和 Python 代码需要详尽的中文注释
|
||
2. **UTF-8 编码**：确保文件编码为 UTF-8，DDL 中使用 `COMMENT ON` 添加中文说明
|
||
3. **日志输出**：关键步骤输出中文日志便于排查
|
||
|
||
### 6.4 业务规则确认
|
||
|
||
以下内容需与业务方确认：
|
||
|
||
1. 附加课识别规则：`skill_name` 的具体枚举值（超休/激励/打赏等）
|
||
2. 助教等级映射：`dim_assistant.level` 的值域（1=初级/2=中级/3=高级/4=星级?）
|
||
3. 充值提成规则：当前需求文档为空，需补充
|
||
4. 赠送卡分类：台费卡/酒水卡/抵用券的区分字段
|
||
|
||
---
|
||
|
||
## 七、验收标准
|
||
|
||
### 7.1 功能验收
|
||
|
||
- [ ] 所有 DWS 表可正常建表、查询
|
||
- [ ] 助教月度汇总数据准确（与手工计算对比）
|
||
- [ ] 档位计算逻辑符合业务规则
|
||
- [ ] 工资计算结果正确
|
||
- [ ] 客户统计支持多时间窗口
|
||
- [ ] 财务汇总数据与 DWD 明细一致
|
||
|
||
### 7.2 文档验收
|
||
|
||
- [ ] `dws_tables_dictionary.md` 完整记录所有表和字段
|
||
- [ ] `README.md` 包含 DWS 使用说明
|
||
- [ ] 代码注释覆盖率 > 80%
|
||
|
||
### 7.3 性能验收
|
||
|
||
- [ ] 日增量刷新 < 5 分钟
|
||
- [ ] 月全量刷新 < 30 分钟
|
||
- [ ] 常用查询响应 < 1 秒
|
||
|
||
---
|
||
|
||
## 八、附录
|
||
|
||
### A. 配置表初始数据
|
||
|
||
```sql
|
||
-- 绩效档位初始数据
|
||
INSERT INTO billiards_dws.cfg_performance_tier
|
||
(tier_code, tier_name, tier_reason, min_hours, max_hours, base_deduction, bonus_ratio, vacation_days)
|
||
VALUES
|
||
(0, '0档 淘汰压力', '淘汰压力', 0, 100, 28, 0.50, 3),
|
||
(1, '1档 及格档', '重点激励', 100, 130, 18, 0.40, 4),
|
||
(2, '2档 良好档', '重点激励', 130, 160, 15, 0.38, 4),
|
||
(3, '3档 优秀档', '优秀标准', 160, 190, 13, 0.35, 5),
|
||
(4, '4档 卓越加速档', '高端人才倾斜', 190, 220, 10, 0.33, 6),
|
||
(5, '5档 冠军加速档', '高端人才倾斜', 220, NULL, 8, 0.30, NULL);
|
||
|
||
-- 助教等级定价初始数据
|
||
INSERT INTO billiards_dws.cfg_assistant_level_price
|
||
(level_code, level_name, base_price, bonus_price)
|
||
VALUES
|
||
(1, '初级', 98, 190),
|
||
(2, '中级', 108, 190),
|
||
(3, '高级', 118, 190),
|
||
(4, '星级', 138, 190),
|
||
(8, '助教管理', 0, 0);
|
||
|
||
-- 奖金规则初始数据
|
||
INSERT INTO billiards_dws.cfg_bonus_rules
|
||
(rule_type, rule_name, condition_type, condition_value, bonus_amount, priority, is_stackable)
|
||
VALUES
|
||
('SPRINT', '冲刺奖-190小时', 'HOURS_GTE', 190, 300, 1, FALSE),
|
||
('SPRINT', '冲刺奖-220小时', 'HOURS_GTE', 220, 800, 2, FALSE),
|
||
('TOP_RANK', 'Top1奖金', 'RANK_EQ', 1, 1000, 1, TRUE),
|
||
('TOP_RANK', 'Top2奖金', 'RANK_EQ', 2, 600, 2, TRUE),
|
||
('TOP_RANK', 'Top3奖金', 'RANK_EQ', 3, 400, 3, TRUE);
|
||
```
|
||
|
||
### B. CLI 命令示例
|
||
|
||
```bash
|
||
# 初始化 DWS Schema
|
||
python -m cli.main --pipeline-flow INGEST_ONLY --tasks INIT_DWS_SCHEMA
|
||
|
||
# 初始化配置数据
|
||
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_INIT_CONFIG
|
||
|
||
# 构建助教日度明细（指定日期）
|
||
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_ASSISTANT_DAILY \
|
||
--window-start "2026-01-01" --window-end "2026-01-31"
|
||
|
||
# 构建助教月度汇总
|
||
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_ASSISTANT_MONTHLY \
|
||
--window-start "2026-01-01" --window-end "2026-02-01"
|
||
|
||
# 构建财务日度汇总
|
||
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_FINANCE_DAILY \
|
||
--window-start "2026-01-01" --window-end "2026-01-31"
|
||
|
||
# 一键刷新所有 DWS 表
|
||
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_REFRESH_ALL
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本历史**
|
||
|
||
| 版本 | 日期 | 作者 | 变更说明 |
|
||
|------|------|------|----------|
|
||
| 1.0 | 2026-02-01 | AI Assistant | 初始版本 |
|