feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

.kiro/steering/dws-doc-authority.md

@@ -0,0 +1,279 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/tasks/**,**/loaders/**,**/scd/**,**/dws/**,**/dwd/**,**/quality/**,**/business-rules/**,**/schemas/**,**/routers/**,**/financial*,**/settlement*,**/consume*,**/accounting*,**/salary*,**/assistant*,**/member*,**/index*,**/winback*,**/newconv*,**/relation_index*,**/spending*,**/stock*,**/finance_*,**/income_*,**/discount_*,**/order_contribution*,**/cfg_*,**/orchestration/**,**/config/**"
+name: dws-doc-authority
+description: DWS 层权威规范。涉及 ETL 任务/财务/结算/消费/助教/会员/指数/统计/配置相关文件时自动加载。
+---
+
+# DWS 层权威规范（强制优先参考）
+
+DWS（Data Warehouse Summary）层从 DWD 明细层按业务维度聚合计算，输出汇总统计表，服务于助教业绩、会员分析、财务统计、指数算法等业务场景。
+
+> DWD-DOC（`docs/reports/DWD-DOC/`）中的强制规则在 DWS 层同样生效，本文档不重复列出。两者冲突时以 DWD-DOC 为准。
+
+## 一、任务体系（19 个已注册任务）
+
+### 1.1 助教业绩域（6 个）
+
+| 任务代码 | 目标表 | 粒度 | 核心指标 |
+|----------|--------|------|----------|
+| `DWS_ASSISTANT_DAILY` | `dws_assistant_daily_detail` | 日期+助教 | 服务次数/时长/金额、去重客户数、废除统计、惩罚检测 |
+| `DWS_ASSISTANT_MONTHLY` | `dws_assistant_monthly_summary` | 月份+助教 | 月度累计、有效业绩、档位匹配、排名（考虑并列） |
+| `DWS_ASSISTANT_CUSTOMER` | `dws_assistant_customer_stats` | 日期+助教+会员 | 全量累计、6 个滚动窗口（7/10/15/30/60/90 天）、活跃度 |
+| `DWS_ASSISTANT_SALARY` | `dws_assistant_salary_calc` | 月份+助教 | 课时收入、奖金明细、应发工资、假期 |
+| `DWS_ASSISTANT_FINANCE` | `dws_assistant_finance_analysis` | 日期+助教 | 日度收入、日均成本、毛利润、毛利率 |
+| `DWS_ASSISTANT_ORDER_CONTRIBUTION` | `dws_assistant_order_contribution` | 日期+助教 | 订单总流水、净流水、时效贡献、时效净贡献 |
+
+### 1.2 会员分析域（2 个）
+
+| 任务代码 | 目标表 | 粒度 | 核心指标 |
+|----------|--------|------|----------|
+| `DWS_MEMBER_CONSUMPTION` | `dws_member_consumption_summary` | 日期+会员 | 全量累计消费、6 个滚动窗口、卡余额、活跃度、客户分层 |
+| `DWS_MEMBER_VISIT` | `dws_member_visit_detail` | 日期+会员+结账单 | 消费金额拆分、支付方式拆分、台桌时长、助教服务明细（JSON） |
+
+### 1.3 财务统计域（4 个）
+
+| 任务代码 | 目标表 | 粒度 | 核心指标 |
+|----------|--------|------|----------|
+| `DWS_FINANCE_DAILY` | `dws_finance_daily_summary` | 日期 | 发生额、优惠合计、确认收入、现金流入/流出/净变动、卡消费、充值统计 |
+| `DWS_FINANCE_RECHARGE` | `dws_finance_recharge_summary` | 日期 | 充值笔数/总额、首充/续充拆分、去重会员数、全店卡余额快照 |
+| `DWS_FINANCE_INCOME_STRUCTURE` | `dws_finance_income_structure` | 日期+收入类型 | 按收入类型（台费/商品/助教基础课/附加课）和区域分析 |
+| `DWS_FINANCE_DISCOUNT_DETAIL` | `dws_finance_discount_detail` | 日期+折扣类型 | 折扣类型拆分（GROUPBUY/VIP/ROUNDING/GIFT_CARD_*/BIG_CUSTOMER/OTHER） |
+
+### 1.4 库存汇总域（3 个）
+
+| 任务代码 | 目标表 | 粒度 | 更新策略 |
+|----------|--------|------|----------|
+| `DWS_GOODS_STOCK_DAILY` | `dws_goods_stock_daily_summary` | 日期+商品 | upsert |
+| `DWS_GOODS_STOCK_WEEKLY` | `dws_goods_stock_weekly_summary` | ISO 周+商品 | upsert |
+| `DWS_GOODS_STOCK_MONTHLY` | `dws_goods_stock_monthly_summary` | 月份+商品 | upsert |
+
+### 1.5 运维任务（2 个）
+
+| 任务代码 | 说明 |
+|----------|------|
+| `DWS_BUILD_ORDER_SUMMARY` | 构建订单汇总中间表 `dws_order_summary` |
+| `DWS_MAINTENANCE` | 统一维护：物化视图刷新 + 历史数据清理 |
+
+
+## 二、强制规则（所有 session 生效）
+
+### 2.1 幂等更新策略
+1. **汇总表默认 delete-before-insert**：按日期范围 + `site_id` 先删后插，保证幂等
+2. **库存表使用 upsert**：`ON CONFLICT DO UPDATE`，因库存快照需保留最新值
+3. **禁止 TRUNCATE**：DWS 表数据量大，TRUNCATE 会导致全表锁定
+
+### 2.2 课程类型与定价
+4. **课程类型通过 `cfg_skill_type` 映射**：`skill_id` → `course_type_code`（BASE/BONUS/ROOM），禁止硬编码 skill_id 判断课程类型
+5. **定价通过 `cfg_assistant_level_price` 取值**：按 SCD2 生效期 as-of join，禁止硬编码价格
+6. **包厢课统一价格**：`dws.salary.room_course_price = 138`（元/小时），从配置读取
+
+### 2.3 绩效档位与工资
+7. **绩效档位通过 `cfg_performance_tier` 取值**：按有效业绩小时数匹配 `[min_hours, max_hours)` 区间
+8. **新入职折算规则**：入职日期在当月 1 日后视为新入职，按日均业绩 × 30 定档；入职日期 > 25 日最高定档至 T2
+9. **奖金规则通过 `cfg_bonus_rules` 取值**：SPRINT 类型不累计取最高档，TOP_RANK 类型按排名发放（第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元）
+10. **排名计算考虑并列**：使用 `calculate_rank_with_ties()`，相同业绩小时数并列同名次
+
+### 2.4 会员与散客
+11. **散客判断**：`member_id ≤ 0` 为散客，不计入会员统计（但计入助教业绩）
+12. **客户分层规则**：高价值（90 天 ≥ 3 次且 ≥ 1000 元）→ 中等（30 天内有消费）→ 低活跃（90 天内有但 30 天内无）→ 流失
+13. **会员信息一律通过 ID 关联维度表**：结算单上所有会员冗余字段均不可靠（DQ-6/DQ-7），通过 `member_id` LEFT JOIN `dwd.dim_member`（`scd2_is_current=1`）
+
+### 2.5 时间窗口与调度
+14. **滚动窗口标准集**：7/10/15/30/60/90 天，使用 `calculate_rolling_stats()` 统一计算
+15. **月度任务宽限期**：月初前 `dws.monthly.prev_month_grace_days`（默认 5）天可处理上月数据
+16. **工资计算周期**：月初前 `dws.salary.run_days`（默认 5）天运行，超期需 `dws.salary.allow_out_of_cycle = true`
+
+### 2.6 SCD2 维度取值
+17. **助教等级 as-of 取值**：工资计算按月份生效期取历史版本，日度统计按 `stat_date` 取当日版本
+18. **会员卡余额 as-of 取值**：通过 `get_member_card_balance_asof()` 按日期取快照
+
+### 2.7 台桌分类
+19. **`cfg_area_category` 仅精确匹配 + 兜底**：2026-03-07 改版后无 LIKE 匹配，分类为 BILLIARD/SNOOKER/OTHER，`BILLIARD_VIP` 已废弃
+
+## 三、指数算法体系
+
+### 3.1 总览
+
+| 指数 | 全称 | 输出表 | 作用 |
+|------|------|--------|------|
+| WBI | Winback Index | `dws_member_winback_index` | 老客挽回优先级 |
+| NCI | Newconv Index | `dws_member_newconv_index` | 新客转化优先级 |
+| RS | Relation Index | `dws_member_assistant_relation_index` | 助教-会员关系强度 |
+| OS | Ownership Index | — | 所有权指数 |
+| MS | Maintenance Score | — | 维护分 |
+| ML | Manual Ledger | `dws_ml_manual_order_alloc` | 人工台账（唯一真源） |
+| SPI | Spending Power Index | `dws_member_spending_power_index` | 消费力指数 |
+
+### 3.2 WBI（老客挽回指数）强制规则
+20. **分项得分**：Overdue（超期分，加权经验 CDF）+ Drop（降频分，近 14 天差值）+ Recharge（充值压力，衰减分）+ Value（价值分，对数压缩）
+21. **Raw Score 公式**：`WBI_raw = w_over × overdue + w_drop × drop + w_re × recharge + w_value × value`
+22. **近访抑制（Recency Suppression）**：距今 < 14 天 suppression = 0（Hard floor）；14-17 天 Sigmoid 衰减
+23. **分流规则**：STOP（距今 ≥ 60 天，高余额例外可选）→ NEW（到店 ≤ 2 次或首访 ≤ 30 天或充值未回访）→ OLD（其他）
+
+### 3.3 NCI（新客转化指数）强制规则
+24. **分项得分**：Welcome（欢迎分，首访/单访 3 天内触发）+ Need（转化紧迫度）+ Salvage（可救度，30-60 天线性衰减）+ Recharge/Value（同 WBI）
+25. **活跃抑制**：新客近 14 天来店 ≥ 2 次且最近活跃，用 0.2 系数抑制转化召回分
+
+### 3.4 指数参数配置
+26. **参数通过 `cfg_index_parameters` 加载**：按 `index_type` 分组，支持 EWMA 平滑，禁止硬编码权重/阈值
+
+
+## 四、配置表体系
+
+### 4.1 绩效档位（`dws.cfg_performance_tier`）
+
+| 档位 | 小时区间 | 抽成（元/小时） | 打赏抽成 | 假期 |
+|------|----------|-----------------|----------|------|
+| T0（0 档） | 0-120 | 28 | 50% | 3 天 |
+| T1（1 档） | 120-150 | 18 | 40% | 4 天 |
+| T2（2 档） | 150-180 | 13 | 35% | 5 天 |
+| T3（3 档） | 180-210 | 10 | 30% | 6 天 |
+| T4（4 档） | 210+ | 8 | 25% | 自由假期 |
+
+> 以上为 2026-03-01 起生效版本，历史版本通过 `effective_from/effective_to` SCD2 管理。
+
+### 4.2 助教等级定价（`dws.cfg_assistant_level_price`）
+
+| 等级 | 基础课（元/小时） | 附加课（元/小时） |
+|------|-------------------|-------------------|
+| 8（助教管理） | 98 | 190 |
+| 10（初级） | 98 | 190 |
+| 20（中级） | 108 | 190 |
+| 30（高级） | 118 | 190 |
+| 40（星级） | 138 | 190 |
+
+### 4.3 奖金规则（`dws.cfg_bonus_rules`）
+
+| 规则类型 | 生效期 | 说明 |
+|----------|--------|------|
+| SPRINT（冲刺奖金） | ≤ 2026-02-28 | 不累计，取最高档 |
+| TOP_RANK（排名奖金） | ≥ 2026-03-01 | 第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元 |
+
+### 4.4 技能→课程类型映射（`dws.cfg_skill_type`）
+
+| 课程类型代码 | 名称 | 定价规则 |
+|-------------|------|----------|
+| BASE | 基础课（陪打/PD） | 按等级定价 98-138 元/小时 |
+| BONUS | 附加课（超休/CX） | 固定 190 元/小时 |
+| ROOM | 包厢课 | 统一 138 元/小时（`dws.salary.room_course_price`） |
+
+### 4.5 台桌分类（`dws.cfg_area_category`）
+
+| 分类代码 | 说明 | 备注 |
+|----------|------|------|
+| BILLIARD | 台球（含原 V1-V4） | 2026-03-07 改版 |
+| SNOOKER | 斯诺克（含原 V5） | 2026-03-07 改版 |
+| OTHER | 兜底 | 未匹配时归入 |
+
+> `BILLIARD_VIP` 已废弃（2026-03-07），禁止引用。
+
+### 4.6 指数参数（`dws.cfg_index_parameters`）
+
+按 `index_type`（WBI/NCI/RS/OS/MS/ML/SPI）分组加载，支持 EWMA 平滑。所有权重和阈值从此表读取，禁止硬编码。
+
+## 五、BaseDwsTask 公共机制
+
+### 5.1 时间分层（TimeLayer）
+
+| 枚举值 | 范围 | 用途 |
+|--------|------|------|
+| LAST_2_DAYS | 近 2 天 | 日度增量 |
+| LAST_1_MONTH | 近 30 天 | 月度汇总 |
+| LAST_3_MONTHS | 近 90 天 | 季度分析 |
+| LAST_6_MONTHS | 近 6 个月（不含本月） | 半年趋势 |
+| ALL | 从 2000-01-01 起 | 全量重算 |
+
+### 5.2 配置缓存（ConfigCache）
+- 类级别共享，TTL 5 分钟
+- 包含：绩效档位、等级定价、奖金规则、区域分类、技能类型
+- 支持 SCD2 生效期过滤
+
+### 5.3 数据读写方法
+- `iter_dwd_rows()`：分批迭代 DWD 数据（默认 1000 行/批）
+- `query_dwd()`：直接执行任意 SQL
+- `delete_existing_data()`：按日期范围 + site_id 删除
+- `bulk_insert()`：批量插入
+- `upsert()`：ON CONFLICT DO UPDATE
+
+### 5.4 辅助计算
+- `calculate_rolling_stats()`：滚动窗口统计
+- `calculate_rank_with_ties()`：并列排名
+- `is_new_hire_in_month()`：新入职判断
+- `is_guest()`：散客判断（member_id ≤ 0）
+- `safe_decimal()` / `safe_int()`：安全类型转换
+- `seconds_to_hours()` / `hours_to_seconds()`：时间单位转换
+- `get_assistant_level_asof()`：SCD2 助教等级
+- `get_member_card_balance_asof()`：SCD2 会员卡余额
+
+## 六、字段命名规范
+
+### 6.1 金额字段
+- 统一 `NUMERIC(12,2)`，货币单位 CNY
+- 储值卡：DWS 层使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡）
+- 财务日报：使用 `recharge_card_consume`
+- 助教费用：`assistant_pd_money`（陪打）、`assistant_cx_money`（超休），禁止使用 `service_fee`
+
+### 6.2 时间字段
+- `stat_date`：统计日期（DATE）
+- `stat_month`：统计月份（CHAR(7)，格式 YYYY-MM）
+- `created_at` / `updated_at`：TIMESTAMPTZ
+
+### 6.3 标识字段
+- `site_id`：门店 ID（多门店隔离，RLS）
+- `tenant_id`：租户 ID
+- `member_id`：会员 ID（≤ 0 为散客）
+- `assistant_id`：助教 ID
+
+## 七、调度与 Flow 类型
+
+| Flow 类型 | 包含阶段 | 说明 |
+|-----------|----------|------|
+| `dwd_dws` | 仅 DWS 汇总 | 日常增量 |
+| `dwd_dws_index` | DWS 汇总 + 指数计算 | 含指数更新 |
+| `api_full` | ODS → DWD → DWS → INDEX | 全流程 |
+
+处理模式：`increment_only`（默认）、`verify_only`（仅校验修复）、`increment_verify`（先增量后校验）
+
+## 八、DWS 层完整表清单
+
+### 汇总表
+`dws_assistant_daily_detail`、`dws_assistant_monthly_summary`、`dws_assistant_customer_stats`、`dws_assistant_salary_calc`、`dws_assistant_finance_analysis`、`dws_assistant_order_contribution`、`dws_member_consumption_summary`、`dws_member_visit_detail`、`dws_finance_daily_summary`、`dws_finance_recharge_summary`、`dws_finance_income_structure`、`dws_finance_discount_detail`、`dws_goods_stock_daily_summary`、`dws_goods_stock_weekly_summary`、`dws_goods_stock_monthly_summary`、`dws_order_summary`
+
+### 指数表
+`dws_member_winback_index`、`dws_member_newconv_index`、`dws_member_recall_index`、`dws_member_assistant_relation_index`、`dws_member_assistant_intimacy`、`dws_member_spending_power_index`、`dws_index_percentile_history`
+
+### 其他表
+`dws_platform_settlement`、`dws_ml_manual_order_source`、`dws_ml_manual_order_alloc`、`dws_assistant_recharge_commission`、`dws_assistant_project_tag`、`dws_member_project_tag`
+
+### 视图
+`v_member_recall_priority`
+
+### 配置表
+`cfg_performance_tier`、`cfg_assistant_level_price`、`cfg_bonus_rules`、`cfg_skill_type`、`cfg_area_category`、`cfg_index_parameters`
+
+## 九、废弃对象（禁止引用）
+
+| 对象 | 删除日期 | 替代方案 |
+|------|----------|----------|
+| `BILLIARD_VIP` 分类代码 | 2026-03-07 | V1-V4 归入 BILLIARD，V5 归入 SNOOKER |
+| `dwd_assistant_trash_event` | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
+| `RecallIndexTask` / `IntimacyIndexTask` | 2026-02-13 | WBI + NCI + RelationIndexTask |
+| SPRINT 奖金规则 | 2026-02-28 止 | TOP_RANK 排名奖金（2026-03-01 起） |
+
+## 十、关键文档索引
+
+| 文档 | 路径 |
+|------|------|
+| DWS 任务详解 | `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md` |
+| DWS 指标定义 | `apps/etl/connectors/feiqiu/docs/business-rules/dws_metrics.md` |
+| 指数算法说明 | `apps/etl/connectors/feiqiu/docs/business-rules/index_algorithm_cn.md` |
+| BaseDwsTask 机制 | `apps/etl/connectors/feiqiu/docs/etl_tasks/base_task_mechanism.md` |
+| BD 手册（DWS 表） | `apps/etl/connectors/feiqiu/docs/database/DWS/main/` |
+| DWD-DOC 权威规则 | `.kiro/steering/dwd-doc-authority.md` |
+
+## 与其他文档的优先级
+
+DWS 层开发时的参考优先级：DWD-DOC > 本文档 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释。
+
+> 本文档基于 2026-03-19 对项目代码、配置表、BD 手册和审计记录的全面收集整理。