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

apps/etl/pipelines/feiqiu/docs/etl_tasks/index_tasks.md

@@ -0,0 +1,731 @@
+# INDEX 层任务详解
+
+> 本文档说明飞球 ETL 系统中 INDEX（指数算法层）的所有任务。
+> INDEX 层基于 DWD/DWS 层数据，通过自定义算法计算业务指数，
+> 服务于会员运营（回流挽回、新客转化）和助教管理（关系归属、付费关联）等场景。
+
+---
+
+## 概述
+
+INDEX 层共有 4 个已注册任务：
+
+| 任务代码 | Python 类 | 目标表 | 指数类型 | 更新策略 |
+|----------|-----------|--------|----------|----------|
+| `DWS_WINBACK_INDEX` | `WinbackIndexTask` | `dws_member_winback_index` | WBI（回流指数） | delete-before-insert（按门店全量刷新） |
+| `DWS_NEWCONV_INDEX` | `NewconvIndexTask` | `dws_member_newconv_index` | NCI（新客转化指数） | delete-before-insert（按门店全量刷新） |
+| `DWS_RELATION_INDEX` | `RelationIndexTask` | `dws_member_assistant_relation_index` | RS/OS/MS/ML（关系指数） | delete-before-insert（按门店全量刷新） |
+| `DWS_ML_MANUAL_IMPORT` | `MlManualImportTask` | `dws_ml_manual_order_source` / `dws_ml_manual_order_alloc` | ML（手动台账导入） | 按 scope 先删后写 |
+
+> 注册位置：`orchestration/task_registry.py`，所有 INDEX 任务的 `requires_db_config=False`、`layer="INDEX"`。
+
+---
+
+## BaseIndexTask 公共机制
+
+`BaseIndexTask`（位于 `tasks/dws/index/base_index_task.py`）继承自 `BaseDwsTask`，为所有指数任务提供统一的算法基础设施。
+
+### 继承层次
+
+```
+BaseTask
+  └── BaseDwsTask
+        └── BaseIndexTask
+              ├── MemberIndexBaseTask   ← WBI / NCI 共享的会员特征提取
+              │     ├── WinbackIndexTask
+              │     └── NewconvIndexTask
+              ├── RelationIndexTask     ← RS/OS/MS/ML 四合一
+              └── MlManualImportTask    ← ML 人工台账导入
+```
+
+### 子类必须实现的抽象方法
+
+```python
+def get_index_type(self) -> str:
+    """返回指数类型标识，如 'WBI'、'NCI'、'RS'"""
+```
+
+### 核心能力
+
+#### 1. 半衰期时间衰减函数
+
+所有指数共享的时间权重模型，核心思想是"越近越重要"：
+
+```
+decay(d; h) = exp(-ln(2) × d / h)
+```
+
+| 参数 | 含义 | 示例 |
+|------|------|------|
+| `d` | 事件距今天数（≥0） | 7 天 |
+| `h` | 半衰期（>0），单位：天 | 7 天 |
+| 返回值 | 衰减权重，范围 (0, 1] | 0.5 |
+
+当 `d = h` 时权重恰好衰减到 0.5；`d = 0` 时权重为 1.0。
+
+#### 2. 分位数计算与截断（Winsorize）
+
+用于消除极端值对归一化的影响：
+
+1. 计算 P5 和 P95 分位点
+2. 将所有 Raw Score 截断到 [P5, P95] 范围内
+
+```python
+calculate_percentiles(scores, lower=5, upper=95) → (P5, P95)
+winsorize(value, lower, upper) → clipped_value
+```
+
+#### 3. 0-10 归一化映射
+
+将 Raw Score 映射到 0-10 分的 Display Score，便于业务理解和排序：
+
+```
+映射流程：Raw Score → [可选压缩] → Winsorize(P5, P95) → MinMax(0, 10)
+```
+
+压缩模式（由 `compression_mode` 参数控制）：
+
+| compression_mode | 方式 | 公式 | 适用场景 |
+|------------------|------|------|----------|
+| 0 | 无压缩 | `y = x` | 分布较均匀时 |
+| 1 | log1p | `y = ln(1 + x)` | 右偏分布（默认） |
+| 2 | asinh | `y = asinh(x)` | 含负值或极端右偏 |
+
+当所有分数几乎相同（`max - min < ε`）时，返回中间值 5.0。
+
+#### 4. 算法参数加载
+
+从 `billiards_dws.cfg_index_parameters` 表按 `index_type` 加载参数：
+
+- 按 `effective_from` 降序取最新生效的参数值
+- 支持按 `index_type` 隔离的内存缓存（TTL = 300 秒）
+- 子类可通过 `get_param(name, default)` 获取单个参数
+
+```python
+load_index_parameters(index_type=None) → Dict[str, float]
+get_param(name, default=0.0, index_type=None) → float
+```
+
+#### 5. 分位点历史管理（EWMA 平滑）
+
+为避免分位点在不同批次间剧烈波动，支持 EWMA（指数加权移动平均）平滑：
+
+```
+Q_t = (1 - α) × Q_{t-1} + α × Q_now
+```
+
+| 参数 | 含义 | 默认值 |
+|------|------|--------|
+| `α`（ewma_alpha） | 平滑系数，越大越跟随当前值 | 0.2 |
+| `Q_{t-1}` | 上一次平滑后的分位点 | 从 `dws_index_percentile_history` 表读取 |
+| `Q_now` | 当前批次计算的分位点 | 实时计算 |
+
+首次计算时无历史记录，直接使用当前分位点（不平滑）。每次计算后将原始分位点和平滑分位点保存到 `dws_index_percentile_history` 表。
+
+#### 6. 统计工具方法
+
+| 方法 | 功能 |
+|------|------|
+| `calculate_median(values)` | 中位数 |
+| `calculate_mad(values)` | MAD（中位绝对偏差），比标准差更稳健 |
+| `safe_log(value)` | 安全对数（value ≤ 0 时返回默认值） |
+| `safe_ln1p(value)` | 安全的 `ln(1+x)` |
+
+
+---
+
+## MemberIndexBaseTask 会员指数共享基类
+
+`MemberIndexBaseTask`（位于 `tasks/dws/index/member_index_base.py`）继承自 `BaseIndexTask`，为 WBI 和 NCI 提供共享的会员活动特征提取逻辑。
+
+### 会员活动特征（MemberActivityData）
+
+从 DWD 层提取并计算的会员特征数据结构：
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `member_id` | int | 会员 ID |
+| `site_id` / `tenant_id` | int | 门店 / 租户 ID |
+| `member_create_time` | datetime | 会员建档时间 |
+| `first_visit_time` | datetime | 首次到店时间 |
+| `last_visit_time` | datetime | 最近到店时间 |
+| `last_recharge_time` | datetime | 最近充值时间 |
+| `t_v` | float | 距最近到店天数（截断到 recency 窗口） |
+| `t_r` | float | 距最近充值天数（截断到 recency 窗口） |
+| `t_a` | float | `min(t_v, t_r)`，综合活跃度 |
+| `visits_14d` / `visits_60d` / `visits_total` | int | 近 14 天 / 60 天 / 总到店次数 |
+| `spend_30d` / `spend_180d` | float | 近 30 天 / 180 天消费金额 |
+| `sv_balance` | float | 储值卡余额 |
+| `recharge_60d_amt` | float | 近 60 天充值金额 |
+| `intervals` | List[float] | 到店间隔天数序列 |
+| `interval_ages_days` | List[int] | 每个间隔对应的"年龄"（距今天数） |
+| `recharge_unconsumed` | int | 充值后是否未回访（1=是） |
+
+### 数据来源
+
+| 数据 | 来源表 | 提取方式 |
+|------|--------|----------|
+| 到店记录 | `billiards_dwd.dwd_settlement_head` | 按天去重，仅计入正常结账（settle_type=1）和激励课结账（settle_type=3 且关联 BONUS 技能） |
+| 充值记录 | `billiards_dwd.dwd_recharge_order` | settle_type=5，近 recency_days 天 |
+| 会员建档时间 | `billiards_dwd.dim_member` | scd2_is_current=1 |
+| 首次到店时间 | `billiards_dwd.dwd_settlement_head` | 全量 MIN(pay_time) |
+| 储值卡余额 | `billiards_dwd.dim_member_card_account` | 按 card_type_id 筛选现金卡 |
+
+> 会员 ID 规范化：优先使用 `member_id`，若为 0 则通过 `dim_member_card_account` 关联取 `tenant_member_id`。
+
+### 会员分群（classify_segment）
+
+WBI 和 NCI 共享的三分群逻辑，决定会员进入哪个指数的计算范围：
+
+| 分群 | 条件 | 进入指数 |
+|------|------|----------|
+| **STOP** | `t_a ≥ recency_days`（默认 60 天无活动） | 不参与评分（除 STOP_HIGH_BALANCE 例外） |
+| **NEW** | 满足以下任一：到店 ≤ 2 次、首访 ≤ 30 天、近期充值未回访 | NCI |
+| **OLD** | 不满足 STOP 和 NEW 条件 | WBI |
+
+STOP_HIGH_BALANCE 例外：当 `enable_stop_high_balance_exception=1` 且储值余额 ≥ `high_balance_threshold`（默认 1000 元）时，STOP 会员仍参与 WBI 评分。
+
+
+---
+
+## DWS_WINBACK_INDEX — 老客挽回指数（WBI）
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_WINBACK_INDEX` |
+| Python 类 | `WinbackIndexTask`（`tasks/dws/index/winback_index_task.py`） |
+| 继承链 | `BaseTask → BaseDwsTask → BaseIndexTask → MemberIndexBaseTask → WinbackIndexTask` |
+| 目标表 | `billiards_dws.dws_member_winback_index` |
+| 主键 | `site_id, member_id` |
+| 指数类型 | `WBI` |
+| 更新策略 | 按门店全量刷新（先 DELETE WHERE site_id = %s，再 INSERT） |
+
+### 业务含义
+
+WBI 衡量老客的"挽回紧急度"——分数越高，表示该会员越需要运营人员主动触达。适用于已有多次到店记录但近期活跃度下降的老客群体。
+
+### 计算范围
+
+仅对 `segment = "OLD"` 或 `status = "STOP_HIGH_BALANCE"` 的会员计算。
+
+### 算法概要
+
+WBI Raw Score 由 4 个分项加权求和，再乘以近期抑制系数：
+
+```
+WBI_raw = suppression × (w_over × Overdue + w_drop × Drop + w_re × Recharge + w_value × Value)
+```
+
+#### 分项 1：超期紧急性（Overdue）
+
+基于会员个人历史到店间隔的加权经验 CDF，衡量当前缺席天数的异常程度：
+
+1. 收集会员历史到店间隔序列 `{interval_i, age_i}`
+2. 计算加权 CDF：`P(interval ≤ t_v)`，权重按间隔年龄半衰期衰减
+3. 对小样本混合等权分布与加权分布（`λ = min(1, N / blend_min_samples)`）
+4. `Overdue = P^α`（α 默认 2.0，放大高概率区间的紧急性）
+
+同时计算理想到店间隔（加权中位数），用于推算 `ideal_next_visit_date`。
+
+#### 分项 2：降频分（Drop）
+
+检测近期到店频率是否低于历史均值：
+
+```
+expected_14d = visits_60d × 14 / 60
+Drop = clip((expected_14d - visits_14d) / (expected_14d + 1), 0, 1)
+```
+
+#### 分项 3：充值未回访压力（Recharge）
+
+若会员充值后未回访（`recharge_unconsumed = 1`），按充值距今天数衰减：
+
+```
+Recharge = decay(t_r, h_recharge)    # h_recharge 默认 7 天
+```
+
+#### 分项 4：价值分（Value）
+
+综合消费金额和储值余额的对数压缩：
+
+```
+Value = w_spend × ln(1 + spend_180d / M0) + w_bal × ln(1 + sv_balance / B0)
+```
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `M0` (amount_base_M0) | 300 | 消费金额压缩基准 |
+| `B0` (balance_base_B0) | 500 | 余额压缩基准 |
+
+#### 近期抑制（Suppression）
+
+防止刚到店的会员获得高分，使用 Sigmoid 门控：
+
+```
+suppression = σ((t_v - gate_days) / slope_days)
+```
+
+- 当 `t_v < hard_floor_days`（默认 14 天）时，`suppression = 0`（完全抑制）
+- 当 `t_v` 远大于 `gate_days` 时，`suppression → 1`（不抑制）
+
+### 默认权重
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `w_over` | 2.0 | 超期紧急性权重 |
+| `w_drop` | 1.0 | 降频权重 |
+| `w_re` | 0.4 | 充值压力权重 |
+| `w_value` | 1.2 | 价值权重 |
+
+
+---
+
+## DWS_NEWCONV_INDEX — 新客转化指数（NCI）
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_NEWCONV_INDEX` |
+| Python 类 | `NewconvIndexTask`（`tasks/dws/index/newconv_index_task.py`） |
+| 继承链 | `BaseTask → BaseDwsTask → BaseIndexTask → MemberIndexBaseTask → NewconvIndexTask` |
+| 目标表 | `billiards_dws.dws_member_newconv_index` |
+| 主键 | `site_id, member_id` |
+| 指数类型 | `NCI` |
+| 更新策略 | 按门店全量刷新（先 DELETE WHERE site_id = %s，再 INSERT） |
+
+### 业务含义
+
+NCI 衡量新客的"转化紧迫度"——分数越高，表示该新客越需要及时跟进以促成二访/三访。适用于首次到店不久或到店次数较少的新客群体。
+
+### 计算范围
+
+仅对 `segment = "NEW"` 的会员计算。
+
+### 算法概要
+
+NCI 由两部分组成：欢迎建联分（Welcome）和转化召回分（Convert），合并为总分：
+
+```
+NCI_raw = raw_score_welcome + raw_score_convert
+```
+
+#### 欢迎建联分（Welcome）
+
+针对首访后 3 天内的会员，鼓励立即触达：
+
+```
+welcome_new = clip(1 - t_v / welcome_window_days, 0, 1)    # 仅 visits_total ≤ 1 时生效
+raw_score_welcome = w_welcome × welcome_new
+```
+
+#### 转化召回分（Convert）
+
+由 4 个分项加权组成，并受活跃度抑制：
+
+```
+raw_score_convert = active_multiplier × (
+    w_need × (Need × Salvage) + w_re × Recharge × touch_multiplier + w_value × Value × touch_multiplier
+)
+```
+
+##### 分项 1：紧迫度（Need）
+
+衡量距二访目标窗口的紧迫程度：
+
+```
+Need = clip((t_v - no_touch_days) / (2 × t2_target_days - no_touch_days), 0, 1)
+```
+
+- `no_touch_days`（默认 3 天）：免打扰窗口，首访后短期内不催促
+- `t2_target_days`（默认 7 天）：二访目标天数
+
+##### 分项 2：挽救系数（Salvage）
+
+30-60 天线性衰减，超过 60 天视为流失：
+
+```
+Salvage = clip((salvage_end - t_a) / (salvage_end - salvage_start), 0, 1)
+```
+
+##### 分项 3：充值未回访压力（Recharge）
+
+与 WBI 相同：`Recharge = decay(t_r, h_recharge)`
+
+##### 分项 4：价值分（Value）
+
+与 WBI 相同：`Value = w_spend × ln(1 + spend_180d / M0) + w_bal × ln(1 + sv_balance / B0)`
+
+#### 活跃新客抑制
+
+近期高频到店的新客不需要催促，降低其排名权重：
+
+```
+若 visits_14d ≥ active_new_visit_threshold_14d 且 t_v ≤ active_new_recency_days:
+    active_multiplier = active_new_penalty (默认 0.2)
+否则:
+    active_multiplier = 1.0
+```
+
+#### 免打扰窗口乘数
+
+价值分和充值分在进入免打扰窗口后才逐步生效：
+
+```
+touch_multiplier = clip(t_v / no_touch_days, 0, 1)
+```
+
+### Display Score 归一化
+
+NCI 产出 3 个 Display Score：
+- `display_score`：总分归一化（使用 EWMA 平滑）
+- `display_score_welcome`：欢迎分归一化（不平滑）
+- `display_score_convert`：转化分归一化（不平滑）
+
+### 默认权重
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `w_welcome` | 1.0 | 欢迎建联权重 |
+| `w_need` | 1.6 | 紧迫度权重 |
+| `w_re` | 0.8 | 充值压力权重 |
+| `w_value` | 1.0 | 价值权重 |
+
+
+---
+
+## DWS_RELATION_INDEX — 关系指数（RS/OS/MS/ML）
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_RELATION_INDEX` |
+| Python 类 | `RelationIndexTask`（`tasks/dws/index/relation_index_task.py`） |
+| 继承链 | `BaseTask → BaseDwsTask → BaseIndexTask → RelationIndexTask` |
+| 目标表 | `billiards_dws.dws_member_assistant_relation_index` |
+| 主键 | `site_id, member_id, assistant_id` |
+| 指数类型 | RS / OS / MS / ML（单任务产出四个子指数） |
+| 更新策略 | 按门店全量刷新（先 DELETE WHERE site_id = %s，再 INSERT） |
+
+### 业务含义
+
+关系指数以"会员-助教"关系对为粒度，一次执行产出 4 个子指数：
+
+| 子指数 | 全称 | 含义 |
+|--------|------|------|
+| **RS** | Relation Strength | 关系强度——衡量会员与助教之间的服务关系紧密程度 |
+| **OS** | Ownership Share | 归属份额——确定会员的"主责助教"归属关系 |
+| **MS** | Momentum Score | 升温动量——衡量关系是在升温还是降温 |
+| **ML** | Money Link | 付费关联——基于人工台账的付费归因强度 |
+
+### 数据来源
+
+| 数据 | 来源表 | 说明 |
+|------|--------|------|
+| 服务记录 | `billiards_dwd.dwd_assistant_service_log` | RS/MS 的核心数据源 |
+| 助教维度 | `billiards_dwd.dim_assistant` | 通过 user_id 关联获取 assistant_id |
+| 人工台账 | `billiards_dws.dws_ml_manual_order_alloc` | ML 的唯一数据源 |
+
+### 会话合并
+
+服务记录按 `(member_id, assistant_id)` 分组后，相邻服务间隔 ≤ `session_merge_hours`（默认 4 小时）的记录合并为一个会话（ServiceSession）。合并后保留：
+- 会话起止时间、总时长
+- 课程权重（激励课 `course_weight = incentive_weight`，默认 1.5；普通课 = 1.0）
+- 是否包含激励课标记
+
+### 子指数 1：RS（关系强度）
+
+```
+RS_raw = (w_f × F + w_d × D) × Gate(R)
+```
+
+| 分项 | 公式 | 含义 |
+|------|------|------|
+| F（频次） | `Σ course_weight × decay(days_ago, halflife_session)` | 加权会话频次 |
+| D（时长） | `Σ √(duration_min / 60) × course_weight × decay(days_ago, halflife_session)` | 加权服务时长 |
+| R（近期性） | `decay(days_since_last_session, halflife_last)` | 最近一次服务的时间衰减 |
+| Gate | `R^gate_alpha` | 近期性门控，无近期服务则整体压低 |
+
+默认参数：`halflife_session=14`, `halflife_last=10`, `w_f=1.0`, `w_d=0.7`, `gate_alpha=0.6`
+
+### 子指数 2：OS（归属份额）
+
+OS 不是独立计算的 Raw Score，而是基于 RS_raw 的份额分配：
+
+1. 筛选 `rs_raw ≥ min_rs_raw_for_ownership`（默认 0.05）的关系对
+2. 计算份额：`os_share = rs_raw / Σ rs_raw`（同一会员下所有合格助教）
+3. 若 `Σ rs_raw < min_total_rs_raw`（默认 0.10），标记为 `UNASSIGNED`
+
+归属标签判定规则：
+
+| 标签 | 条件 |
+|------|------|
+| `MAIN` | 第一名份额 ≥ `ownership_main_threshold`（0.60）且与第二名差距 ≥ `ownership_gap_threshold`（0.15） |
+| `COMANAGE` | 份额 ≥ `ownership_comanage_threshold`（0.35）但不满足 MAIN 条件 |
+| `POOL` | 其余合格关系对 |
+| `UNASSIGNED` | 总 RS 不足，无法形成稳定归属 |
+
+### 子指数 3：MS（升温动量）
+
+衡量关系是在升温（MS > 0）还是降温（MS ≈ 0）：
+
+```
+f_short = Σ course_weight × decay(days_ago, halflife_short)    # 短期半衰期 7 天
+f_long  = Σ course_weight × decay(days_ago, halflife_long)     # 长期半衰期 30 天
+MS_raw  = max(0, ln(f_short + ε) / (f_long + ε))
+```
+
+短期频次高于长期频次时 MS 为正，表示关系在升温。
+
+### 子指数 4：ML（付费关联）
+
+以人工台账窄表（`dws_ml_manual_order_alloc`）为唯一数据源：
+
+```
+ML_raw = Σ ln(1 + allocated_amount / amount_base) × decay(days_ago, halflife_recharge)
+```
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `amount_base` | 500 | 金额压缩基准 |
+| `halflife_recharge` | 21 天 | 充值半衰期 |
+
+若某 `(member_id, assistant_id)` 对仅在台账中出现而无服务记录，会自动创建关系对。
+
+### Display Score 归一化
+
+RS、MS、ML 各自独立归一化到 0-10 分，分位历史按 `index_type` 隔离（分别记录 RS/MS/ML 的分位点）。OS 不做归一化，直接输出份额和标签。
+
+
+---
+
+## DWS_ML_MANUAL_IMPORT — ML 人工台账导入
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_ML_MANUAL_IMPORT` |
+| Python 类 | `MlManualImportTask`（`tasks/dws/index/ml_manual_import_task.py`） |
+| 继承链 | `BaseTask → BaseDwsTask → BaseIndexTask → MlManualImportTask` |
+| 目标表 | `billiards_dws.dws_ml_manual_order_source`（宽表）+ `billiards_dws.dws_ml_manual_order_alloc`（窄表） |
+| 主键 | 宽表：`site_id, external_id, import_scope_key, row_no`；窄表：`site_id, external_id, assistant_id` |
+| 指数类型 | `ML` |
+| 更新策略 | 按 scope 先删后写（DAY 或 P30 批次覆盖） |
+
+### 业务含义
+
+ML 人工台账导入是一个工具型任务，用于将运营人员手工整理的订单-助教归因数据导入系统。导入后的数据作为 `DWS_RELATION_INDEX` 任务中 ML 子指数的唯一数据源。
+
+该任务不依赖时间窗口，由调度器以工具任务方式直接触发。
+
+### 文件路径解析
+
+按以下优先级查找台账文件：
+
+1. 配置项 `run.ml_manual_ledger_file`
+2. 配置项 `run.ml_manual_file`
+3. 环境变量 `ML_MANUAL_LEDGER_FILE`
+
+### Excel 模板格式
+
+台账文件为 `.xlsx` 格式，第一行为表头，第二行起为数据。模板列定义：
+
+| 列名 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `site_id` | int | 否（默认取配置） | 门店 ID |
+| `biz_date` | date | 是 | 业务日期 |
+| `external_id` | string | 是 | 外部订单 ID（唯一标识） |
+| `member_id` | int | 否 | 会员 ID |
+| `pay_time` | datetime | 否（默认取 biz_date） | 支付时间 |
+| `order_amount` | decimal | 否 | 订单金额 |
+| `currency` | string | 否（默认 CNY） | 币种 |
+| `assistant_id_1` ~ `assistant_id_5` | int | 否 | 助教 ID（最多 5 个） |
+| `assistant_name_1` ~ `assistant_name_5` | string | 否 | 助教姓名 |
+| `remark` | string | 否 | 备注 |
+
+### 导入逻辑
+
+#### 1. 读取与规范化
+
+- 使用 `openpyxl` 读取 Excel，跳过空行
+- 每行规范化：类型转换、缺省值填充、助教列表提取
+- `external_id` 为必填，缺失则抛出 `ValueError`
+
+#### 2. 助教分摊
+
+同一订单支持最多 5 个助教归因，默认均分：
+
+```
+share_ratio = 1 / N
+allocated_amount = order_amount × share_ratio
+```
+
+#### 3. 覆盖策略（ImportScope）
+
+根据 `biz_date` 与当前日期的距离，采用不同的覆盖粒度：
+
+| 条件 | scope_type | 覆盖范围 | 说明 |
+|------|------------|----------|------|
+| `today - biz_date ≤ 30 天` | `DAY` | 单日 | 按 `site_id + biz_date` 日覆盖 |
+| `today - biz_date > 30 天` | `P30` | 30 天批次 | 以固定纪元（2026-01-01）为锚点，按 30 天分桶 |
+
+P30 分桶算法：
+```
+bucket_index = (biz_date - EPOCH_ANCHOR).days // 30
+bucket_start = EPOCH_ANCHOR + bucket_index × 30 天
+bucket_end   = bucket_start + 29 天
+```
+
+#### 4. 写入流程
+
+1. 按 scope 删除旧数据（宽表 + 窄表）
+2. 插入宽表（`dws_ml_manual_order_source`）
+3. Upsert 窄表（`dws_ml_manual_order_alloc`），冲突键为 `(site_id, external_id, assistant_id)`
+4. 提交事务
+
+#### 5. 导入批次号
+
+格式：`MLM_<YYYYMMDDHHmmss>_<uuid8>`，如 `MLM_20260215143022_a1b2c3d4`
+
+导入用户按优先级取：环境变量 `ETL_OPERATOR` → `USERNAME` → `USER` → `"system"`
+
+
+---
+
+## cfg_index_parameters 配置表
+
+所有指数任务的算法参数统一存储在 `billiards_dws.cfg_index_parameters` 表中，支持按时间生效和历史追溯。
+
+### 表结构
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `param_id` | SERIAL PK | 自增主键 |
+| `index_type` | VARCHAR(50) NOT NULL | 指数类型：`RS` / `OS` / `MS` / `ML` / `NCI` / `WBI` |
+| `param_name` | VARCHAR(100) NOT NULL | 参数名称 |
+| `param_value` | NUMERIC(14,6) NOT NULL | 参数值 |
+| `description` | TEXT | 参数说明 |
+| `effective_from` | DATE NOT NULL | 生效起始日期（默认当天） |
+| `effective_to` | DATE | 生效截止日期（NULL = 永久有效） |
+| `created_at` | TIMESTAMPTZ | 创建时间 |
+| `updated_at` | TIMESTAMPTZ | 更新时间 |
+
+唯一约束：`(index_type, param_name, effective_from)`
+
+索引：`idx_cfg_index_params_type`（index_type）、`idx_cfg_index_params_effective`（effective_from, effective_to）
+
+### 参数加载逻辑
+
+```sql
+SELECT param_name, param_value
+FROM billiards_dws.cfg_index_parameters
+WHERE index_type = %s
+  AND effective_from <= CURRENT_DATE
+  AND (effective_to IS NULL OR effective_to >= CURRENT_DATE)
+ORDER BY effective_from DESC
+```
+
+同一 `param_name` 若有多条生效记录，取 `effective_from` 最新的一条（代码中通过 `seen` 集合去重）。
+
+### 参数调优方式
+
+新增一条 `effective_from` 为新日期的记录即可覆盖旧参数，旧记录自动失效（无需删除）。如需回滚，将新记录的 `effective_to` 设为过去日期即可。
+
+### WBI 参数清单
+
+| 参数名 | 默认值 | 说明 |
+|--------|--------|------|
+| `lookback_days_recency` | 60 | 近期活跃判定窗口（天） |
+| `visit_lookback_days` | 180 | 到店记录回溯窗口（天） |
+| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |
+| `compression_mode` | 0 | 压缩模式（0=无/1=log1p/2=asinh） |
+| `use_smoothing` | 1 | 是否启用 EWMA 分位平滑 |
+| `ewma_alpha` | 0.2 | EWMA 平滑系数 |
+| `new_visit_threshold` | 2 | 新客到店次数阈值 |
+| `new_days_threshold` | 30 | 新客首访天数阈值 |
+| `recharge_recent_days` | 14 | 近期充值窗口（天） |
+| `new_recharge_max_visits` | 10 | 充值新客最大到店次数 |
+| `overdue_alpha` | 2.0 | 超期 CDF 幂指数 |
+| `overdue_weight_halflife_days` | 30 | 超期加权 CDF 间隔半衰期（天） |
+| `overdue_weight_blend_min_samples` | 8 | 加权 CDF 最小样本数 |
+| `h_recharge` | 7 | 充值衰减半衰期（天） |
+| `amount_base_M0` | 300 | 消费金额压缩基准 |
+| `balance_base_B0` | 500 | 余额压缩基准 |
+| `value_w_spend` / `value_w_bal` | 1.0 / 1.0 | 价值分中消费/余额权重 |
+| `w_over` / `w_drop` / `w_re` / `w_value` | 2.0 / 1.0 / 0.4 / 1.2 | 四分项权重 |
+| `recency_hard_floor_days` | 14 | 近期硬抑制天数 |
+| `recency_gate_days` | 14 | Sigmoid 门控中心（天） |
+| `recency_gate_slope_days` | 3 | Sigmoid 门控斜率（天） |
+| `enable_stop_high_balance_exception` | 0 | 是否启用 STOP 高余额例外 |
+| `high_balance_threshold` | 1000 | 高余额阈值（元） |
+
+### NCI 参数清单
+
+| 参数名 | 默认值 | 说明 |
+|--------|--------|------|
+| `lookback_days_recency` | 60 | 近期活跃判定窗口（天） |
+| `visit_lookback_days` | 180 | 到店记录回溯窗口（天） |
+| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |
+| `compression_mode` | 0 | 压缩模式 |
+| `use_smoothing` | 1 | 是否启用 EWMA 分位平滑 |
+| `ewma_alpha` | 0.2 | EWMA 平滑系数 |
+| `no_touch_days_new` | 3 | 免打扰窗口（天） |
+| `t2_target_days` | 7 | 二访目标天数 |
+| `salvage_start` / `salvage_end` | 30 / 60 | 挽救系数衰减区间（天） |
+| `welcome_window_days` | 3 | 欢迎建联窗口（天） |
+| `active_new_visit_threshold_14d` | 2 | 活跃新客 14 天到店阈值 |
+| `active_new_recency_days` | 7 | 活跃新客近期天数 |
+| `active_new_penalty` | 0.2 | 活跃新客抑制系数 |
+| `h_recharge` | 7 | 充值衰减半衰期（天） |
+| `amount_base_M0` / `balance_base_B0` | 300 / 500 | 价值分压缩基准 |
+| `value_w_spend` / `value_w_bal` | 1.0 / 0.8 | 价值分权重 |
+| `w_welcome` / `w_need` / `w_re` / `w_value` | 1.0 / 1.6 / 0.8 / 1.0 | 分项权重 |
+
+### RS 参数清单
+
+| 参数名 | 默认值 | 说明 |
+|--------|--------|------|
+| `lookback_days` | 60 | 服务行为回溯窗口（天） |
+| `session_merge_hours` | 4 | 会话合并阈值（小时） |
+| `incentive_weight` | 1.5 | 激励课权重 |
+| `halflife_session` | 14 | 会话半衰期（天） |
+| `halflife_last` | 10 | 最近服务半衰期（天） |
+| `weight_f` / `weight_d` | 1.0 / 0.7 | 频次/时长权重 |
+| `gate_alpha` | 0.6 | 近期性门控指数 |
+| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |
+| `compression_mode` | 1 | 压缩模式（默认 log1p） |
+| `use_smoothing` / `ewma_alpha` | 1 / 0.2 | EWMA 平滑 |
+
+### OS 参数清单
+
+| 参数名 | 默认值 | 说明 |
+|--------|--------|------|
+| `min_rs_raw_for_ownership` | 0.05 | 参与归属计算的最小 RS_raw |
+| `min_total_rs_raw` | 0.10 | 形成稳定归属的最小 sum_rs |
+| `ownership_main_threshold` | 0.60 | 主责份额阈值 |
+| `ownership_comanage_threshold` | 0.35 | 共管份额阈值 |
+| `ownership_gap_threshold` | 0.15 | 主责与次席差距阈值 |
+| `eps` | 0.000001 | 数值稳定项 |
+
+### MS 参数清单
+
+| 参数名 | 默认值 | 说明 |
+|--------|--------|------|
+| `lookback_days` | 60 | 服务行为回溯窗口（天） |
+| `session_merge_hours` | 4 | 会话合并阈值（小时） |
+| `incentive_weight` | 1.5 | 激励课权重 |
+| `halflife_short` / `halflife_long` | 7 / 30 | 短期/长期半衰期（天） |
+| `eps` | 0.000001 | 数值稳定项 |
+| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |
+| `compression_mode` | 1 | 压缩模式（默认 log1p） |
+| `use_smoothing` / `ewma_alpha` | 1 / 0.2 | EWMA 平滑 |
+
+### ML 参数清单
+
+| 参数名 | 默认值 | 说明 |
+|--------|--------|------|
+| `lookback_days` | 60 | 充值行为回溯窗口（天） |
+| `amount_base` | 500 | 金额压缩基准 |
+| `halflife_recharge` | 21 | 充值半衰期（天） |
+| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |
+| `compression_mode` | 1 | 压缩模式（默认 log1p） |
+| `use_smoothing` / `ewma_alpha` | 1 / 0.2 | EWMA 平滑 |
+
+> 种子数据脚本：`database/seed_index_parameters.sql`
+> DDL 定义：`database/schema_dws.sql`（第 21 节）