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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/bd_manual/dws/BD_manual_cfg_area_category.md
+++ b/docs/bd_manual/dws/BD_manual_cfg_area_category.md
@@ -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, '其他');
+```
--- a/docs/bd_manual/dws/BD_manual_cfg_assistant_level_price.md
+++ b/docs/bd_manual/dws/BD_manual_cfg_assistant_level_price.md
@@ -0,0 +1,59 @@
+# 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 | | 附加课单价（元/小时），固定190元 |
+| 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元/小时 | 190元/小时 |
+| 10 | 初级 | 98元/小时 | 190元/小时 |
+| 20 | 中级 | 108元/小时 | 190元/小时 |
+| 30 | 高级 | 118元/小时 | 190元/小时 |
+| 40 | 星级 | 138元/小时 | 190元/小时 |
+
+## 使用说明
+
+**取值方式**
+
+SCD2口径：助教等级来自dim_assistant，取数时需按有效期as-of join
+
+**说明**
+- 包厢课（基础课）统一按138元/小时计价，不随等级变化
+
+```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';
+```
--- a/docs/bd_manual/dws/BD_manual_cfg_bonus_rules.md
+++ b/docs/bd_manual/dws/BD_manual_cfg_bonus_rules.md
@@ -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 | | 规则代码。**枚举值**: TOP_1, TOP_2, TOP_3（SPRINT_*为历史规则） |
+| 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 | | 更新时间 |
+
+## 奖金规则示例
+
+### 冲刺奖金（历史口径，至2026-02-28，不累计取最高档）
+| 规则代码 | 小时阈值 | 奖金金额 | 优先级 |
+|----------|----------|----------|--------|
+| SPRINT_190 | 190小时 | 300元 | 1 |
+| SPRINT_220 | 220小时 | 800元 | 2 |
+
+### Top3排名奖金（2026-03-01起，独立发放）
+| 规则代码 | 排名 | 奖金金额 |
+|----------|------|----------|
+| 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-02-28'
+  AND effective_to >= '2026-02-28'
+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-03-01'
+  AND effective_to >= '2026-03-01';
+```
+
+**排名口径说明**
+- Top3排名按有效业绩小时数（effective_hours）降序排列
+- 如遇并列则都算（如2个第一，则记为2个第一，下一个是第三）
--- a/docs/bd_manual/dws/BD_manual_cfg_index_parameters.md
+++ b/docs/bd_manual/dws/BD_manual_cfg_index_parameters.md
@@ -0,0 +1,51 @@
+# cfg_index_parameters 指数算法参数配置表
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | cfg_index_parameters |
+| 主键 | param_id |
+| 唯一键 | (index_type, param_name, effective_from) |
+| 数据来源 | 手动配置 / seed_index_parameters.sql |
+| 说明 | 指数算法（WBI/NCI/RS/OS/MS/ML）的公共与专用参数 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | param_id | SERIAL | NO | 自增主键 |
+| 2 | index_type | VARCHAR | NO | 指数类型：WBI/NCI/RS/OS/MS/ML/COMMON |
+| 3 | param_name | VARCHAR | NO | 参数名称（如 percentile_lower、ewma_alpha） |
+| 4 | param_value | NUMERIC | NO | 参数值 |
+| 5 | description | TEXT | YES | 参数说明 |
+| 6 | effective_from | DATE | NO | 生效起始日期（默认 CURRENT_DATE） |
+| 7 | effective_to | DATE | YES | 生效截止日期（NULL 表示永久有效） |
+| 8 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 9 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 公共参数说明
+
+| 参数名 | 说明 |
+|--------|------|
+| percentile_lower | 分位截断下锚点（如 5%） |
+| percentile_upper | 分位截断上锚点（如 95%） |
+| ewma_alpha | EWMA 平滑系数（0~1） |
+
+## 使用说明
+
+```sql
+-- 查询 RS 指数当前有效参数
+SELECT param_name, param_value
+FROM billiards_dws.cfg_index_parameters
+WHERE index_type = 'RS'
+  AND effective_from <= CURRENT_DATE
+  AND (effective_to IS NULL OR effective_to >= CURRENT_DATE);
+```
+
+## 初始化
+
+种子脚本：`database/seed_index_parameters.sql`
--- a/docs/bd_manual/dws/BD_manual_cfg_performance_tier.md
+++ b/docs/bd_manual/dws/BD_manual_cfg_performance_tier.md
@@ -0,0 +1,73 @@
+# cfg_performance_tier 绩效档位配置表
+
+> 生成时间：2026-02-03
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | cfg_performance_tier |
+| 主键 | tier_id |
+| 数据来源 | 手工维护/seed脚本 |
+| 说明 | 助教绩效档位配置，包含阈值、抽成比例、假期天数 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
+|------|--------|------|------|------|------|
+| 1 | tier_id | SERIAL | NO | PK | 档位ID（自增） |
+| 2 | tier_code | VARCHAR(20) | NO | | 档位代码。**示例值**: T0, T1, T2, T3, T4 |
+| 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 | | 是否休假自由（最高档为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 | | 更新时间 |
+
+## 档位配置示例（2026-03-01起）
+
+| 档位代码 | 档位名称 | 小时数范围 | 专业课抽成 | 打赏课抽成 | 假期 |
+|----------|----------|------------|------------|------------|------|
+| T0 | 0档-淘汰压力 | 0-120 | 28元/小时 | 50% | 3天 |
+| T1 | 1档-及格档 | 120-150 | 18元/小时 | 40% | 4天 |
+| T2 | 2档-良好档 | 150-180 | 13元/小时 | 35% | 5天 |
+| T3 | 3档-优秀档 | 180-210 | 10元/小时 | 30% | 6天 |
+| T4 | 4档-销冠竞争 | 210+ | 8元/小时 | 25% | 自由 |
+
+**新入职规则（2026-03-01起）**
+- 本月首次入职：按日均业绩小时数 × 30 定档
+- 入职日期 > 25 日：最高定档至 2 档（T2）
+
+## 使用说明
+
+**取值方式**
+
+按月份匹配生效的配置：
+```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)
--- a/docs/bd_manual/dws/BD_manual_cfg_skill_type.md
+++ b/docs/bd_manual/dws/BD_manual_cfg_skill_type.md
@@ -0,0 +1,64 @@
+# 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（附加课）, ROOM（包厢课） |
+| 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 | 课程类型代码 | 课程类型名称 |
+|----------|------------|--------------|--------------|
+| 2790683529513797 | 基础课 | BASE | 基础课 |
+| 2790683529513798 | 附加课 | BONUS | 附加课 |
+| 3039912271463941 | 包厢课 | ROOM | 包厢课 |
+
+## 使用说明
+
+**取值方式**
+
+```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元/小时
+- 包厢课: 单独统计（基础课口径，统一按138元/小时计价）
--- a/docs/bd_manual/dws/BD_manual_dws_assistant_customer_stats.md
+++ b/docs/bd_manual/dws/BD_manual_dws_assistant_customer_stats.md
@@ -0,0 +1,98 @@
+# dws_assistant_customer_stats 助教服务客户统计表
+
+> 生成时间：2026-02-03 | 更新时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| 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(start_use_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 |
+| 注意事项 | 滚动窗口需要足够的历史数据支撑 |
--- a/docs/bd_manual/dws/BD_manual_dws_assistant_daily_detail.md
+++ b/docs/bd_manual/dws/BD_manual_dws_assistant_daily_detail.md
@@ -0,0 +1,118 @@
+# 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 | room_service_count | INTEGER | NO | 包厢课服务次数 |
+| 13 | total_seconds | INTEGER | NO | 总计费时长（秒） |
+| 14 | base_seconds | INTEGER | NO | 基础课计费时长（秒） |
+| 15 | bonus_seconds | INTEGER | NO | 附加课计费时长（秒） |
+| 16 | room_seconds | INTEGER | NO | 包厢课计费时长（秒） |
+| 17 | total_hours | NUMERIC(10,2) | NO | 总计费小时数 |
+| 18 | base_hours | NUMERIC(10,2) | NO | 基础课小时数 |
+| 19 | bonus_hours | NUMERIC(10,2) | NO | 附加课小时数 |
+| 20 | room_hours | NUMERIC(10,2) | NO | 包厢课小时数 |
+| 21 | total_ledger_amount | NUMERIC(12,2) | NO | 总计费金额（元） |
+| 22 | base_ledger_amount | NUMERIC(12,2) | NO | 基础课计费金额 |
+| 23 | bonus_ledger_amount | NUMERIC(12,2) | NO | 附加课计费金额 |
+| 24 | room_ledger_amount | NUMERIC(12,2) | NO | 包厢课计费金额 |
+| 25 | unique_customers | INTEGER | NO | 服务客户数（去重） |
+| 26 | unique_tables | INTEGER | NO | 服务台桌数（去重） |
+| 27 | trashed_seconds | INTEGER | NO | 被废除的服务时长（秒） |
+| 28 | trashed_count | INTEGER | NO | 被废除的服务次数 |
+| 29 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 30 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 数据来源
+
+### 主要来源：dwd_assistant_service_log
+```sql
+SELECT 
+    site_id,
+    DATE(start_use_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(start_use_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,
+    SUM(room_hours) AS room_hours
+FROM billiards_dws.dws_assistant_daily_detail
+GROUP BY assistant_id, DATE_TRUNC('month', stat_date);
+```
+
+**物化汇总层（可选）**
+- L1~L4 物化视图：`mv_dws_assistant_daily_detail_l1` / `l2` / `l3` / `l4`
+- 刷新任务：`DWS_MV_REFRESH_ASSISTANT_DAILY`
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯 |
+| 数据范围 | 2025-07-21 ~ 至今 |
+| 依赖表 | dwd_assistant_service_log, dwd_assistant_trash_event, dim_assistant |
--- a/docs/bd_manual/dws/BD_manual_dws_assistant_finance_analysis.md
+++ b/docs/bd_manual/dws/BD_manual_dws_assistant_finance_analysis.md
@@ -0,0 +1,96 @@
+# 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 | revenue_room | NUMERIC(14,2) | NO | 包厢课收入 |
+| 11 | cost_daily | NUMERIC(14,2) | NO | 日均工资成本（月工资/工作天数） |
+| 12 | gross_profit | NUMERIC(14,2) | NO | 毛利 = 收入 - 成本 |
+| 13 | gross_margin | NUMERIC(5,4) | NO | 毛利率 |
+| 14 | service_count | INTEGER | NO | 服务次数 |
+| 15 | service_hours | NUMERIC(10,2) | NO | 服务小时数 |
+| 16 | room_service_count | INTEGER | NO | 包厢课服务次数 |
+| 17 | room_service_hours | NUMERIC(10,2) | NO | 包厢课服务小时数 |
+| 18 | unique_customers | INTEGER | NO | 服务客户数 |
+| 19 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 20 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 数据来源
+
+### 收入来源：dwd_assistant_service_log
+```sql
+SELECT 
+    DATE(start_use_time) AS stat_date,
+    site_assistant_id AS assistant_id,
+    SUM(ledger_amount) AS revenue_total,
+    SUM(CASE WHEN COALESCE(st.course_type_code, 'BASE') = 'BASE' THEN ledger_amount ELSE 0 END) AS revenue_base,
+    SUM(CASE WHEN COALESCE(st.course_type_code, 'BASE') = 'BONUS' THEN ledger_amount ELSE 0 END) AS revenue_bonus,
+    SUM(CASE WHEN COALESCE(st.course_type_code, 'BASE') = 'ROOM' THEN ledger_amount ELSE 0 END) AS revenue_room,
+    COUNT(*) AS service_count,
+    SUM(income_seconds) / 3600.0 AS service_hours,
+    COUNT(CASE WHEN COALESCE(st.course_type_code, 'BASE') = 'ROOM' THEN 1 END) AS room_service_count,
+    SUM(CASE WHEN COALESCE(st.course_type_code, 'BASE') = 'ROOM' THEN income_seconds ELSE 0 END) / 3600.0 AS room_service_hours,
+    COUNT(DISTINCT tenant_member_id) AS unique_customers
+FROM billiards_dwd.dwd_assistant_service_log s
+LEFT JOIN billiards_dws.cfg_skill_type st
+    ON st.skill_id = s.skill_id AND st.is_active = TRUE
+WHERE s.is_delete = 0
+GROUP BY DATE(start_use_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，需先完成薪资计算 |
--- a/docs/bd_manual/dws/BD_manual_dws_assistant_monthly_summary.md
+++ b/docs/bd_manual/dws/BD_manual_dws_assistant_monthly_summary.md
@@ -0,0 +1,126 @@
+# 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 | room_service_count | INTEGER | NO | 包厢课服务次数 |
+| 16 | total_hours | NUMERIC(10,2) | NO | 总计费小时数 |
+| 17 | base_hours | NUMERIC(10,2) | NO | 基础课小时数 |
+| 18 | bonus_hours | NUMERIC(10,2) | NO | 附加课小时数 |
+| 19 | room_hours | NUMERIC(10,2) | NO | 包厢课小时数 |
+| 20 | effective_hours | NUMERIC(10,2) | NO | 有效业绩小时数（影响档位）= total_hours - trashed_hours |
+| 21 | trashed_hours | NUMERIC(10,2) | NO | 被废除小时数 |
+| 22 | total_ledger_amount | NUMERIC(12,2) | NO | 总计费金额 |
+| 23 | base_ledger_amount | NUMERIC(12,2) | NO | 基础课计费金额 |
+| 24 | bonus_ledger_amount | NUMERIC(12,2) | NO | 附加课计费金额 |
+| 25 | room_ledger_amount | NUMERIC(12,2) | NO | 包厢课计费金额 |
+| 26 | unique_customers | INTEGER | NO | 月度服务客户数（去重） |
+| 27 | unique_tables | INTEGER | NO | 月度服务台桌数（去重） |
+| 28 | avg_service_seconds | NUMERIC(10,2) | NO | 平均单次服务时长（秒） |
+| 29 | tier_id | INTEGER | YES | 匹配的档位ID |
+| 30 | tier_code | VARCHAR(20) | YES | 档位代码（如T0-T4） |
+| 31 | tier_name | VARCHAR(50) | YES | 档位名称 |
+| 32 | rank_by_hours | INTEGER | YES | 月度排名（按effective_hours降序） |
+| 33 | rank_with_ties | INTEGER | YES | 考虑并列的排名 |
+| 34 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 35 | 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(room_service_count) AS room_service_count,
+    SUM(total_hours) AS total_hours,
+    SUM(base_hours) AS base_hours,
+    SUM(bonus_hours) AS bonus_hours,
+    SUM(room_hours) AS room_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);
+```
+
+### 月度客户/台桌去重（从DWD直接去重）
+```sql
+SELECT
+    site_assistant_id AS assistant_id,
+    DATE_TRUNC('month', start_use_time)::DATE AS stat_month,
+    COUNT(DISTINCT CASE WHEN tenant_member_id > 0 THEN tenant_member_id END) 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_assistant_id, DATE_TRUNC('month', start_use_time);
+```
+
+### 档位匹配
+```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
+LIMIT 1;
+```
+
+## 使用说明
+
+**新入职判断**
+- 入职日期 >= 统计月1日0点 则为新入职
+- 2026-03-01起：新入职定档按日均×30；入职日期>25日时最高2档（T2）
+
+**排名计算**
+```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, dwd_assistant_service_log, cfg_performance_tier, dim_assistant |
--- a/docs/bd_manual/dws/BD_manual_dws_assistant_recharge_commission.md
+++ b/docs/bd_manual/dws/BD_manual_dws_assistant_recharge_commission.md
@@ -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层无此数据 |
+| 处理 | 需要人工补录历史数据 |
--- a/docs/bd_manual/dws/BD_manual_dws_assistant_salary_calc.md
+++ b/docs/bd_manual/dws/BD_manual_dws_assistant_salary_calc.md
@@ -0,0 +1,101 @@
+# 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 | room_hours | NUMERIC(10,2) | NO | 包厢课小时数 |
+| 15 | tier_id | INTEGER | YES | 档位ID |
+| 16 | tier_code | VARCHAR(20) | YES | 档位代码 |
+| 17 | tier_name | VARCHAR(50) | YES | 档位名称 |
+| 18 | rank_with_ties | INTEGER | YES | 月度排名（考虑并列） |
+| 19 | base_course_price | NUMERIC(10,2) | NO | 基础课客户支付价格 |
+| 20 | bonus_course_price | NUMERIC(10,2) | NO | 附加课客户支付价格（固定190） |
+| 21 | base_deduction | NUMERIC(10,2) | NO | 专业课抽成（元/小时） |
+| 22 | bonus_deduction_ratio | NUMERIC(5,4) | NO | 打赏课抽成比例 |
+| 23 | base_income | NUMERIC(12,2) | NO | 基础课收入 |
+| 24 | bonus_income | NUMERIC(12,2) | NO | 附加课收入 |
+| 25 | room_income | NUMERIC(12,2) | NO | 包厢课收入（按基础课口径） |
+| 26 | total_course_income | NUMERIC(12,2) | NO | 课时收入合计 |
+| 27 | sprint_bonus | NUMERIC(12,2) | NO | 冲刺奖金（历史/按规则配置） |
+| 28 | top_rank_bonus | NUMERIC(12,2) | NO | Top3排名奖金 |
+| 29 | recharge_commission | NUMERIC(12,2) | NO | 充值提成 |
+| 30 | other_bonus | NUMERIC(12,2) | NO | 其他奖金 |
+| 31 | total_bonus | NUMERIC(12,2) | NO | 奖金合计 |
+| 32 | gross_salary | NUMERIC(12,2) | NO | 应发工资 |
+| 33 | vacation_days | INTEGER | NO | 次月可休假天数 |
+| 34 | vacation_unlimited | BOOLEAN | NO | 休假自由标记 |
+| 35 | calc_notes | TEXT | YES | 计算备注 |
+| 36 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 37 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 工资计算公式
+
+### 课时收入
+```
+基础课收入 = base_hours × (base_course_price - base_deduction)
+附加课收入 = bonus_hours × 190 × (1 - bonus_deduction_ratio)
+包厢课收入 = room_hours × (138 - base_deduction)  -- 包厢课统一138元/小时
+课时收入合计 = 基础课收入 + 附加课收入 + 包厢课收入
+```
+
+### 奖金
+```
+Top3奖金: 1st=1000元, 2nd=600元, 3rd=400元（2026-03-01起）
+充值提成: 来自dws_assistant_recharge_commission
+```
+
+### 应发工资
+```
+gross_salary = total_course_income + total_bonus
+```
+
+## 计算示例
+
+| 项目 | 数值 | 计算过程 |
+|------|------|----------|
+| 基础课小时数 | 170 | 来自monthly_summary |
+| 附加课小时数 | 15 | 来自monthly_summary |
+| 包厢课小时数 | 0 | 来自monthly_summary |
+| 等级 | 中级(20) | base_course_price=108 |
+| 档位 | T3 | base_deduction=10, bonus_ratio=0.30 |
+| 基础课收入 | 16,660 | 170 × (108-10) |
+| 附加课收入 | 1,995 | 15 × 190 × 0.70 |
+| Top3奖金 | 0 | 未进入Top3 |
+| 应发工资 | 18,655 | 16,660 + 1,995 + 0 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ⚠️ 部分可回溯 |
+| 数据范围 | 2025年8月起 |
+| 依赖表 | dws_assistant_monthly_summary, cfg_*, dws_assistant_recharge_commission |
+| 限制 | 充值提成需手工导入历史数据 |
--- a/docs/bd_manual/dws/BD_manual_dws_finance_daily_summary.md
+++ b/docs/bd_manual/dws/BD_manual_dws_finance_daily_summary.md
@@ -0,0 +1,157 @@
+# 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,
+    COUNT(*) AS 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(pay_amount) AS cash_pay_amount,
+    SUM(balance_amount) AS balance_pay_amount,
+    SUM(recharge_card_amount) AS card_pay_amount,
+    SUM(coupon_amount) AS coupon_amount,
+    SUM(member_discount_amount) AS member_discount_amount,
+    SUM(adjust_amount) AS adjust_amount,
+    SUM(rounding_amount) AS rounding_amount,
+    SUM(pl_coupon_sale_amount) AS pl_coupon_sale_amount
+FROM billiards_dwd.dwd_settlement_head
+WHERE site_id = :site_id
+GROUP BY DATE(pay_time);
+```
+
+### 团购核销：dwd_groupbuy_redemption（按结账日对齐）
+```sql
+SELECT 
+    sh.pay_time::DATE AS stat_date,
+    COUNT(CASE WHEN sh.coupon_amount > 0 THEN 1 END) AS groupbuy_count,
+    SUM(
+        CASE 
+            WHEN sh.coupon_amount > 0 THEN
+                CASE 
+                    WHEN sh.pl_coupon_sale_amount > 0 THEN sh.pl_coupon_sale_amount
+                    ELSE COALESCE(gr.ledger_unit_price, 0)
+                END
+            ELSE 0
+        END
+    ) AS groupbuy_pay_total
+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
+GROUP BY sh.pay_time::DATE;
+```
+
+### 充值订单：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);
+```
+
+### 赠送卡消费：dwd_member_balance_change（按余额变动）
+```sql
+SELECT 
+    change_time::DATE AS stat_date,
+    SUM(ABS(change_amount)) AS gift_card_consume
+FROM billiards_dwd.dwd_member_balance_change
+WHERE site_id = :site_id
+  AND from_type = 1
+  AND change_amount < 0
+  AND COALESCE(is_delete, 0) = 0
+  AND card_type_id IN (:gift_card_type_ids)
+GROUP BY change_time::DATE;
+```
+
+## 使用说明
+
+**计算公式**
+```
+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
+```
+
+**物化汇总层（可选）**
+- L1~L4 物化视图：`mv_dws_finance_daily_summary_l1` / `l2` / `l3` / `l4`
+- 刷新任务：`DWS_MV_REFRESH_FINANCE_DAILY`
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯 |
+| 数据范围 | 2025-07-16 ~ 至今 |
+| 依赖表 | dwd_settlement_head, dwd_groupbuy_redemption, dwd_recharge_order, dwd_member_balance_change, dws_finance_expense_summary, dws_platform_settlement |
+| 注意 | platform_settlement需Excel导入 |
--- a/docs/bd_manual/dws/BD_manual_dws_finance_discount_detail.md
+++ b/docs/bd_manual/dws/BD_manual_dws_finance_discount_detail.md
@@ -0,0 +1,98 @@
+# 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 + dwd_member_balance_change |
+| 更新频率 | 每日更新 |
+| 说明 | 以"日期+优惠类型"为粒度，分析优惠构成 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 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_TABLE | 台费卡抵扣 | dwd_member_balance_change |
+| GIFT_CARD_DRINK | 酒水卡抵扣 | dwd_member_balance_change |
+| GIFT_CARD_COUPON | 活动抵用券抵扣 | dwd_member_balance_change |
+| MANUAL | 手动调整 | dwd_settlement_head.adjust_amount |
+| ROUNDING | 抹零 | dwd_settlement_head.rounding_amount |
+| BIG_CUSTOMER | 大客户优惠 | dwd_settlement_head（特定会员优惠） |
+| OTHER | 其他优惠 | 其他无法归类的优惠 |
+
+## 数据来源
+
+```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
+FROM billiards_dwd.dwd_settlement_head
+WHERE site_id = :site_id
+  AND settle_status = 1
+GROUP BY pay_time::DATE;
+```
+
+```sql
+-- 赠送卡消费（按卡类型拆分）
+SELECT
+    change_time::DATE AS stat_date,
+    card_type_id,
+    COUNT(*) AS consume_count,
+    SUM(ABS(change_amount)) AS consume_amount
+FROM billiards_dwd.dwd_member_balance_change
+WHERE site_id = :site_id
+  AND from_type = 1
+  AND change_amount < 0
+  AND COALESCE(is_delete, 0) = 0
+  AND card_type_id IN (:gift_card_type_ids)
+GROUP BY change_time::DATE, card_type_id;
+```
+
+## 使用说明
+
+**占比计算**
+```sql
+discount_ratio = discount_amount / SUM(discount_amount) OVER (PARTITION BY stat_date)
+```
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯 |
+| 数据范围 | 2025-07-16 ~ 至今 |
+| 依赖表 | dwd_settlement_head, dwd_groupbuy_redemption, dwd_member_balance_change |
--- a/docs/bd_manual/dws/BD_manual_dws_finance_expense_summary.md
+++ b/docs/bd_manual/dws/BD_manual_dws_finance_expense_summary.md
@@ -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层无此数据 |
+| 处理 | 需要人工补录历史数据 |
--- a/docs/bd_manual/dws/BD_manual_dws_finance_income_structure.md
+++ b/docs/bd_manual/dws/BD_manual_dws_finance_income_structure.md
@@ -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 |
--- a/docs/bd_manual/dws/BD_manual_dws_finance_recharge_summary.md
+++ b/docs/bd_manual/dws/BD_manual_dws_finance_recharge_summary.md
@@ -0,0 +1,97 @@
+# 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_money + gift_money) AS recharge_total,
+    SUM(pay_money) AS recharge_cash,
+    SUM(gift_money) 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_money ELSE 0 END) AS first_recharge_cash,
+    SUM(CASE WHEN is_first = 1 THEN gift_money ELSE 0 END) AS first_recharge_gift,
+    -- 续充
+    SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN 1 ELSE 0 END) AS renewal_count,
+    SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN pay_money 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
+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_is_current = 1;
+```
+
+## 使用说明
+
+**首充判断**
+- is_first = 1: 首充
+- is_first = 0: 续充
+
+**储值卡ID**
+- 储值卡 card_type_id = 2793249295533893
+**赠送卡ID**
+- 台费卡 2791990152417157
+- 酒水卡 2794699703437125
+- 活动抵用券 2793266846533445
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯 |
+| 数据范围 | 2025-07-21 ~ 至今 |
+| 依赖表 | dwd_recharge_order, dim_member_card_account |
--- a/docs/bd_manual/dws/BD_manual_dws_index_percentile_history.md
+++ b/docs/bd_manual/dws/BD_manual_dws_index_percentile_history.md
@@ -0,0 +1,51 @@
+# dws_index_percentile_history 指数分位历史表
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_index_percentile_history |
+| 主键 | history_id |
+| 唯一键 | (site_id, index_type, calc_time) |
+| 数据来源 | 指数计算任务自动写入 |
+| 更新频率 | 每次指数计算时追加 |
+| 说明 | 记录每次指数计算的分位锚点，用于 EWMA 平滑和展示分映射 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | history_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | index_type | VARCHAR | NO | 指数类型：WBI/NCI/RS/MS/ML |
+| 4 | calc_time | TIMESTAMPTZ | NO | 计算时间 |
+| 5 | percentile_5 | NUMERIC | YES | 原始 P5 分位值 |
+| 6 | percentile_95 | NUMERIC | YES | 原始 P95 分位值 |
+| 7 | percentile_5_smoothed | NUMERIC | YES | EWMA 平滑后 P5 |
+| 8 | percentile_95_smoothed | NUMERIC | YES | EWMA 平滑后 P95 |
+| 9 | record_count | INTEGER | YES | 参与计算的记录数 |
+| 10 | min_raw_score | NUMERIC | YES | 原始分最小值 |
+| 11 | max_raw_score | NUMERIC | YES | 原始分最大值 |
+| 12 | avg_raw_score | NUMERIC | YES | 原始分平均值 |
+| 13 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+
+## 业务口径
+
+- 每次指数计算时，先从本表取上一次的 smoothed 值作为 EWMA 基准
+- 新 smoothed = alpha × 本次原始分位 + (1 - alpha) × 上次 smoothed
+- RS/MS/ML 展示分均走分位映射，OS 不走分位映射
+- 分位历史按 `index_type` 隔离，各指数独立维护
+
+## 使用说明
+
+```sql
+-- 查询 RS 指数最近一次分位锚点
+SELECT *
+FROM billiards_dws.dws_index_percentile_history
+WHERE index_type = 'RS'
+ORDER BY calc_time DESC
+LIMIT 1;
+```
--- a/docs/bd_manual/dws/BD_manual_dws_member_assistant_intimacy.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_assistant_intimacy.md
@@ -0,0 +1,66 @@
+# dws_member_assistant_intimacy 客户-助教亲密度指数表（WBI）
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_member_assistant_intimacy |
+| 主键 | intimacy_id |
+| 唯一键 | (site_id, member_id, assistant_id) |
+| 数据来源 | dwd_assistant_service_log |
+| 更新频率 | 建议每4小时 |
+| 说明 | WBI 亲密度指数，衡量客户与助教之间的服务关系紧密程度 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | intimacy_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | tenant_id | BIGINT | NO | 租户ID |
+| 4 | member_id | BIGINT | NO | 会员ID |
+| 5 | assistant_id | BIGINT | NO | 助教ID |
+| 6 | session_count | INTEGER | NO | 总服务次数 |
+| 7 | total_duration_minutes | INTEGER | NO | 总服务时长（分钟） |
+| 8 | basic_session_count | INTEGER | NO | 基础课服务次数 |
+| 9 | incentive_session_count | INTEGER | NO | 附加课服务次数 |
+| 10 | days_since_last_session | INTEGER | YES | 距最近服务天数 |
+| 11 | attributed_recharge_count | INTEGER | NO | 归因充值次数 |
+| 12 | attributed_recharge_amount | NUMERIC | NO | 归因充值金额 |
+| 13 | score_frequency | NUMERIC | YES | 频率维度得分 |
+| 14 | score_recency | NUMERIC | YES | 近期维度得分 |
+| 15 | score_recharge | NUMERIC | YES | 充值维度得分 |
+| 16 | score_duration | NUMERIC | YES | 时长维度得分 |
+| 17 | burst_multiplier | NUMERIC | YES | 爆发乘数（短期高频加成） |
+| 18 | raw_score | NUMERIC | YES | 原始分 |
+| 19 | display_score | NUMERIC | YES | 展示分（分位映射后） |
+| 20 | calc_time | TIMESTAMPTZ | NO | 计算时间 |
+| 21 | calc_version | INTEGER | NO | 计算版本号 |
+| 22 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 23 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 业务口径
+
+- WBI = f(频率, 近期, 充值, 时长) × 爆发乘数
+- 展示分走分位映射（P5~P95 截断后线性映射到 0~100）
+- 同 site_id 删除后重写（覆盖写入）
+
+## 使用说明
+
+```sql
+-- 查询某助教的客户亲密度排行
+SELECT member_id, display_score, session_count
+FROM billiards_dws.dws_member_assistant_intimacy
+WHERE site_id = :site_id AND assistant_id = :assistant_id
+ORDER BY display_score DESC;
+```
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅（按批次重算覆盖） |
+| 依赖参数 | cfg_index_parameters（WBI） |
--- a/docs/bd_manual/dws/BD_manual_dws_member_assistant_relation_index.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_assistant_relation_index.md
@@ -0,0 +1,64 @@
+# dws_member_assistant_relation_index 客户-助教关系指数表
+
+> 生成时间：2026-02-08 | 更新时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_member_assistant_relation_index |
+| 主键 | relation_id |
+| 唯一键 | (site_id, member_id, assistant_id) |
+| 数据来源 | dwd_assistant_service_log、dws_ml_manual_order_alloc |
+| 更新频率 | 建议每4小时 |
+| 说明 | 单任务产出 RS/OS/MS/ML 四类关系指标 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | relation_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | tenant_id | BIGINT | NO | 租户ID |
+| 4 | member_id | BIGINT | NO | 会员ID |
+| 5 | assistant_id | BIGINT | NO | 助教ID |
+| 6 | session_count | INTEGER | NO | 总服务次数 |
+| 7 | total_duration_minutes | INTEGER | NO | 总服务时长（分钟） |
+| 8 | basic_session_count | INTEGER | NO | 基础课服务次数 |
+| 9 | incentive_session_count | INTEGER | NO | 附加课服务次数 |
+| 10 | days_since_last_session | INTEGER | YES | 距最近服务天数 |
+| 11 | rs_f | NUMERIC | NO | RS 频率分量 |
+| 12 | rs_d | NUMERIC | NO | RS 时长分量 |
+| 13 | rs_r | NUMERIC | NO | RS 近期分量 |
+| 14 | rs_raw | NUMERIC | NO | RS 原始分（关系强度/熟悉度） |
+| 15 | rs_display | NUMERIC | NO | RS 展示分（分位映射后） |
+| 16 | os_share | NUMERIC | NO | OS 归属份额（0~1） |
+| 17 | os_label | VARCHAR | NO | OS 归属标签：UNASSIGNED/MAIN/COMANAGE/POOL |
+| 18 | os_rank | INTEGER | YES | OS 同 member 下归属排序 |
+| 19 | ms_f_short | NUMERIC | NO | MS 短期频率分量 |
+| 20 | ms_f_long | NUMERIC | NO | MS 长期频率分量 |
+| 21 | ms_raw | NUMERIC | NO | MS 原始分（升温动量） |
+| 22 | ms_display | NUMERIC | NO | MS 展示分（分位映射后） |
+| 23 | ml_order_count | INTEGER | NO | ML 台账归因订单数 |
+| 24 | ml_allocated_amount | NUMERIC | NO | ML 台账分摊金额 |
+| 25 | ml_raw | NUMERIC | NO | ML 原始分（付费关联） |
+| 26 | ml_display | NUMERIC | NO | ML 展示分（分位映射后） |
+| 27 | calc_time | TIMESTAMPTZ | NO | 计算时间 |
+| 28 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 29 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 业务口径
+
+1. ML 唯一真源为 `dws_ml_manual_order_alloc`，无台账时 `ml_raw=0`。  
+2. `dwd_recharge_order` 的 last-touch 仅保留备用路径（默认关闭）。  
+3. `RS/MS/ML` 展示分均走分位映射，且分位历史按 `index_type` 隔离。  
+4. OS 不走分位映射，直接输出 `os_share + os_label + os_rank`。  
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅（按批次重算覆盖） |
+| 覆盖写入 | 同 site_id 删除后重写 |
+| 依赖参数 | cfg_index_parameters（RS/OS/MS/ML） |
--- a/docs/bd_manual/dws/BD_manual_dws_member_consumption_summary.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_consumption_summary.md
@@ -0,0 +1,102 @@
+# dws_member_consumption_summary 会员消费汇总表
+
+> 生成时间：2026-02-03 | 更新时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| 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 |
--- a/docs/bd_manual/dws/BD_manual_dws_member_newconv_index.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_newconv_index.md
@@ -0,0 +1,80 @@
+# dws_member_newconv_index 新客转化指数表（NCI）
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_member_newconv_index |
+| 主键 | newconv_id |
+| 唯一键 | (site_id, member_id) |
+| 数据来源 | dim_member + dwd_settlement_head + dwd_recharge_order |
+| 更新频率 | 建议每2小时 |
+| 说明 | NCI 新客转化指数，评估新注册会员的转化潜力和进展 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | newconv_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | tenant_id | BIGINT | NO | 租户ID |
+| 4 | member_id | BIGINT | NO | 会员ID |
+| 5 | status | VARCHAR | YES | 转化状态 |
+| 6 | segment | VARCHAR | YES | 客户分群 |
+| 7 | member_create_time | TIMESTAMPTZ | YES | 会员注册时间 |
+| 8 | first_visit_time | TIMESTAMPTZ | YES | 首次到店时间 |
+| 9 | last_visit_time | TIMESTAMPTZ | YES | 最近到店时间 |
+| 10 | last_recharge_time | TIMESTAMPTZ | YES | 最近充值时间 |
+| 11 | t_v | NUMERIC | YES | 注册到首次到店天数 |
+| 12 | t_r | NUMERIC | YES | 注册到首次充值天数 |
+| 13 | t_a | NUMERIC | YES | 注册到活跃天数 |
+| 14 | visits_14d | INTEGER | NO | 近14天到店次数 |
+| 15 | visits_60d | INTEGER | NO | 近60天到店次数 |
+| 16 | visits_total | INTEGER | NO | 累计到店次数 |
+| 17 | spend_30d | NUMERIC | NO | 近30天消费金额 |
+| 18 | spend_180d | NUMERIC | NO | 近180天消费金额 |
+| 19 | sv_balance | NUMERIC | NO | 储值卡余额 |
+| 20 | recharge_60d_amt | NUMERIC | NO | 近60天充值金额 |
+| 21 | interval_count | INTEGER | NO | 到店间隔计数 |
+| 22 | need_new | NUMERIC | YES | 需求度子分 |
+| 23 | salvage_new | NUMERIC | YES | 挽救度子分 |
+| 24 | recharge_new | NUMERIC | YES | 充值度子分 |
+| 25 | value_new | NUMERIC | YES | 价值度子分 |
+| 26 | welcome_new | NUMERIC | YES | 欢迎度子分 |
+| 27 | raw_score_welcome | NUMERIC | YES | 欢迎阶段原始分 |
+| 28 | raw_score_convert | NUMERIC | YES | 转化阶段原始分 |
+| 29 | raw_score | NUMERIC | YES | 综合原始分 |
+| 30 | display_score_welcome | NUMERIC | YES | 欢迎阶段展示分 |
+| 31 | display_score_convert | NUMERIC | YES | 转化阶段展示分 |
+| 32 | display_score | NUMERIC | YES | 综合展示分 |
+| 33 | last_wechat_touch_time | TIMESTAMPTZ | YES | 最近微信触达时间 |
+| 34 | calc_time | TIMESTAMPTZ | NO | 计算时间 |
+| 35 | calc_version | INTEGER | NO | 计算版本号 |
+| 36 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 37 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 业务口径
+
+- NCI 分为两阶段：欢迎阶段（welcome）和转化阶段（convert）
+- 展示分走分位映射（P5~P95 截断后线性映射到 0~100）
+- 同 site_id 删除后重写（覆盖写入）
+
+## 使用说明
+
+```sql
+-- 查询高转化潜力新客（展示分 > 70）
+SELECT member_id, status, segment, display_score
+FROM billiards_dws.dws_member_newconv_index
+WHERE site_id = :site_id AND display_score > 70
+ORDER BY display_score DESC;
+```
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅（按批次重算覆盖） |
+| 依赖参数 | cfg_index_parameters（NCI） |
--- a/docs/bd_manual/dws/BD_manual_dws_member_recall_index.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_recall_index.md
@@ -0,0 +1,64 @@
+# dws_member_recall_index 会员召回指数表
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_member_recall_index |
+| 主键 | recall_id |
+| 唯一键 | (site_id, member_id) |
+| 数据来源 | dwd_settlement_head + dwd_recharge_order + dim_member |
+| 更新频率 | 建议每2小时 |
+| 说明 | 召回指数，评估会员的回访紧迫度，用于召回优先级排序 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | recall_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | tenant_id | BIGINT | NO | 租户ID |
+| 4 | member_id | BIGINT | NO | 会员ID |
+| 5 | days_since_last_visit | INTEGER | YES | 距最近到店天数 |
+| 6 | visit_interval_median | NUMERIC | YES | 到店间隔中位数（天） |
+| 7 | visit_interval_mad | NUMERIC | YES | 到店间隔 MAD（中位绝对偏差） |
+| 8 | days_since_first_visit | INTEGER | YES | 距首次到店天数 |
+| 9 | days_since_last_recharge | INTEGER | YES | 距最近充值天数 |
+| 10 | visits_last_14_days | INTEGER | NO | 近14天到店次数 |
+| 11 | visits_last_60_days | INTEGER | NO | 近60天到店次数 |
+| 12 | score_overdue | NUMERIC | YES | 逾期子分（超出正常间隔的程度） |
+| 13 | score_new_bonus | NUMERIC | YES | 新客加分（新注册会员额外权重） |
+| 14 | score_recharge_bonus | NUMERIC | YES | 充值加分（有充值记录额外权重） |
+| 15 | score_hot_drop | NUMERIC | YES | 热度衰减分（近期活跃度下降惩罚） |
+| 16 | raw_score | NUMERIC | YES | 原始分 |
+| 17 | display_score | NUMERIC | YES | 展示分（分位映射后） |
+| 18 | calc_time | TIMESTAMPTZ | NO | 计算时间 |
+| 19 | calc_version | INTEGER | NO | 计算版本号 |
+| 20 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 21 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 业务口径
+
+- 召回分 = score_overdue + score_new_bonus + score_recharge_bonus - score_hot_drop
+- 逾期判断基于 visit_interval_median + MAD 的统计偏差
+- 展示分走分位映射（P5~P95 截断后线性映射到 0~100）
+
+## 使用说明
+
+```sql
+-- 查询需要召回的会员（展示分 > 60，按紧迫度排序）
+SELECT member_id, days_since_last_visit, display_score
+FROM billiards_dws.dws_member_recall_index
+WHERE site_id = :site_id AND display_score > 60
+ORDER BY display_score DESC;
+```
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅（按批次重算覆盖） |
+| 依赖参数 | cfg_index_parameters（RECALL） |
--- a/docs/bd_manual/dws/BD_manual_dws_member_visit_detail.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_visit_detail.md
@@ -0,0 +1,130 @@
+# 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,
+    create_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 + adjust_amount + rounding_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
+WHERE is_delete = 0
+GROUP BY order_settle_id;
+```
+
+### 台费时长：dwd_table_fee_log
+```sql
+SELECT
+    order_settle_id,
+    SUM(COALESCE(real_table_use_seconds, 0)) AS table_use_seconds
+FROM billiards_dwd.dwd_table_fee_log
+WHERE COALESCE(is_delete, 0) = 0
+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, dwd_table_fee_log, dim_table, dim_member |
--- a/docs/bd_manual/dws/BD_manual_dws_member_winback_index.md
+++ b/docs/bd_manual/dws/BD_manual_dws_member_winback_index.md
@@ -0,0 +1,79 @@
+# dws_member_winback_index 会员赢回指数表（WBI）
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_member_winback_index |
+| 主键 | winback_id |
+| 唯一键 | (site_id, member_id) |
+| 数据来源 | dim_member + dwd_settlement_head + dwd_recharge_order |
+| 更新频率 | 建议每2小时 |
+| 说明 | 赢回指数，评估流失/沉睡会员的赢回价值和可能性 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | winback_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | tenant_id | BIGINT | NO | 租户ID |
+| 4 | member_id | BIGINT | NO | 会员ID |
+| 5 | status | VARCHAR | YES | 赢回状态 |
+| 6 | segment | VARCHAR | YES | 客户分群 |
+| 7 | member_create_time | TIMESTAMPTZ | YES | 会员注册时间 |
+| 8 | first_visit_time | TIMESTAMPTZ | YES | 首次到店时间 |
+| 9 | last_visit_time | TIMESTAMPTZ | YES | 最近到店时间 |
+| 10 | last_recharge_time | TIMESTAMPTZ | YES | 最近充值时间 |
+| 11 | t_v | NUMERIC | YES | 注册到首次到店天数 |
+| 12 | t_r | NUMERIC | YES | 注册到首次充值天数 |
+| 13 | t_a | NUMERIC | YES | 注册到活跃天数 |
+| 14 | visits_14d | INTEGER | NO | 近14天到店次数 |
+| 15 | visits_60d | INTEGER | NO | 近60天到店次数 |
+| 16 | visits_total | INTEGER | NO | 累计到店次数 |
+| 17 | spend_30d | NUMERIC | NO | 近30天消费金额 |
+| 18 | spend_180d | NUMERIC | NO | 近180天消费金额 |
+| 19 | sv_balance | NUMERIC | NO | 储值卡余额 |
+| 20 | recharge_60d_amt | NUMERIC | NO | 近60天充值金额 |
+| 21 | interval_count | INTEGER | NO | 到店间隔计数 |
+| 22 | overdue_old | NUMERIC | YES | 逾期子分 |
+| 23 | drop_old | NUMERIC | YES | 活跃度衰减子分 |
+| 24 | recharge_old | NUMERIC | YES | 充值价值子分 |
+| 25 | value_old | NUMERIC | YES | 历史价值子分 |
+| 26 | raw_score | NUMERIC | YES | 原始分 |
+| 27 | display_score | NUMERIC | YES | 展示分（分位映射后） |
+| 28 | last_wechat_touch_time | TIMESTAMPTZ | YES | 最近微信触达时间 |
+| 29 | calc_time | TIMESTAMPTZ | NO | 计算时间 |
+| 30 | calc_version | INTEGER | NO | 计算版本号 |
+| 31 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 32 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+| 33 | overdue_cdf_p | NUMERIC | YES | 逾期 CDF 概率值 |
+| 34 | ideal_interval_days | NUMERIC | YES | 理想到店间隔天数 |
+| 35 | ideal_next_visit_date | DATE | YES | 理想下次到店日期 |
+
+## 业务口径
+
+- 赢回分 = f(逾期, 活跃衰减, 充值价值, 历史价值)
+- 与 NCI（新客转化）互补：NCI 面向新客，WBI 面向老客/流失客
+- 展示分走分位映射（P5~P95 截断后线性映射到 0~100）
+- ideal_next_visit_date 基于历史到店间隔的统计分布预测
+
+## 使用说明
+
+```sql
+-- 查询高赢回价值的流失会员
+SELECT member_id, status, segment, display_score, ideal_next_visit_date
+FROM billiards_dws.dws_member_winback_index
+WHERE site_id = :site_id AND display_score > 60
+ORDER BY display_score DESC;
+```
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅（按批次重算覆盖） |
+| 依赖参数 | cfg_index_parameters（WBI） |
--- a/docs/bd_manual/dws/BD_manual_dws_ml_manual_order_alloc.md
+++ b/docs/bd_manual/dws/BD_manual_dws_ml_manual_order_alloc.md
@@ -0,0 +1,46 @@
+# dws_ml_manual_order_alloc ML人工台账分摊窄表
+
+> 生成时间：2026-02-08 | 更新时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_ml_manual_order_alloc |
+| 主键 | alloc_id |
+| 唯一键 | (site_id, external_id, assistant_id) |
+| 数据来源 | dws_ml_manual_order_source 拆分 |
+| 更新频率 | 每次导入后实时覆盖 |
+| 说明 | 关系指数 ML 的直接输入表 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | alloc_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | biz_date | DATE | NO | 业务日期 |
+| 4 | external_id | VARCHAR | NO | 订单ID |
+| 5 | member_id | BIGINT | NO | 会员ID（默认0） |
+| 6 | pay_time | TIMESTAMPTZ | NO | 支付时间 |
+| 7 | order_amount | NUMERIC | NO | 订单金额 |
+| 8 | assistant_id | BIGINT | NO | 归因助教ID |
+| 9 | assistant_name | VARCHAR | YES | 助教名称 |
+| 10 | share_ratio | NUMERIC | NO | 分摊比例（默认 1/N） |
+| 11 | allocated_amount | NUMERIC | NO | 分摊金额（order_amount × share_ratio） |
+| 12 | currency | VARCHAR | NO | 币种（默认 CNY） |
+| 13 | import_scope_key | VARCHAR | NO | 覆盖范围键（DAY/P30） |
+| 14 | import_batch_no | VARCHAR | NO | 导入批次号 |
+| 15 | import_file_name | VARCHAR | NO | 导入文件名 |
+| 16 | import_time | TIMESTAMPTZ | NO | 导入时间 |
+| 17 | import_user | VARCHAR | YES | 导入操作人 |
+| 18 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 19 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 生成规则
+
+1. 宽表每行提取非空助教列表。  
+2. 若助教数为 `N`，则每个助教 `share_ratio=1/N`。  
+3. 同一 `(site_id, external_id, assistant_id)` 重复导入时 upsert 覆盖。  
+4. 该表是 ML 主口径唯一真源。  
--- a/docs/bd_manual/dws/BD_manual_dws_ml_manual_order_source.md
+++ b/docs/bd_manual/dws/BD_manual_dws_ml_manual_order_source.md
@@ -0,0 +1,53 @@
+# dws_ml_manual_order_source ML人工台账宽表
+
+> 生成时间：2026-02-08 | 更新时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_ml_manual_order_source |
+| 主键 | source_id |
+| 唯一键 | (site_id, external_id, import_scope_key, row_no) |
+| 数据来源 | GUI 上传的人工台账 Excel |
+| 更新频率 | 按需导入 |
+| 说明 | 订单一行，支持最多5个助教字段 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | source_id | BIGSERIAL | NO | 自增主键 |
+| 2 | site_id | BIGINT | NO | 门店ID |
+| 3 | biz_date | DATE | NO | 业务日期 |
+| 4 | external_id | VARCHAR | NO | 订单ID（必填） |
+| 5 | member_id | BIGINT | NO | 会员ID（默认0） |
+| 6 | pay_time | TIMESTAMPTZ | NO | 支付时间 |
+| 7 | order_amount | NUMERIC | NO | 订单金额 |
+| 8 | currency | VARCHAR | NO | 币种（默认 CNY） |
+| 9 | assistant_id_1 | BIGINT | YES | 助教1 ID |
+| 10 | assistant_name_1 | VARCHAR | YES | 助教1 名称 |
+| 11 | assistant_id_2 | BIGINT | YES | 助教2 ID |
+| 12 | assistant_name_2 | VARCHAR | YES | 助教2 名称 |
+| 13 | assistant_id_3 | BIGINT | YES | 助教3 ID |
+| 14 | assistant_name_3 | VARCHAR | YES | 助教3 名称 |
+| 15 | assistant_id_4 | BIGINT | YES | 助教4 ID |
+| 16 | assistant_name_4 | VARCHAR | YES | 助教4 名称 |
+| 17 | assistant_id_5 | BIGINT | YES | 助教5 ID |
+| 18 | assistant_name_5 | VARCHAR | YES | 助教5 名称 |
+| 19 | import_batch_no | VARCHAR | NO | 导入批次号 |
+| 20 | import_file_name | VARCHAR | NO | 导入文件名 |
+| 21 | import_scope_key | VARCHAR | NO | 覆盖范围键 |
+| 22 | import_time | TIMESTAMPTZ | NO | 导入时间 |
+| 23 | import_user | VARCHAR | YES | 导入操作人 |
+| 24 | row_no | INTEGER | NO | Excel 行号 |
+| 25 | remark | TEXT | YES | 备注 |
+| 26 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 27 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 覆盖规则
+
+1. 30天内：按 `site_id + biz_date` 日覆盖。  
+2. 超过30天：按固定纪元 `2026-01-01` 划分 30 天桶覆盖。  
+3. 覆盖策略：先删后写（整批重写）。  
--- a/docs/bd_manual/dws/BD_manual_dws_order_summary.md
+++ b/docs/bd_manual/dws/BD_manual_dws_order_summary.md
@@ -0,0 +1,84 @@
+# dws_order_summary 订单汇总宽表
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 表名 | dws_order_summary |
+| 主键 | (site_id, order_settle_id) |
+| 数据来源 | dwd_settlement_head + 关联明细表 |
+| 更新频率 | 每小时增量更新 |
+| 说明 | 以订单为粒度的汇总宽表，整合台费、助教、商品、团购、优惠、支付、流水等维度 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | site_id | BIGINT | NO | 门店ID（联合主键） |
+| 2 | order_settle_id | BIGINT | NO | 结算单ID（联合主键） |
+| 3 | order_trade_no | VARCHAR | YES | 订单交易号 |
+| 4 | order_date | DATE | NO | 订单日期（优先 pay_time，其次 create_time） |
+| 5 | tenant_id | BIGINT | NO | 租户ID |
+| 6 | member_id | BIGINT | YES | 会员ID（NULL 或 0 为散客） |
+| 7 | member_flag | BOOLEAN | NO | 是否会员订单 |
+| 8 | recharge_order_flag | BOOLEAN | NO | 充值订单标记（消费金额=0 且实付>0） |
+| 9 | item_count | INTEGER | NO | 订单项数 |
+| 10 | total_item_quantity | INTEGER | NO | 订单项总数量 |
+| 11 | table_fee_amount | NUMERIC | NO | 台费金额 |
+| 12 | assistant_service_amount | NUMERIC | NO | 助教服务金额 |
+| 13 | goods_amount | NUMERIC | NO | 商品金额 |
+| 14 | group_amount | NUMERIC | NO | 团购金额 |
+| 15 | total_coupon_deduction | NUMERIC | NO | 优惠券抵扣总额 |
+| 16 | member_discount_amount | NUMERIC | NO | 会员折扣金额 |
+| 17 | manual_discount_amount | NUMERIC | NO | 手动折扣金额 |
+| 18 | order_original_amount | NUMERIC | NO | 原价估算（实付+优惠/抵扣） |
+| 19 | order_final_amount | NUMERIC | NO | 最终应付金额 |
+| 20 | stored_card_deduct | NUMERIC | NO | 储值卡抵扣金额 |
+| 21 | external_paid_amount | NUMERIC | NO | 外部支付金额（实付-卡类抵扣） |
+| 22 | total_paid_amount | NUMERIC | NO | 总实付金额 |
+| 23 | book_table_flow | NUMERIC | NO | 台费流水 |
+| 24 | book_assistant_flow | NUMERIC | NO | 助教流水 |
+| 25 | book_goods_flow | NUMERIC | NO | 商品流水 |
+| 26 | book_group_flow | NUMERIC | NO | 团购流水 |
+| 27 | book_order_flow | NUMERIC | NO | 订单总流水（台费+助教+商品+团购） |
+| 28 | order_effective_consume_cash | NUMERIC | NO | 有效消费现金 |
+| 29 | order_effective_recharge_cash | NUMERIC | NO | 有效充值现金 |
+| 30 | order_effective_flow | NUMERIC | NO | 有效流水 |
+| 31 | refund_amount | NUMERIC | NO | 退款金额 |
+| 32 | net_income | NUMERIC | NO | 净收入（实付-退款） |
+| 33 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 34 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+
+## 业务口径
+
+- order_date 优先取 pay_time，其次 create_time
+- recharge_order_flag：消费金额=0 且实付>0 时标记为充值订单
+- order_original_amount = 实付 + 优惠/抵扣
+- book_order_flow = 台费 + 助教 + 商品 + 团购
+- net_income = total_paid_amount - refund_amount
+
+## 使用说明
+
+```sql
+-- 按日统计订单概况
+SELECT 
+    order_date,
+    COUNT(*) AS order_count,
+    SUM(order_final_amount) AS total_amount,
+    SUM(net_income) AS net_income,
+    SUM(CASE WHEN member_flag THEN 1 ELSE 0 END) AS member_orders
+FROM billiards_dws.dws_order_summary
+WHERE site_id = :site_id
+GROUP BY order_date
+ORDER BY order_date DESC;
+```
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯 |
+| 依赖表 | dwd_settlement_head, dwd_table_fee_log, dwd_assistant_service_log, dwd_store_goods_sale, dwd_groupbuy_redemption, dwd_payment, dwd_refund |
--- a/docs/bd_manual/dws/BD_manual_dws_platform_settlement.md
+++ b/docs/bd_manual/dws/BD_manual_dws_platform_settlement.md
@@ -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手工导入，需从平台后台导出 |
+| 处理 | 需要人工补录历史平台结算数据 |
--- a/docs/bd_manual/dws/BD_manual_v_member_recall_priority.md
+++ b/docs/bd_manual/dws/BD_manual_v_member_recall_priority.md
@@ -0,0 +1,69 @@
+# v_member_recall_priority 会员召回优先级视图
+
+> 生成时间：2026-02-13
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards_dws |
+| 对象名 | v_member_recall_priority |
+| 类型 | VIEW（视图） |
+| 数据来源 | dws_member_newconv_index UNION dws_member_winback_index |
+| 说明 | 合并新客转化（NCI）和赢回（WBI）指数，统一召回优先级排序 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | site_id | BIGINT | YES | 门店ID |
+| 2 | tenant_id | BIGINT | YES | 租户ID |
+| 3 | member_id | BIGINT | YES | 会员ID |
+| 4 | index_type | VARCHAR | YES | 指数类型：NCI（新客转化）/ WBI（赢回） |
+| 5 | status | VARCHAR | YES | 状态 |
+| 6 | segment | VARCHAR | YES | 客户分群 |
+| 7 | member_create_time | TIMESTAMPTZ | YES | 会员注册时间 |
+| 8 | first_visit_time | TIMESTAMPTZ | YES | 首次到店时间 |
+| 9 | last_visit_time | TIMESTAMPTZ | YES | 最近到店时间 |
+| 10 | last_recharge_time | TIMESTAMPTZ | YES | 最近充值时间 |
+| 11 | t_v | NUMERIC | YES | 注册到首次到店天数 |
+| 12 | t_r | NUMERIC | YES | 注册到首次充值天数 |
+| 13 | t_a | NUMERIC | YES | 注册到活跃天数 |
+| 14 | visits_14d | INTEGER | YES | 近14天到店次数 |
+| 15 | visits_60d | INTEGER | YES | 近60天到店次数 |
+| 16 | visits_total | INTEGER | YES | 累计到店次数 |
+| 17 | spend_30d | NUMERIC | YES | 近30天消费金额 |
+| 18 | spend_180d | NUMERIC | YES | 近180天消费金额 |
+| 19 | sv_balance | NUMERIC | YES | 储值卡余额 |
+| 20 | recharge_60d_amt | NUMERIC | YES | 近60天充值金额 |
+| 21 | need_new | NUMERIC | YES | NCI 需求度子分 |
+| 22 | salvage_new | NUMERIC | YES | NCI 挽救度子分 |
+| 23 | recharge_new | NUMERIC | YES | NCI 充值度子分 |
+| 24 | value_new | NUMERIC | YES | NCI 价值度子分 |
+| 25 | welcome_new | NUMERIC | YES | NCI 欢迎度子分 |
+| 26 | raw_score_welcome | NUMERIC | YES | 欢迎阶段原始分 |
+| 27 | raw_score_convert | NUMERIC | YES | 转化阶段原始分 |
+| 28 | raw_score | NUMERIC | YES | 综合原始分 |
+| 29 | display_score_welcome | NUMERIC | YES | 欢迎阶段展示分 |
+| 30 | display_score_convert | NUMERIC | YES | 转化阶段展示分 |
+| 31 | display_score | NUMERIC | YES | 综合展示分 |
+| 32 | last_wechat_touch_time | TIMESTAMPTZ | YES | 最近微信触达时间 |
+| 33 | calc_time | TIMESTAMPTZ | YES | 计算时间 |
+
+## 业务口径
+
+- 本视图将 NCI（新客转化）和 WBI（赢回）两张表 UNION 合并
+- 通过 `index_type` 字段区分来源
+- NCI 子分字段在 WBI 行中为 NULL，反之亦然
+- 按 `display_score DESC` 排序即可获得统一的召回优先级
+
+## 使用说明
+
+```sql
+-- 获取综合召回优先级列表
+SELECT member_id, index_type, status, segment, display_score
+FROM billiards_dws.v_member_recall_priority
+WHERE site_id = :site_id
+ORDER BY display_score DESC
+LIMIT 50;
+```