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

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`