Neo-ZQYY/docs/database/BD_Manual_dws_member_spending_power_index.md

BD_Manual：dws_member_spending_power_index（SPI 消费力指数）

DWS 表：dws.dws_member_spending_power_index DWD 数据源：dwd.dwd_settlement_head（消费订单）、dwd.dwd_recharge_order（充值订单） 配置表：dws.cfg_index_parameters（index_type='SPI'） 任务代码：DWS_SPENDING_POWER_INDEX 代码位置：apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py DDL 位置：docs/database/ddl/etl_feiqiu__dws.sql 迁移脚本：db/etl_feiqiu/migrations/2026-02-23_create_dws_member_spending_power_index.sql 种子数据：db/etl_feiqiu/seeds/seed_index_parameters.sql（index_type='SPI' 部分）

---

1. 表结构

列名	类型	默认值	业务含义	取值范围/示例
spi_id	BIGINT (SERIAL)	nextval 序列	自增主键（PK）	自增
site_id	INTEGER NOT NULL	—	门店 ID	飞球门店 ID
member_id	BIGINT NOT NULL	—	会员 ID	飞球会员 ID
spend_30	NUMERIC(14,2)	0	近 30 天消费总额（元）	0.00 ~ 金额值
spend_90	NUMERIC(14,2)	0	近 90 天消费总额（元）	0.00 ~ 金额值
recharge_90	NUMERIC(14,2)	0	近 90 天充值总额（元）	0.00 ~ 金额值
orders_30	INTEGER	0	近 30 天消费笔数	0 ~ 正整数
orders_90	INTEGER	0	近 90 天消费笔数	0 ~ 正整数
visit_days_30	INTEGER	0	近 30 天消费日数（按天去重）	0 ~ 30
visit_days_90	INTEGER	0	近 90 天消费日数（按天去重）	0 ~ 90
avg_ticket_90	NUMERIC(14,2)	0	90 天客单价（= spend_90 / max(orders_90, 1)）	0.00 ~ 金额值
active_weeks_90	INTEGER	0	近 90 天有消费的自然周数	0 ~ 13
daily_spend_ewma_90	NUMERIC(14,2)	0	日消费 EWMA（指数加权移动平均）	0.00 ~ 金额值
score_level_raw	NUMERIC(10,4)	0	Level 子分原始分（消费水平）	≥ 0
score_speed_raw	NUMERIC(10,4)	0	Speed 子分原始分（消费速度）	≥ 0
score_stability_raw	NUMERIC(10,4)	0	Stability 子分原始分（消费稳定性）	0.0000 ~ 1.0000
score_level_display	NUMERIC(5,2)	0	Level 子分展示分	0.00 ~ 10.00
score_speed_display	NUMERIC(5,2)	0	Speed 子分展示分	0.00 ~ 10.00
score_stability_display	NUMERIC(5,2)	0	Stability 子分展示分	0.00 ~ 10.00
raw_score	NUMERIC(10,4)	0	SPI 总分原始分（加权合成）	≥ 0
display_score	NUMERIC(5,2)	0	SPI 总分展示分	0.00 ~ 10.00
calc_time	TIMESTAMPTZ	NOW()	本次计算时间	ISO 时间戳
created_at	TIMESTAMPTZ	NOW()	记录创建时间	ISO 时间戳
updated_at	TIMESTAMPTZ	NOW()	记录最后更新时间	ISO 时间戳

---

2. 主键与索引

名称	类型	列	说明
dws_member_spending_power_index_pkey	PRIMARY KEY	spi_id	物理主键（自增序列）
idx_spi_site_member	UNIQUE INDEX	(site_id, member_id)	业务主键：每个门店每个会员唯一一条记录
idx_spi_display_score	INDEX	(site_id, display_score DESC)	按门店查询展示分排名，支持 TOP-N 查询

---

3. 数据写入策略

• delete-before-insert：每次执行按 site_id 全量刷新
  1. DELETE FROM dws.dws_member_spending_power_index WHERE site_id = %s
  2. 批量 INSERT 新计算结果
• 无数据时跳过（不删除、不插入），返回 {'status': 'skipped', 'reason': 'no_data'}

---

4. 算法概要

4.1 数据来源

来源表	筛选条件	提取内容
dwd.dwd_settlement_head	近 90 天，settle_type IN (1, 3)	消费金额、笔数、消费日数、周覆盖、日消费序列
dwd.dwd_recharge_order	近 90 天，settle_type = 5	充值总额

4.2 子分公式

• Level（消费水平，权重 0.60）： L = w_s30 × ln(1 + spend_30/M30) + w_s90 × ln(1 + spend_90/M90) + w_ticket × ln(1 + avg_ticket_90/T0) + w_r90 × ln(1 + recharge_90/R90)

• Speed（消费速度，权重 0.30）： S = w_abs × V_abs + w_rel × max(0, V_rel) + w_ewma × V_ewma

  • V_abs = ln(1 + spend_30 / (max(visit_days_30, 1) × V0))
  • V_rel = ln((v_30 + ε) / (v_90 + ε))，仅加速加分
  • V_ewma = ln(1 + daily_spend_ewma_90 / E0)

• Stability（消费稳定性，权重 0.10）： P = active_weeks_90 / 13，取值 [0, 1]

4.3 总分合成

SPI_raw = w_L × L + w_S × S + w_P × P（默认 0.60 / 0.30 / 0.10）

4.4 展示分映射

Raw → Winsorize(P5, P95) → 可选压缩(log1p/asinh) → MinMax [0, 10] → 可选 EWMA 平滑

子分（Level/Speed/Stability）各自独立映射，使用 SPI_LEVEL / SPI_SPEED / SPI_STABILITY 隔离分位历史。

---

5. 配置参数

所有参数存储在 dws.cfg_index_parameters（index_type='SPI'），缺失时回退到代码中 DEFAULT_PARAMS。

参数名	默认值	说明
spend_window_short_days	30	短窗口天数
spend_window_long_days	90	长窗口天数
ewma_alpha_daily_spend	0.3	日消费 EWMA 平滑系数
amount_base_spend_30	500.0	30 天消费金额压缩基数
amount_base_spend_90	1500.0	90 天消费金额压缩基数
amount_base_ticket_90	200.0	客单价压缩基数
amount_base_recharge_90	1000.0	充值金额压缩基数
amount_base_speed_abs	100.0	绝对速度压缩基数
amount_base_ewma_90	50.0	EWMA 速度压缩基数
w_level_spend_30	0.30	Level 子分中 spend_30 权重
w_level_spend_90	0.35	Level 子分中 spend_90 权重
w_level_ticket_90	0.20	Level 子分中 avg_ticket_90 权重
w_level_recharge_90	0.15	Level 子分中 recharge_90 权重
w_speed_abs	0.50	Speed 子分中绝对速度权重
w_speed_rel	0.30	Speed 子分中相对速度权重
w_speed_ewma	0.20	Speed 子分中 EWMA 速度权重
weight_level	0.60	总分中 Level 权重
weight_speed	0.30	总分中 Speed 权重
weight_stability	0.10	总分中 Stability 权重
stability_window_days	90	稳定性计算窗口
use_stability	1	是否启用稳定性子分（0=禁用）
percentile_lower	5	Winsorize 下分位
percentile_upper	95	Winsorize 上分位
compression_mode	1	压缩模式：0=无，1=log1p，2=asinh
use_smoothing	1	是否启用 EWMA 分位平滑
ewma_alpha	0.2	分位平滑 EWMA 系数
speed_epsilon	1e-6	速度计算防除零小量

---

6. 前置依赖

• 任务依赖：DWS_MEMBER_CONSUMPTION（需先完成会员消费汇总）
• 数据源表：dwd.dwd_settlement_head、dwd.dwd_recharge_order 必须已有数据
• 配置表：dws.cfg_index_parameters 中 index_type='SPI' 种子数据已插入（缺失时使用默认值）
• 分位历史表：dws.dws_index_percentile_history（首次执行时无历史，不平滑）

---

7. 验证 SQL

7.1 检查表是否存在且有数据

SELECT
    COUNT(*)          AS total_rows,
    COUNT(DISTINCT site_id) AS site_count,
    MIN(calc_time)    AS earliest_calc,
    MAX(calc_time)    AS latest_calc
FROM dws.dws_member_spending_power_index;

7.2 检查展示分范围是否合规（应全部在 [0, 10]）

SELECT
    COUNT(*) FILTER (WHERE display_score < 0 OR display_score > 10)          AS spi_out_of_range,
    COUNT(*) FILTER (WHERE score_level_display < 0 OR score_level_display > 10)   AS level_out_of_range,
    COUNT(*) FILTER (WHERE score_speed_display < 0 OR score_speed_display > 10)   AS speed_out_of_range,
    COUNT(*) FILTER (WHERE score_stability_display < 0 OR score_stability_display > 10) AS stability_out_of_range
FROM dws.dws_member_spending_power_index;
-- 预期：所有列均为 0

7.3 检查业务主键唯一性（不应有重复）

SELECT site_id, member_id, COUNT(*) AS cnt
FROM dws.dws_member_spending_power_index
GROUP BY site_id, member_id
HAVING COUNT(*) > 1;
-- 预期：无结果返回

7.4 按门店查看 SPI 分布概况

SELECT
    site_id,
    COUNT(*)                          AS member_count,
    ROUND(AVG(display_score), 2)      AS avg_spi,
    ROUND(MIN(display_score), 2)      AS min_spi,
    ROUND(MAX(display_score), 2)      AS max_spi,
    ROUND(PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY display_score), 2) AS median_spi
FROM dws.dws_member_spending_power_index
GROUP BY site_id
ORDER BY site_id;

7.5 检查 Stability 子分原始分范围（应在 [0, 1]）

SELECT COUNT(*) AS out_of_range
FROM dws.dws_member_spending_power_index
WHERE score_stability_raw < 0 OR score_stability_raw > 1;
-- 预期：0

---

8. 兼容性说明

影响范围	说明
ETL 任务	新增任务 DWS_SPENDING_POWER_INDEX，依赖 DWS_MEMBER_CONSUMPTION。不影响现有 WBI/NCI/RS/OS/MS/ML 指数任务
后端 API	当前无 API 直接读取此表。后续如需暴露 SPI 数据，需新增接口
管理后台	当前无前端页面展示 SPI。后续可在会员详情页新增 SPI 展示
小程序	无影响
其他指数	SPI 独立于现有指数体系，不修改任何已有表或任务逻辑
分位历史	SPI 会向 dws.dws_index_percentile_history 写入 index_type='SPI'/SPI_LEVEL/SPI_SPEED/SPI_STABILITY 的分位记录

---

9. 回滚策略

9.1 删除数据（保留表结构）

DELETE FROM dws.dws_member_spending_power_index;
DELETE FROM dws.dws_index_percentile_history WHERE index_type LIKE 'SPI%';
DELETE FROM dws.cfg_index_parameters WHERE index_type = 'SPI';

9.2 完整回滚（删除表）

DROP INDEX IF EXISTS dws.idx_spi_display_score;
DROP INDEX IF EXISTS dws.idx_spi_site_member;
DROP TABLE IF EXISTS dws.dws_member_spending_power_index;
DROP SEQUENCE IF EXISTS dws.dws_member_spending_power_index_spi_id_seq;

9.3 回滚任务注册

从 orchestration/task_registry.py 中移除 DWS_SPENDING_POWER_INDEX 注册行，并从 tasks/dws/index/__init__.py 和 tasks/dws/__init__.py 中移除 SpendingPowerIndexTask 导出。

---

10. 代码引用

• 任务类：tasks/dws/index/spending_power_index_task.py → SpendingPowerIndexTask
• 继承：BaseIndexTask（tasks/dws/index/base_index_task.py）
• 任务注册：orchestration/task_registry.py → DWS_SPENDING_POWER_INDEX
• 属性测试：tests/test_spi_properties.py
• 单元测试：apps/etl/connectors/feiqiu/tests/unit/test_spi_task.py
• 迁移脚本：db/etl_feiqiu/migrations/2026-02-23_create_dws_member_spending_power_index.sql
• 种子数据：db/etl_feiqiu/seeds/seed_index_parameters.sql