# dws_finance_recharge_summary 充值统计表

> 生成时间：2026-02-03

## 表信息

| 属性 | 值 |
|------|-----|
| Schema | dws |
| 表名 | dws_finance_recharge_summary |
| 主键 | id |
| 唯一键 | (site_id, stat_date) |
| 数据来源 | dwd_recharge_order |
| 更新频率 | 每日更新 |
| 说明 | 以"日期"为粒度，统计充值数据，区分首充/续充 |

## 字段说明

| 序号 | 字段名 | 类型 | 可空 | 说明 |
|------|--------|------|------|------|
| 1 | id | BIGSERIAL | NO | 自增主键 |
| 2 | site_id | BIGINT | NO | 门店ID |
| 3 | tenant_id | BIGINT | NO | 租户ID |
| 4 | stat_date | DATE | NO | 统计日期 |
| 5 | recharge_count | INTEGER | NO | 充值笔数 |
| 6 | recharge_total | NUMERIC(14,2) | NO | 充值总额（含赠送） |
| 7 | recharge_cash | NUMERIC(14,2) | NO | 现金充值金额 |
| 8 | recharge_gift | NUMERIC(14,2) | NO | 赠送金额 |
| 9 | first_recharge_count | INTEGER | NO | 首充笔数 |
| 10 | first_recharge_cash | NUMERIC(14,2) | NO | 首充现金 |
| 11 | first_recharge_gift | NUMERIC(14,2) | NO | 首充赠送 |
| 12 | first_recharge_total | NUMERIC(14,2) | NO | 首充总额 |
| 13 | renewal_count | INTEGER | NO | 续充笔数 |
| 14 | renewal_cash | NUMERIC(14,2) | NO | 续充现金 |
| 15 | renewal_gift | NUMERIC(14,2) | NO | 续充赠送 |
| 16 | renewal_total | NUMERIC(14,2) | NO | 续充总额 |
| 17 | recharge_member_count | INTEGER | NO | 充值会员数（去重） |
| 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 | 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 | 更新时间 |

## 数据来源

### 充值订单：dwd_recharge_order
```sql
SELECT 
    DATE(pay_time) AS stat_date,
    COUNT(*) AS recharge_count,
    SUM(pay_amount + point_amount) AS recharge_total,
    SUM(pay_amount) AS recharge_cash,
    SUM(point_amount) AS recharge_gift,
    -- 首充
    SUM(CASE WHEN is_first = 1 THEN 1 ELSE 0 END) AS first_recharge_count,
    SUM(CASE WHEN is_first = 1 THEN pay_amount ELSE 0 END) AS first_recharge_cash,
    SUM(CASE WHEN is_first = 1 THEN point_amount ELSE 0 END) AS first_recharge_gift,
    -- 续充
    SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN 1 ELSE 0 END) AS renewal_count,
    SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN pay_amount ELSE 0 END) AS renewal_cash,
    -- 会员数
    COUNT(DISTINCT member_id) AS recharge_member_count
FROM dwd.dwd_recharge_order
GROUP BY DATE(pay_time);
```

### 卡余额快照：dim_member_card_account
```sql
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 = 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
  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`。

## 使用说明

**首充判断**
- is_first = 1: 首充
- is_first = 0: 续充

**储值卡ID**
- 储值卡 card_type_id = 2793249295533893
**赠送卡ID**（归入 `gift_card_balance`）
- 台费卡 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
- 月卡 2793306611533637

> ⚠️ 年卡和月卡的余额目前未被 `_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（余额快照 + 新增充值 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 的文档
- 变更摘要: 赠送卡ID 部分添加归入说明，新增"其他卡类型"段落标注年卡/月卡未被统计的遗漏
- 风险与验证: 纯文档变更，无运行时影响
-->
