1

2026-03-15 10:15:02 +08:00
parent 2dd217522c
commit 72bb11b34f
916 changed files with 65306 additions and 16102803 deletions
--- a/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_assistant_order_contribution.md
+++ b/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_assistant_order_contribution.md
@@ -0,0 +1,266 @@
+# BD_Manual：dws_assistant_order_contribution（助教订单流水四项统计）
+
+> DWS 表：`dws.dws_assistant_order_contribution`
+> DWD 数据源：`dwd.dwd_settlement_head`（结算主表）、`dwd.dwd_table_fee_log`（台费明细）、`dwd.dwd_assistant_service_log`（助教服务记录）
+> 任务代码：`DWS_ASSISTANT_ORDER_CONTRIBUTION`
+> 代码位置：`apps/etl/connectors/feiqiu/tasks/dws/assistant_order_contribution_task.py`
+> DDL 位置：`docs/database/ddl/etl_feiqiu__dws.sql`
+> 迁移脚本：`db/etl_feiqiu/migrations/2025-02-24__create_dws_assistant_order_contribution.sql`
+> RLS 视图：`db/etl_feiqiu/migrations/2025-02-24__create_rls_view_assistant_order_contribution.sql`
+> FDW 映射：`db/zqyy_app/migrations/2025-02-24__add_fdw_dws_extensions.sql`
+
+---
+
+## 1. 表结构
+
+| 列名 | 类型 | 默认值 | 业务含义 | 取值范围/示例 |
+|------|------|--------|---------|-------------|
+| `contribution_id` | BIGINT (SERIAL) | nextval 序列 | 自增主键（PK） | 自增 |
+| `site_id` | BIGINT NOT NULL | — | 门店 ID | 飞球门店 ID |
+| `tenant_id` | BIGINT NOT NULL | — | 租户 ID | 飞球租户 ID |
+| `assistant_id` | BIGINT NOT NULL | — | 助教 ID | 飞球助教 ID |
+| `assistant_nickname` | VARCHAR(100) | NULL | 助教昵称 | 中文昵称 |
+| `stat_date` | DATE NOT NULL | — | 统计日期 | `2025-01-15` |
+| `order_gross_revenue` | NUMERIC(14,2) | 0 | 订单总流水 = 台费 + 酒水食品 + 所有助教服务费 | `0.00` ~ 金额值 |
+| `order_net_revenue` | NUMERIC(14,2) | 0 | 订单净流水 = 订单总流水 - 所有助教服务分成 | `0.00` ~ 金额值 |
+| `time_weighted_revenue` | NUMERIC(14,2) | 0 | 时效贡献流水 = 台费按时长分摊 + 个人服务费 + 酒水食品按时长比例 | `0.00` ~ 金额值 |
+| `time_weighted_net_revenue` | NUMERIC(14,2) | 0 | 时效净贡献 = 时效贡献流水 - 个人服务分成 | `0.00` ~ 金额值 |
+| `order_count` | INTEGER | 0 | 当日参与订单数 | `0` ~ 正整数 |
+| `total_service_seconds` | INTEGER | 0 | 当日总服务时长（秒） | `0` ~ 正整数 |
+| `created_at` | TIMESTAMPTZ | NOW() | 记录创建时间 | ISO 时间戳 |
+| `updated_at` | TIMESTAMPTZ | NOW() | 记录最后更新时间 | ISO 时间戳 |
+
+---
+
+## 2. 主键与索引
+
+| 名称 | 类型 | 列 | 说明 |
+|------|------|----|------|
+| `dws_assistant_order_contribution_pkey` | PRIMARY KEY | `contribution_id` | 物理主键（自增序列） |
+| `idx_aoc_site_assistant_date` | UNIQUE INDEX | `(site_id, assistant_id, stat_date)` | 业务主键：每个门店每个助教每天唯一一条记录 |
+| `idx_aoc_stat_date` | INDEX | `(site_id, stat_date)` | 按门店+日期查询，支持日度报表 |
+
+---
+
+## 3. 数据写入策略
+
+- **delete-before-insert**：每次执行按 `site_id` + 日期窗口全量刷新
+  1. `DELETE FROM dws.dws_assistant_order_contribution WHERE site_id = %s AND stat_date BETWEEN %s AND %s`
+  2. 批量 `INSERT` 新计算结果
+- 继承 `BaseDwsTask` 默认 load 实现，幂等可重跑
+
+---
+
+## 4. 算法概要
+
+### 4.1 数据来源
+
+| 来源表 | 筛选条件 | 提取内容 |
+|--------|---------|---------|
+| `dwd.dwd_settlement_head` | 日期窗口内，`settle_type IN (1, 3)` | 结算单信息、酒水食品金额 |
+| `dwd.dwd_table_fee_log` | 关联结算单 | 台桌使用时长、台费金额、区域 |
+| `dwd.dwd_assistant_service_log` | 关联结算单 | 助教服务时长、服务流水、分成、课程类型 |
+
+### 4.2 四项统计公式
+
+**订单总流水（order_gross_revenue）**
+```
+order_gross_revenue = total_table_fee + total_goods_amount + SUM(所有助教 ledger_amount)
+```
+每个参与助教获得相同值。
+
+**订单净流水（order_net_revenue）**
+```
+order_net_revenue = order_gross_revenue - SUM(所有助教 commission)
+```
+每个参与助教获得相同值。
+
+**时效贡献流水（time_weighted_revenue）**
+```
+对于台桌 t：
+  billable_seconds = MAX(SUM(助教服务时长), 台桌使用时长)
+  台费分摊_a = table_fee_t × (service_seconds_a / billable_seconds)
+
+酒水食品分摊_a = total_goods_amount × (助教 a 总服务时长 / 所有助教总服务时长)
+
+time_weighted_revenue_a = SUM(各台桌台费分摊_a) + ledger_amount_a + 酒水食品分摊_a
+```
+
+**时效净贡献（time_weighted_net_revenue）**
+```
+time_weighted_net_revenue_a = time_weighted_revenue_a - commission_a
+```
+
+### 4.3 超休/打赏课特殊处理
+
+当 `course_type = BONUS` 时，四项统计均等于个人服务流水和分成，不参与订单级分摊。
+
+---
+
+## 5. 前置依赖
+
+- 任务依赖：`DWD_LOAD_FROM_ODS`（需先完成 DWD 层数据加载）
+- 数据源表：`dwd.dwd_settlement_head`、`dwd.dwd_table_fee_log`、`dwd.dwd_assistant_service_log` 必须已有数据
+
+---
+
+## 6. 验证 SQL
+
+### 6.1 检查表是否存在且有数据
+
+```sql
+SELECT
+    COUNT(*)                    AS total_rows,
+    COUNT(DISTINCT site_id)     AS site_count,
+    COUNT(DISTINCT assistant_id) AS assistant_count,
+    MIN(stat_date)              AS earliest_date,
+    MAX(stat_date)              AS latest_date
+FROM dws.dws_assistant_order_contribution;
+```
+
+### 6.2 检查业务主键唯一性（不应有重复）
+
+```sql
+SELECT site_id, assistant_id, stat_date, COUNT(*) AS cnt
+FROM dws.dws_assistant_order_contribution
+GROUP BY site_id, assistant_id, stat_date
+HAVING COUNT(*) > 1;
+-- 预期：无结果返回
+```
+
+### 6.3 检查四项统计数值合理性（非负）
+
+```sql
+SELECT
+    COUNT(*) FILTER (WHERE order_gross_revenue < 0)       AS neg_gross,
+    COUNT(*) FILTER (WHERE order_net_revenue < 0)         AS neg_net,
+    COUNT(*) FILTER (WHERE time_weighted_revenue < 0)     AS neg_twr,
+    COUNT(*) FILTER (WHERE time_weighted_net_revenue < 0) AS neg_twnr
+FROM dws.dws_assistant_order_contribution;
+-- 预期：所有列均为 0
+```
+
+### 6.4 按门店查看统计概况
+
+```sql
+SELECT
+    site_id,
+    COUNT(*)                                        AS record_count,
+    SUM(order_count)                                AS total_orders,
+    ROUND(AVG(order_gross_revenue), 2)              AS avg_gross,
+    ROUND(AVG(order_net_revenue), 2)                AS avg_net,
+    ROUND(AVG(time_weighted_revenue), 2)            AS avg_twr,
+    ROUND(AVG(time_weighted_net_revenue), 2)        AS avg_twnr
+FROM dws.dws_assistant_order_contribution
+GROUP BY site_id
+ORDER BY site_id;
+```
+
+---
+
+## 7. RLS 视图与 FDW 映射
+
+### 7.1 RLS 视图（ETL 库 app schema）
+
+```sql
+-- 视图名：app.v_dws_assistant_order_contribution
+CREATE OR REPLACE VIEW app.v_dws_assistant_order_contribution AS
+SELECT * FROM dws.dws_assistant_order_contribution
+WHERE site_id = current_setting('app.current_site_id')::bigint;
+```
+
+### 7.2 FDW 外部表（业务库 fdw_etl schema）
+
+```sql
+-- 外部表名：fdw_etl.v_dws_assistant_order_contribution
+-- 通过 app schema RLS 视图访问，非直接访问 dws schema
+CREATE FOREIGN TABLE fdw_etl.v_dws_assistant_order_contribution (...)
+SERVER etl_server
+OPTIONS (schema_name 'app', table_name 'v_dws_assistant_order_contribution');
+```
+
+---
+
+## 8. 兼容性说明
+
+| 影响范围 | 说明 |
+|---------|------|
+| ETL 任务 | 新增任务 `DWS_ASSISTANT_ORDER_CONTRIBUTION`，依赖 `DWD_LOAD_FROM_ODS`。不影响现有 DWS 任务 |
+| 后端 API | 当前无 API 直接读取此表。后续小程序助教看板需新增接口 |
+| 管理后台 | 当前无前端页面展示。后续可在助教详情页新增流水统计展示 |
+| 小程序 | 小程序助教端将通过后端 API 读取此表数据展示四项统计 |
+| 其他 DWS 表 | 独立于现有 `dws_assistant_daily_detail`，不修改任何已有表或任务逻辑 |
+
+---
+
+## 9. 回滚策略
+
+### 9.1 删除数据（保留表结构）
+
+```sql
+DELETE FROM dws.dws_assistant_order_contribution;
+```
+
+### 9.2 完整回滚（删除表 + 视图 + FDW）
+
+```sql
+-- 1. 删除 FDW 外部表（业务库）
+DROP FOREIGN TABLE IF EXISTS fdw_etl.v_dws_assistant_order_contribution;
+
+-- 2. 删除 RLS 视图（ETL 库）
+DROP VIEW IF EXISTS app.v_dws_assistant_order_contribution;
+
+-- 3. 删除表和索引（ETL 库）
+DROP INDEX IF EXISTS dws.idx_aoc_stat_date;
+DROP INDEX IF EXISTS dws.idx_aoc_site_assistant_date;
+DROP TABLE IF EXISTS dws.dws_assistant_order_contribution;
+```
+
+### 9.3 回滚任务注册
+
+从 `orchestration/task_registry.py` 中移除 `DWS_ASSISTANT_ORDER_CONTRIBUTION` 注册行，并从 `tasks/dws/__init__.py` 中移除 `AssistantOrderContributionTask` 导出。
+
+---
+
+## 10. 代码引用
+
+- 任务类：`tasks/dws/assistant_order_contribution_task.py` → `AssistantOrderContributionTask`
+- 数据结构：`TableUsage`、`AssistantService`、`OrderData`（同文件）
+- 继承：`BaseDwsTask`
+- 任务注册：`orchestration/task_registry.py` → `DWS_ASSISTANT_ORDER_CONTRIBUTION`
+- 属性测试：`tests/test_dws_contribution_properties.py`
+- 迁移脚本：`db/etl_feiqiu/migrations/2025-02-24__create_dws_assistant_order_contribution.sql`
+- RLS 视图：`db/etl_feiqiu/migrations/2025-02-24__create_rls_view_assistant_order_contribution.sql`
+- FDW 映射：`db/zqyy_app/migrations/2025-02-24__add_fdw_dws_extensions.sql`
+- 验证脚本：`apps/etl/connectors/feiqiu/scripts/verify_dws_extensions.py`
+
+---
+
+## 11. 关联扩展字段说明
+
+本次 Spec（02-etl-dws-miniapp-extensions）同时扩展了两张已有表的字段，简要说明如下：
+
+### 11.1 dws_member_consumption_summary 新增字段
+
+| 列名 | 类型 | 默认值 | 业务含义 |
+|------|------|--------|---------|
+| `recharge_count_30d` | INTEGER | 0 | 近 30 天充值次数 |
+| `recharge_count_60d` | INTEGER | 0 | 近 60 天充值次数 |
+| `recharge_count_90d` | INTEGER | 0 | 近 90 天充值次数 |
+| `recharge_amount_30d` | NUMERIC(14,2) | 0 | 近 30 天充值金额 |
+| `recharge_amount_60d` | NUMERIC(14,2) | 0 | 近 60 天充值金额 |
+| `recharge_amount_90d` | NUMERIC(14,2) | 0 | 近 90 天充值金额 |
+| `avg_ticket_amount` | NUMERIC(14,2) | 0 | 次均消费 = total_consume_amount / MAX(total_visit_count, 1) |
+
+迁移脚本：`db/etl_feiqiu/migrations/2025-02-24__alter_member_consumption_add_recharge_fields.sql`
+
+### 11.2 dws_assistant_daily_detail 新增字段
+
+| 列名 | 类型 | 默认值 | 业务含义 |
+|------|------|--------|---------|
+| `penalty_minutes` | NUMERIC(10,2) | 0 | 定档折算惩罚分钟数，无惩罚时为 0 |
+| `penalty_reason` | TEXT | NULL | 惩罚原因描述，无惩罚时为 NULL |
+| `is_exempt` | BOOLEAN | FALSE | 是否豁免惩罚 |
+| `per_hour_contribution` | NUMERIC(14,2) | NULL | 单人每小时贡献流水 = 台费每小时单价 / 助教人数 |
+
+迁移脚本：`db/etl_feiqiu/migrations/2025-02-24__alter_assistant_daily_add_penalty_fields.sql`
--- a/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_goods_stock_summary.md
+++ b/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_goods_stock_summary.md
@@ -0,0 +1,80 @@
+# BD_Manual：DWS 库存汇总（日/周/月）
+
+> DWS 表：`dws.dws_goods_stock_daily_summary`、`dws.dws_goods_stock_weekly_summary`、`dws.dws_goods_stock_monthly_summary`
+> DWD 数据源：`dwd.dwd_goods_stock_summary`
+> 任务代码：`DWS_GOODS_STOCK_DAILY`、`DWS_GOODS_STOCK_WEEKLY`、`DWS_GOODS_STOCK_MONTHLY`
+> 代码位置：`apps/etl/connectors/feiqiu/tasks/dws/goods_stock_daily_task.py`、`goods_stock_weekly_task.py`、`goods_stock_monthly_task.py`
+> DDL 位置：`docs/database/ddl/etl_feiqiu__dws.sql`
+> 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__create_dws_goods_stock_summary.sql`（已归档）
+
+---
+
+## 1. 表结构（三张表结构相同）
+
+| DWS 列名 | 类型 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|-------------|
+| `site_id` | BIGINT | 门店 ID（PK 之一） | 飞球门店 ID |
+| `tenant_id` | BIGINT | 租户 ID | 飞球租户 ID |
+| `stat_date` | DATE | 统计日期（PK 之一）。日度=当天日期，周度=ISO 周一日期，月度=月首日期 | 如 `2026-01-15`、`2026-01-13`（周一）、`2026-01-01`（月首） |
+| `site_goods_id` | BIGINT | 门店商品 ID（PK 之一），关联 `dim_store_goods.site_goods_id` | 飞球商品 ID |
+| `goods_name` | TEXT | 商品名称 | 如 `百威啤酒` |
+| `goods_unit` | TEXT | 计量单位 | 如 `瓶`、`包` |
+| `goods_category_id` | BIGINT | 一级商品分类 ID | 飞球分类 ID |
+| `goods_category_second_id` | BIGINT | 二级商品分类 ID | 飞球分类 ID |
+| `category_name` | TEXT | 一级分类名称 | 如 `酒水` |
+| `range_start_stock` | NUMERIC | 期初库存（统计周期起点的库存量） | 数值 |
+| `range_end_stock` | NUMERIC | 期末库存（统计周期终点的库存量） | 数值 |
+| `range_in` | NUMERIC | 入库数量（统计周期内的采购/调拨入库总量） | 数值 |
+| `range_out` | NUMERIC | 出库数量（统计周期内的调拨出库/报损总量） | 数值 |
+| `range_sale` | NUMERIC | 销售数量（统计周期内的销售出库总量） | 数值 |
+| `range_sale_money` | NUMERIC(12,2) | 销售金额（元），统计周期内的销售总金额 | 金额值 |
+| `range_inventory` | NUMERIC | 盘点调整量（统计周期内的盘盈/盘亏净量） | 正/负数值 |
+| `current_stock` | NUMERIC | 当前库存（统计周期末的实时库存量） | 数值 |
+| `stat_period` | TEXT | 汇总粒度标识 | `'daily'` / `'weekly'` / `'monthly'` |
+| `created_at` | TIMESTAMPTZ | 记录创建时间 | 自动填充 `now()` |
+| `updated_at` | TIMESTAMPTZ | 记录最后更新时间 | 自动填充 `now()` |
+
+---
+
+## 2. 主键
+
+`(site_id, stat_date, site_goods_id)` — 按门店、日期、商品维度唯一。
+
+---
+
+## 3. 粒度说明
+
+| 表名 | 粒度 | stat_date 规则 | stat_period |
+|------|------|---------------|-------------|
+| `dws_goods_stock_daily_summary` | 日 | 当天日期 | `'daily'` |
+| `dws_goods_stock_weekly_summary` | 周 | ISO 周一日期 | `'weekly'` |
+| `dws_goods_stock_monthly_summary` | 月 | 月首日期（如 `2026-01-01`） | `'monthly'` |
+
+---
+
+## 4. 聚合逻辑
+
+- extract：从 `dwd.dwd_goods_stock_summary` 按时间范围查询
+- transform：按粒度对 `fetched_at` 进行分组聚合
+  - `range_start_stock`：取周期内最早记录的 `range_start_stock`
+  - `range_end_stock`：取周期内最晚记录的 `range_end_stock`
+  - `range_in` / `range_out` / `range_sale` / `range_inventory`：SUM 汇总
+  - `range_sale_money`：SUM 汇总
+  - `current_stock`：取周期内最晚记录的 `current_stock`
+  - `goods_name` / `goods_unit` / `category_name`：取最晚记录的值
+- load：upsert 写入目标表，主键冲突时更新
+
+---
+
+## 5. 前置依赖
+
+- `dwd.dwd_goods_stock_summary` 表必须已创建并有数据
+- ODS 任务配置 `requires_window=True` 必须已生效并重新采集
+
+---
+
+## 6. 代码引用
+
+- 任务代码：`tasks/dws/goods_stock_daily_task.py`、`goods_stock_weekly_task.py`、`goods_stock_monthly_task.py`
+- 继承：`BaseDwsTask`（`tasks/dws/base_dws_task.py`）
+- 任务注册：`DWS_GOODS_STOCK_DAILY`、`DWS_GOODS_STOCK_WEEKLY`、`DWS_GOODS_STOCK_MONTHLY`
--- a/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_member_spending_power_index.md
+++ b/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_member_spending_power_index.md
@@ -0,0 +1,251 @@
+# 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 检查表是否存在且有数据
+
+```sql
+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]）
+
+```sql
+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 检查业务主键唯一性（不应有重复）
+
+```sql
+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 分布概况
+
+```sql
+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]）
+
+```sql
+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 删除数据（保留表结构）
+
+```sql
+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 完整回滚（删除表）
+
+```sql
+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`
--- a/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_project_tags.md
+++ b/apps/etl/connectors/feiqiu/docs/database/DWS/changes/BD_Manual_dws_project_tags.md
@@ -0,0 +1,78 @@
+# BD 手册：dws_assistant_project_tag / dws_member_project_tag（项目标签表）
+
+> 变更日期：2026-03-12
+> 变更类型：补充任务注册（seed 脚本遗漏修复）
+
+## 变更说明
+
+两张项目标签表（`dws.dws_assistant_project_tag`、`dws.dws_member_project_tag`）于 2026-03-07 创建，代码层（task class + TaskRegistry）已完整实现，但 `db/etl_feiqiu/seeds/seed_scheduler_tasks.sql` 遗漏了这两个任务码，导致 `meta.etl_task` 表中无记录，调度时报"未启用或不存在"。
+
+本次修复：
+- 在 seed 脚本中补充 `DWS_ASSISTANT_PROJECT_TAG` 和 `DWS_MEMBER_PROJECT_TAG`
+- 在测试库 `test_etl_feiqiu` 的 `meta.etl_task` 表中插入两条记录（`enabled = TRUE`）
+
+## 表概览
+
+| 表名 | Schema | 粒度 | 时间窗口数 | 数据来源 |
+|------|--------|------|-----------|----------|
+| `dws_assistant_project_tag` | dws | 助教 + 时间窗口 + 项目类型 | 6 | `dwd_assistant_service_log` + `dim_table` + `cfg_area_category` |
+| `dws_member_project_tag` | dws | 会员 + 时间窗口 + 项目类型 | 2 | `dwd_table_fee_log` + `dim_table` + `cfg_area_category` |
+
+两表共享相同的标签计算逻辑：按时间窗口聚合各项目时长，计算占比，≥25% 分配标签。
+
+## 兼容性影响
+
+- ETL 调度：修复后两个任务可正常被 admin 后台调度执行
+- 后端 API：无影响（API 层直接查询 DWS 表，表结构未变）
+- 小程序/管理后台：无影响（前端查询不依赖 `meta.etl_task`）
+- 其他 ETL 任务：无影响（两个任务独立运行，不被其他任务依赖）
+
+## 回滚策略
+
+```sql
+-- 1. 从 meta.etl_task 移除注册
+DELETE FROM meta.etl_task
+WHERE task_code IN ('DWS_ASSISTANT_PROJECT_TAG', 'DWS_MEMBER_PROJECT_TAG');
+
+-- 2. 还原 seed 脚本：从 task_codes 数组中移除这两行
+--    'DWS_ASSISTANT_PROJECT_TAG',
+--    'DWS_MEMBER_PROJECT_TAG',
+```
+
+## 验证 SQL
+
+```sql
+-- 1. 确认 meta.etl_task 中两个任务已注册且启用
+SELECT task_code, store_id, enabled, created_at
+FROM meta.etl_task
+WHERE task_code IN ('DWS_ASSISTANT_PROJECT_TAG', 'DWS_MEMBER_PROJECT_TAG');
+-- 期望：2 行，enabled = TRUE
+
+-- 2. 确认 seed 脚本与 task_registry 一致（无遗漏）
+-- 手动比对 seed_scheduler_tasks.sql 中的 task_codes 与 task_registry.py 中的注册列表
+
+-- 3. 确认两张 DWS 表存在且结构正确
+SELECT table_name, column_name, data_type
+FROM information_schema.columns
+WHERE table_schema = 'dws'
+  AND table_name IN ('dws_assistant_project_tag', 'dws_member_project_tag')
+ORDER BY table_name, ordinal_position;
+-- 期望：每张表 15 个字段
+
+-- 4. 确认调度可正常执行（在 admin 后台触发后检查）
+SELECT task_code, status, started_at, finished_at
+FROM meta.etl_run r
+JOIN meta.etl_task t ON r.task_id = t.task_id
+WHERE t.task_code IN ('DWS_ASSISTANT_PROJECT_TAG', 'DWS_MEMBER_PROJECT_TAG')
+ORDER BY r.started_at DESC
+LIMIT 4;
+```
+
+## 详细 BD 手册
+
+两张表的完整字段说明、索引、数据链路、业务规则见模块级 BD 手册：
+- `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_assistant_project_tag.md`
+- `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_member_project_tag.md`
+
+ETL 任务详细说明见：
+- `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md`（项目标签域章节）