在准备环境前提交次全部更改。

apps/etl/connectors/feiqiu/docs/database/overview/dws_tables_dictionary.md

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

apps/etl/connectors/feiqiu/docs/database/overview/ods_tables_dictionary.md

@@ -0,0 +1,124 @@
+# ODS 数据字典
+
+## 概述
+
+ODS（Operational Data Store）层是数据仓库的操作数据存储层，保留从上游 SaaS API 抽取的原始数据。所有 ODS 表位于 `ods` schema，字段以 API 导出原样为主，ETL 补充 `content_hash`、`source_file`、`source_endpoint`、`fetched_at`、`payload` 等元数据字段。
+
+- Schema：`ods`
+- 来源 DDL：`database/schema_ODS_doc.sql`
+- 主键模式：所有 ODS 表均采用 `(业务主键, content_hash)` 复合主键，用于 SCD 变更检测
+- 表级文档：`docs/database/ODS/main/BD_manual_{表名}.md`
+- 字段映射文档：`docs/database/ODS/mappings/mapping_{API端点名}_{表名}.md`
+
+## 表清单
+
+| 序号 | 表名 | 中文说明 | 主键 | 记录数 | 数据来源（API 端点） |
+|------|------|----------|------|-------:|----------------------|
+| 1 | `assistant_accounts_master` | 助教档案主数据 | id, content_hash | 223 | `PersonnelManagement/SearchAssistantInfo` |
+| 2 | `assistant_cancellation_records` | 助教作废/取消记录 | id, content_hash | 100 | `AssistantPerformance/GetAbolitionAssistant` |
+| 3 | `assistant_service_records` | 助教服务流水 | id, content_hash | 10,203 | `AssistantPerformance/GetOrderAssistantDetails` |
+| 4 | `goods_stock_movements` | 商品库存变动流水 | sitegoodsstockid, content_hash | 35,005 | `GoodsStockManage/QueryGoodsOutboundReceipt` |
+| 5 | `goods_stock_summary` | 商品库存汇总 | sitegoodsid, content_hash | 867 | `TenantGoods/GetGoodsStockReport` |
+| 6 | `group_buy_packages` | 团购套餐主数据 | id, content_hash | 52 | `PackageCoupon/QueryPackageCouponList` |
+| 7 | `group_buy_redemption_records` | 团购核销记录 | id, content_hash | 19,532 | `Site/GetSiteTableUseDetails` |
+| 8 | `member_balance_changes` | 会员余额变更流水 | id, content_hash | 7,366 | `MemberProfile/GetMemberCardBalanceChange` |
+| 9 | `member_profiles` | 会员档案/会员账户信息 | id, content_hash | 1,202 | `MemberProfile/GetTenantMemberList` |
+| 10 | `member_stored_value_cards` | 会员储值/卡券账户列表 | id, content_hash | 2,008 | `MemberProfile/GetTenantMemberCardList` |
+| 11 | `payment_transactions` | 支付流水 | id, content_hash | 24,674 | `PayLog/GetPayLogListPage` |
+| 12 | `platform_coupon_redemption_records` | 平台券核销/使用记录 | id, content_hash | 18,125 | `Promotion/GetOfflineCouponConsumePageList` |
+| 13 | `recharge_settlements` | 充值结算记录 | id, content_hash | 3,333 | `Site/GetRechargeSettleList` |
+| 14 | `refund_transactions` | 退款流水 | id, content_hash | 50 | `Order/GetRefundPayLogList` |
+| 15 | `settlement_records` | 结账/结算记录 | id, content_hash | 55,137 | `Site/GetAllOrderSettleList` |
+| 16 | `settlement_ticket_details` | 结算小票明细 | ordersettleid, content_hash | 193 | `Order/GetOrderSettleTicketNew` |
+| 17 | `site_tables_master` | 门店桌台主数据 | id, content_hash | 949 | `Table/GetSiteTables` |
+| 18 | `stock_goods_category_tree` | 商品分类树 | id, content_hash | 9 | `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
+| 19 | `store_goods_master` | 门店商品主数据 | id, content_hash | 1,398 | `TenantGoods/GetGoodsInventoryList` |
+| 20 | `store_goods_sales_records` | 门店商品销售流水 | id, content_hash | 17,563 | `TenantGoods/GetGoodsSalesList` |
+| 21 | `table_fee_discount_records` | 台费折扣记录 | id, content_hash | 3,100 | `Site/GetTaiFeeAdjustList` |
+| 22 | `table_fee_transactions` | 台费流水 | id, content_hash | 28,881 | `Site/GetSiteTableOrderDetails` |
+| 23 | `tenant_goods_master` | 租户商品主数据 | id, content_hash | 176 | `TenantGoods/QueryTenantGoods` |
+
+## 按业务域分类
+
+### 会员域
+
+| 表名 | 说明 | 记录数 |
+|------|------|-------:|
+| `member_profiles` | 会员档案/会员账户信息 | 1,202 |
+| `member_stored_value_cards` | 会员储值/卡券账户列表 | 2,008 |
+| `member_balance_changes` | 会员余额变更流水 | 7,366 |
+
+### 助教域
+
+| 表名 | 说明 | 记录数 |
+|------|------|-------:|
+| `assistant_accounts_master` | 助教档案主数据 | 223 |
+| `assistant_service_records` | 助教服务流水 | 10,203 |
+| `assistant_cancellation_records` | 助教作废/取消记录 | 100 |
+
+### 订单/结算域
+
+| 表名 | 说明 | 记录数 |
+|------|------|-------:|
+| `settlement_records` | 结账/结算记录 | 55,137 |
+| `settlement_ticket_details` | 结算小票明细 | 193 |
+| `payment_transactions` | 支付流水 | 24,674 |
+| `refund_transactions` | 退款流水 | 50 |
+| `recharge_settlements` | 充值结算记录 | 3,333 |
+
+### 台费域
+
+| 表名 | 说明 | 记录数 |
+|------|------|-------:|
+| `table_fee_transactions` | 台费流水 | 28,881 |
+| `table_fee_discount_records` | 台费折扣记录 | 3,100 |
+| `site_tables_master` | 门店桌台主数据 | 949 |
+
+### 商品/库存域
+
+| 表名 | 说明 | 记录数 |
+|------|------|-------:|
+| `tenant_goods_master` | 租户商品主数据 | 176 |
+| `store_goods_master` | 门店商品主数据 | 1,398 |
+| `store_goods_sales_records` | 门店商品销售流水 | 17,563 |
+| `stock_goods_category_tree` | 商品分类树 | 9 |
+| `goods_stock_summary` | 商品库存汇总 | 867 |
+| `goods_stock_movements` | 商品库存变动流水 | 35,005 |
+
+### 团购/平台域
+
+| 表名 | 说明 | 记录数 |
+|------|------|-------:|
+| `group_buy_packages` | 团购套餐主数据 | 52 |
+| `group_buy_redemption_records` | 团购核销记录 | 19,532 |
+| `platform_coupon_redemption_records` | 平台券核销/使用记录 | 18,125 |
+
+---
+
+## ETL 元数据字段说明
+
+所有 ODS 表均包含以下 ETL 补充字段：
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `content_hash` | TEXT | 对业务字段计算 SHA256，作为复合主键的一部分，用于 SCD 变更检测 |
+| `source_file` | TEXT | 数据来源文件名（如 `member_profiles.json`） |
+| `source_endpoint` | TEXT | 数据来源 API 端点路径 |
+| `fetched_at` | TIMESTAMPTZ | 数据抓取/入库时间戳 |
+| `payload` | JSONB | 完整原始 JSON 记录快照，用于数据回溯 |
+
+## 数据更新策略
+
+| 更新方式 | 说明 |
+|----------|------|
+| 全量抓取 | 主数据表（`*_master`、`*_profiles`、`*_packages`、`*_tree`）每次全量拉取 |
+| 增量抓取 | 流水/事实表（`*_records`、`*_transactions`、`*_changes`）按时间窗口增量拉取 |
+| 幂等入库 | 通过 `(业务主键, content_hash)` 复合主键实现 upsert，相同内容不重复写入 |
+
+## 相关文档
+
+- 表级文档：[`docs/database/ODS/main/`](../ODS/main/) — 每张表的详细字段说明
+- 字段映射：[`docs/database/ODS/mappings/`](../ODS/mappings/) — API JSON → ODS 字段映射
+- DDL 定义：[`database/schema_ODS_doc.sql`](../../database/schema_ODS_doc.sql)
+- DWD 数据字典：[`docs/database/overview/dwd_main_tables_dictionary.md`](dwd_main_tables_dictionary.md)
+- DWS 数据字典：[`docs/database/overview/dws_tables_dictionary.md`](dws_tables_dictionary.md)