root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

在前后端开发联调前 的提交20260223

Browse Source
This commit is contained in:
Neo
2026-02-23 23:02:20 +08:00
parent 254ccb1e77
commit fafc95e64c
1142 changed files with 10366960 additions and 36957 deletions
Download Patch File Download Diff File Expand all files Collapse all files

706
docs/prd/SPI 消费力指数.md Normal file
View File

@@ -0,0 +1,706 @@
# 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])