# 会员余额变动 — GetMemberCardBalanceChange > 模块：`MemberProfile` · ODS 表：`member_balance_changes` · 事实表（增量） --- ## 一、接口概述 查询会员卡余额变动明细，记录每一次充值、消费扣款、赠送、退款等导致卡内余额发生变化的事件。每条记录包含变动前后余额、变动金额、来源类型、支付方式、操作员等信息。本表是会员卡层面的"总账/明细账表"，严格满足 `after = before + account_data` 的余额恒等关系。 | 属性 | 值 | |------|-----| | 完整路径 | `POST /MemberProfile/GetMemberCardBalanceChange` | | Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` | | 鉴权 | `Authorization: Bearer ` | | 分页 | `page` + `limit`（最大 100） | | 时间范围 | 需要（`startTime` / `endTime`） | --- ## 二、请求 ### 请求体（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 个字段，按逻辑分组说明如下。 --- ## 四、响应字段详解（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` = 跨门店/平台级操作（如活动抵用券退款） | | `register_site_id` | int | `2790685415443269` | 会员卡注册门店 ID（办卡所在门店），与 `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` = 台费卡 | | `memberCardTypeName` | string | `"储值卡"` | 卡种名称，与 `card_type_id` 一一对应。枚举值：`"储值卡"`、`"活动抵用券"`、`"酒水卡"`、`"台费卡"` | | `memberName` | string | `"曾丹烨"` | 会员姓名/称呼 | | `memberMobile` | string | `"13922213242"` | 会员手机号 | ### 4.3 门店名称 | 字段 | 类型 | 示例 | 说明 | |------|------|------|------| | `paySiteName` | string | `"朗朗桌球"` | 余额变更发生的门店名称。当 `site_id=0` 时为空字符串 | | `registerSiteName` | string | `"朗朗桌球"` | 卡片注册门店名称（办卡地点） | ### 4.4 金额与余额（核心） | 字段 | 类型 | 示例 | 说明 | |------|------|------|------| | `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.5 变动来源与支付方式 | 字段 | 类型 | 示例 | 说明 | |------|------|------|------| | `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.6 操作员信息 | 字段 | 类型 | 示例 | 说明 | |------|------|------|------| | `operator_id` | int | `2790687322443013` | 执行本次余额变更操作的员工 ID | | `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀），如 `"收银员:郑丽珊"`、`"店长:谢晓洪"` | ### 4.7 状态与备注 | 字段 | 类型 | 示例 | 说明 | |------|------|------|------| | `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已逻辑删除。系统倾向"不可逆记账"，冲销通过反向变动实现 | | `remark` | string | `""` | 备注。多数为空，`"充值退款"` 仅出现在 `from_type=7` 的记录上 | ### 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` 的记录为平台级/活动结算场景