init: 项目初始提交 - NeoZQYY Monorepo 完整代码

apps/etl/pipelines/feiqiu/docs/requirements/DWS 数据库处理需求.md

@@ -0,0 +1,101 @@
+# DWS 数据层需求
+## 简介
+项目路径：C:\dev\LLTQ\ETL\feiqiu-ETL
+
+本文档描述在ETL已完成的DWD层数据基础上对DWS层的数据处理：
+- 完成对DWS层数据库的处理，即数据库设计，成果为DDL的SQL语句。
+- 数据读取处理到落库，即DWD读取，Python处理，SQL写入。
+- 在动手之前，先出一个任务计划文档，写明事实的具体技术方案细节。
+
+文档更多聚焦业务描述，你需要使用专业技能，使用面向对象编程OOP思想，完成程序设计直至代码完成：
+- 参考.\README.md 了解现在项目现状。
+- 参考.\etl_billiards\docs 了解 DWD的schema的表和字段。
+- SQL和Python代码需要详尽的，高密度的中文注释。
+- 完成内容，需要详尽高密度的补充至.\README.md，以方便后续维护。
+- DWS的表与表的字段 参考.\etl_billiards\docs\dwd_main_tables_dictionary.md 完成类似的数据库文档，方便后续维护。
+- 注意中文编码需求。
+
+## 通用需求
+### 数据分层 
+我希望使用互联网软件的业内通用方法，将数据按照更新时间分为4层，以符合业务层面的查询效率速度。
+- 第一层：回溯两天前到当前数据。
+- 第二层：回溯1个月前到当前数据。
+- 第三层：回溯3个月前到当前数据。
+- 第四层：全量数据。
+- 需要有配套的机制及时添加删除整理数据。
+
+### 统计注意
+当统计一些数据时，注意口径，数据有效性标识。举例：
+- 计算助教业绩/工资时，需要参考助教废除表，相关业务数据的影响。
+- 计算助教业绩/工资时，注意辨别 助教课 附加课影响。
+
+## 业务需求
+### 系统设置
+- 助教绩效与工资结算方案需落库并标记生效时间（按月取生效规则）。
+
+**旧方案（2025年7月生效，历史口径）**
+- 球房统一抽成：18元/小时
+- 保底奖励机制：
+
+| 保底线等级 | 对应完成小时数 | 保底收入 |
+|-----------|----------------|----------|
+| 初级 | 130 | 12000 |
+| 中级 | 150 | 16000 |
+| 高级 | 160 | 18000 |
+| 星级 | 170 | 23000 |
+
+- 保底与助教分成（客户支付减去球房抽成）取最大值发放
+  - 注：旧方案为保底制，DWS档位表不直接建模保底，历史回溯需另行补录/修正
+
+**新方案（2026-03-01起，现行口径）**
+
+| 档位 | 总业绩小时数阈值 | 专业课抽成（元/小时） | 打赏课抽成 | 次月休假（天） |
+|------|------------------|----------------------|------------|----------------|
+| 0档 淘汰压力 | H < 120 | 28 | 50% | 3 |
+| 1档 及格档 | 120 ≤ H < 150 | 18 | 40% | 4 |
+| 2档 良好档 | 150 ≤ H < 180 | 13 | 35% | 5 |
+| 3档 优秀档 | 180 ≤ H < 210 | 10 | 30% | 6 |
+| 4档 销冠竞争 | H ≥ 210 | 8 | 25% | 休假自由 |
+
+*课程类型（dwd_assistant_service_log 表的 skill_name）*
+- 基础课：又名专业课/上桌/上钟，按分钟计时
+- 附加课：又名超休/激励/打赏，按整小时计时
+- 包厢课：归入基础课口径，客户支付统一 138 元/小时
+- 总业绩小时数阈值 = 基础课 + 附加课
+
+*客户支付价格*
+- 基础课：初级 98 元/小时，中级 108 元/小时，高级 118 元/小时，星级 138 元/小时
+- 附加课：统一 190 元/小时
+- 包厢课（基础课）：统一 138 元/小时
+
+*Top3 销冠奖（2026-03-01起）*
+- 第1名：1000 元
+- 第2名：600 元
+- 第3名：400 元
+
+规则：
+1、过档后，所有时长按新档位进行计算。  
+举例：当前某中级助教已完成185小时，基础课170小时，附加课15小时：  
+170 × (108 - 10) + 15 × 190 × (1 - 0.30)
+
+2、本月新入职助教定档：  
+按日均 × 30 的总业绩小时数定档。  
+在当月25日后入职的新助教，最高定档至2档（T2）。  
+该折算仅用于定档，不适用于 Top3 奖的计算口径。
+
+### 助教维度
+以每个助教个体的视角
+- 我要知道我的业绩档位，历史月份与本月档位进度，档位影响的收入单价。及相邻月份的变化。
+- 我要知道我的有效业绩：历史月份与本月的 基础课课时，激励课课时，全部课课时。相邻月份的变化。
+- 我要知道我的收入：历史月份与本月的收入（注意助教等级，业绩档位，课程种类等因素的总和计算）。相邻月份的变化。
+- 我要知道我的客户情况：过去7天、10天、15天、30天、60天、90天 的跨度进行统计，我服务过（基础课+附加课）的客户数据，并关联每次服务的 时间 时长 台桌 分类 等详细信息。
+
+### 客户维度
+统计每个客户的信息
+- 我要知道每个客户：过去7天、10天、15天、30天、60天、90天 的跨度进行统计，来店消费情况，并关联每次服务的 时间 食品饮品 时长 台桌 分类 助教服务 等详细信息。
+
+
+### 财务维度
+财务维度的需求（已经落到原型图需求级别了），见财务页面需求.md
+
+

apps/etl/pipelines/feiqiu/docs/requirements/DWS口径与规则补充.md

@@ -0,0 +1,314 @@
+时间分层机制：需求明确“四层时间分层（近2天/近1月/近3月/全量）”，方案只写了更新频率，需补齐具体实现（分区策略/分层表或物化汇总层/定期归档与清理作业）。
+
+DDL 完整性：补充说明中提到缺失的表（如 cfg_tier_effective_period、dws_assistant_salary_calc、dws_member_visit_detail、dws_finance_discount_detail、dws_finance_recharge_summary、dws_finance_expense_summary）需要在 schema_dws.sql 里落全；方案里写了“更新DDL”，但应明确完整DDL清单与字段级定义。
+
+薪酬规则与生效期：档位、奖金、规则有“按月/按时间生效”的要求，方案目前只有 cfg_performance_tier/cfg_bonus_rules，需要补充生效期字段或独立“规则生效期配置表”，否则历史月份口径会错。
+
+SCD2 / as-of 口径：助教等级是SCD2维度，历史月份不能直接用“当前等级”。方案需明确“按有效期 as-of join”的取数规则。
+
+技能枚举规范：需求要求用 skill_id 判断基础课/附加课；方案应明确 skill_id→课程类型映射（可用配置表），避免 skill_name 漏记。
+
+滚动区间统计：需求中明确 7/10/15/30/60/90 天窗口，方案未明确存储方式（建议在 dws_assistant_customer_stats、dws_member_consumption_summary 中直接落多窗口字段，或新增滚动汇总表）。
+
+财务口径矩阵需全覆盖：方案已有“数据来源矩阵”，但需扩展至财务页面每一项指标（发生额/优惠拆分/确认收入/现金流/充值/平台回款/支出结构），确保每一项都有明确字段+公式+来源表。
+手工导入表规范：支出/平台回款/充值提成的Excel导入要补“字段定义、时间粒度、门店维度、去重与校验规则”，否则实现阶段会反复返工。
+
+区域/房型维表：方案已有 cfg_area_category，但需落地“具体映射规则 + 默认兜底 + 异常值处理”，并与 BD_manual_dim_table.md 一致。
+
+# 更新
+
+时间口径定义：本周/上周/本季度/上季度/最近半年不含本月 等窗口的“起止边界”为月第一天0点。周起始日为周一。
+
+环比规则：开启对比时，是“对比上一个等长区间”相比。
+
+有效业绩的排除规则：仅对“助教废除表”的记录进行处理排除。其影响绩效。
+
+新入职定档规则：月1日0点之后入住的，计算为新入职。入职日以助教表入职时间为准。
+
+Top3 奖金排名口径：按绩效总小时数。如遇并列则都算，比如2个第一，则记为2个第一，一个第三。
+
+充值提成规则：比例/阶梯/时间口径缺失：通过手动导入表格，表格中会明确月份，提成关联充值订单金额和助教获得的提成金额。
+
+大客户优惠/其他优惠划分规则：目前需要抽样分析。
+平台回款/服务费口径：明确导入数据字段包含：回款金额、佣金、服务费、回款日期、平台类型、订单关联键。
+
+散客处理：member_id=0 的客户是散客。不进入客户维度统计。
+
+门店/租户范围：现在只有一个门店，一个租户。
+
+
+
+
+我想让你帮我基于DWS层的数据（也可使用DWD层），设计2个指数算法：
+- 客户召回指数：根据客户的到店时间，计算由助教或工作人员进行召回的必要性和紧急程度。算法不仅尊重每个客户的到店周期习惯，还要对新客户和刚充值客户进行一定的召回倾向。
+- 客户与助教亲密程度：根据单个客户与单个助教发生的服务关系，为助教的约课精力分配，约课成功率进行推算参考。计算2个对象的亲密程度。附加课（激励/超休）权重是基础课的1.5倍。重要的指标包括服务频次，为其充值（服务开始到结束后的1个小时内发生的充值即算做为其充值。此逻辑仅在指数算法有效），最后一次服务发生到现在的间隔等。次重要的是每次服务的时长（同一个客人，对某一个助教的服务，间隔小于4小时，则算作同次服务）。若一段时间内频次，频率出现激增，则加重权重。
+注意：指数算法需要符合人性直觉，对时间间隔周期敏感。指数会周期更新（1小时到1天不等，根据实际业务进行调整），计算的分数会直接覆盖旧分数，是一个动态的实时的分数。我建议算法没有最高分，是一个线性的分数，更新完一轮后，将最高分映射为满分上限10.0分。在0.0-10.0区间内，映射所有分数。
+
+参考资料如下，告诉我你的实施计划。
+
+# 指数算法方案（假设所有输入特征已具备）
+
+> 统一约定：以“天”为时间单位；回溯窗口最多 60 天；指数每轮重算并覆盖旧分数。  
+> 所有指数先计算 **Raw Score（无上限）**，再映射为 **Display Score（0.0–10.0）** 用于展示与排序。
+
+---
+
+## 0. 通用函数与参数
+
+### 0.1 时间衰减函数（半衰期模型）
+设事件距今天数为 \(d \ge 0\)，半衰期为 \(h>0\)（天）：
+
+\[
+\mathrm{decay}(d;h)=\exp\left(-\ln(2)\cdot \frac{d}{h}\right)
+\]
+
+解释：当 \(d=h\) 时权重衰减到 0.5；越近权重越大，符合“近两周更重要”的直觉。
+
+### 0.2 更新窗口
+- 回溯：最近 \(W=60\) 天内的到店/服务/充值事件
+- 近期重点：半衰期通常取 \(7\sim 14\) 天
+
+---
+
+## 1) 客户召回指数（Recall Index, RI）
+
+### 1.1 目标
+衡量“是否需要召回”及“紧急程度”。  
+同时尊重客户个人到店周期，并对 **新客户**、**刚充值客户** 增加召回倾向。
+
+### 1.2 假设输入特征（概念层，不细化字段）
+对每个客户 \(c\)，假设已具备：
+- \(t\): 距离最近一次到店（或最近一次服务结束）已过去的天数
+- \(\mu\): 客户过去 60 天到店间隔的“典型周期”（建议中位数）
+- \(\sigma\): 客户到店间隔波动尺度（建议 MAD / IQR 等稳健尺度）
+- \(d_{\text{first}}\): 距离首访的天数（若无首访则视为很大）
+- \(d_{\text{re}}\): 距离最近一次充值的天数（若无充值则视为很大）
+- \(n_{14}, n_{60}\): 近 14 天/60 天到店（或会话）次数
+
+> 注：若 \(t>60\)，可按 \(t=60\) 截断用于衰减计算，避免“太久不来”占用资源。
+
+### 1.3 参数（可调默认值）
+- \(\sigma_0=2\)：波动下限（天），避免 \(\sigma\) 过小导致超期过敏
+- 新客半衰期 \(h_{\text{new}}=7\)
+- 刚充值半衰期 \(h_{\text{re}}=10\)
+- 召回各分量权重：
+  - \(w_{\text{over}}=3.0\)（超期紧急性，主导）
+  - \(w_{\text{new}}=1.0\)
+  - \(w_{\text{re}}=1.0\)
+  - \(w_{\text{hot}}=1.0\)（近期活跃后断档）
+- 防除零：\(\epsilon=10^{-6}\)
+
+### 1.4 计算步骤（Raw Score）
+
+#### (1) 超期紧急性（尊重个人周期）
+先做稳健标准化超期量：
+\[
+\sigma'=\max(\sigma,\sigma_0)
+\]
+\[
+z=\max\left(0,\frac{t-\mu}{\sigma'}\right)
+\]
+将其映射到 \(0\sim 1\) 的“超期强度”（越超期越接近 1）：
+\[
+\mathrm{overdue}=1-\exp(-z)
+\]
+
+#### (2) 新客户召回倾向（快衰减）
+设“新客”条件为 \(d_{\text{first}}\le 60\)：
+\[
+\mathrm{new\_bonus}=
+\begin{cases}
+\mathrm{decay}(d_{\text{first}};h_{\text{new}}), & d_{\text{first}}\le 60\\
+0, & \text{否则}
+\end{cases}
+\]
+
+#### (3) 刚充值召回倾向（快衰减）
+设“近期充值”条件为 \(d_{\text{re}}\le 60\)：
+\[
+\mathrm{re\_bonus}=
+\begin{cases}
+\mathrm{decay}(d_{\text{re}};h_{\text{re}}), & d_{\text{re}}\le 60\\
+0, & \text{否则}
+\end{cases}
+\]
+
+#### (4) 近期活跃后断档加重（“热了又断”更值得召回）
+定义短期/长期活跃率：
+\[
+r_{14}=\frac{n_{14}}{14},\quad r_{60}=\frac{n_{60}+1}{60}
+\]
+活跃比：
+\[
+\mathrm{hot\_ratio}=\frac{r_{14}}{r_{60}+\epsilon}
+\]
+将“高于常态”的部分做对数压缩（避免爆炸）：
+\[
+\mathrm{hot\_drop}=\max\left(0,\ln\left(1+(\mathrm{hot\_ratio}-1)\right)\right)
+\]
+
+#### (5) 汇总 Raw Score（无上限）
+\[
+RI_{\text{raw}}=
+w_{\text{over}}\cdot \mathrm{overdue}
++w_{\text{new}}\cdot \mathrm{new\_bonus}
++w_{\text{re}}\cdot \mathrm{re\_bonus}
++w_{\text{hot}}\cdot \mathrm{hot\_drop}
+\]
+
+---
+
+## 2) 客户-助教亲密指数（Intimacy Index, II）
+
+### 2.1 目标
+衡量“客户 \(c\) 与助教 \(a\) 的关系强度与近期温度”，用于：
+- 助教约课精力分配
+- 约课成功率的先验参考
+
+强调：
+- **附加课权重 = 基础课的 1.5 倍**
+- 指标重要性：频次、归因充值、最近一次间隔 > 时长
+- 若短期频率激增，权重要加重
+
+### 2.2 假设输入特征（概念层）
+对每个客户-助教对 \((c,a)\)，假设已具备（近 60 天）：
+- 会话集合 \(i\in S\)，每个会话有：
+  - 距今天数 \(\Delta d_i\)
+  - 时长（分钟）\(\mathrm{dur}_i\)
+  - 课型权重 \(\tau_i\in\{1.0,1.5\}\)（基础/附加）
+- 最近一次会话距今天数：\(d_{\text{last}}\)
+- 归因充值集合 \(j\in R\)，每笔充值有：
+  - 金额 \(\mathrm{amt}_j\)
+  - 距今天数 \(\Delta d^{(r)}_j\)
+
+### 2.3 参数（可调默认值）
+- 会话衰减半衰期 \(h_{\text{sess}}=14\)
+- 最近一次衰减半衰期 \(h_{\text{last}}=10\)
+- 充值衰减半衰期 \(h_{\text{pay}}=21\)
+- 金额压缩基准 \(A_0=500\)（选门店常见充值档位）
+- Burst（激增）检测半衰期：
+  - 短期 \(h_{\text{short}}=7\)
+  - 长期 \(h_{\text{long}}=30\)
+- 汇总权重：
+  - \(w_F=2.0\)（频次）
+  - \(w_R=1.5\)（最近一次）
+  - \(w_M=2.0\)（归因充值）
+  - \(w_D=0.5\)（时长）
+- 激增放大系数 \(\gamma=0.6\)
+- 防除零：\(\epsilon=10^{-6}\)
+
+### 2.4 计算步骤（Raw Score）
+
+#### (1) 频次强度（课型加权 + 近因加权）
+\[
+F=\sum_{i\in S}\tau_i\cdot \mathrm{decay}(\Delta d_i;h_{\text{sess}})
+\]
+
+#### (2) 最近一次温度（单独建模，直觉更强）
+\[
+R=\mathrm{decay}(d_{\text{last}};h_{\text{last}})
+\]
+
+#### (3) 归因充值强度（金额压缩 + 时间衰减）
+金额压缩采用对数（抑制长尾）：
+\[
+m(\mathrm{amt})=\ln\left(1+\frac{\mathrm{amt}}{A_0}\right)
+\]
+\[
+M=\sum_{j\in R} m(\mathrm{amt}_j)\cdot \mathrm{decay}(\Delta d^{(r)}_j;h_{\text{pay}})
+\]
+
+#### (4) 时长贡献（次要：温和加分，避免一局超长碾压）
+\[
+D=\sum_{i\in S}\sqrt{\frac{\mathrm{dur}_i}{60}}\cdot \tau_i\cdot \mathrm{decay}(\Delta d_i;h_{\text{sess}})
+\]
+
+#### (5) 频率激增（Burst）放大
+分别计算短期/长期的“近因频次”：
+\[
+F_{\text{short}}=\sum_{i\in S}\tau_i\cdot \mathrm{decay}(\Delta d_i;h_{\text{short}})
+\]
+\[
+F_{\text{long}}=\sum_{i\in S}\tau_i\cdot \mathrm{decay}(\Delta d_i;h_{\text{long}})
+\]
+激增幅度（仅放大“高于常态”的部分，并做对数压缩）：
+\[
+\mathrm{burst}=\max\left(0,\ln\left(1+\left(\frac{F_{\text{short}}}{F_{\text{long}}+\epsilon}-1\right)\right)\right)
+\]
+放大因子：
+\[
+\mathrm{mult}=1+\gamma\cdot \mathrm{burst}
+\]
+
+#### (6) 汇总 Raw Score（无上限）
+\[
+II_{\text{raw}}=\left(w_F F + w_R R + w_M M + w_D D\right)\cdot \mathrm{mult}
+\]
+
+---
+
+## 3) 统一的 0.0–10.0 映射方案（稳健替代“按最大值等比”）
+
+> 目标：既能保持“高分更紧急/更亲密”的排序，又不被极端离群点劫持整体区间。  
+> 该映射对 RI 与 II 通用，分别在各自对象集合上计算分位点。
+
+### 3.1 每轮映射步骤（推荐：分位截断 + 可选压缩 + MinMax）
+
+对某个指数的全体 Raw 分数集合 \(\{x_k\}\)（如所有客户的 \(RI_{\text{raw}}\) 或所有 pair 的 \(II_{\text{raw}}\)）：
+
+1) 计算稳健锚点分位数（建议）：
+- 下锚：\(Q_L = P05(x)\)（5 分位）
+- 上锚：\(Q_U = P95(x)\)（95 分位）
+
+2) 分位截断（Winsorize）：
+\[
+x'_k = \min\left(\max(x_k,Q_L),Q_U\right)
+\]
+
+3) （可选）非线性压缩（当仍呈长尾时启用；II 通常更适合启用）  
+两种任选一种即可：
+- \[
+g(x)=\ln(1+x)
+\]
+- \[
+g(x)=\mathrm{asinh}(x)
+\]
+得到：
+\[
+y_k=g(x'_k)
+\]
+
+4) 映射到 \([0,10]\)：
+\[
+\text{score}_k=
+10\cdot \frac{y_k-\min(y)}{\max(y)-\min(y)+\epsilon}
+\]
+
+### 3.2 防抖（可选但强烈建议）：分位点做 EWMA 平滑
+若你发现“每轮分布轻微变化导致全员分数跳动”，可对 \(Q_L, Q_U\) 做平滑：
+
+\[
+Q_{U,t}=(1-\alpha)Q_{U,t-1}+\alpha Q_{U,t}^{\text{now}},\quad \alpha=0.2
+\]
+\[
+Q_{L,t}=(1-\alpha)Q_{L,t-1}+\alpha Q_{L,t}^{\text{now}}
+\]
+
+> 更新频率越高（例如每小时），越推荐启用平滑；每日更新可不启用或取更大 \(\alpha\)。
+
+### 3.3 极端边界处理
+- 若出现 \(\max(y)-\min(y)\) 很小（几乎全员相同），则直接置：
+  - \(\text{score}=5.0\) 或按业务设定为 0.0/固定值
+- 对 \(t>60\) 的客户，可视业务做“召回上限策略”：例如将其召回分数封顶在 8~9（避免永远占据第一优先级），但 Raw 分数仍可保留用于分析。
+
+---
+
+## 4) 实施建议（不涉及字段级）
+- 先按默认参数跑 1~2 周，观察：
+  - 召回指数 TopN 是否符合店内直觉（人工抽检）
+  - 亲密指数在助教维度是否形成合理“主客群”
+  - 分数跨轮次是否抖动（决定是否启用分位点 EWMA）
+- 权重调整优先级：
+  1) 映射稳定性（分位截断阈值、是否启用压缩/平滑）
+  2) RI：\(w_{\text{over}}\) 与 \(h_{\text{new}},h_{\text{re}}\)
+  3) II：\(w_F,w_M\) 与 \(h_{\text{sess}},h_{\text{pay}}\)，以及 \(\gamma\)

apps/etl/pipelines/feiqiu/docs/requirements/DWS财务口径补充.md

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

apps/etl/pipelines/feiqiu/docs/requirements/关系指数PRD.txt

@@ -0,0 +1,473 @@
+PRD：保留 NCI / WBI，删除亲密指数，新增 RS / OS / MS / ML 指数体系
+
+生效目标：用**客户级（NCI/WBI）负责“触达优先级”，用关系级（RS/OS/MS/ML）**负责“归属与执行”，替代原 INTIMACY 的混合口径，提升可解释性与可运营性。
+统计与映射方法沿用现有“时间衰减 + 分位截断 + 0–10 映射 + 可选 EWMA 平滑”的工程框架（减少改造风险）。
+
+1. 背景与问题
+1.1 背景
+
+当前体系已有两类客户级指数：
+
+NCI（新客转化指数）：用于新客欢迎与转化排序
+
+WBI（老客挽回指数）：用于老客召回排序
+
+同时存在一个关系级的 亲密指数（INTIMACY），但它把“关系强度、归属、升温、付费关联”混在一个分数里，导致：
+
+一个分数承担多个运营目的，解释困难，策略难稳定
+
+动量（burst）乘法放大会掩盖“真实关系强度”
+
+充值归因可靠性要求高，一旦归因口径瑕疵会放大偏差
+
+1.2 目标
+
+保留 NCI / WBI 不变（持续作为客户级“触达优先级”）
+
+删除 INTIMACY（停止计算/停止被消费）
+
+新增四个关系级指数：RS / OS / MS / ML
+
+RS：关系强度（熟不熟）
+
+OS：归属份额（主要归谁）
+
+MS：动量升温（最近是否回暖/升温）
+
+ML：付费关联（推增值/储值由谁推更可能成）
+
+2. 术语与设计依据（对齐工程约定）
+2.1 时间衰减（半衰期）
+
+统一采用半衰期形式的指数衰减，保证“越近越重要”的可解释性。
+
+2.2 0–10 映射（展示分）
+
+统一采用：
+
+P5/P95 分位截断（Winsorize）降低极端值影响
+
+可选压缩（log1p/asinh）
+
+MinMax 映射到 0–10
+
+可选 EWMA 平滑减少跨批次抖动
+
+2.3 价值/触达优先级方法论（NCI/WBI 保留原因）
+
+RFM（Recency/Frequency/Monetary）作为客户分层与运营触达优先级的主流方法，与你的 WBI/NCI 结构一致（尤其是 recency + frequency + monetary 信号）。
+其中 NCI/WBI 继续承担“客户级排序”，关系级指数负责“落人/归属/推荐成功率”。
+
+3. 用户与核心运营场景
+3.1 角色
+
+店长/运营：配置策略、看板、复盘
+
+助教主管：分派任务、监控撞单/共管
+
+助教：执行跟进、召回、增值推荐
+
+3.2 场景总览（决策逻辑分层）
+
+客户级：要不要触达、先触达谁 → NCI / WBI
+
+关系级：由谁触达、怎么触达 → OS（定责）+ RS/MS/ML（定策略）
+
+4. 新指标定义（删除 INTIMACY，新增 RS/OS/MS/ML）
+
+粒度说明：RS/OS/MS/ML 均为 (site_id, member_id, assistant_id) 关系对粒度。
+数据基础与会话合并逻辑沿用原 INTIMACY 的服务日志抽取与 session merge（减少工程变动）。
+NCI/WBI 完全保留原逻辑与输出。
+
+4.1 RS：关系强度（Relationship Strength）
+
+用途：判断“这位助教与该客户是否真的熟、关系是否牢”。
+核心输入：
+
+合并会话后的：次数、时长、课型权重（基础/附加）
+
+距今天数（会话结束时间）
+
+最近一次服务距今天数
+
+计算（建议口径）：
+
+会话权重：τ_i = 1.0（基础） 或 incentive_weight（附加）
+
+会话衰减：decay(d; h) = exp(-ln(2)*d/h)
+
+频次项：F = Σ ( τ_i * decay(d_i; h_session) )
+
+时长项：D = Σ ( sqrt(dur_hours_i) * τ_i * decay(d_i; h_session) )
+
+最近门控：R = decay(days_since_last; h_last)
+
+RS_raw：
+
+base = w_F*F + w_D*D
+
+gate = R^(gate_alpha)
+
+RS_raw = base * gate
+
+输出：
+
+RS_raw
+
+RS_display（0–10，沿用通用映射与可选 EWMA）
+
+4.2 OS：归属份额（Ownership Share）
+
+用途：解决“客户到底归谁主跟，避免多人撞单”。
+核心输入：同一客户在所有助教上的 RS_raw。
+
+计算：
+
+对每个 member_id：OS = RS_raw_i / (Σ RS_raw_all_assistants + eps)
+
+加入噪声门槛：
+
+若 RS_raw_i < min_rs_raw_for_ownership，则 OS 视为 0（不参与归属）
+
+若 Σ RS_raw_all_assistants < min_total_rs_raw，则该客户视为“未形成稳定归属”
+
+输出：
+
+OS_share（0–1，推荐 UI 显示百分比）
+
+OS_label（主责/共管/公海）：
+
+主责：OS_share >= ownership_main_threshold
+
+共管：ownership_comanage_threshold <= OS_share < ownership_main_threshold
+
+公海：OS_share < ownership_comanage_threshold
+
+OS 不建议做分位映射（它是份额值，天然可解释）。如必须 0–10，只做 OS_share*10 的线性映射。
+
+4.3 MS：动量升温（Momentum）
+
+用途：判断“最近是否升温/回流”，用于跟进紧急程度（而不是关系强度）。
+核心输入：短期与长期的加权频次（含衰减与课型权重）。
+
+计算：
+
+F_short = Σ( τ_i * decay(d_i; h_short) )
+
+F_long = Σ( τ_i * decay(d_i; h_long) )
+
+ratio = (F_short + eps) / (F_long + eps)
+
+MS_raw（只保留升温部分）：
+
+MS_raw = max(0, ln(ratio))
+
+输出：
+
+MS_raw
+
+MS_display（0–10，通用映射与可选 EWMA）
+
+4.4 ML：付费关联（Monetization Link）
+
+用途：判断“推储值/增值由谁推更可能成”，用于选择执行人/协同人。
+核心输入：服务后短窗口内的充值归因、金额、时间衰减。
+
+关键前提（必须做的口径修复）：
+
+单笔充值只归因一个助教：采用“last-touch”原则
+
+对每笔充值：在归因窗口内，找 session_end <= pay_time 且最接近 pay_time 的那条会话对应的助教归因
+
+计算：
+
+对每笔归因充值 r：
+
+金额压缩：ln(1 + amt / amount_base)
+
+时间衰减：decay(days_ago_r; h_recharge)
+
+ML_raw = Σ( ln(1 + amt/amount_base) * decay(days_ago_r; h_recharge) )
+
+输出：
+
+ML_raw
+
+ML_display（0–10，通用映射与可选 EWMA）
+
+5. 数据依赖与产出表
+5.1 输入数据（沿用原 INTIMACY 的服务/充值口径）
+
+服务日志：billiards_dwd.dwd_assistant_service_log + billiards_dwd.dim_assistant
+
+充值订单：billiards_dwd.dwd_recharge_order（settle_type=5）
+
+课型映射：cfg_skill_type（决定 BONUS/BASE 权重）
+
+5.2 输出表（新增）
+
+建议新增统一关系表（替代原 dws_member_assistant_intimacy）：
+
+表名：billiards_dws.dws_member_assistant_relation_index
+主键：(site_id, member_id, assistant_id)
+核心字段：
+
+基础特征（用于解释与排查）：
+session_count, total_duration_minutes, basic_session_count, incentive_session_count, days_since_last_session
+attributed_recharge_count, attributed_recharge_amount
+
+指数：
+rs_raw, rs_display
+os_share, os_label, os_rank
+ms_raw, ms_display
+ml_raw, ml_display
+
+时间：calc_time, created_at, updated_at
+
+NCI/WBI 输出表保持不变。
+
+5.3 删除/下线（原 INTIMACY）
+
+停止写入：billiards_dws.dws_member_assistant_intimacy
+
+兼容期保留表但不再更新，前端与运营入口不再读取
+
+6. cfg_index_parameters 配置体系更新（你要求的“更新”核心）
+6.1 现有配置表结构（保持不变）
+
+cfg_index_parameters 继续使用现有字段：
+(param_id, index_type, param_name, param_value, description, effective_from, effective_to, created_at, updated_at)
+
+6.2 index_type 更新范围
+
+保留：NCI, WBI（不改参数，不改逻辑）
+
+删除：INTIMACY（通过 effective_to 失效，不再读取）
+
+新增：RS, OS, MS, ML
+
+其它 index_type（如 RECALL）本 PRD 不涉及，保持现状。
+
+7. 新增参数清单（默认值建议）
+
+说明：参数名尽量沿用现有风格（snake_case），并把“展示映射参数”复用到 RS/MS/ML 三个需要 0–10 映射的指数上。Winsorize 与 EWMA 的合理性见设计依据。
+
+7.1 RS 参数（index_type = RS）
+param_name	默认值	说明
+lookback_days	60	回看窗口（天）
+session_merge_hours	4	会话合并间隔（小时）
+incentive_weight	1.5	附加课权重
+halflife_session	14	会话衰减半衰期（天）
+halflife_last	10	最近服务衰减半衰期（天）
+weight_F	1.0	频次项权重
+weight_D	0.7	时长项权重
+gate_alpha	0.6	最近门控幂次（越大越强调“必须最近”）
+percentile_lower	5	映射下分位
+percentile_upper	95	映射上分位
+compression_mode	1	0=none,1=log1p,2=asinh
+use_smoothing	1	是否启用 EWMA 平滑
+ewma_alpha	0.2	EWMA α
+7.2 OS 参数（index_type = OS）
+param_name	默认值	说明
+min_rs_raw_for_ownership	0.05	归属噪声门槛（低于此 RS_raw 不参与 OS）
+min_total_rs_raw	0.10	客户总体关系强度过低则视为“未形成归属”
+ownership_main_threshold	0.60	OS 主责阈值
+ownership_comanage_threshold	0.35	OS 共管阈值
+eps	1e-6	分母保护
+7.3 MS 参数（index_type = MS）
+param_name	默认值	说明
+lookback_days	60	回看窗口（天）
+session_merge_hours	4	会话合并间隔（小时）
+incentive_weight	1.5	附加课权重
+halflife_short	7	短期半衰期（天）
+halflife_long	30	长期半衰期（天）
+eps	1e-6	比值保护
+percentile_lower	5	映射下分位
+percentile_upper	95	映射上分位
+compression_mode	1	0=none,1=log1p,2=asinh
+use_smoothing	1	是否启用 EWMA 平滑
+ewma_alpha	0.2	EWMA α
+7.4 ML 参数（index_type = ML）
+param_name	默认值	说明
+lookback_days	60	回看窗口（天）
+recharge_attribute_hours	1	充值归因窗口（小时）
+attribution_mode	1	1=last_touch（单笔充值只归因一个助教）
+amount_base	500	金额压缩基数
+halflife_recharge	21	充值衰减半衰期（天）
+percentile_lower	5	映射下分位
+percentile_upper	95	映射上分位
+compression_mode	1	0=none,1=log1p,2=asinh
+use_smoothing	1	是否启用 EWMA 平滑
+ewma_alpha	0.2	EWMA α
+8. 配置迁移策略（cfg_index_parameters 具体更新方式）
+8.1 INTIMACY 下线
+
+将 index_type = 'INTIMACY' 的现行有效参数统一设置 effective_to = 下线日（建议为新版本生效日前一天）
+
+代码层：不再加载/执行 INTIMACY 任务
+
+8.2 新增 RS/OS/MS/ML 参数
+
+插入上述四个 index_type 的参数行，设置 effective_from = 新版本生效日
+
+param_id 由数据库自增生成（不在 PRD 固定）
+
+8.3 生效日期建议
+
+当前日期为 2026-02-08（台北时区），建议：
+
+新增四类参数 effective_from = 2026-02-09
+
+INTIMACY effective_to = 2026-02-08
+
+9. 任务与工程改造范围
+9.1 ETL 任务
+
+保留：NCI/WBI 原任务
+
+新增：RelationIndexTask（或拆为 RS/MS/ML/OS 四个任务，但建议一个任务产出一张关系表）
+
+删除/停用：原 IntimacyIndexTask
+
+9.2 关键工程点（必须实现）
+
+复用 session merge（降低风险）
+
+充值归因改为 last_touch 单归因（ML 可靠性的硬前提）
+
+RS/MS/ML 的 display 映射复用 BaseIndexTask（一致性与可调参性）
+
+OS 份额化与标签化（防撞单的唯一有效方式）
+
+10. 运营使用方式（落地规则）
+10.1 任务队列（建议固定四条队列）
+
+新客欢迎：按 NCI_welcome 排序
+
+新客转化：按 NCI_convert 排序
+
+老客召回：按 WBI 排序
+
+活跃升温承接：按 MS 排序
+
+10.2 “落人”规则（所有队列通用）
+
+有明确归属：按 OS_label=主责 的助教派单
+
+共管：只派给主责助教，协同人由 ML 或 RS 次高者确定
+
+公海：派给当班/新客官/运营池
+
+10.3 增值推荐（谁推更可能成）
+
+选客户：以 NCI/WBI 中的价值/充值未回访信号做筛选
+
+选执行人：以 ML 高者为主，OS 作为责任边界，RS 决定话术深度
+
+11. 验收标准（可测试、可回归）
+11.1 数据正确性
+
+OS：同一 member_id 下所有 assistant_id 的 OS_share（参与归属者）求和≈1
+
+RS：新增会话、会话更近、时长更长 → RS_raw 单调上升（统计抽样验证）
+
+MS：短期频次明显高于长期 → MS_raw>0；否则 MS_raw=0
+
+ML：充值发生在归因窗口内且越近越大 → ML_raw 越高；且单笔充值只归因一个助教
+
+11.2 运营可用性
+
+至少能稳定支持：
+
+客户分配（OS）
+
+跟进紧急程度（MS）
+
+召回优先级（WBI）
+
+新客欢迎/转化（NCI）
+
+推增值选人（ML）
+
+12. 风险与对策
+
+OS 噪声归属：低互动关系也被算份额
+→ 用 min_rs_raw_for_ownership 与 min_total_rs_raw 双门槛
+
+ML 偏差：归因口径不稳定导致误导选人
+→ 强制 last_touch 单归因；窗口可调；上线初期做抽样对账
+
+display 分数跨批次漂移（相对分固有属性）
+→ 开启 EWMA 平滑降低短期抖动
+
+13. 上线与灰度建议
+
+第 1 阶段（影子跑数）：RS/OS/MS/ML 与 INTIMACY 并行计算但不对外展示（1–2 周）
+
+第 2 阶段（切读）：前端/运营策略只读 RS/OS/MS/ML；INTIMACY 停止消费
+
+第 3 阶段（下线）：停更 INTIMACY 表，保留历史查询周期后再清理
+
+14. 交付物清单
+
+新增关系表：dws_member_assistant_relation_index
+
+新增指数任务：RelationIndexTask（含 RS/OS/MS/ML）
+
+cfg_index_parameters：
+
+INTIMACY 参数失效（effective_to）
+
+新增 RS/OS/MS/ML 参数（effective_from）
+
+运营端：
+
+队列：新客欢迎/新客转化/老客召回/升温承接
+
+客户详情：展示 NCI、WBI、以及每位助教的 RS/OS/MS/ML
+
+15. 实施定稿补充（2026-02-08）
+
+1. ML 数据源定稿为“人工台账唯一真源”：
+- `dws_ml_manual_order_alloc` 为 ML 主口径输入；
+- 无台账时 `ML_raw=0`；
+- `dwd_recharge_order` 的 last-touch 仅保留备用代码路径（默认关闭，`ML.source_mode=0`）。
+
+2. 台账规则定稿：
+- 一单可归多个助教，默认均分；
+- `external_id` 作为订单ID，必填；
+- 同一 `(site_id, external_id, assistant_id)` 重复导入时覆盖；
+- 覆盖边界：
+  - 30天内：按 `site_id + biz_date` 日覆盖；
+  - 超过30天：按固定纪元 `2026-01-01` 的 30 天桶覆盖。
+
+3. 关系指数任务形态：
+- 单任务 `RelationIndexTask` 一次产出 RS/OS/MS/ML；
+- 输出表：`dws_member_assistant_relation_index`；
+- `RS/MS/ML` 分位映射与 EWMA 历史按 `index_type` 隔离。
+
+4. 参数补充：
+- `index_type=OS` 新增 `ownership_gap_threshold`（默认 0.15）；
+- `index_type=ML` 新增 `source_mode`（默认 0，manual_only）。
+
+5. 上线策略修订：
+- 当前未正式上线，直接切换读新表；
+- 影子期不再作为强制步骤。
+
+16. 实施更新（2026-02-13）
+
+1. ML 数据源最终定稿：
+   - 彻底移除 last-touch 备用路径代码（`_apply_last_touch_ml` 方法已删除）；
+   - 移除 `source_mode` 和 `recharge_attribute_hours` 参数（代码默认值与数据库种子均已清理）；
+   - ML 仅使用人工台账 `dws_ml_manual_order_alloc`，无备用路径。
+
+2. 旧版指数清理：
+   - `RecallIndexTask` 已删除（由 WBI+NCI 替代）；
+   - `IntimacyIndexTask` 已删除（由 RelationIndexTask 替代）；
+   - 对应数据库表 `dws_member_recall_index` / `dws_member_assistant_intimacy` 通过迁移脚本 DROP；
+   - `cfg_index_parameters` 中 RECALL / INTIMACY 参数已清理。
+
+3. WBI 修复：
+   - `STOP_HIGH_BALANCE` 会员现在参与评分（之前只记录不评分）。
+
+4. 迁移脚本：`database/migrations/20260213_remove_legacy_index.sql`

apps/etl/pipelines/feiqiu/docs/requirements/指数运营场景矩阵.txt

@@ -0,0 +1,26 @@
+<!-- AI_CHANGELOG [2026-02-13] 更新 NCI/WBI/OS/MS/ML 描述以对齐代码实现；移除 RECALL/INTIMACY -->
+各指数作用与算法逻辑概览（更新于 2026-02-13）
+
+| 指数                              | 粒度           | 主要解决的问题                  | 核心信号（输入）                                           | 算法逻辑（简述）                                                                                            | 输出形式                                             |
+| ------------------------------- | ------------ | ------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **NCI 新客转化指数**                  | 客户（member）   | 新客欢迎建联与二访转化优先级排序         | 首访/单访、近14/60天到店次数、距上次到店/充值天数、消费与余额、充值未回访           | 将 NEW 客户分为"欢迎窗口"和"转化窗口"：欢迎分在首访后短窗口内递减；转化分=紧迫度×可救度，并叠加"充值未回访压力/价值"（充值和价值分在免打扰窗口后渐进生效，由 touch_multiplier 控制）；对近期高活跃新客做抑制，避免打扰；最终做 0–10 映射      | `raw` + `display(0–10)`，并提供 welcome/convert 子展示分 |
+| **WBI 老客挽回指数**                  | 客户（member）   | 老客召回紧急程度与价值潜力的综合排序       | 距上次到店/充值天数、到店间隔分布（个人周期）、近14/60天降频、充值未回访、近180天消费与余额 | 先分流（NEW/OLD/STOP，高余额 STOP 例外可进入并参与评分）；OLD/STOP_HIGH_BALANCE 客户 WBI=超期（加权经验CDF的p^alpha变换）+降频+充值未回访压力+价值；双层抑制机制：hard_floor_days 硬截断 + sigmoid 门控（recency_gate_days + slope_days）；额外输出 ideal_interval_days（理想回访间隔）和 ideal_next_visit_date（建议下次到店日期）；最终 0–10 映射 | `raw` + `display(0–10)` + `ideal_next_visit_date`                          |
+| **RS 关系强度指数**                   | 客户-助教对（pair） | 判断"这位助教和该客户是否真的熟、关系是否牢"  | 近窗口内合并会话：次数、时长、课型权重、会话距今天数；最近一次服务距今天数              | 将"频次+时长"融合成单一"互动量"（base = weight_f×f_score + weight_d×d_score），并做时间衰减；再用最近接触作为门控（gate = r_score^gate_alpha），降低"只靠历史堆积"的误判；rs_raw = base × gate；最终 0–10 映射                              | `raw` + `display(0–10)`                          |
+| **OS 归属份额指数**                   | 客户-助教对（pair） | 客户到底该分给谁跟（防多人撞单）         | 同一客户在所有助教上的 RS                                     | 先过滤 RS < min_rs_raw_for_ownership 的噪声对；OS = 该助教 RS / 该客户所有 eligible 助教 RS 之和（份额化）；若 sum_rs < min_total_rs_raw 则全部标记 UNASSIGNED；标签分配：top1 份额 ≥ main_threshold 且与第二名差距 ≥ gap_threshold → MAIN（主责），份额 ≥ comanage_threshold → COMANAGE（共管），其余 → POOL（公海）；同时输出 os_rank 排名                                                 | **0–1 份额** + 标签（MAIN/COMANAGE/POOL/UNASSIGNED） + 排名             |
+| **MS 动量/升温指数**                  | 客户-助教对（pair） | 判断"近期是否明显升温/回流"，用于跟进紧急程度 | 短期加权频次 vs 长期加权频次（仅用课型权重 course_weight，不含时长；含时间衰减）                         | 计算短期活跃与长期基线的比值（ratio = f_short / f_long），取正向"升温"部分作为动量（ms_raw = max(0, log(ratio))）；**不再乘进 RS**，避免动量掩盖真实关系强度；MS 只关心频次变化趋势，时长由 RS 负责；最终 0–10 映射                                    | `raw` + `display(0–10)`                          |
+| **ML 付费关联指数**                   | 客户-助教对（pair） | 判断"由谁去推储值/增值更可能成功"       | 人工台账归因充值（金额、距今天数）；由 Excel 导入的 dws_ml_manual_order_alloc 表提供                        | 仅使用人工台账数据（不使用自动归因）；对归因充值金额做对数压缩（log1p(amount/amount_base)）并时间衰减累加；无台账数据时 ML_raw=0；最终 0–10 映射                                   | `raw` + `display(0–10)`                          |
+
+
+按运营场景归类——用哪些指数、怎么配合运营
+| 场景大类           | 具体场景/触发                      | 主用指数         | 辅助指数                        | 运营动作（怎么做）                     | 分派/排序建议（怎么用分数）                                            |
+| -------------- | ---------------------------- | ------------ | --------------------------- | ----------------------------- | --------------------------------------------------------- |
+| **客户分配（归属）**   | 新客首次到店/单访（NEW）               | NCI（welcome） | RS/OS（若有服务记录）               | 建联、加微信、解释规则与权益、预约二访           | NEW 客户按 NCI_welcome 从高到低分配给"新客官/当班"；若已有服务记录则优先分给 RS 最高的助教 |
+| **客户分配（归属）**   | 多助教共同服务、避免撞单                 | OS           | RS                          | 确定主跟进人+备份协同；低份额进入公海           | 先过滤 RS 过低的噪声对；OS≥阈值判主责；OS 中间段做共管；OS 低入公海                  |
+| **跟进紧急程度（活跃）** | 近期明显升温/回流                    | MS           | OS、RS                       | 48小时内快速承接：约局、续约、体验升级          | 在各助教名下按 MS 排序拉任务；只给 OS 主责助教派单，避免多人同时触达                    |
+| **跟进紧急程度（活跃）** | 关系强但开始变冷（尚未进入老客召回）           | RS           | MS                          | 关怀回访、确认体验、轻激励召回               | 按"RS 高且最近温度下降"的组合优先；仍由 OS 主责助教执行                          |
+| **新客转化**       | 二访转化窗口（Need×Salvage 高）       | NCI（convert） | OS/RS（选人）                   | 明确二访理由与时间点，减少硬推；对活跃新客遵守免打扰    | NEW 客户按 NCI_convert 排序；触达频次由 NCI 的抑制机制控制                  |
+| **老客召回紧急程度**   | OLD 客户召回（过门槛且可触达）            | WBI          | OS/RS（选人）、ML（若涉及储值）         | 召回话术：周期超期/降频原因探询+回访安排；高余额优先人工 | OLD 客户按 WBI 排序形成召回队列；优先派给 OS 主责助教；无归属进公海召回组               |
+| **专项召回**       | 充值未回访（recharge_unconsumed=1） | WBI（充值相关信号）  | ML、OS、RS                    | "余额权益/使用提醒"切入，目标是回店消耗与续充      | WBI 高者优先；由 ML 高且 OS 合理的助教主推（提高转化）                         |
+| **增值推荐（由谁推）**  | 要推储值/包时/陪练等增值                | ML           | OS、RS、MS                    | 由"更可能促成付费的人"主推；升温期可提高转化强度     | 先按客户价值/意愿侧（在 NCI/WBI 价值项里已体现）筛人，再用 ML 选人、用 OS 定责          |
+| **触达控制（避免打扰）** | 新客刚来过、仍活跃                    | NCI（内置抑制）    | —                           | 降低触达，转为到店现场服务转化               | 对触达任务队列，直接用 NCI 的抑制结果降低优先级或不派单                            |
+| **门店管理/复盘**    | 助教名下 RS 高但 WBI 也高（熟客仍流失）     | WBI + RS     | OS、MS                       | 复盘服务质量/排班稳定性/体验问题，调整服务策略      | 不是派单场景，而是"异常监控看板"：按组合信号筛出需复盘的助教与客户群                       |

apps/etl/pipelines/feiqiu/docs/requirements/财务页面需求.md

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