feat: gift card breakdown - migrations, fdw queries, finance recharge task, board-finance page updates

apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_recharge_summary.md

@@ -38,9 +38,15 @@
 | 18 | new_member_count | INTEGER | NO | 新增会员数 |
 | 19 | total_card_balance | NUMERIC(14,2) | NO | 全部会员卡余额（当日末） |
 | 20 | cash_card_balance | NUMERIC(14,2) | NO | 储值卡余额 |
-| 21 | gift_card_balance | NUMERIC(14,2) | NO | 赠送卡余额 |
-| 22 | created_at | TIMESTAMPTZ | NO | 创建时间 |
-| 23 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
+| 21 | gift_card_balance | NUMERIC(14,2) | NO | 赠送卡余额（合计） |
+| 22 | gift_liquor_balance | NUMERIC(14,2) | NO | 酒水卡余额（当日末快照），DEFAULT 0 |
+| 23 | gift_table_fee_balance | NUMERIC(14,2) | NO | 台费卡余额（当日末快照），DEFAULT 0 |
+| 24 | gift_voucher_balance | NUMERIC(14,2) | NO | 抵用券余额（当日末快照），DEFAULT 0 |
+| 25 | gift_liquor_recharge | NUMERIC(14,2) | NO | 酒水卡新增充值（赠送部分），DEFAULT 0 |
+| 26 | gift_table_fee_recharge | NUMERIC(14,2) | NO | 台费卡新增充值（赠送部分），DEFAULT 0 |
+| 27 | gift_voucher_recharge | NUMERIC(14,2) | NO | 抵用券新增充值（赠送部分），DEFAULT 0 |
+| 28 | created_at | TIMESTAMPTZ | NO | 创建时间 |
+| 29 | updated_at | TIMESTAMPTZ | NO | 更新时间 |
 
 ## 数据来源
 
@@ -70,11 +76,46 @@ GROUP BY DATE(pay_time);
 SELECT 
     SUM(balance) AS total_card_balance,
     SUM(CASE WHEN card_type_id = 2793249295533893 THEN balance ELSE 0 END) AS cash_card_balance,
-    SUM(CASE WHEN card_type_id != 2793249295533893 THEN balance ELSE 0 END) AS gift_card_balance
+    SUM(CASE WHEN card_type_id != 2793249295533893 THEN balance ELSE 0 END) AS gift_card_balance,
+    -- 赠送卡按卡类型拆分余额
+    SUM(CASE WHEN card_type_id = 2794699703437125 THEN balance ELSE 0 END) AS gift_liquor_balance,
+    SUM(CASE WHEN card_type_id = 2791990152417157 THEN balance ELSE 0 END) AS gift_table_fee_balance,
+    SUM(CASE WHEN card_type_id = 2793266846533445 THEN balance ELSE 0 END) AS gift_voucher_balance
 FROM dwd.dim_member_card_account
-WHERE scd2_is_current = 1;
+WHERE scd2_is_current = 1
+  AND COALESCE(is_delete, 0) = 0;
 ```
 
+### 赠送卡新增充值拆分：dwd_recharge_order JOIN dim_member_card_account
+```sql
+SELECT 
+    dca.card_type_id,
+    SUM(ro.point_amount) AS gift_recharge
+FROM dwd.dwd_recharge_order ro
+JOIN dwd.dim_member_card_account dca
+    ON ro.tenant_member_card_id = dca.tenant_member_id
+WHERE ro.site_id = :site_id
+    AND DATE(ro.pay_time) >= :start_date
+    AND DATE(ro.pay_time) <= :end_date
+    AND dca.card_type_id IN (2794699703437125, 2791990152417157, 2793266846533445)
+    AND dca.scd2_is_current = 1
+    AND COALESCE(dca.is_delete, 0) = 0
+GROUP BY dca.card_type_id;
+-- 结果映射：
+--   2794699703437125 → gift_liquor_recharge（酒水卡）
+--   2791990152417157 → gift_table_fee_recharge（台费卡）
+--   2793266846533445 → gift_voucher_recharge（抵用券）
+```
+
+## 恒等式约束
+
+| 约束 | 表达式 | 说明 |
+|------|--------|------|
+| 余额恒等 | `gift_card_balance = gift_liquor_balance + gift_table_fee_balance + gift_voucher_balance` | 赠送卡总余额 = 三种卡类型余额之和 |
+| 新增恒等 | `recharge_gift = gift_liquor_recharge + gift_table_fee_recharge + gift_voucher_recharge` | 赠送总额 = 三种卡类型新增之和 |
+
+> ETL 不做运行时校验，由数据质量检查任务事后验证。验证 SQL 见 `scripts/ops/verify_gift_breakdown.sql`。
+
 ## 使用说明
 
 **首充判断**
@@ -84,9 +125,9 @@ WHERE scd2_is_current = 1;
 **储值卡ID**
 - 储值卡 card_type_id = 2793249295533893
 **赠送卡ID**（归入 `gift_card_balance`）
-- 台费卡 2791990152417157
-- 酒水卡 2794699703437125
-- 活动抵用券 2793266846533445
+- 台费卡 2791990152417157 → `gift_table_fee_balance` / `gift_table_fee_recharge`
+- 酒水卡 2794699703437125 → `gift_liquor_balance` / `gift_liquor_recharge`
+- 活动抵用券 2793266846533445 → `gift_voucher_balance` / `gift_voucher_recharge`
 
 **其他卡类型**（当前未计入 `cash_card_balance` 或 `gift_card_balance`）
 - 年卡 2791987095408517
@@ -94,16 +135,47 @@ WHERE scd2_is_current = 1;
 
 > ⚠️ 年卡和月卡的余额目前未被 `_extract_card_balances()` 统计，不包含在 `total_card_balance` 中。详见 P12 PRD（`docs/prd/specs/P12-gift-card-breakdown.md`）。
 
+## 数据流向
+
+```
+DWD 层
+├── dim_member_card_account (card_type_id + balance)
+│   ├── → gift_liquor_balance   (card_type_id=2794699703437125)
+│   ├── → gift_table_fee_balance (card_type_id=2791990152417157)
+│   └── → gift_voucher_balance  (card_type_id=2793266846533445)
+│
+├── dwd_recharge_order JOIN dim_member_card_account (point_amount)
+│   ├── → gift_liquor_recharge   (card_type_id=2794699703437125)
+│   ├── → gift_table_fee_recharge (card_type_id=2791990152417157)
+│   └── → gift_voucher_recharge  (card_type_id=2793266846533445)
+│
+└── dwd_settlement_head (gift_card_amount)
+    └── → 消费行仅提供总额，无法按卡类型拆分
+
+ETL (FinanceRechargeTask)
+├── _extract_card_balances()        → 余额拆分
+├── _extract_gift_recharge_breakdown() → 新增充值拆分
+└── transform()                     → 合并 6 字段写入 DWS
+
+DWS → RLS 视图 → FDW 外部表 → 后端 API → 小程序
+```
+
 ## 可回溯性
 
 | 项目 | 说明 |
 |------|------|
 | 可回溯 | ✅ 完全可回溯 |
 | 数据范围 | 2025-07-21 ~ 至今 |
-| 依赖表 | dwd_recharge_order, dim_member_card_account |
+| 依赖表 | dwd_recharge_order, dim_member_card_account（余额快照 + 新增充值 JOIN） |
 
 <!--
 AI_CHANGELOG:
+- 日期: 2026-03-21
+- Prompt: gift-card-breakdown spec Task 11.1 — BD 手册更新
+- 直接原因: DWS 层新增 6 个赠送卡细分字段（3 种卡类型 × 余额+新增），需同步 BD 手册
+- 变更摘要: 字段说明表新增 6 字段（gift_liquor/table_fee/voucher_balance/recharge）；数据来源新增余额拆分 SQL 和新增充值 JOIN SQL；新增恒等式约束章节；新增数据流向章节；赠送卡 ID 映射补充字段对应关系；依赖表说明更新
+- 风险与验证: 纯文档变更，无运行时影响
+
 - 日期: 2026-03-19
 - Prompt: card_type_id 年卡/月卡映射同步
 - 直接原因: 用户确认 2791987095408517=年卡、2793306611533637=月卡，同步到所有涉及 card_type_id 的文档