# 会员余额变动 — GetMemberCardBalanceChange

> 模块：`MemberProfile` · ODS 表：`member_balance_changes` · 事实表（增量）

---

## 一、接口概述

查询会员卡余额变动明细，记录每一次充值、消费扣款、赠送、退款等导致卡内余额发生变化的事件。每条记录包含变动前后余额、变动金额、来源类型、支付方式、操作员等信息。本表是会员卡层面的"总账/明细账表"，严格满足 `after = before + account_data` 的余额恒等关系。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/GetMemberCardBalanceChange` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
| 响应数据路径 | `data.tenantMemberCardLogs` |

---

## 二、请求

### 请求体（JSON）

```json
{
  "startTime": "2026-02-01 08:00:00",
  "endTime": "2026-02-13 08:00:00",
  "fromType": 0,
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `fromType` | int | 是 | 来源类型筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

```
{
  "code": 200,
  "data": {
    "list": [ { ... }, { ... } ],
    "total": 200
  }
}
```

`data.list` 中每个对象即为一条余额变更记录，共 25 个字段（含 3 个本金明细字段），按 8 个逻辑分组说明如下。

---

## 四、响应字段详解（25 个字段）

### 4.1 主键与关联 ID

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957881605869253` | 余额变更记录主键 ID，唯一标识一条余额变化事件 |
| `relate_id` | int | `2957881518788421` | 关联业务记录 ID。视 `from_type` 而定，可能对应充值记录 ID、订单结算单 ID、活动核销记录 ID 等。`0` = 无挂接业务单（如纯后台调整） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 余额变动发生的门店 ID。`0` = 跨门店/平台级操作（如活动抵用券退款） |
| `paySiteName` | string | `"朗朗桌球"` | 余额变更发生的门店名称（`site_id` 的冗余展示字段）。当 `site_id=0` 时为空字符串 |
| `register_site_id` | int | `2790685415443269` | 会员卡注册门店 ID（办卡所在门店），与 `site_id` 区分"办卡地"和"交易发生地" |
| `registerSiteName` | string | `"朗朗桌球"` | 卡片注册门店名称（`register_site_id` 的冗余展示字段） |

### 4.2 会员与会员卡维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenant_member_id` | int | `2799212845565701` | 租户内会员主键 ID。对应会员档案表的 `id` |
| `system_member_id` | int | `2799212844549893` | 系统级会员 ID（全局唯一） |
| `tenant_member_card_id` | int | `2799219999295237` | 会员卡账户 ID，指明本次变更针对哪一张卡。对应储值卡列表的 `id` |
| `card_type_id` | int | `2793249295533893` | 卡种类型 ID。枚举：`2793249295533893` = 储值卡，`2793266846533445` = 活动抵用券，`2794699703437125` = 酒水卡，`2791990152417157` = 台费卡，`2791987095408517` = 年卡，`2793306611533637` = 月卡 |
| `memberCardTypeName` | string | `"储值卡"` | 卡种名称，与 `card_type_id` 一一对应。枚举值：`"储值卡"`、`"活动抵用券"`、`"酒水卡"`、`"台费卡"`、`"年卡"`、`"月卡"` |
| `memberName` | string | `"曾丹烨"` | 会员姓名/称呼 |
| `memberMobile` | string | `"13922213242"` | 会员手机号 |

### 4.3 金额与余额（核心）

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `before` | float | `816.3` | 变动前卡账户余额（元） |
| `account_data` | float | `-120.0` | 本次变动金额（元）。正数 = 增加（充值/赠送），负数 = 减少（消费/退款） |
| `after` | float | `696.3` | 变动后卡账户余额（元）。恒等关系：`after = before + account_data` |
| `refund_amount` | float | `0.0` | 退款相关金额（元）。当前未使用，全部为 `0.0` |

### 4.4 变动来源与支付方式

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `from_type` | int | `1` | 变动来源类型（核心枚举）。`1` = 日常消费扣款（负数），`2` = 其他增加，`3` = 充值增加（正数，有外部支付），`4` = 调整/赠送增加（正数，后台发放），`7` = 充值退款（负数，remark 为"充值退款"），`9` = 活动抵用券余额冲减（负数，site_id=0） |
| `payment_method` | int | `0` | 支付方式。`0` = 内部结算/非外部支付（from_type=1/2/7/9），`3` = 赠送/后台调账渠道（from_type=4），`4` = 外部支付渠道（from_type=3，如扫码充值） |

### 4.5 操作员信息

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 执行本次余额变更操作的员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀），如 `"收银员:郑丽珊"`、`"店长:谢晓洪"` |

### 4.6 状态与备注

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已逻辑删除。系统倾向"不可逆记账"，冲销通过反向变动实现 |
| `remark` | string | `""` | 备注。多数为空，`"充值退款"` 仅出现在 `from_type=7` 的记录上 |

### 4.7 本金明细

> 储值卡余额由"本金"和"赠送金"两部分组成。以下字段记录本金维度的变动，与 4.4 的总余额变动互补。

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `principal_before` | number | `2854.73` | 变动前本金余额（元） |
| `principal_data` | number | `-132.0` | 本金变动金额（元）。正数=增加，负数=减少 |
| `principal_after` | number | `2722.73` | 变动后本金余额（元）。恒等关系：`principal_after = principal_before + principal_data` |

### 4.8 时间

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 22:52:48"` | 余额变更记录创建时间，通常接近交易发生时间 |

---

## 五、响应样例（单条记录）

```json
{
  "memberCardTypeName": "储值卡",
  "paySiteName": "朗朗桌球",
  "registerSiteName": "朗朗桌球",
  "memberName": "曾丹烨",
  "memberMobile": "13922213242",
  "id": 2957881605869253,
  "account_data": -120.0,
  "after": 696.3,
  "before": 816.3,
  "card_type_id": 2793249295533893,
  "create_time": "2025-11-09 22:52:48",
  "from_type": 1,
  "is_delete": 0,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "payment_method": 0,
  "refund_amount": 0.0,
  "register_site_id": 2790685415443269,
  "relate_id": 2957881518788421,
  "remark": "",
  "site_id": 2790685415443269,
  "system_member_id": 2799212844549893,
  "tenant_id": 2790683160709957,
  "tenant_member_card_id": 2799219999295237,
  "tenant_member_id": 2799212845565701
}
```

---

## 六、跨表关联

### 与会员档案（`member_profiles`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_id` | `id` | 租户内会员主键 |
| `system_member_id` | `system_member_id` | 系统级会员 ID |

### 与储值卡列表（`member_stored_value_cards`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_card_id` | `id` | 卡账户 ID → 具体哪张卡 |
| `card_type_id` | `card_type_id` | 卡种类型 ID |

> 余额变更流水通过 `tenant_member_card_id` 指向具体卡账户，再通过 `card_type_id` 确定卡种。

### 与支付记录

充值类记录（`from_type=3`）的 `relate_id` 对应充值记录 ID，`payment_method` 与支付记录中的支付渠道枚举保持一致。

### 与订单/消费流水

消费扣款（`from_type=1`）和活动冲减（`from_type=9`）的 `relate_id` 对应订单/结算单/活动扣款单的主键，可与台费流水、助教流水、门店销售记录中的 `order_settle_id` 建立关系。

### 与门店维度

- `site_id` / `paySiteName`：交易发生门店
- `register_site_id` / `registerSiteName`：办卡门店
- 少数 `site_id=0` 的记录为平台级/活动结算场景

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/member_balance_changes.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 3 个缺失字段（cardtypename, principalbalance, tenantname）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.8"时间"组混入 principal_after/principal_before/principal_data 三个本金字段
- 变更摘要: 新增 4.8"本金明细"组（3 字段）；原 4.8 时间组重编号为 4.9
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 25+3 = 28（含本金字段）

- 日期: 2026-03-19
- Prompt: card_type_id 年卡/月卡映射同步
- 直接原因: 用户确认 2791987095408517=年卡、2793306611533637=月卡，同步到所有涉及 card_type_id 的文档
- 变更摘要: card_type_id 枚举和 memberCardTypeName 枚举补充年卡/月卡
- 风险与验证: 纯文档变更，无运行时影响
-->
