# PRD：SPI 消费力指数（Spending Power Index）建设方案（MD）

* **文档版本**：v1.0
* **状态**：定稿（可进入研发设计/排期）
* **适用范围**：门店客户运营（新客转化、老客召回、增值推荐、资源分配）
* **相关指数体系**：`NCI`、`WBI`、`RS`、`OS`、`MS`、`ML`（SPI 为新增客户级指数）

---

## 1. 背景与目标

### 1.1 背景

当前体系中：

* `NCI` 用于新客欢迎与转化优先级
* `WBI` 用于老客召回优先级
* `RS/OS/MS/ML` 用于关系强度、归属、动量、付费关联（助教-客户关系对粒度）

但尚缺少一个**客户级的“消费能力/消费层级”指数**，导致以下问题：

* 高价值客户与普通客户在运营动作上难以区分投入强度
* 增值服务推荐缺少“消费能力层级”依据
* 资源分配容易只看“紧急程度”，忽略“投入产出比（ROI）”

### 1.2 目标

新增 **SPI（Spending Power Index，消费力指数）**，评估客户在门店场景内的“消费力代理值”，重点基于：

* **消费水平（Level）**
* **消费速度（Speed）**
* **消费稳定性（Stability，可选修正项）**

> 说明：稳定性窗口**最长只使用 90 天**，不使用 180 天（按本次需求明确要求）。

### 1.3 非目标

* 不评估金融/征信意义上的“信用能力”
* 不直接替代 NCI/WBI（紧迫度）
* 不直接替代 RS/OS/MS/ML（关系归属与执行人选择）

---

## 2. 设计原则与方法依据

1. **行为数据驱动**：使用消费/充值明细作为消费力代理信号（门店经营场景可解释、可落地）。
2. **稳健统计**：金额类数据长尾明显，展示分采用分位截断（Winsorize）降低极端值影响。Winsorization 本质是用指定分位数限制极端值影响，适合交易金额数据。
3. **时间敏感**：近期行为更有参考价值，采用指数衰减与 EWMA 平滑（近期更高权重）来处理速度与展示分稳定性。指数衰减与半衰期是标准时间权重形式，EWMA 则是常见的时间序列平滑方法。
4. **与现有体系兼容**：沿用现有 `BaseIndexTask` 的映射逻辑（P5/P95 → 压缩 → MinMax 0–10 → 可选 EWMA）。
5. **运营闭环导向**：SPI 不是单独使用，需与 NCI/WBI/RS/OS/MS/ML 组合使用。

> 补充说明：RFM（Recency/Frequency/Monetary）是成熟的客户价值/客户分层框架，SPI 在其基础上强化“消费速度”与门店场景的可执行性。

---

## 3. 指数定义

## 3.1 指数名称

* 中文：**消费力指数**
* 英文：**Spending Power Index**
* 缩写：**SPI**

## 3.2 粒度

* **客户级（member）**
* 主键建议：`(site_id, member_id)`

## 3.3 业务含义

SPI 用于衡量客户在门店体系内的综合消费力层级，回答：

* 这个客户整体消费能力在门店内属于什么层级？
* 近期消费推进速度是否明显变快？
* 是稳定高消费，还是偶发冲高？

---

## 4. 数据来源与口径

## 4.1 数据来源（建议）

### A. 消费订单明细（核心）

* 来源：结算/订单主表及明细表（按现有 DWD 口径）
* 字段（至少）：

  * `site_id`
  * `member_id`
  * `pay_time`
  * `pay_amount`（实付）
  * `settle_type`（必要时过滤）
  * 明细项分类（台费、商品、服务等）

### B. 充值订单明细（辅助）

* 来源：`dwd_recharge_order`
* 字段（至少）：

  * `site_id`
  * `member_id`
  * `pay_time`
  * `pay_amount`
  * `settle_type = 5`

### C. 可选增强

* 储值卡余额（用于解释）

---

## 4.2 时间窗口（定稿）

> **稳定性最长只用 90 天。**

* **短窗口**：30 天（近期消费速度）
* **中窗口**：90 天（消费层级、速度基线、稳定性）

---

## 4.3 统计口径（建议）

* 消费金额：使用 `pay_amount`（实付）
* 按天去重的消费日：用于计算消费日密度
* 若同一天多笔消费：计入总额，消费日数仅计 1 天
* 充值金额：使用充值订单 `pay_amount`
* 金额单位：与现有系统保持一致（元）

---

## 5. SPI 算法设计（v1）

> v1 采用“主分 + 子分”的结构，保证解释性：

* `Level`（消费水平）
* `Speed`（消费速度）
* `Stability`（消费稳定性，作为修正项；最长 90 天）
* `SPI = f(Level, Speed, Stability)`

---

## 5.1 基础特征定义（客户级）

设：

* `spend_30`：近30天消费总额
* `spend_90`：近90天消费总额
* `recharge_90`：近90天充值总额
* `orders_30 / orders_90`：近30/90天消费笔数
* `visit_days_30 / visit_days_90`：近30/90天有消费的自然日数（按天去重）
* `avg_ticket_90 = spend_90 / max(orders_90, 1)`：90天客单
* `weekly_spend_90`：近90天按周汇总消费额序列（约13周）
* `daily_spend_series_90`：近90天按日消费额序列（用于 EWMA）

---

## 5.2 子分一：消费水平（Level）

### 目的

衡量客户的消费金额层级与客单水平，兼顾充值规模（预算能力代理信号）。

### 建议公式

[
L = w_{s30}\cdot \ln(1+\frac{spend_{30}}{M30})

* w_{s90}\cdot \ln(1+\frac{spend_{90}}{M90})
* w_{ticket}\cdot \ln(1+\frac{avg_ticket_{90}}{T0})
* w_{r90}\cdot \ln(1+\frac{recharge_{90}}{R90})
  ]

### 说明

* 使用 `log1p` 压缩长尾，避免大额客户过度支配排序
* 30天与90天并用：兼顾近期层级与稳定层级
* 充值是辅助信号，不应压过真实消费金额

---

## 5.3 子分二：消费速度（Speed）

### 目的

衡量“近期消费推进快不快”，体现消费节奏变化。

### A. 绝对速度（近期强度）

[
V_{abs} = \ln \left(1+\frac{spend_{30}}{\max(visit_days_{30},1)\cdot V0}\right)
]

含义：近30天“每个消费日平均消费强度”。

### B. 相对速度（近期 vs 基线）

[
v_{30}=\frac{spend_{30}}{30}, \quad v_{90}=\frac{spend_{90}}{90}
]
[
V_{rel} = \ln\left(\frac{v_{30}+\epsilon}{v_{90}+\epsilon}\right)
]

* `V_rel > 0`：近期消费速度快于90天基线（加速）
* `V_rel < 0`：近期消费速度低于基线（放缓）

### C. 平滑速度（EWMA，可选）

对 `daily_spend_series_90` 做 EWMA，得到 `daily_spend_ewma_90`：
[
V_{ewma}=\ln(1+\frac{daily_spend_ewma_{90}}{E0})
]

### Speed 子分（建议）

[
S = w_{abs}\cdot V_{abs} + w_{rel}\cdot max(0, V_{rel}) + w_{ewma}\cdot V_{ewma}
]

> v1 建议仅对“加速”加分（`max(0,V_rel)`），不对“减速”直接扣分；减速信号已在 WBI 中承担召回压力逻辑。

---

## 5.4 子分三：消费稳定性（Stability，最长 90 天）

### 目的

识别“稳定高消费”与“偶发冲高”，防止单笔大单导致 SPI 虚高。

### 窗口要求（定稿）

**只使用近90天**

### 建议特征（v1 可二选一或组合）

[
Stab_{cover} = \frac{#(\text{近90天有消费的周数})}{13}
]

### Stability 子分（v1 推荐）

[
P = Stab_{cover}
]
（v1 先采用覆盖率，简单、稳健、工程成本低）

---

## 5.5 SPI 总分（Raw）

### 建议结构（v1）

[
SPI_{raw} = w_L \cdot L + w_S \cdot S + w_P \cdot P
]

### 建议默认权重（v1）

* `w_L = 0.60`
* `w_S = 0.30`
* `w_P = 0.10`

> 若你希望先简化上线，也可 v1.0 不启用稳定性（`w_P=0`），v1.1 再开启。
> 但本需求已明确“稳定性最长 90 天即可”，建议直接纳入 v1，权重先低配。

---

## 6. 展示分映射（Raw → Display 0–10）

SPI 与子分（Level/Speed/Stability）展示分均建议复用现有统一逻辑：

1. 收集全体 Raw 分数
2. 计算 `P5/P95`
3. Winsorize 截断到 `[P5, P95]`
4. 可选压缩（`none/log1p/asinh`）
5. MinMax 映射到 `[0,10]`
6. 可选 EWMA 平滑分位点
7. 展示分保留 2 位小数

> 该映射适合金额类/长尾分布指标，可降低极端值造成的排序失真。

---

## 7. 输出表设计（新增）

## 7.1 表名建议

`billiards_dws.dws_member_spending_power_index`

## 7.2 主键

* `(site_id, member_id)`

## 7.3 字段建议（v1）

### 基础特征（解释与排查）

* `spend_30`
* `spend_90`
* `recharge_90`
* `orders_30`
* `orders_90`
* `visit_days_30`
* `visit_days_90`
* `avg_ticket_90`
* `active_weeks_90`
* `daily_spend_ewma_90`（若启用）

### 子分

* `score_level_raw`
* `score_level_display`
* `score_speed_raw`
* `score_speed_display`
* `score_stability_raw`
* `score_stability_display`

### 总分

* `raw_score`（SPI_raw）
* `display_score`（SPI_display）

### 元数据

* `calc_time`
* `created_at`
* `updated_at`

---

## 8. 配置体系（cfg_index_parameters）新增项

## 8.1 index_type

新增：

* `SPI`

## 8.2 参数清单（建议默认值）

### 窗口与平滑

| 参数                        | 默认值 | 说明            |
| ------------------------- | --: | ------------- |
| `spend_window_short_days` |  30 | 短窗口（速度）       |
| `spend_window_long_days`  |  90 | 长窗口（层级/稳定性上限） |
| `ewma_alpha_daily_spend`  | 0.3 | 日消费 EWMA 平滑系数 |

### 金额压缩基数

| 参数                        |  默认值 | 说明         |
| ------------------------- | ---: | ---------- |
| `amount_base_spend_30`    |  按门店分布校准 | 30天消费压缩基数  |
| `amount_base_spend_90`    | 按门店分布校准 | 90天消费压缩基数  |
| `amount_base_ticket_90`   |  按门店分布校准 | 90天客单压缩基数  |
| `amount_base_recharge_90` | 按门店分布校准 | 90天充值压缩基数  |
| `amount_base_speed_abs`   |  按门店分布校准 | 绝对速度压缩基数   |
| `amount_base_ewma_90`     |  按门店分布校准 | EWMA速度压缩基数 |

### 权重（总分）

| 参数                 |  默认值 | 说明           |
| ------------------ | ---: | ------------ |
| `weight_level`     | 0.60 | Level 权重     |
| `weight_speed`     | 0.30 | Speed 权重     |
| `weight_stability` | 0.10 | Stability 权重 |

### 权重（Level 子分）

| 参数                    |  默认值 | 说明             |
| --------------------- | ---: | -------------- |
| `w_level_spend_30`    | 0.30 | Level 中 30天消费项 |
| `w_level_spend_90`    | 0.35 | Level 中 90天消费项 |
| `w_level_ticket_90`   | 0.20 | Level 中 90天客单项 |
| `w_level_recharge_90` | 0.15 | Level 中 90天充值项 |

### 权重（Speed 子分）

| 参数             |  默认值 | 说明        |
| -------------- | ---: | --------- |
| `w_speed_abs`  | 0.50 | 绝对速度项     |
| `w_speed_rel`  | 0.30 | 相对速度项（加速） |
| `w_speed_ewma` | 0.20 | EWMA速度项   |

### 稳定性参数（90天上限）

| 参数                      | 默认值 | 说明            |
| ----------------------- | --: | ------------- |
| `stability_window_days` |  90 | 稳定性窗口（固定上限90） |
| `use_stability`         |   1 | 是否启用稳定性子分     |
| `stability_mode`        |   1 | 1=周覆盖率（v1推荐）  |

### 映射与平滑（复用 BaseIndexTask）

| 参数                 | 默认值 | 说明                       |
| ------------------ | --: | ------------------------ |
| `percentile_lower` |   5 | 下分位                      |
| `percentile_upper` |  95 | 上分位                      |
| `compression_mode` |   1 | 0=none, 1=log1p, 2=asinh |
| `use_smoothing`    |   1 | 是否启用分位平滑                 |
| `ewma_alpha`       | 0.2 | 分位 EWMA 平滑系数             |

---

## 9. 任务与计算策略（建议）

## 9.1 任务形态

* 新增客户级任务：`SpendingPowerIndexTask`
* 粒度：`(site_id, member_id)`
* 建议频率：**每日**（与 NCI/WBI 接近，便于客户级看板统一刷新）

## 9.2 计算流程

1. 抽取消费订单明细（近90天）
2. 抽取充值订单明细（近90天）
3. 聚合客户级特征（30天/90天）
4. 计算 `Level/Speed/Stability` 子分 Raw
5. 计算 `SPI_raw`
6. 映射为展示分（0–10）
7. 写入 `dws_member_spending_power_index`（delete-before-insert 或 upsert）

---

## 10. SPI 参与的所有相关运营场景（完整清单）

> 原则：**SPI 不单独决定“要不要触达”，而是与 NCI/WBI（紧急度）+ RS/OS/MS/ML（执行关系）组合使用。**

---

## 10.1 新客运营（NCI 场景）

### 场景 A1：新客欢迎优先级（欢迎建联）

* **主用指数**：`NCI_welcome`
* **SPI 作用**：决定欢迎动作投入强度（轻触达/强服务）
* **策略**

  * `NCI_welcome 高 + SPI 高`：优先人工建联、安排更高质量接待与后续方案
  * `NCI_welcome 高 + SPI 中低`：标准欢迎流程，重点推动二访而非高价增值

### 场景 A2：新客二访转化

* **主用指数**：`NCI_convert`
* **SPI 作用**：判断适合推“基础二访”还是“升级体验包/储值方案”
* **配合指数**

  * `OS`：谁负责触达
  * `ML`：若涉及充值/储值，由谁推更容易成交

### 场景 A3：新客近期活跃（避免过度打扰）

* **主用指数**：`NCI`（内置活跃抑制）
* **SPI 作用**：不用于提高打扰频率，而用于现场服务策略分层
* **运营建议**

  * 高 SPI 新客：现场体验升级、服务深度设计
  * 低 SPI 新客：降低销售压力，先建立习惯

---

## 10.2 老客召回（WBI 场景）

### 场景 B1：老客召回名单排序

* **主用指数**：`WBI`
* **SPI 作用**：决定召回资源优先级（投入强度/人工优先）
* **策略**

  * `WBI 高 + SPI 高`：优先人工召回、重点维护
  * `WBI 高 + SPI 中低`：先低成本触达（消息/轻优惠）

### 场景 B2：充值未回访专项召回

* **主用指数**：`WBI`（充值未回访压力）
* **SPI 作用**：判断值得投入多大召回成本
* **配合指数**

  * `ML`：选执行人（谁推更容易成）
  * `OS`：定责（避免撞单）

### 场景 B3：高消费力沉默客户（价值保全）

* **触发逻辑**：`SPI 高` 且 `WBI` 进入召回区间
* **运营重点**：不是纯促销，而是“关系修复/体验恢复/高价值保留”

---

## 10.3 活跃客户跟进与升温承接（MS 场景）

### 场景 C1：近期消费/来店升温客户承接

* **主用指数**：`MS`（关系动量）
* **SPI 作用**：判断承接动作的强度与档位
* **配合指数**

  * `OS`：由谁跟进
  * `RS`：关系强弱决定话术深浅
  * `ML`：如涉及储值推荐，决定由谁推

### 场景 C2：关系强但消费层级下滑（潜在降档预警）

* **组合信号**：`RS 高` + `SPI_speed 下降`（或 SPI 总分下滑）
* **运营动作**：先做需求确认/体验诊断，再决定促销或产品调整

---

## 10.4 增值服务与储值推荐（ML + SPI 场景）

### 场景 D1：筛选“值得重点推增值”的客户

* **主用指数**：`SPI`
* **配合指数**：`MS`（时机）、`RS`（关系）、`WBI/NCI`（是否当前应触达）
* **策略**

  * `SPI 高 + MS 高`：优先推增值（最佳时机）
  * `SPI 高 + WBI 高`：先召回再推，不要直接硬销
  * `SPI 低 + RS 高`：可做低门槛增值尝试，不推高价方案

### 场景 D2：确定“由谁来推更可能成功”

* **主用指数**：`ML`
* **SPI 作用**：决定是否值得高成本人力投入
* **配合指数**

  * `OS`：责任边界
  * `RS`：关系基础
  * `MS`：时机窗口

---

## 10.5 客户分层与运营资源配置（门店/店长视角）

### 场景 E1：客户池分层（高/中/低消费力）

* **主用指数**：`SPI_display`
* **作用**：作为全店客户分层基础维度（可与活跃度、风险度交叉）
* **建议分层**

  * 高消费力（Top 10–20%）
  * 中消费力
  * 低消费力

### 场景 E2：人力资源分配（助教时间预算）

* **组合指数**

  * 客户优先级：`NCI/WBI`
  * 客户消费力：`SPI`
  * 执行人选择：`OS/ML`
* **规则示例**

  * 高 NCI/WBI + 高 SPI：优先人工跟进
  * 高 NCI/WBI + 低 SPI：半自动/标准化触达
  * 低 NCI/WBI + 高 SPI：低频但重点维系

### 场景 E3：活动名单筛选

* **SPI 作用**：筛选活动档位与名单
* **示例**

  * 高 SPI 客户：高阶体验/高客单活动
  * 中低 SPI 客户：入门体验/拉频次活动

---

## 10.6 管理与复盘（分析场景）

### 场景 F1：增值策略复盘

* **组合指标**：`SPI`（客户层级） + `ML`（执行人付费关联）
* **看什么**

  * 高 SPI 客户是否被正确触达
  * 高 SPI 客户的增值转化是否集中在正确助教（ML 高者）

### 场景 F2：客户结构变化监控

* **主用指数**：`SPI`
* **看什么**

  * 高 SPI 客户数量变化
  * 各层级客户占比变化
  * 高 SPI 客户的活跃/沉默迁移（结合 WBI）

### 场景 F3：门店经营质量诊断（非直接派单）

* **组合信号**

  * `SPI 高` 客户群体的 `WBI` 是否整体抬升（高价值流失预警）
  * `SPI 高` 客户群体的 `MS` 是否持续走低（热度下降）

---

## 11. 运营使用规则（落地建议）

## 11.1 统一原则

* **NCI/WBI 决定“要不要优先触达”**
* **SPI 决定“投入多大资源、用什么档位策略”**
* **OS/RS/MS/ML 决定“谁来做、什么时候做、谁更容易做成”**

## 11.2 一个实用的组合模板

### 新客转化

* 选人群：`NCI_convert 高`
* 分档：`SPI 高/中/低`
* 落人：`OS`（若已有关系）否则新客官
* 增值时机：`MS 高` 再推，执行人选 `ML 高`

### 老客召回

* 选人群：`WBI 高`
* 分档：`SPI 高` 优先人工，`SPI 低` 低成本触达
* 落人：`OS=MAIN`，若无归属则公海召回组
* 若涉及储值：执行人优先 `ML 高`

---

## 12. 验收标准（数据与业务）

## 12.1 数据正确性

* `SPI_raw` 在新增消费/充值后总体应单调不减（同等其他条件下）
* `score_speed_raw` 在近30天消费速度高于近90天基线时应提升
* `score_stability_raw` 仅使用近90天数据（不引用 180 天）
* 展示分稳定：在总体分布无大变化时，`display_score` 不应异常跳变（启用 EWMA）

## 12.2 业务可用性

* 运营可基于 SPI 完成客户分层（高/中/低）
* 运营可在 NCI/WBI 队列中使用 SPI 做资源投入分层
* 增值推荐场景可用 SPI + ML + OS 形成可执行规则

---

## 13. 风险与控制

1. **异常大单抬高 SPI**

   * 控制：Winsorize + 压缩变换 + 稳定性子分（90天覆盖率）

2. **充值替代真实消费导致高估**

   * 控制：充值在 Level 子分中权重较低（辅助信号）

3. **短期活动造成速度异常升高**

   * 控制：速度项只部分加权；稳定性项用于修正

4. **跨门店可比性问题**

   * 控制：SPI 默认用于门店内排序；如需跨店对比，需后续增加门店标准化层

---

## 14. 上线计划（建议）

### Phase 1：影子跑数（1–2 周）

* 后台计算 SPI，不对运营展示
* 验证分布、极值、客户样本解释性

### Phase 2：看板展示与规则试运行（2–4 周）

* 接入 NCI/WBI 队列的辅助分档
* 先用于“投入强度分层”，不直接自动派单

### Phase 3：策略联动

* 用于活动名单筛选、增值推荐档位
* 与 `ML/OS/MS` 联动形成自动建议

---

## 15. 研发实现清单（交付物）

1. 新增任务：`SpendingPowerIndexTask`
2. 新增结果表：`dws_member_spending_power_index`
3. 新增配置：`cfg_index_parameters` 中 `index_type='SPI'`
4. 新增看板字段：

   * `SPI_display`
   * `Level/Speed/Stability` 子分展示
5. 新增运营策略读取逻辑（可选）：

   * NCI/WBI 队列中读取 SPI 做资源分档

---

## 16. 附录：公式与约定（实现参考）

### 16.1 指数衰减（如后续引入时间衰减特征）

[
decay(d; h)=exp(-ln(2)\cdot d / h)
]
（半衰期形式，`d=h` 时权重降为 0.5）([维基百科][2])

### 16.2 展示分映射（沿用现有 BaseIndexTask）

* P5/P95 Winsorize
* `compression_mode`: `none / log1p / asinh`
* MinMax → `[0,10]`
* 可选 EWMA 分位平滑（`ewma_alpha`）([维基百科][1])