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`
