在前后端开发联调前 的提交20260223

docs/database/BD_Manual_member_balance_changes.md

@@ -0,0 +1,74 @@
+# BD_Manual：member_balance_changes（会员余额变动）
+
+> ODS 表：`ods.member_balance_changes`
+> DWD 表：`dwd.dwd_member_balance_change`（主表）、`dwd.dwd_member_balance_change_ex`（扩展表）
+> API 接口：会员余额变动记录列表
+> JSON 路径：`member_balance_changes.json → data.memberAccountChanges`
+> 装载方式：事实表增量插入（`DwdLoadTask`）
+> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
+
+---
+
+## 1. dwd_member_balance_change（主表，22 列）
+
+| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|---------|---------|-------------|
+| `balance_change_id` | BIGINT | `id` | FACT_MAPPINGS | 余额变动记录唯一标识（PK） | 飞球雪花 ID |
+| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
+| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
+| `register_site_id` | BIGINT | `register_site_id` | 自动映射 | 会员注册门店 ID | 飞球门店 ID |
+| `tenant_member_id` | BIGINT | `tenant_member_id` | 自动映射 | 租户维度会员 ID | 飞球会员 ID |
+| `system_member_id` | BIGINT | `system_member_id` | 自动映射 | 系统维度会员 ID（跨租户唯一） | 飞球会员 ID |
+| `tenant_member_card_id` | BIGINT | `tenant_member_card_id` | 自动映射 | 会员卡 ID | 飞球会员卡 ID |
+| `card_type_id` | BIGINT | `card_type_id` | 自动映射 | 会员卡类型 ID | 飞球卡类型 ID |
+| `card_type_name` | VARCHAR(32) | `membercardtypename` | FACT_MAPPINGS | 会员卡类型名称快照 | 如 `普通会员卡` |
+| `member_name` | VARCHAR(64) | `membername` | FACT_MAPPINGS | 会员姓名快照 | 姓名 |
+| `member_mobile` | VARCHAR(20) | `membermobile` | FACT_MAPPINGS | 会员手机号快照 | 11 位手机号 |
+| `balance_before` | NUMERIC(18,2) | `before` | FACT_MAPPINGS | 变动前余额（元） | 金额值 |
+| `change_amount` | NUMERIC(18,2) | `account_data` | FACT_MAPPINGS | 变动金额（元），正数为充入，负数为扣减 | 正/负金额 |
+| `balance_after` | NUMERIC(18,2) | `after` | FACT_MAPPINGS | 变动后余额（元） | 金额值 |
+| `from_type` | INTEGER | `from_type` | 自动映射 | 变动来源类型：1=结算扣款，2=充值，3=退款返还，4=系统调整，7=转账，9=其他 | `1`/`2`/`3`/`4`/`7`/`9` |
+| `payment_method` | INTEGER | `payment_method` | 自动映射 | 支付方式 | 枚举值 |
+| `change_time` | TIMESTAMPTZ | `create_time` | FACT_MAPPINGS | 变动发生时间 | ISO 时间戳 |
+| `is_delete` | INTEGER | `is_delete` | 自动映射 | 是否已删除：0=正常，1=已删除 | `0` / `1` |
+| `remark` | VARCHAR(255) | `remark` | 自动映射 | 备注说明 | 自由文本或 NULL |
+| `principal_before` | NUMERIC(18,2) | `principal_before` | FACT_MAPPINGS | 变动前本金余额（元），不含赠送金 | 金额值 |
+| `principal_after` | NUMERIC(18,2) | `principal_after` | FACT_MAPPINGS | 变动后本金余额（元） | 金额值 |
+| `principal_change_amount` | NUMERIC(18,2) | *计算列* | FACT_MAPPINGS | 本金变动金额（元），= `principal_after - principal_before` | 正/负金额 |
+
+---
+
+## 2. dwd_member_balance_change_ex（扩展表，8 列）
+
+| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|---------|---------|-------------|
+| `balance_change_id` | BIGINT | `id` | FACT_MAPPINGS | 余额变动记录唯一标识（PK） | 同主表 |
+| `pay_site_name` | VARCHAR(64) | `paysitename` | FACT_MAPPINGS | 支付门店名称快照 | 如 `朗朗桌球` |
+| `register_site_name` | VARCHAR(64) | `registersitename` | FACT_MAPPINGS | 注册门店名称快照 | 如 `朗朗桌球` |
+| `refund_amount` | NUMERIC(18,2) | `refund_amount` | 自动映射 | 退款金额（元） | `0.00` ~ 金额值 |
+| `operator_id` | BIGINT | `operator_id` | 自动映射 | 操作员 ID，执行本次余额变动的员工。0 表示系统自动 | `0` 或员工 ID |
+| `operator_name` | VARCHAR(64) | `operator_name` | 自动映射 | 操作员姓名 | 姓名或 NULL |
+| `principal_data` | TEXT | `principal_data` | FACT_MAPPINGS | 本金变动金额（元），正数为充入本金，负数为扣减本金 | 正/负金额 |
+| `relate_id` | BIGINT | `relate_id` | FACT_MAPPINGS | 关联业务单据 ID，指向触发本次余额变动的业务记录。按 `from_type` 不同指向不同表：1→结算单 ID，2→充值单 ID，3→退款单 ID，7→转账单 ID。`from_type=4`（系统调整）和 `9`（其他）时为 0 | `0` 或业务单据 ID |
+
+---
+
+## 3. from_type 枚举值详解
+
+| from_type | 含义 | relate_id 指向 | 数据量 |
+|-----------|------|---------------|--------|
+| 1 | 结算扣款（消费） | 结算单 ID（`dwd_settlement_head.order_settle_id`） | 5637 条 |
+| 2 | 充值 | 充值单 ID（`dwd_recharge_order.recharge_order_id`） | 110 条 |
+| 3 | 退款返还 | 退款单 ID（`dwd_refund.refund_id`） | 650 条 |
+| 4 | 系统调整 | 0（无关联单据） | 775 条 |
+| 7 | 转账 | 转账单 ID | 15 条 |
+| 9 | 其他 | 0（无关联单据） | 179 条 |
+
+---
+
+## 4. 代码引用
+
+- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_member_balance_change"]` / `FACT_MAPPINGS["dwd.dwd_member_balance_change_ex"]`
+- TABLE_MAP：`"dwd.dwd_member_balance_change" → "ods.member_balance_changes"`
+- DWS 下游：`dws_member_analysis_task.py`（会员消费分析）
+- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__add_member_balance_change_ex_relate_id.sql`（已归档）