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

feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系

Browse Source 
## P1 数据库基础
- zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu
- etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表
- 清理 assistant_abolish 残留数据

## P2 ETL/DWS 扩展
- 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution)
- 新增 assistant_order_contribution_task 任务及 RLS 视图
- member_consumption 增加充值字段、assistant_daily 增加处罚字段
- 更新 ODS/DWD/DWS 任务文档及业务规则文档
- 更新 consistency_checker、flow_runner、task_registry 等核心模块

## P3 小程序鉴权系统
- 新增 xcx_auth 路由/schema（微信登录 + JWT）
- 新增 wechat/role/matching/application 服务层
- zqyy_app 鉴权表迁移 + 角色权限种子数据
- auth/dependencies.py 支持小程序 JWT 鉴权

## 文档与审计
- 新增 DOCUMENTATION-MAP 文档导航
- 新增 7 份 BD_Manual 数据库变更文档
- 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth）
- 新增全栈集成审计记录、部署检查清单更新
- 新增 BACKLOG 路线图、FDW→Core 迁移计划

## Kiro 工程化
- 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务）
- 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan）
- 新增 6 个 Hook（合规检查/会话日志/提交审计等）
- 新增 doc-map steering 文件

## 运维与测试
- 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告
- 新增属性测试：test_dws_contribution / test_auth_system
- 清理过期 export 报告文件
- 更新 .gitignore 排除规则
This commit is contained in:
Neo
2026-02-26 08:03:53 +08:00
parent fafc95e64c
commit b25308c3f4
224 changed files with 17660 additions and 32198 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
apps/etl/connectors/feiqiu/docs/CHANGELOG.md
View File

@@ -5,6 +5,26 @@
---
## 2026-02-26
### 文档审计 — 任务统计、业务口径、SCD2 规则全面校正
- **摘要**：对 `docs/` 下 9 个文档进行系统性审计与修正，以 `task_registry.py` 为唯一事实来源，修复任务数量、域分组、表名、工具链引用等 15 处不一致
- **修正清单**：
- `docs/README.md`：移除不存在的 `audit/`、`reports/` 目录引用
- `docs/etl_tasks/README.md`：ODS 22→23、DWS 13→17、补充 `ODS_STAFF_INFO`/`DWS_ASSISTANT_ORDER_CONTRIBUTION`/库存汇总域/SPI
- `docs/etl_tasks/ods_tasks.md`：任务总数 22→23
- `docs/etl_tasks/dws_tasks.md`：任务总数 14→17、域分组四组→五组、补充库存汇总域概述表格
- `docs/etl_tasks/base_task_mechanism.md`：DWS 13→17、INDEX 4→5
- `docs/operations/environment_setup.md`：移除重复段落
- `docs/operations/troubleshooting.md`：`pip install -r requirements.txt` → `uv sync`
- `docs/business-rules/dws_metrics.md`：完全重写，移除不存在的表、修正表名、补充库存汇总域和指数算法章节
- `docs/business-rules/scd2_rules.md`：完全重写，填充 9 个维度表的实际跟踪字段、补充 `dim_staff` 维度、文档化变更检测机制
- **影响范围**：文档（`docs/` 全目录，无代码变更）
- **风险**：极低（纯文档修正）
---
## 2026-02-19
### 文档全面刷新 — Schema 名称、技术栈、任务统计同步至项目现状

4
apps/etl/connectors/feiqiu/docs/README.md
View File

@@ -6,8 +6,6 @@
|-------------|------|
| [`architecture/`](architecture/README.md) | 架构设计文档 — 系统整体架构、数据流向（ODS→DWD→DWS）、模块交互关系 |
| [`api-reference/`](api-reference/) | API 参考文档（25 个端点的标准化文档 + JSON 样本） |
| [`audit/`](audit/README.md) | 审计目录（历史归档，新记录已迁移至根 `docs/audit/`） |
| [`audit/repo/`](audit/repo/) | 仓库审计报告（由 `scripts/audit/` 自动生成：文件清单、调用流、文档对齐） |
| [`business-rules/`](business-rules/README.md) | 业务规则文档 — 指数算法、DWS 口径定义、SCD2 处理规则等业务逻辑 |
| [`database/`](database/README.md) | 数据库文档统一目录 — 层级概览 + ODS/DWD/DWS/ETL_Admin 表级文档 |
| [`database/overview/`](database/overview/) | 层级概览 / 速查索引（表清单、主键、记录数、业务域分类） |
@@ -17,8 +15,6 @@
| [`database/ETL_Admin/`](database/ETL_Admin/) | ETL 管理层表手册（etl_cursor/etl_run/etl_task） |
| [`etl_tasks/`](etl_tasks/README.md) | ETL 任务文档（ODS/DWD/DWS/指数任务说明与机制） |
| [`operations/`](operations/README.md) | 运维文档 — 环境搭建指南、调度配置说明、故障排查手册 |
| [`reports/`](reports/) | 分析报告（数据质量、一致性检查等输出） |
| [`requirements/`](requirements/) | 需求文档（功能需求、口径补充、指数 PRD 等） |
| [`CHANGELOG.md`](CHANGELOG.md) | 项目级版本变更历史（日期、变更摘要、影响范围） |
## 维护约定

235
apps/etl/connectors/feiqiu/docs/business-rules/dws_metrics.md
View File

@@ -3,7 +3,7 @@
本文档定义 `dws` 模式下各汇总指标的业务口径、计算规则和数据来源。
所有指标均基于 DWD 明细层数据聚合生成。
> **状态**：骨架文档，各章节待补充具体计算公式与字段映射。
> 各任务的详细实现（数据来源表、输出字段、核心逻辑）请参阅 [dws_tasks.md](../etl_tasks/dws_tasks.md)。
---
@@ -11,39 +11,51 @@
### 1.1 助教日报（dws_assistant_daily_detail）
<!-- 待补充：日维度助教业绩指标定义，包括订单数、服务时长、收入等 -->
- 目标表：`dws.dws_assistant_daily_detail`
- 数据来源：DWD 订单事实表、助教维度表
- 数据来源：`dwd_assistant_service_log`、`dwd_assistant_trash_event`、`dim_assistant`（SCD2）
- 粒度：门店 × 助教 × 日期
- 核心指标：*(待定义)*
- 核心指标：服务次数（总/基础课/附加课/包厢课）、计费秒数与小时数、台账金额、去重客户数与台桌数、废除统计
- 课程类型分类：通过 `cfg_skill_type` 映射 `skill_id` → `BASE`/`BONUS`/`ROOM`
- 助教等级：SCD2 as-of 取值，取统计日当日生效的等级版本
### 1.2 助教月报（dws_assistant_monthly_summary）
<!-- 待补充：月维度助教业绩汇总指标 -->
- 目标表：`dws.dws_assistant_monthly_summary`
- 数据来源：助教日报聚合
- 数据来源：`dws_assistant_daily_detail` 聚合 + `dwd_assistant_service_log`（月度去重）+ `dim_assistant` + `cfg_performance_tier`
- 粒度：门店 × 助教 × 年月
- 核心指标：*(待定义)*
- 核心指标：月度累计服务次数/时长/金额、有效业绩小时数（`total_hours - trashed_hours`）、绩效档位匹配、排名（考虑并列）
- 新入职判断：入职日期在当月 1 日后即视为新入职，档位匹配按日均折算 30 天
- 月度去重客户/台桌：从 DWD 直接去重，避免日度求和失真
### 1.3 助教客户统计（dws_assistant_customer_stats）
<!-- 待补充：助教服务客户维度的统计指标 -->
- 目标表：`dws.dws_assistant_customer_stats`
- 数据来源：DWD 订单事实表、会员维度表
- 数据来源：`dwd_assistant_service_log`、`dim_member`、`dim_assistant`
- 粒度：门店 × 助教 × 会员
- 核心指标：*(待定义)*
- 核心指标：全量累计（首次/最近服务日期、累计次数/时长/金额）、6 个滚动窗口（7/10/15/30/60/90 天）、活跃度判定
- 散客排除：`member_id` 为 0 或 None 不进入统计
- HAVING 过滤：仅保留最近 90 天内有服务记录的助教-客户对
### 1.4 助教财务分析（dws_assistant_finance_analysis）
<!-- 待补充：助教维度的财务分析指标 -->
- 目标表：`dws.dws_assistant_finance_analysis`
- 数据来源：DWD 支付/退款事实表
- 数据来源：`dwd_assistant_service_log`、`cfg_skill_type`、`dws_assistant_salary_calc`、`dws_assistant_daily_detail`
- 粒度：门店 × 助教 × 日期
- 核心指标：*(待定义)*
- 核心指标：日度收入（总/基础课/附加课/包厢课）、日均成本（`gross_salary / work_days`）、毛利润与毛利率
- 依赖：`DWS_ASSISTANT_SALARY` 和 `DWS_ASSISTANT_DAILY` 的输出
### 1.5 助教订单流水贡献（dws_assistant_order_contribution）
- 目标表：`dws.dws_assistant_order_contribution`
- 数据来源：`dwd_settlement_head`、`dwd_table_fee_log`、`dwd_assistant_service_log`
- 粒度：门店 × 助教 × 日期
- 核心指标（四项统计）：
- `order_gross_revenue`：订单总流水（台费 + 酒水食品 + 所有助教服务费）
- `order_net_revenue`：订单净流水（总流水 - 所有助教服务分成）
- `time_weighted_revenue`：时效贡献流水（按服务时长占比分摊）
- `time_weighted_net_revenue`：时效净贡献（时效贡献 - 个人服务分成）
- 超休/打赏课特殊处理：`course_type = BONUS` 的助教不参与订单级分摊
- 依赖：`DWD_LOAD_FROM_ODS`
---
@@ -51,21 +63,17 @@
### 2.1 助教薪酬（dws_assistant_salary_calc）
<!-- 待补充：薪酬计算规则、提成比例、结算周期 -->
- 目标表：`dws.dws_assistant_salary_calc`
- 数据来源：助教日报/月报、充值提成
- 粒度：门店 × 助教 × 结算周期
- 核心指标：*(待定义)*
### 2.2 充值提成（dws_assistant_recharge_commission）
<!-- 待补充：充值提成计算规则 -->
- 目标表：`dws.dws_assistant_recharge_commission`
- 数据来源：DWD 充值事实表
- 粒度：门店 × 助教 × 日期
- 核心指标：*(待定义)*
- 数据来源：`dws_assistant_monthly_summary`、`dws_assistant_recharge_commission`、`cfg_performance_tier`、`cfg_assistant_level_price`、`cfg_bonus_rules`
- 粒度：门店 × 助教 × 结算月份
- 核心公式：
- 应发工资 = 课时收入 + 奖金合计
- 基础课收入 = `base_hours × (base_course_price - base_deduction)`
- 附加课收入 = `bonus_hours × bonus_course_price × (1 - bonus_deduction_ratio)`
- 包厢课收入 = `room_hours × (room_course_price - base_deduction)`
- 奖金合计 = 冲刺奖金 + Top3 排名奖金 + 充值提成 + 其他奖金
- 等级定价：SCD2 按月份取历史生效值
- 运行调度：默认仅月初前 5 天运行
---
@@ -73,57 +81,33 @@
### 3.1 财务日报汇总（dws_finance_daily_summary）
<!-- 待补充：每日财务汇总口径，含收入、支出、利润等 -->
- 目标表：`dws.dws_finance_daily_summary`
- 数据来源：DWD 支付/退款/订单事实表
- 数据来源：`dwd_settlement_head`、`dwd_groupbuy_redemption`、`dwd_recharge_order`、`dwd_member_balance_change`
- 粒度：门店 × 日期
- 核心指标：*(待定义)*
- 核心指标：发生额（正价）、优惠合计（团购/会员/赠送卡/手动/抹零）、确认收入、现金流入/流出/净变动、卡消费、充值统计（首充/续充）、订单统计
- 确认收入 = 发生额 - 优惠合计
- 金额字段统一 `NUMERIC(12,2)`，货币单位人民币（CNY）
### 3.2 收入结构（dws_finance_income_structure）
<!-- 待补充：收入按来源/类型的分类口径 -->
- 目标表：`dws.dws_finance_income_structure`
- 数据来源：DWD 支付事实表
- 粒度：门店 × 日期 × 收入类型
- 核心指标：*(待定义)*
- 数据来源：`dwd_settlement_head`、`dwd_table_fee_log`、`dwd_assistant_service_log`、`dim_table`、`cfg_area_category`
- 粒度：门店 × 日期 × 结构类型 × 分类代码
- 两种分析维度：按收入类型（`INCOME_TYPE`：台费/商品/助教基础课/助教附加课）、按区域（`AREA`：通过 `cfg_area_category` 映射）
### 3.3 折扣明细（dws_finance_discount_detail）
<!-- 待补充：折扣/优惠统计口径 -->
- 目标表：`dws.dws_finance_discount_detail`
- 数据来源：DWD 订单事实表
- 粒度：门店 × 日期
- 核心指标：*(待定义)*
- 数据来源：`dwd_settlement_head`、`dwd_groupbuy_redemption`、`dwd_member_balance_change`
- 粒度：门店 × 日期 × 折扣类型
- 折扣类型：`GROUPBUY`/`VIP`/`ROUNDING`/`GIFT_CARD_TABLE`/`GIFT_CARD_DRINK`/`GIFT_CARD_COUPON`/`BIG_CUSTOMER`/`OTHER`
### 3.4 充值汇总（dws_finance_recharge_summary）
<!-- 待补充：充值金额、笔数等汇总口径 -->
- 目标表：`dws.dws_finance_recharge_summary`
- 数据来源：DWD 充值事实表
- 数据来源：`dwd_recharge_order`、`dim_member_card_account`
- 粒度：门店 × 日期
- 核心指标：*(待定义)*
### 3.5 支出汇总（dws_finance_expense_summary）
<!-- 待补充：支出分类汇总口径 -->
- 目标表：`dws.dws_finance_expense_summary`
- 数据来源：DWD 支出事实表
- 粒度：门店 × 日期
- 核心指标：*(待定义)*
### 3.6 平台结算（dws_platform_settlement）
<!-- 待补充：第三方平台（团购等）结算口径 -->
- 目标表：`dws.dws_platform_settlement`
- 数据来源：DWD 团购/支付事实表
- 粒度：门店 × 日期
- 核心指标：*(待定义)*
- 核心指标：充值笔数/总额（现金+赠送）、首充/续充拆分、去重会员数、全店卡余额快照
---
@@ -131,21 +115,19 @@
### 4.1 会员消费汇总（dws_member_consumption_summary）
<!-- 待补充：会员消费行为汇总口径 -->
- 目标表：`dws.dws_member_consumption_summary`
- 数据来源：DWD 订单/支付事实表、会员维度表
- 数据来源：`dwd_settlement_head`、`dim_member`（SCD2）、`dim_member_card_account`（SCD2）
- 粒度：门店 × 会员
- 核心指标：*(待定义)*
- 核心指标：全量累计消费、6 个滚动窗口（7/10/15/30/60/90 天）的到店次数与消费金额、卡余额（现金卡/赠送卡）、活跃度、客户分层
- 客户分层规则：高价值（90 天 ≥ 3 次且 ≥ 1000 元）→ 中等（30 天内有消费）→ 低活跃（90 天内有但 30 天内无）→ 流失
- 散客排除：`member_id` 为 0 或 None 不进入统计
### 4.2 会员到访明细（dws_member_visit_detail）
<!-- 待补充：会员到访频次、时段分布等口径 -->
- 目标表：`dws.dws_member_visit_detail`
- 数据来源：DWD 订单事实表
- 粒度：门店 × 会员 × 日期
- 核心指标：*(待定义)*
- 数据来源：`dwd_settlement_head`、`dwd_assistant_service_log`、`dwd_table_fee_log`、`dim_member`、`dim_table`、`cfg_area_category`
- 粒度：门店 × 会员 × 结账单
- 核心指标：消费金额拆分（台费/商品/助教）、支付方式拆分（现金/储值卡/赠送卡/团购券）、台桌使用时长、助教服务明细（JSON）
---
@@ -153,67 +135,84 @@
### 5.1 订单汇总宽表（dws_order_summary）
<!-- 待补充：订单维度的汇总宽表口径 -->
- 目标表：`dws.dws_order_summary`
- 数据来源：DWD 订单/支付/退款事实表
- 数据来源：`dwd_settlement_head`、`dwd_table_fee_log`、`dwd_assistant_service_log`、`dwd_store_goods_sale`、`dwd_groupbuy_redemption`、`dwd_refund`/`dwd_refund_ex`
- 粒度：门店 × 结账单
- 核心指标：*(待定义)*
- 核心指标：费用明细（台费/助教/商品/团购）、优惠、金额汇总、支付方式、台账流水、有效消费、退款与净收入
- 通过 6 个 CTE 多表合并，金额优先取明细表聚合值，回退到结账单头表汇总字段
---
## 6. 自定义指数算法
## 6. 库存汇总
指数算法的详细计算流程、参数与归一化方法请参阅 [index_algorithm_cn.md](index_algorithm_cn.md)。
### 6.1 库存日度汇总（dws_goods_stock_daily_summary）
- 目标表：`dws.dws_goods_stock_daily_summary`
- 数据来源：`dwd_goods_stock_summary`
- 粒度：门店 × 日期 × 商品
- 更新策略：upsert（ON CONFLICT DO UPDATE）
- 核心逻辑：按 `fetched_at` 日期分组，数值指标取 SUM，期初/期末取当日首/末条记录
### 6.2 库存周度汇总（dws_goods_stock_weekly_summary）
- 目标表：`dws.dws_goods_stock_weekly_summary`
- 数据来源：`dwd_goods_stock_summary`
- 粒度：门店 × ISO 周 × 商品
- 更新策略：upsert（ON CONFLICT DO UPDATE）
- 核心逻辑：按 ISO 周分组，`stat_date` = 该周周一
### 6.3 库存月度汇总（dws_goods_stock_monthly_summary）
- 目标表：`dws.dws_goods_stock_monthly_summary`
- 数据来源：`dwd_goods_stock_summary`
- 粒度：门店 × 自然月 × 商品
- 更新策略：upsert（ON CONFLICT DO UPDATE）
- 核心逻辑：按自然月分组，`stat_date` = 该月第一天
---
## 7. 自定义指数算法
指数算法的详细计算流程、参数与归一化方法请参阅 [index_tasks.md](../etl_tasks/index_tasks.md)。
以下为各指数对应的汇总表概览：
### 6.1 会员召回指数 — WBI（dws_member_recall_index）
<!-- 待补充：WBI 指数的业务口径与触发条件 -->
- 目标表：`dws.dws_member_recall_index`
- 粒度：门店 × 会员
### 6.2 新客转化指数 — NCI（dws_member_newconv_index）
<!-- 待补充：NCI 指数的业务口径与评分规则 -->
- 目标表：`dws.dws_member_newconv_index`
- 粒度：门店 × 会员
### 6.3 关系指数 — RS（dws_member_assistant_relation_index）
<!-- 待补充：RS 指数的业务口径与亲密度计算 -->
- 目标表：`dws.dws_member_assistant_relation_index`
- 粒度：门店 × 会员 × 助教
### 6.4 助教-会员亲密度（dws_member_assistant_intimacy）
<!-- 待补充：亲密度评分口径 -->
- 目标表：`dws.dws_member_assistant_intimacy`
- 粒度：门店 × 会员 × 助教
### 6.5 回流指数 — OS（dws_member_winback_index）
<!-- 待补充：OS 指数的业务口径与回流判定规则 -->
### 7.1 回流指数 — WBI（dws_member_winback_index）
- 目标表：`dws.dws_member_winback_index`
- 粒度：门店 × 会员
- 任务代码：`DWS_WINBACK_INDEX`
- 依赖：`DWS_MEMBER_VISIT`、`DWS_MEMBER_CONSUMPTION`
### 6.6 人工台账 — ML（dws_ml_manual_order_source / dws_ml_manual_order_alloc）
### 7.2 新客转化指数 — NCI（dws_member_newconv_index）
<!-- 待补充：ML 人工台账的业务口径与分配规则 -->
- 目标表：`dws.dws_member_newconv_index`
- 粒度：门店 × 会员
- 任务代码：`DWS_NEWCONV_INDEX`
- 依赖：`DWS_MEMBER_VISIT`、`DWS_MEMBER_CONSUMPTION`
### 7.3 关系指数 — RS（dws_member_assistant_relation_index）
- 目标表：`dws.dws_relation_index`
- 粒度：门店 × 会员 × 助教
- 任务代码：`DWS_RELATION_INDEX`
- 依赖：`DWS_ASSISTANT_DAILY`
### 7.4 消费力指数 — SPI（dws_member_spending_power_index）
- 目标表：`dws.dws_member_spending_power_index`
- 粒度：门店 × 会员
- 任务代码：`DWS_SPENDING_POWER_INDEX`
- 依赖：`DWS_MEMBER_CONSUMPTION`
### 7.5 人工台账 — ML（dws_ml_manual_order_source / dws_ml_manual_order_alloc）
- 宽表：`dws.dws_ml_manual_order_source`
- 窄表：`dws.dws_ml_manual_order_alloc`
- 粒度：门店 × 订单 × 助教
- 任务代码：`DWS_ML_MANUAL_IMPORT`
### 6.7 指数百分位历史（dws_index_percentile_history）
<!-- 待补充：指数百分位归一化的历史快照口径 -->
### 7.6 指数百分位历史（dws_index_percentile_history）
- 目标表：`dws.dws_index_percentile_history`
- 粒度：门店 × 指数类型 × 日期

130
apps/etl/connectors/feiqiu/docs/business-rules/scd2_rules.md
View File

@@ -3,8 +3,6 @@
本文档定义 `dwd` 模式下维度表的 SCD2（Slowly Changing Dimension Type 2）处理策略、
生效区间管理和版本控制规则。
> **状态**：骨架文档，各维度表的跟踪字段与变更触发条件待补充。
---
## 1. 概述
@@ -17,9 +15,18 @@ SCD2 通过保留维度记录的历史版本来追踪属性变化。当被跟踪
### 1.2 实现模块
- 处理器：`scd/scd2_handler.py` — `SCD2Handler` 类
- 核心方法：`upsert(table_name, natural_key, tracked_fields, record, effective_date)`
- 返回值：`INSERT`（新记录）、`UPDATE`（属性变更）、`UNCHANGED`（无变化）
- 处理器：`tasks/dwd/dwd_load_task.py` — `_merge_dim_scd2()` 方法
- 变更检测：`_is_row_changed()` — 比较所有非 SCD2 控制列，任一列值不同即视为变更
- 批量关闭：`_close_current_dim_bulk()` — 批量设置旧版本的 `scd2_end_time` 和 `scd2_is_current = 0`
- 批量插入：`_insert_dim_rows_bulk()` — 批量插入新版本行
### 1.3 变更检测逻辑
`_is_row_changed(current, incoming, dwd_cols)` 遍历目标表的所有列（排除 SCD2 控制列），逐列比较当前版本与新数据。比较时会进行类型归一化处理：
- 空值归一化：`None`、空字符串、`"null"` 视为等价
- 数值归一化：字符串形式的数字与 `Decimal`/`int` 比较前先转换
- 布尔归一化：`"true"`/`"1"`/`"yes"` 等与 `True` 视为等价
- 日期归一化：字符串形式的日期与 `datetime` 比较前先解析
---
@@ -38,103 +45,119 @@ SCD2 通过保留维度记录的历史版本来追踪属性变化。当被跟踪
- 主键：`(natural_key, scd2_start_time)` — 同一自然键的不同版本通过生效时间区分
- 唯一索引：`WHERE scd2_is_current = 1` — 保证每个自然键只有一条当前记录
- 排他约束（GiST）：`tstzrange(scd2_start_time, scd2_end_time)` — 防止同一自然键的版本时间段重叠
---
## 3. 处理流程
```
收到维度记录
_merge_dim_scd2(cur, dwd_table, ods_table, dwd_cols, ods_cols, now)
│
▼
按 natural_key 查找 valid_to IS NULL 的当前记录
├── 1. 从 ODS 取最新有效版本（DISTINCT ON + is_delete IS DISTINCT FROM 1）
│
├── 不存在 → INSERT 新记录（is_current=1, valid_from=now）
├── 2. 从 DWD 取当前版本（scd2_is_current = 1）
│
└── 存在 → 比较 tracked_fields
│
├── 无变化 → UNCHANGED（跳过）
│
└── 有变化 → UPDATE 旧记录（valid_to=now, is_current=0）
INSERT 新记录（valid_from=now, is_current=1）
├── 3. 按自然键逐条比较：
│ │
│ ├── DWD 中不存在 → 收集为待插入（INSERT）
│ │
│ ├── 存在但 _is_row_changed() 返回 True → 收集为待更新
│ │ ├── 关闭旧版本（scd2_end_time = now, scd2_is_current = 0）
│ │ └── 插入新版本（scd2_start_time = now, scd2_is_current = 1, version + 1）
│ │
│ └── 存在且无变化 → 跳过（UNCHANGED）
│
├── 4. _close_current_dim_bulk() — 批量关闭旧版本
│
└── 5. _insert_dim_rows_bulk() — 批量插入新版本
```
---
## 4. 维度表 SCD2 配置
> 跟踪字段 = 表中除自然键和 SCD2 控制列（`scd2_start_time`/`scd2_end_time`/`scd2_is_current`/`scd2_version`）之外的所有列。任一跟踪字段值变化即触发新版本。
### 4.1 门店维度（dim_site / dim_site_ex）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.table_fee_transactions`（从台费流水中的 `siteProfile` 快照提取）
- 自然键：`site_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- dim_site 跟踪字段：`org_id`、`tenant_id`、`shop_name`、`site_label`、`full_address`、`address`、`longitude`、`latitude`、`tenant_site_region_id`、`business_tel`、`site_type`、`shop_status`
- dim_site_ex 跟踪字段：`avatar`、`address`、`longitude`、`latitude`、`tenant_site_region_id`、`auto_light`、`light_status`、`light_type`、`light_token`、`site_type`、`site_label`、`attendance_enabled`、`attendance_distance`、`customer_service_qrcode`、`customer_service_wechat`、`fixed_pay_qrcode`、`prod_env`、`shop_status`、`create_time`、`update_time`
- 变更触发场景：门店名称/地址/状态/经纬度等基础信息变更
### 4.2 台桌维度（dim_table / dim_table_ex）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.site_tables_master`
- 自然键：`table_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- dim_table 跟踪字段：`site_id`、`table_name`、`site_table_area_id`、`site_table_area_name`、`tenant_table_area_id`、`table_price`、`order_id`
- dim_table_ex 跟踪字段：`show_status`、`is_online_reservation`、`table_cloth_use_time`、`table_cloth_use_cycle`、`table_status`、`create_time`、`light_status`、`tablestatusname`、`sitename`、`applet_qr_code_url`、`audit_status`、`charge_free`、`delay_lights_time`、`is_rest_area`、`only_allow_groupon`、`order_delay_time`、`self_table`、`temporary_light_second`、`virtual_table`
- 变更触发场景：台桌名称/区域/价格/状态变更
### 4.3 助教维度（dim_assistant / dim_assistant_ex）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.assistant_accounts_master`
- 自然键：`assistant_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- dim_assistant 跟踪字段：`user_id`、`assistant_no`、`real_name`、`nickname`、`mobile`、`tenant_id`、`site_id`、`team_id`、`team_name`、`level`、`entry_time`、`resign_time`、`leave_status`、`assistant_status`
- dim_assistant_ex 跟踪字段：`gender`、`birth_date`、`avatar`、`introduce`、`video_introduction_url`、`height`、`weight`、`shop_name`、`group_id`、`group_name`、`person_org_id`、`staff_id`、`staff_profile_id`、`assistant_grade`、`sum_grade`、`get_grade_times`、`charge_way`、`allow_cx`、`is_guaranteed`、`salary_grant_enabled`、`entry_type`、`entry_sign_status`、`resign_sign_status`、`work_status`、`show_status`、`show_sort`、`online_status`、`is_delete`、`criticism_status`、`create_time`、`update_time`、`start_time`、`end_time`、`last_table_id`、`last_table_name`、`last_update_name`、`order_trade_no`、`ding_talk_synced`、`site_light_cfg_id`、`light_equipment_id`、`light_status`、`is_team_leader`、`serial_number`、`system_role_id`、`job_num`、`cx_unit_price`、`pd_unit_price`
- 变更触发场景：助教等级/团队/状态/入职离职/评分等变更
### 4.4 会员维度（dim_member / dim_member_ex）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.member_profiles`
- 自然键：`member_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- dim_member 跟踪字段：`system_member_id`、`tenant_id`、`register_site_id`、`mobile`、`nickname`、`member_card_grade_code`、`member_card_grade_name`、`create_time`、`update_time`、`pay_money_sum`、`recharge_money_sum`、`birthday`
- dim_member_ex 跟踪字段：`referrer_member_id`、`point`、`register_site_name`、`growth_value`、`user_status`、`status`、`person_tenant_org_id`、`person_tenant_org_name`、`register_source`
- 变更触发场景：会员昵称/手机号/卡等级/累计消费充值/状态等变更
### 4.5 会员卡账户维度（dim_member_card_account / dim_member_card_account_ex）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.member_stored_value_cards`
- 自然键：`member_card_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- dim_member_card_account 跟踪字段：`tenant_id`、`register_site_id`、`tenant_member_id`、`system_member_id`、`card_type_id`、`member_card_grade_code`、`member_card_grade_code_name`、`member_card_type_name`、`member_name`、`member_mobile`、`balance`、`start_time`、`end_time`、`last_consume_time`、`status`、`is_delete`、`principal_balance`、`member_grade`
- dim_member_card_account_ex 跟踪字段：（60+ 列，含各类折扣比例、抵扣开关等，详见 DDL）
- 变更触发场景：卡余额/状态/折扣配置/有效期等变更
### 4.6 商品维度（dim_tenant_goods / dim_tenant_goods_ex / dim_store_goods / dim_store_goods_ex）
### 4.6 商品维度
<!-- 待补充：自然键、跟踪字段列表 -->
#### 租户商品（dim_tenant_goods / dim_tenant_goods_ex）
- Schema：`dwd`
- 自然键：`tenant_goods_id` / `site_goods_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- ODS 来源：`ods.tenant_goods_master`
- 自然键：`tenant_goods_id`
- dim_tenant_goods 跟踪字段：`tenant_id`、`supplier_id`、`category_name`、`goods_category_id`、`goods_second_category_id`、`goods_name`、`goods_number`、`unit`、`market_price`、`goods_state`、`create_time`、`update_time`、`is_delete`、`not_sale`
#### 门店商品（dim_store_goods / dim_store_goods_ex）
- ODS 来源：`ods.store_goods_master`
- 自然键：`site_goods_id`
- dim_store_goods 跟踪字段：`tenant_id`、`site_id`、`tenant_goods_id`、`goods_name`、`goods_category_id`、`goods_second_category_id`、`category_level1_name`、`category_level2_name`、`batch_stock_qty`、`sale_qty`、`total_sales_qty`、`sale_price`、`created_at`、`updated_at`、`avg_monthly_sales`、`goods_state`、`enable_status`、`send_state`、`is_delete`、`commodity_code`、`not_sale`
### 4.7 商品分类维度（dim_goods_category）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.stock_goods_category_tree`
- 自然键：`category_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- 跟踪字段：`tenant_id`、`category_name`、`alias_name`、`parent_category_id`、`business_name`、`tenant_goods_business_id`、`category_level`、`is_leaf`、`open_salesman`、`sort_order`、`is_warehousing`
- 变更触发场景：分类名称/层级/排序/启用状态变更
### 4.8 团购套餐维度（dim_groupbuy_package / dim_groupbuy_package_ex）
<!-- 待补充：自然键、跟踪字段列表 -->
- Schema：`dwd`
- ODS 来源：`ods.group_buy_packages`
- 自然键：`groupbuy_package_id`
- 跟踪字段：*(待定义)*
- 变更触发场景：*(待补充)*
- dim_groupbuy_package 跟踪字段：`tenant_id`、`site_id`、`package_name`、`package_template_id`、`selling_price`、`coupon_face_value`、`duration_seconds`、`start_time`、`end_time`、`table_area_name`、`is_enabled`、`is_delete`、`create_time`、`tenant_table_area_id_list`、`card_type_ids`、`sort`、`is_first_limit`
- 变更触发场景：套餐名称/价格/面值/有效期/启用状态变更
### 4.9 员工维度（dim_staff / dim_staff_ex）
- ODS 来源：`ods.staff_info_master`
- 自然键：`staff_id`
- dim_staff 跟踪字段：`staff_name`、`alias_name`、`mobile`、`gender`、`job`、`tenant_id`、`site_id`、`system_role_id`、`staff_identity`、`status`、`leave_status`、`entry_time`、`resign_time`、`is_delete`
- dim_staff_ex 跟踪字段：`avatar`、`job_num`、`account_status`、`rank_id`、`rank_name`、`new_rank_id`、`new_staff_identity`、`is_reserve`、`shop_name`、`site_label`、`tenant_org_id`、`system_user_id`、`cashier_point_id`、`cashier_point_name`、`group_id`、`group_name`、`staff_profile_id`、`auth_code`、`auth_code_create`、`ding_talk_synced`、`salary_grant_enabled`、`entry_type`、`entry_sign_status`、`resign_sign_status`、`criticism_status`、`create_time`、`user_roles`
- 变更触发场景：员工姓名/岗位/角色/状态/入职离职等变更
---
@@ -167,9 +190,10 @@ ORDER BY scd2_start_time;
## 6. 注意事项
- **时区**：`scd2_start_time` / `scd2_end_time` 使用 `TIMESTAMPTZ`，统一以服务器时区存储
- **时区**：`scd2_start_time` / `scd2_end_time` 使用 `TIMESTAMPTZ`，统一以 `Asia/Shanghai` 时区存储
- **并发安全**：当前实现在单次 ETL 运行内串行处理，未做行级锁；并发写入需额外保护
- **删除策略**：维度记录不做物理删除，仅通过关闭版本（`scd2_is_current = 0`）标记失效
- **ODS 来源过滤**：从 ODS 取数时统一使用 `DISTINCT ON (natural_key) ... WHERE is_delete IS DISTINCT FROM 1 ORDER BY natural_key, fetched_at DESC`，确保取最新有效版本
---

19
apps/etl/connectors/feiqiu/docs/etl_tasks/README.md
View File

@@ -51,10 +51,10 @@ graph LR
| 文档 | 说明 |
|------|------|
| [BaseTask 公共机制](base_task_mechanism.md) | 任务基类模板方法、TaskContext、时间窗口、注册表、Flow 执行 |
| [ODS 层任务](ods_tasks.md) | 22 个通用 ODS 任务的架构、配置结构、API 端点、目标表 |
| [ODS 层任务](ods_tasks.md) | 23 个通用 ODS 任务的架构、配置结构、API 端点、目标表 |
| [DWD 层任务](dwd_tasks.md) | DWD_LOAD_FROM_ODS 核心装载、SCD2 处理、质量校验 |
| [DWS 层任务](dws_tasks.md) | 助教业绩、会员分析、财务统计、运维任务共 13 个 DWS 任务 |
| [INDEX 层任务](index_tasks.md) | WBI/NCI/RS 指数算法 + ML 手动台账导入 |
| [DWS 层任务](dws_tasks.md) | 助教业绩、会员分析、财务统计、库存汇总、运维任务共 17 个 DWS 任务 |
| [INDEX 层任务](index_tasks.md) | WBI/NCI/RS/SPI 指数算法 + ML 手动台账导入 |
| [工具类任务](utility_tasks.md) | Schema 初始化、手动入库、归档、截止检查、完整性校验 |
---
@@ -89,6 +89,7 @@ graph LR
| `ODS_STORE_GOODS_SALES` | `OdsGoodsLedgerTask` | `ods.store_goods_sales_records` | 门店商品销售流水 | [查看](ods_tasks.md) |
| `ODS_TENANT_GOODS` | `OdsTenantGoodsTask` | `ods.tenant_goods_master` | 租户商品档案 | [查看](ods_tasks.md) |
| `ODS_SETTLEMENT_RECORDS` | `OdsOrderSettleTask` | `ods.settlement_records` | 结账记录 | [查看](ods_tasks.md) |
| `ODS_STAFF_INFO` | `OdsStaffInfoTask` | `ods.staff_info_master` | 员工档案（含在职/离职） | [查看](ods_tasks.md) |
### DWD 层（明细数据）
@@ -108,6 +109,7 @@ graph LR
| `DWS_ASSISTANT_CUSTOMER` | `AssistantCustomerTask` | `dws_assistant_customer_stats` | 日期+助教+会员 | [查看](dws_tasks.md) |
| `DWS_ASSISTANT_SALARY` | `AssistantSalaryTask` | `dws_assistant_salary_calc` | 月份+助教 | [查看](dws_tasks.md) |
| `DWS_ASSISTANT_FINANCE` | `AssistantFinanceTask` | `dws_assistant_finance_analysis` | 日期+助教 | [查看](dws_tasks.md) |
| `DWS_ASSISTANT_ORDER_CONTRIBUTION` | `AssistantOrderContributionTask` | `dws_assistant_order_contribution` | 日期+助教 | [查看](dws_tasks.md) |
#### 会员分析域
@@ -125,6 +127,14 @@ graph LR
| `DWS_FINANCE_INCOME_STRUCTURE` | `FinanceIncomeStructureTask` | `dws_finance_income_structure` | 日期+收入类型 | [查看](dws_tasks.md) |
| `DWS_FINANCE_DISCOUNT_DETAIL` | `FinanceDiscountDetailTask` | `dws_finance_discount_detail` | 日期+折扣类型 | [查看](dws_tasks.md) |
#### 库存汇总域
| 任务代码 | Python 类 | 目标表 | 粒度 | 详情 |
|----------|-----------|--------|------|------|
| `DWS_GOODS_STOCK_DAILY` | `GoodsStockDailyTask` | `dws_goods_stock_daily_summary` | 日期+商品 | [查看](dws_tasks.md) |
| `DWS_GOODS_STOCK_WEEKLY` | `GoodsStockWeeklyTask` | `dws_goods_stock_weekly_summary` | ISO周+商品 | [查看](dws_tasks.md) |
| `DWS_GOODS_STOCK_MONTHLY` | `GoodsStockMonthlyTask` | `dws_goods_stock_monthly_summary` | 月份+商品 | [查看](dws_tasks.md) |
#### 运维任务
| 任务代码 | Python 类 | 简要说明 | 详情 |
@@ -140,6 +150,7 @@ graph LR
| `DWS_NEWCONV_INDEX` | `NewconvIndexTask` | `dws_member_newconv_index` | NCI（新客转化指数） | [查看](index_tasks.md) |
| `DWS_RELATION_INDEX` | `RelationIndexTask` | `dws_relation_index` | RS（关系指数） | [查看](index_tasks.md) |
| `DWS_ML_MANUAL_IMPORT` | `MlManualImportTask` | `dws_ml_manual_ledger` | ML（手动台账导入） | [查看](index_tasks.md) |
| `DWS_SPENDING_POWER_INDEX` | `SpendingPowerIndexTask` | `dws_member_spending_power_index` | SPI（消费力指数） | [查看](index_tasks.md) |
### 工具类 / 校验类
@@ -353,4 +364,4 @@ python -m cli.main --tasks DATA_INTEGRITY_CHECK
---
> 最后更新日期：2026-02-18
> 最后更新日期：2026-02-26

4
apps/etl/connectors/feiqiu/docs/etl_tasks/base_task_mechanism.md
View File

@@ -286,8 +286,8 @@ default_registry.register("DWS_ASSISTANT_FINANCE", AssistantFinanceTask, layer="
|----|------|------|
| ODS | 23 | 通用 ODS 任务（由 `ODS_TASK_CLASSES` 动态生成），全部默认 `skip_unchanged=True` |
| DWD | 2 | 含核心装载任务 `DWD_LOAD_FROM_ODS` 和质量检查 |
| DWS | 13 | 助教业绩、会员分析、财务统计、统一维护任务（原 3 个 MV 刷新/清理任务已合并为 DWS_MAINTENANCE） |
| INDEX | 4 | 回流指数、新客转化指数、关系指数、手动台账导入 |
| DWS | 17 | 助教业绩（含订单流水贡献）、会员分析、财务统计、库存汇总、运维维护（原 3 个 MV 刷新/清理任务已合并为 DWS_MAINTENANCE） |
| INDEX | 5 | 回流指数、新客转化指数、关系指数、消费力指数、手动台账导入 |
| 工具类 | 7 | Schema 初始化、手动入库、归档、校验等 |
| 校验类 | 1 | 数据完整性校验 |

58
apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md
View File

@@ -8,9 +8,9 @@
## 概述
DWS 层共有 13 个已注册任务，按业务域分为四组：
DWS 层共有 17 个已注册任务（含 DWS_MAINTENANCE），按业务域分为五组：
### 助教业绩域（5 个）
### 助教业绩域（6 个）
| 任务代码 | Python 类 | 目标表 | 粒度 | 更新策略 |
|----------|-----------|--------|------|----------|
@@ -19,6 +19,7 @@ DWS 层共有 13 个已注册任务，按业务域分为四组：
| `DWS_ASSISTANT_CUSTOMER` | `AssistantCustomerTask` | `dws_assistant_customer_stats` | 日期+助教+会员 | delete-before-insert |
| `DWS_ASSISTANT_SALARY` | `AssistantSalaryTask` | `dws_assistant_salary_calc` | 月份+助教 | delete-before-insert |
| `DWS_ASSISTANT_FINANCE` | `AssistantFinanceTask` | `dws_assistant_finance_analysis` | 日期+助教 | delete-before-insert |
| `DWS_ASSISTANT_ORDER_CONTRIBUTION` | `AssistantOrderContributionTask` | `dws_assistant_order_contribution` | 日期+助教 | delete-before-insert |
### 会员分析域（2 个）
@@ -36,6 +37,14 @@ DWS 层共有 13 个已注册任务，按业务域分为四组：
| `DWS_FINANCE_INCOME_STRUCTURE` | `FinanceIncomeStructureTask` | `dws_finance_income_structure` | 日期+收入类型 | delete-before-insert |
| `DWS_FINANCE_DISCOUNT_DETAIL` | `FinanceDiscountDetailTask` | `dws_finance_discount_detail` | 日期+折扣类型 | delete-before-insert |
### 库存汇总域（3 个）
| 任务代码 | Python 类 | 目标表 | 粒度 | 更新策略 |
|----------|-----------|--------|------|----------|
| `DWS_GOODS_STOCK_DAILY` | `GoodsStockDailyTask` | `dws_goods_stock_daily_summary` | 日期+商品 | upsert |
| `DWS_GOODS_STOCK_WEEKLY` | `GoodsStockWeeklyTask` | `dws_goods_stock_weekly_summary` | ISO周+商品 | upsert |
| `DWS_GOODS_STOCK_MONTHLY` | `GoodsStockMonthlyTask` | `dws_goods_stock_monthly_summary` | 月份+商品 | upsert |
### 运维任务（2 个）
| 任务代码 | Python 类 | 继承 | 说明 | 更新策略 |
@@ -377,6 +386,51 @@ dwd_assistant_service_log ────► DWS_ASSISTANT_CUSTOMER（客户关系
---
### DWS_ASSISTANT_ORDER_CONTRIBUTION — 助教订单流水四项统计
| 属性 | 值 |
|------|-----|
| 任务代码 | `DWS_ASSISTANT_ORDER_CONTRIBUTION` |
| Python 类 | `AssistantOrderContributionTask`（`tasks/dws/assistant_order_contribution_task.py`） |
| 目标表 | `dws.dws_assistant_order_contribution` |
| 主键 | `site_id`, `assistant_id`, `stat_date` |
| 粒度 | 日期 + 助教 |
| 更新策略 | delete-before-insert（按日期窗口） |
| 更新频率 | 每日更新 |
| 依赖 | `DWD_LOAD_FROM_ODS` |
#### 数据来源
| 来源表 | Schema | 用途 |
|--------|--------|------|
| `dwd_settlement_head` | `dwd` | 结算主表（订单级信息） |
| `dwd_table_fee_log` | `dwd` | 台费明细（台桌使用时长、台费金额） |
| `dwd_assistant_service_log` | `dwd` | 助教服务记录（服务时长、流水、分成） |
#### 聚合维度与输出字段
按 `(assistant_id, stat_date)` 聚合，输出以下字段：
| 字段分组 | 字段 | 说明 |
|----------|------|------|
| 标识 | `site_id`, `tenant_id`, `assistant_id`, `assistant_nickname`, `stat_date` | 门店、助教、日期 |
| 四项统计 | `order_gross_revenue` | 订单总流水：台费 + 酒水食品 + 所有助教服务费 |
| | `order_net_revenue` | 订单净流水：订单总流水 - 所有助教服务分成 |
| | `time_weighted_revenue` | 时效贡献流水：按服务时长折算的个人贡献 |
| | `time_weighted_net_revenue` | 时效净贡献：时效贡献流水 - 个人服务分成 |
| 辅助 | `order_count`, `total_service_seconds` | 参与订单数、总服务时长秒数 |
#### 核心业务逻辑
1. **订单总流水（order_gross_revenue）**：助教参与订单的全部流水（台费 + 酒水食品 + 所有助教服务费），每个参与助教获得相同值
2. **订单净流水（order_net_revenue）**：订单总流水 - 该订单所有助教的服务分成总额，每个参与助教获得相同值
3. **时效贡献流水（time_weighted_revenue）**：台费按助教在各台桌的服务时长占比分摊 + 个人服务费 + 酒水食品按总时长比例均分
4. **时效净贡献（time_weighted_net_revenue）**：时效贡献流水 - 该助教个人的服务分成
5. **超休/打赏课特殊处理**：`course_type = BONUS` 的助教不参与订单级分摊，四项统计均等于个人服务流水和分成
6. **台费分摊公式**：`billable_seconds = MAX(SUM(助教服务时长), 台桌使用时长)`，各助教按 `service_seconds / billable_seconds` 比例分摊
---
### DWS_ASSISTANT_DAILY — 助教日度业绩明细
| 属性 | 值 |

205
apps/etl/connectors/feiqiu/docs/etl_tasks/index_tasks.md
View File

@@ -8,16 +8,17 @@
## 概述
INDEX 层共有 4 个已注册任务：
INDEX 层共有 5 个已注册任务：
| 任务代码 | 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_SPENDING_POWER_INDEX` | `SpendingPowerIndexTask` | `dws_member_spending_power_index` | SPI（消费力指数） | 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"`。
> 注册位置：`orchestration/task_registry.py`，所有 INDEX 任务的 `requires_db_config=False`、`layer="INDEX"`。SPI 任务额外声明 `depends_on=["DWS_MEMBER_CONSUMPTION"]`。
---
@@ -34,8 +35,9 @@ BaseTask
├── MemberIndexBaseTask ← WBI / NCI 共享的会员特征提取
│ ├── WinbackIndexTask
│ └── NewconvIndexTask
├── RelationIndexTask ← RS/OS/MS/ML 四合一
└── MlManualImportTask ← ML 人工台账导入
├── RelationIndexTask ← RS/OS/MS/ML 四合一
├── SpendingPowerIndexTask ← SPI 消费力指数（独立数据提取）
└── MlManualImportTask ← ML 人工台账导入
```
### 子类必须实现的抽象方法
@@ -414,6 +416,177 @@ NCI 产出 3 个 Display Score：
| `w_value` | 1.0 | 价值权重 |
---
## DWS_SPENDING_POWER_INDEX — 消费力指数（SPI）
| 属性 | 值 |
|------|-----|
| 任务代码 | `DWS_SPENDING_POWER_INDEX` |
| Python 类 | `SpendingPowerIndexTask`（`tasks/dws/index/spending_power_index_task.py`） |
| 继承链 | `BaseTask → BaseDwsTask → BaseIndexTask → SpendingPowerIndexTask` |
| 目标表 | `dws.dws_member_spending_power_index` |
| 主键 | `site_id, member_id` |
| 指数类型 | `SPI` |
| 依赖任务 | `DWS_MEMBER_CONSUMPTION` |
| 更新策略 | 按门店全量刷新（先 DELETE WHERE site_id = %s，再 INSERT） |
### 业务含义
SPI 衡量会员在门店内的综合消费力层级——分数越高，表示该会员的消费能力和消费意愿越强。适用于客户分层、资源分配和精准营销场景，与 WBI/NCI 等运营指数协同使用。
SPI 不使用 `MemberIndexBaseTask` 的会员分群逻辑（NEW/OLD/STOP），所有在近 90 天内有消费或充值记录的会员均参与计算。
### 计算范围
所有在近 90 天内有消费订单（settle_type IN (1, 3)）或充值订单（settle_type = 5）的会员。无任何消费/充值数据的门店跳过计算，返回 `{'status': 'skipped', 'reason': 'no_data'}`。
### 数据来源
| 数据 | 来源表 | 提取方式 |
|------|--------|----------|
| 消费订单 | `dwd.dwd_settlement_head` | settle_type IN (1, 3)，近 90 天，聚合为会员级特征 |
| 充值订单 | `dwd.dwd_recharge_order` | settle_type = 5，近 90 天，聚合为会员级充值特征 |
| 算法参数 | `dws.cfg_index_parameters` | index_type = 'SPI' |
### 基础特征（SPIMemberFeatures）
从 DWD 层提取并计算的会员级消费特征：
| 字段 | 类型 | 含义 |
|------|------|------|
| `spend_30` | float | 近 30 天消费总额 |
| `spend_90` | float | 近 90 天消费总额 |
| `recharge_90` | float | 近 90 天充值总额 |
| `orders_30` | int | 近 30 天消费笔数 |
| `orders_90` | int | 近 90 天消费笔数 |
| `visit_days_30` | int | 近 30 天消费日数（按天去重） |
| `visit_days_90` | int | 近 90 天消费日数（按天去重） |
| `avg_ticket_90` | float | 90 天客单价：`spend_90 / max(orders_90, 1)` |
| `active_weeks_90` | int | 近 90 天有消费的自然周数（最多 13 周） |
| `daily_spend_ewma_90` | float | 近 90 天日消费 EWMA |
### 算法概要
SPI 由三个子分加权合成：
```
SPI_raw = w_L × Level + w_S × Speed + w_P × Stability
```
默认权重：`w_L = 0.60`、`w_S = 0.30`、`w_P = 0.10`。
#### 子分 1：消费水平（Level）
基于消费金额和客单价的 log1p 压缩加权，衡量客户消费金额层级：
```
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)
```
| 参数 | 默认值 | 含义 |
|------|--------|------|
| `w_level_spend_30` (w_s30) | 0.30 | 近 30 天消费权重 |
| `w_level_spend_90` (w_s90) | 0.35 | 近 90 天消费权重 |
| `w_level_ticket_90` (w_ticket) | 0.20 | 客单价权重 |
| `w_level_recharge_90` (w_r90) | 0.15 | 充值权重 |
| `amount_base_spend_30` (M30) | 500 | 30 天消费压缩基数 |
| `amount_base_spend_90` (M90) | 1500 | 90 天消费压缩基数 |
| `amount_base_ticket_90` (T0) | 200 | 客单价压缩基数 |
| `amount_base_recharge_90` (R90) | 1000 | 充值压缩基数 |
当所有消费和充值金额均为 0 时，Level 子分为 0.0。
#### 子分 2：消费速度（Speed）
衡量近期消费推进速度与节奏变化，由三个速度指标加权合成：
```
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_30 = spend_30/30`，`v_90 = spend_90/90` | 近期消费速率相对长期的变化 |
| V_ewma（EWMA 速度） | `ln(1 + daily_spend_ewma_90 / E0)` | 日消费 EWMA 的对数压缩 |
设计要点：仅对加速（`V_rel > 0`）加分，不对减速直接扣分（通过 `max(0, V_rel)` 实现）。
| 参数 | 默认值 | 含义 |
|------|--------|------|
| `w_speed_abs` | 0.50 | 绝对速度权重 |
| `w_speed_rel` | 0.30 | 相对速度权重 |
| `w_speed_ewma` | 0.20 | EWMA 速度权重 |
| `amount_base_speed_abs` (V0) | 100 | 绝对速度压缩基数 |
| `amount_base_ewma_90` (E0) | 50 | EWMA 速度压缩基数 |
| `speed_epsilon` (ε) | 1e-6 | 防除零小量 |
#### 子分 3：消费稳定性（Stability）
基于近 90 天周覆盖率，识别稳定高消费与偶发冲高：
```
P = active_weeks_90 / 13
```
近 90 天共约 13 个自然周，`active_weeks_90` 为其中有消费的周数。取值范围 [0, 1]。
当 `use_stability = 0` 时，Stability 子分权重视为 0，跳过稳定性计算。
### Display Score 归一化
SPI 产出 4 组 Display Score，各自独立归一化到 0-10 分：
| 展示分 | 对应 Raw Score | 分位历史 index_type |
|--------|---------------|---------------------|
| `display_score` | `raw_score`（SPI 总分） | `SPI` |
| `score_level_display` | `score_level_raw` | `SPI_LEVEL` |
| `score_speed_display` | `score_speed_raw` | `SPI_SPEED` |
| `score_stability_display` | `score_stability_raw` | `SPI_STABILITY` |
归一化流程复用 `BaseIndexTask.batch_normalize_to_display`：
```
Raw Score → [可选压缩] → Winsorize(P5, P95) → MinMax(0, 10) → [可选 EWMA 平滑]
```
### 金额压缩基数校准
SPI 支持金额压缩基数的自动校准机制：
1. 首次执行或参数缺失时，从门店近 90 天消费数据计算各基数的中位数作为建议值
2. 若 `cfg_index_parameters` 中已存在对应参数，优先使用配置表中的值
3. 实际使用的基数值会输出到日志，便于运营人员审查和手动调优
### 执行流程
```
1. 获取 site_id
2. load_index_parameters('SPI') 加载参数（缺失参数使用 DEFAULT_PARAMS）
3. _extract_spending_features：从 dwd_settlement_head 提取消费特征
4. _extract_recharge_features：从 dwd_recharge_order 提取充值特征
5. _compute_daily_spend_ewma：计算日消费 EWMA
6. _calibrate_amount_bases：校准金额压缩基数
7. 逐会员计算：compute_level → compute_speed → compute_stability → compute_spi_raw
8. batch_normalize_to_display：SPI 总分 + 三个子分各自独立归一化
9. DELETE FROM dws_member_spending_power_index WHERE site_id = %s
10. _save_spi_data：批量 INSERT
11. 保存分位点历史到 dws_index_percentile_history（index_type='SPI'）
```
### 默认权重
| 参数 | 默认值 | 含义 |
|------|--------|------|
| `weight_level` | 0.60 | Level 子分在总分中的权重 |
| `weight_speed` | 0.30 | Speed 子分在总分中的权重 |
| `weight_stability` | 0.10 | Stability 子分在总分中的权重 |
---
## DWS_RELATION_INDEX — 关系指数（RS/OS/MS/ML）
@@ -751,5 +924,29 @@ ORDER BY effective_from DESC
| `compression_mode` | 1 | 压缩模式（默认 log1p） |
| `use_smoothing` / `ewma_alpha` | 1 / 0.2 | EWMA 平滑 |
### SPI 参数清单
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `spend_window_short_days` | 30 | 短期消费窗口（天） |
| `spend_window_long_days` | 90 | 长期消费窗口（天） |
| `ewma_alpha_daily_spend` | 0.3 | 日消费 EWMA 平滑系数 |
| `amount_base_spend_30` | 500 | 30 天消费压缩基数 |
| `amount_base_spend_90` | 1500 | 90 天消费压缩基数 |
| `amount_base_ticket_90` | 200 | 客单价压缩基数 |
| `amount_base_recharge_90` | 1000 | 充值压缩基数 |
| `amount_base_speed_abs` | 100 | 绝对速度压缩基数 |
| `amount_base_ewma_90` | 50 | EWMA 速度压缩基数 |
| `w_level_spend_30` / `w_level_spend_90` | 0.30 / 0.35 | Level 子分中消费权重 |
| `w_level_ticket_90` / `w_level_recharge_90` | 0.20 / 0.15 | Level 子分中客单/充值权重 |
| `w_speed_abs` / `w_speed_rel` / `w_speed_ewma` | 0.50 / 0.30 / 0.20 | Speed 子分三项权重 |
| `weight_level` / `weight_speed` / `weight_stability` | 0.60 / 0.30 / 0.10 | SPI 总分三子分权重 |
| `stability_window_days` | 90 | 稳定性计算窗口（天） |
| `use_stability` | 1 | 是否启用稳定性子分（0=跳过） |
| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |
| `compression_mode` | 1 | 压缩模式（默认 log1p） |
| `use_smoothing` / `ewma_alpha` | 1 / 0.2 | EWMA 分位平滑 |
| `speed_epsilon` | 1e-6 | 速度计算防除零小量 |
> 种子数据脚本：`db/etl_feiqiu/seeds/seed_index_parameters.sql`
> DDL 定义：`docs/database/ddl/etl_feiqiu__dws.sql`

2
apps/etl/connectors/feiqiu/docs/etl_tasks/ods_tasks.md
View File

@@ -228,7 +228,7 @@ execute(cursor_data)
### content_hash 去重机制
`content_hash` 是通用 ODS 任务的核心去重手段，所有 22 个任务默认开启（`skip_unchanged=True`）。
`content_hash` 是通用 ODS 任务的核心去重手段，所有 23 个任务默认开启（`skip_unchanged=True`）。
#### 计算方式

6
apps/etl/connectors/feiqiu/docs/operations/environment_setup.md
View File

@@ -118,12 +118,6 @@ psql "$PG_DSN" -f db/etl_feiqiu/seeds/seed_*.sql
> 注：旧的 `db/etl_feiqiu/schemas/` 和 `db/etl_feiqiu/migrations/` 已归档至 `db/_archived/`。
> DDL 基线现由 `docs/database/ddl/` 统一管理，可通过 `python scripts/ops/gen_consolidated_ddl.py` 重新生成。
或使用 CLI 工具任务初始化：
```bash
python -m cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA,INIT_DWS_SCHEMA,SEED_DWS_CONFIG --pg-dsn "$PG_DSN"
```
## 5. 验证安装
```bash

2
apps/etl/connectors/feiqiu/docs/operations/troubleshooting.md
View File

@@ -123,7 +123,7 @@
**解决方案**：
```bash
pip install -r requirements.txt
uv sync
```
### 5.3 编码问题