root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
79f9a0e1daac0978a417b96b56bc9e15b6b9791b
Neo-ZQYY/.kiro/steering/dws-doc-authority.md

15 KiB
Raw Blame History

inclusion, fileMatchPattern, name, description
inclusion fileMatchPattern name description
fileMatch **/tasks/**,**/loaders/**,**/scd/**,**/dws/**,**/dwd/**,**/quality/**,**/business-rules/**,**/schemas/**,**/routers/**,**/financial*,**/settlement*,**/consume*,**/accounting*,**/salary*,**/assistant*,**/member*,**/index*,**/winback*,**/newconv*,**/relation_index*,**/spending*,**/stock*,**/finance_*,**/income_*,**/discount_*,**/order_contribution*,**/cfg_*,**/orchestration/**,**/config/** dws-doc-authority DWS 层权威规范。涉及 ETL 任务/财务/结算/消费/助教/会员/指数/统计/配置相关文件时自动加载。

DWS 层权威规范（强制优先参考）

DWS（Data Warehouse Summary）层从 DWD 明细层按业务维度聚合计算，输出汇总统计表，服务于助教业绩、会员分析、财务统计、指数算法等业务场景。

DWD-DOC（docs/reports/DWD-DOC/）中的强制规则在 DWS 层同样生效，本文档不重复列出。两者冲突时以 DWD-DOC 为准。

一、任务体系（19 个已注册任务）

1.1 助教业绩域（6 个）

任务代码 目标表 粒度 核心指标
DWS_ASSISTANT_DAILY dws_assistant_daily_detail 日期+助教 服务次数/时长/金额、去重客户数、废除统计、惩罚检测
DWS_ASSISTANT_MONTHLY dws_assistant_monthly_summary 月份+助教 月度累计、有效业绩、档位匹配、排名（考虑并列）
DWS_ASSISTANT_CUSTOMER dws_assistant_customer_stats 日期+助教+会员 全量累计、6 个滚动窗口（7/10/15/30/60/90 天）、活跃度
DWS_ASSISTANT_SALARY dws_assistant_salary_calc 月份+助教 课时收入、奖金明细、应发工资、假期
DWS_ASSISTANT_FINANCE dws_assistant_finance_analysis 日期+助教 日度收入、日均成本、毛利润、毛利率
DWS_ASSISTANT_ORDER_CONTRIBUTION dws_assistant_order_contribution 日期+助教 订单总流水、净流水、时效贡献、时效净贡献

1.2 会员分析域（2 个）

任务代码 目标表 粒度 核心指标
DWS_MEMBER_CONSUMPTION dws_member_consumption_summary 日期+会员 全量累计消费、6 个滚动窗口、卡余额、活跃度、客户分层
DWS_MEMBER_VISIT dws_member_visit_detail 日期+会员+结账单 消费金额拆分、支付方式拆分、台桌时长、助教服务明细（JSON）

1.3 财务统计域（4 个）

任务代码 目标表 粒度 核心指标
DWS_FINANCE_DAILY dws_finance_daily_summary 日期 发生额、优惠合计、确认收入、现金流入/流出/净变动、卡消费、充值统计
DWS_FINANCE_RECHARGE dws_finance_recharge_summary 日期 充值笔数/总额、首充/续充拆分、去重会员数、全店卡余额快照
DWS_FINANCE_INCOME_STRUCTURE dws_finance_income_structure 日期+收入类型 按收入类型（台费/商品/助教基础课/附加课）和区域分析
DWS_FINANCE_DISCOUNT_DETAIL dws_finance_discount_detail 日期+折扣类型 折扣类型拆分（GROUPBUY/VIP/ROUNDING/GIFT_CARD_*/BIG_CUSTOMER/OTHER）

1.4 库存汇总域（3 个）

任务代码 目标表 粒度 更新策略
DWS_GOODS_STOCK_DAILY dws_goods_stock_daily_summary 日期+商品 upsert
DWS_GOODS_STOCK_WEEKLY dws_goods_stock_weekly_summary ISO 周+商品 upsert
DWS_GOODS_STOCK_MONTHLY dws_goods_stock_monthly_summary 月份+商品 upsert

1.5 运维任务（2 个）

任务代码 说明
DWS_BUILD_ORDER_SUMMARY 构建订单汇总中间表 dws_order_summary
DWS_MAINTENANCE 统一维护：物化视图刷新 + 历史数据清理

二、强制规则（所有 session 生效）

2.1 幂等更新策略

  1. 汇总表默认 delete-before-insert：按日期范围 + site_id 先删后插，保证幂等
  2. 库存表使用 upsert：ON CONFLICT DO UPDATE，因库存快照需保留最新值
  3. 禁止 TRUNCATE：DWS 表数据量大，TRUNCATE 会导致全表锁定

2.2 课程类型与定价

  1. 课程类型通过 cfg_skill_type 映射：skill_id → course_type_code（BASE/BONUS/ROOM），禁止硬编码 skill_id 判断课程类型
  2. 定价通过 cfg_assistant_level_price 取值：按 SCD2 生效期 as-of join，禁止硬编码价格
  3. 包厢课统一价格：dws.salary.room_course_price = 138（元/小时），从配置读取

2.3 绩效档位与工资

  1. 绩效档位通过 cfg_performance_tier 取值：按有效业绩小时数匹配 [min_hours, max_hours) 区间
  2. 新入职折算规则：入职日期在当月 1 日后视为新入职，按日均业绩 × 30 定档；入职日期 > 25 日最高定档至 T2
  3. 奖金规则通过 cfg_bonus_rules 取值：SPRINT 类型不累计取最高档，TOP_RANK 类型按排名发放（第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元）
  4. 排名计算考虑并列：使用 calculate_rank_with_ties()，相同业绩小时数并列同名次

2.4 会员与散客

  1. 散客判断：member_id ≤ 0 为散客，不计入会员统计（但计入助教业绩）
  2. 客户分层规则：高价值（90 天 ≥ 3 次且 ≥ 1000 元）→ 中等（30 天内有消费）→ 低活跃（90 天内有但 30 天内无）→ 流失
  3. 会员信息一律通过 ID 关联维度表：结算单上所有会员冗余字段均不可靠（DQ-6/DQ-7），通过 member_id LEFT JOIN dwd.dim_member（scd2_is_current=1）

2.5 时间窗口与调度

  1. 滚动窗口标准集：7/10/15/30/60/90 天，使用 calculate_rolling_stats() 统一计算
  2. 月度任务宽限期：月初前 dws.monthly.prev_month_grace_days（默认 5）天可处理上月数据
  3. 工资计算周期：月初前 dws.salary.run_days（默认 5）天运行，超期需 dws.salary.allow_out_of_cycle = true

2.6 SCD2 维度取值

  1. 助教等级 as-of 取值：工资计算按月份生效期取历史版本，日度统计按 stat_date 取当日版本
  2. 会员卡余额 as-of 取值：通过 get_member_card_balance_asof() 按日期取快照

2.7 台桌分类

  1. cfg_area_category 仅精确匹配 + 兜底：2026-03-07 改版后无 LIKE 匹配，分类为 BILLIARD/SNOOKER/OTHER，BILLIARD_VIP 已废弃

三、指数算法体系

3.1 总览

指数 全称 输出表 作用
WBI Winback Index dws_member_winback_index 老客挽回优先级
NCI Newconv Index dws_member_newconv_index 新客转化优先级
RS Relation Index dws_member_assistant_relation_index 助教-会员关系强度
OS Ownership Index — 所有权指数
MS Maintenance Score — 维护分
ML Manual Ledger dws_ml_manual_order_alloc 人工台账（唯一真源）
SPI Spending Power Index dws_member_spending_power_index 消费力指数

3.2 WBI（老客挽回指数）强制规则

  1. 分项得分：Overdue（超期分，加权经验 CDF）+ Drop（降频分，近 14 天差值）+ Recharge（充值压力，衰减分）+ Value（价值分，对数压缩）
  2. Raw Score 公式：WBI_raw = w_over × overdue + w_drop × drop + w_re × recharge + w_value × value
  3. 近访抑制（Recency Suppression）：距今 < 14 天 suppression = 0（Hard floor）；14-17 天 Sigmoid 衰减
  4. 分流规则：STOP（距今 ≥ 60 天，高余额例外可选）→ NEW（到店 ≤ 2 次或首访 ≤ 30 天或充值未回访）→ OLD（其他）

3.3 NCI（新客转化指数）强制规则

  1. 分项得分：Welcome（欢迎分，首访/单访 3 天内触发）+ Need（转化紧迫度）+ Salvage（可救度，30-60 天线性衰减）+ Recharge/Value（同 WBI）
  2. 活跃抑制：新客近 14 天来店 ≥ 2 次且最近活跃，用 0.2 系数抑制转化召回分

3.4 指数参数配置

  1. 参数通过 cfg_index_parameters 加载：按 index_type 分组，支持 EWMA 平滑，禁止硬编码权重/阈值

四、配置表体系

4.1 绩效档位（dws.cfg_performance_tier）

档位 小时区间 抽成（元/小时） 打赏抽成 假期
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 起生效版本，历史版本通过 effective_from/effective_to SCD2 管理。

4.2 助教等级定价（dws.cfg_assistant_level_price）

等级 基础课（元/小时） 附加课（元/小时）
8（助教管理） 98 190
10（初级） 98 190
20（中级） 108 190
30（高级） 118 190
40（星级） 138 190

4.3 奖金规则（dws.cfg_bonus_rules）

规则类型 生效期 说明
SPRINT（冲刺奖金） ≤ 2026-02-28 不累计，取最高档
TOP_RANK（排名奖金） ≥ 2026-03-01 第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元

4.4 技能→课程类型映射（dws.cfg_skill_type）

课程类型代码 名称 定价规则
BASE 基础课（陪打/PD） 按等级定价 98-138 元/小时
BONUS 附加课（超休/CX） 固定 190 元/小时
ROOM 包厢课 统一 138 元/小时（dws.salary.room_course_price）

4.5 台桌分类（dws.cfg_area_category）

分类代码 说明 备注
BILLIARD 台球（含原 V1-V4） 2026-03-07 改版
SNOOKER 斯诺克（含原 V5） 2026-03-07 改版
OTHER 兜底 未匹配时归入

BILLIARD_VIP 已废弃（2026-03-07），禁止引用。

4.6 指数参数（dws.cfg_index_parameters）

按 index_type（WBI/NCI/RS/OS/MS/ML/SPI）分组加载，支持 EWMA 平滑。所有权重和阈值从此表读取，禁止硬编码。

五、BaseDwsTask 公共机制

5.1 时间分层（TimeLayer）

枚举值 范围 用途
LAST_2_DAYS 近 2 天 日度增量
LAST_1_MONTH 近 30 天 月度汇总
LAST_3_MONTHS 近 90 天 季度分析
LAST_6_MONTHS 近 6 个月（不含本月） 半年趋势
ALL 从 2000-01-01 起 全量重算

5.2 配置缓存（ConfigCache）

  • 类级别共享，TTL 5 分钟
  • 包含：绩效档位、等级定价、奖金规则、区域分类、技能类型
  • 支持 SCD2 生效期过滤

5.3 数据读写方法

  • iter_dwd_rows()：分批迭代 DWD 数据（默认 1000 行/批）
  • query_dwd()：直接执行任意 SQL
  • delete_existing_data()：按日期范围 + site_id 删除
  • bulk_insert()：批量插入
  • upsert()：ON CONFLICT DO UPDATE

5.4 辅助计算

  • calculate_rolling_stats()：滚动窗口统计
  • calculate_rank_with_ties()：并列排名
  • is_new_hire_in_month()：新入职判断
  • is_guest()：散客判断（member_id ≤ 0）
  • safe_decimal() / safe_int()：安全类型转换
  • seconds_to_hours() / hours_to_seconds()：时间单位转换
  • get_assistant_level_asof()：SCD2 助教等级
  • get_member_card_balance_asof()：SCD2 会员卡余额

六、字段命名规范

6.1 金额字段

  • 统一 NUMERIC(12,2)，货币单位 CNY
  • 储值卡：DWS 层使用 balance_pay（总额）、recharge_card_pay（现金充值卡）、gift_card_pay（赠送卡）
  • 财务日报：使用 recharge_card_consume
  • 助教费用：assistant_pd_money（陪打）、assistant_cx_money（超休），禁止使用 service_fee

6.2 时间字段

  • stat_date：统计日期（DATE）
  • stat_month：统计月份（CHAR(7)，格式 YYYY-MM）
  • created_at / updated_at：TIMESTAMPTZ

6.3 标识字段

  • site_id：门店 ID（多门店隔离，RLS）
  • tenant_id：租户 ID
  • member_id：会员 ID（≤ 0 为散客）
  • assistant_id：助教 ID

七、调度与 Flow 类型

Flow 类型 包含阶段 说明
dwd_dws 仅 DWS 汇总 日常增量
dwd_dws_index DWS 汇总 + 指数计算 含指数更新
api_full ODS → DWD → DWS → INDEX 全流程

处理模式：increment_only（默认）、verify_only（仅校验修复）、increment_verify（先增量后校验）

八、DWS 层完整表清单

汇总表

dws_assistant_daily_detail、dws_assistant_monthly_summary、dws_assistant_customer_stats、dws_assistant_salary_calc、dws_assistant_finance_analysis、dws_assistant_order_contribution、dws_member_consumption_summary、dws_member_visit_detail、dws_finance_daily_summary、dws_finance_recharge_summary、dws_finance_income_structure、dws_finance_discount_detail、dws_goods_stock_daily_summary、dws_goods_stock_weekly_summary、dws_goods_stock_monthly_summary、dws_order_summary

指数表

dws_member_winback_index、dws_member_newconv_index、dws_member_recall_index、dws_member_assistant_relation_index、dws_member_assistant_intimacy、dws_member_spending_power_index、dws_index_percentile_history

其他表

dws_platform_settlement、dws_ml_manual_order_source、dws_ml_manual_order_alloc、dws_assistant_recharge_commission、dws_assistant_project_tag、dws_member_project_tag

视图

v_member_recall_priority

配置表

cfg_performance_tier、cfg_assistant_level_price、cfg_bonus_rules、cfg_skill_type、cfg_area_category、cfg_index_parameters

九、废弃对象（禁止引用）

对象 删除日期 替代方案
BILLIARD_VIP 分类代码 2026-03-07 V1-V4 归入 BILLIARD，V5 归入 SNOOKER
dwd_assistant_trash_event 2026-02-22 dwd_assistant_service_log_ex.is_trash
RecallIndexTask / IntimacyIndexTask 2026-02-13 WBI + NCI + RelationIndexTask
SPRINT 奖金规则 2026-02-28 止 TOP_RANK 排名奖金（2026-03-01 起）

十、关键文档索引

文档 路径
DWS 任务详解 apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md
DWS 指标定义 apps/etl/connectors/feiqiu/docs/business-rules/dws_metrics.md
指数算法说明 apps/etl/connectors/feiqiu/docs/business-rules/index_algorithm_cn.md
BaseDwsTask 机制 apps/etl/connectors/feiqiu/docs/etl_tasks/base_task_mechanism.md
BD 手册（DWS 表） apps/etl/connectors/feiqiu/docs/database/DWS/main/
DWD-DOC 权威规则 .kiro/steering/dwd-doc-authority.md

与其他文档的优先级

DWS 层开发时的参考优先级：DWD-DOC > 本文档 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释。

本文档基于 2026-03-19 对项目代码、配置表、BD 手册和审计记录的全面收集整理。

Reference in New Issue View Git Blame Copy Permalink