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

apps/etl/connectors/feiqiu/docs/requirements/DWS需求与口径.md

@@ -0,0 +1,176 @@
+# DWS 需求与口径（合并版）
+
+> 合并自原 `DWS 数据库处理需求.md`、`DWS财务口径补充.md`、`DWS口径与规则补充.md`（2026-02-19）。
+> 指数算法需求已独立至 `关系指数PRD.txt`（RS/OS/MS/ML）和 `指数运营场景矩阵.txt`，本文不再包含。
+> 财务页面 UI 原型见 `财务页面需求.md`。
+
+---
+
+## 一、总体目标
+
+在 ETL 已完成的 DWD 层数据基础上，完成 DWS 层的数据处理：
+- 数据库设计（DDL）
+- DWD 读取 → Python 处理 → SQL 写入
+- SQL 和 Python 代码需要详尽的中文注释
+
+参考路径：
+- DWD schema 文档：`docs/database/`
+- DWS DDL：`db/etl_feiqiu/schemas/`
+- DWS 种子数据：`db/etl_feiqiu/seeds/`
+
+---
+
+## 二、通用需求
+
+### 2.1 数据时间分层
+四层时间分层（按更新时间），以符合业务层面的查询效率：
+- 第一层：回溯两天前到当前数据
+- 第二层：回溯 1 个月前到当前数据
+- 第三层：回溯 3 个月前到当前数据
+- 第四层：全量数据
+- 需要有配套的机制及时添加删除整理数据
+
+实现方式：分区策略/分层表或物化汇总层/定期归档与清理作业。
+
+### 2.2 统计口径注意
+- 计算助教业绩/工资时，需参考助教废除表，排除相关业务数据的影响
+- 计算助教业绩/工资时，注意辨别基础课/附加课影响
+- 散客处理：`member_id=0` 的客户是散客，不进入客户维度统计
+- 门店/租户范围：当前只有一个门店，一个租户
+
+### 2.3 时间口径定义
+- 本周/上周/本季度/上季度/最近半年不含本月等窗口的"起止边界"为月第一天 0 点
+- 周起始日为周一
+- 环比规则：开启对比时，是"对比上一个等长区间"
+
+---
+
+## 三、系统设置（薪酬方案）
+
+助教绩效与工资结算方案需落库并标记生效时间（按月取生效规则）。
+
+### 3.1 旧方案（2025 年 7 月生效，历史口径）
+- 球房统一抽成：18 元/小时
+- 保底奖励机制：
+
+| 保底线等级 | 对应完成小时数 | 保底收入 |
+|-----------|----------------|----------|
+| 初级 | 130 | 12000 |
+| 中级 | 150 | 16000 |
+| 高级 | 160 | 18000 |
+| 星级 | 170 | 23000 |
+
+- 保底与助教分成（客户支付减去球房抽成）取最大值发放
+
+### 3.2 新方案（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`，实际用 `skill_id` 枚举判断）：
+- 基础课：又名专业课/上桌/上钟，按分钟计时
+- 附加课：又名超休/激励/打赏，按整小时计时
+- 包厢课：归入基础课口径，客户支付统一 138 元/小时
+- 总业绩小时数阈值 = 基础课 + 附加课
+
+客户支付价格：
+- 基础课：初级 98 元/小时，中级 108 元/小时，高级 118 元/小时，星级 138 元/小时
+- 附加课：统一 190 元/小时
+- 包厢课（基础课）：统一 138 元/小时
+
+Top3 销冠奖（2026-03-01 起）：第 1 名 1000 元，第 2 名 600 元，第 3 名 400 元。
+- 排名口径：按绩效总小时数。如遇并列则都算（如 2 个第一，则记为 2 个第一，1 个第三）
+
+规则：
+1. 过档后，所有时长按新档位进行计算。举例：当前某中级助教已完成 185 小时，基础课 170 小时，附加课 15 小时：`170 × (108 - 10) + 15 × 190 × (1 - 0.30)`
+2. 本月新入职助教定档：按日均 × 30 的总业绩小时数定档。月 1 日 0 点之后入职的计算为新入职，入职日以助教表入职时间为准。在当月 25 日后入职的新助教，最高定档至 2 档（T2）。该折算仅用于定档，不适用于 Top3 奖的计算口径。
+
+### 3.3 薪酬规则与生效期
+- 档位、奖金、规则有"按月/按时间生效"的要求
+- 配置表：`cfg_performance_tier`、`cfg_bonus_rules`，需补充生效期字段或独立"规则生效期配置表"
+- SCD2 / as-of 口径：助教等级是 SCD2 维度，历史月份不能直接用"当前等级"，需按有效期 as-of join 取数
+- 技能枚举规范：用 `skill_id` 判断基础课/附加课，通过 `cfg_skill_type` 配置表映射
+
+---
+
+## 四、业务需求
+
+### 4.1 助教维度
+以每个助教个体的视角：
+- 业绩档位：历史月份与本月档位进度，档位影响的收入单价，相邻月份的变化
+- 有效业绩：历史月份与本月的基础课课时、激励课课时、全部课课时，相邻月份的变化
+- 收入：历史月份与本月的收入（注意助教等级、业绩档位、课程种类等因素的总和计算），相邻月份的变化
+- 客户情况：过去 7/10/15/30/60/90 天的跨度统计，服务过的客户数据，关联每次服务的时间、时长、台桌、分类等详细信息
+- 有效业绩的排除规则：仅对"助教废除表"的记录进行处理排除
+
+### 4.2 客户维度
+统计每个客户的信息：
+- 过去 7/10/15/30/60/90 天的跨度统计，来店消费情况
+- 关联每次服务的时间、食品饮品、时长、台桌、分类、助教服务等详细信息
+
+### 4.3 财务维度
+详见 `财务页面需求.md`（UI 原型级需求）。
+
+---
+
+## 五、财务口径补充
+
+### 5.1 支出/成本数据
+- DWD 里只有商品成本 `dwd_store_goods_sale.cost_money`
+- 房租、水电、物业、工资、报销、平台服务费等现金支出 → 数据库结构中预留，后期通过 Excel 手动导入
+
+### 5.2 平台回款与团购差价
+- DWD 只有团购核销/验券记录（`dwd_groupbuy_redemption` / `dwd_platform_coupon_redemption`）
+- 平台结算/回款/佣金/服务费明细 → 数据库结构中预留，后期通过 Excel 手动导入
+- 导入数据字段包含：回款金额、佣金、服务费、回款日期、平台类型、订单关联键
+
+### 5.3 优惠分类口径
+- 赠送卡抵扣 = 酒水卡 + 台费卡 + 活动抵用券结账抵扣
+- 团购优惠 = `ledger_amount` + `assistant_promotion_money` - `ledger_unit_price`
+- 大客户优惠和其他优惠 = 手动调账产生的优惠（订单中的折扣、台桌折扣、商品折扣、手动优惠，需抽样分析确认）
+
+### 5.4 发生额/正价口径
+- 结账记录中的正价：`table_charge_money`（台费正价）、`goods_money`（商品正价）、`assistant_pd_money`（助教基础课正价）、`assistant_cx_money`（助教激励课正价）
+- 团购中的正价：`ledger_amount`（台桌正价）+ `assistant_promotion_money`（助教正价）
+- 团购中的核销价：`ledger_unit_price`
+
+### 5.5 订单支付信息
+- 会员卡支付金额：`recharge_card_amount`（卡类型需从 `dwd_settlement_head` 的 `order_settle_id` 去 `dwd_member_balance_change` 表找到卡的类型）
+- 收银实付：`pay_amount`
+- 团购抵消的台费：`coupon_amount`
+- 团购支付的金额：若 `pl_coupon_sale_amount` 非 0 则使用；若为 0 且 `coupon_amount` 不为 0，则到 `dwd_groupbuy_redemption` 找对应订单的 `ledger_unit_price`
+- 台费打折：`adjust_amount`
+- 团购券优惠 = 团购抵消的台费 - 团购支付的金额
+
+### 5.6 区域/房型维度
+- `BD_manual_dim_table.md` 中有台区分布的对应关系
+- 配置表 `cfg_area_category` 需落地具体映射规则 + 默认兜底 + 异常值处理
+
+### 5.7 充值与赠送卡口径
+- 酒水卡、台费卡、活动抵用券是赠送卡，分类在 `dim_member_card_account` 的 `card_type_id`
+- 储值卡是充值的"现金卡"
+- 充值提成：数据库结构中预留，后期通过 Excel 手动导入（记录月份、充值金额、储值卡关联、提成金额）
+
+### 5.8 财务口径矩阵
+需扩展至财务页面每一项指标（发生额/优惠拆分/确认收入/现金流/充值/平台回款/支出结构），确保每一项都有明确字段 + 公式 + 来源表。
+
+### 5.9 手工导入表规范
+支出/平台回款/充值提成的 Excel 导入需补"字段定义、时间粒度、门店维度、去重与校验规则"。
+
+---
+
+## 六、实现要点备忘
+
+### 6.1 滚动区间统计
+需求中明确 7/10/15/30/60/90 天窗口，在 `dws_assistant_customer_stats`、`dws_member_consumption_summary` 中直接落多窗口字段。
+
+### 6.2 DDL 完整性
+所有方案中列出的表需在 `db/etl_feiqiu/schemas/` 中落全 DDL。
+
+### 6.3 时间分层实现
+UI 需要"最近半年不含本月、上季度"等时间维度，并满足上个周期的环比。DWS 分层仅到 3 个月，可能需要额外聚合层。

apps/etl/connectors/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/connectors/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/connectors/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
+
+## 助教收支分析
+助教基础课 客户支付 | 球房抽成 | 球房均小时抽成
+  ├─ 初级 客户支付 | 球房抽成 | 球房均小时抽成
+  ├─ 中级 客户支付 | 球房抽成 | 球房均小时抽成
+  ├─ 高级 客户支付 | 球房抽成 | 球房均小时抽成
+  └─ 星级 客户支付 | 球房抽成 | 球房均小时抽成
+
+助教激励课 客户支付 | 球房抽成 | 球房均小时抽成
+
+
+
+
+
+
+