# 会员余额变动（GetMemberCardBalanceChange）

> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetMemberCardBalanceChange` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/MemberProfile/GetMemberCardBalanceChange` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `member_balance_changes` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |

## 请求参数

| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `fromType` | int | `0` | 来源类型（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |

## 响应字段（共 25 个）

| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `memberCardTypeName` | string | '储值卡' |
| 2 | `paySiteName` | string | '朗朗桌球' |
| 3 | `registerSiteName` | string | '朗朗桌球' |
| 4 | `memberName` | string | '曾丹烨' |
| 5 | `memberMobile` | string | '13922213242' |
| 6 | `id` | int | 2957881605869253 |
| 7 | `account_data` | float | -120.0 |
| 8 | `after` | float | 696.3 |
| 9 | `before` | float | 816.3 |
| 10 | `card_type_id` | int | 2793249295533893 |
| 11 | `create_time` | string | '2025-11-09 22:52:48' |
| 12 | `from_type` | int | 1 |
| 13 | `is_delete` | int | 0 |
| 14 | `operator_id` | int | 2790687322443013 |
| 15 | `operator_name` | string | '收银员:郑丽珊' |
| 16 | `payment_method` | int | 0 |
| 17 | `refund_amount` | float | 0.0 |
| 18 | `register_site_id` | int | 2790685415443269 |
| 19 | `relate_id` | int | 2957881518788421 |
| 20 | `remark` | string | '' |
| 21 | `site_id` | int | 2790685415443269 |
| 22 | `system_member_id` | int | 2799212844549893 |
| 23 | `tenant_id` | int | 2790683160709957 |
| 24 | `tenant_member_card_id` | int | 2799219999295237 |
| 25 | `tenant_member_id` | int | 2799212845565701 |

## 新增字段（相对本地 JSON 样本）

以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：

| 字段名 | 类型 |
|--------|------|
| `principal_after` | float |
| `principal_before` | float |
| `principal_data` | float |

## 详细字段分析

> 以下内容迁移自旧版 `member_balance_changes-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。

二、记录级字段逐项说明（含类型、含义、枚举/规律）

下面按逻辑分类（ID/关联、会员维度、卡种信息、金额余额、类型来源、支付方式、时间、站点/操作员、状态标志、备注等）逐项说明。

1. 主键与关联 ID 类字段

id

类型：int

含义：余额变更记录的主键 ID，唯一标识这一条“账户余额变化事件”。

relate_id

类型：int

值分布：共 167 个不同值，0 约 18 次，绝大部分为非 0 的长整型。

含义（推测）：关联业务记录的 ID：

例如某次充值记录的 ID、某张订单/结算单 ID、某次活动抵用券核销记录 ID 等。

为 0 时，通常表示没有挂接具体业务单（例如纯后台调整）。

与其它表的关系：

视 from_type 而定，可能对应：

充值记录（如果有导出）；

订单结算记录；

活动抵用券账单等。

tenant_id

类型：int

含义：租户/商户 ID，本数据中是固定值（同一品牌/商户）。

site_id

类型：int

值分布：

2790685415443269（朗朗桌球）出现 198 条；

0 出现 2 条。

含义：

非 0：记录所属的具体门店 ID（与其他 JSON 内的 site_id 一致）。

0：特殊场景，通常代表“跨门店/虚拟站点/平台级操作”。在本数据中，这两条记录恰好是“活动抵用券”相关的退款/冲销记录。

关联：可与门店档案（siteProfile.id）对应。

register_site_id

类型：int

值：全为 2790685415443269

含义：会员卡的“注册门店 ID”，即办卡所在门店。

对比：

register_site_id 表示“卡当初在哪家店办的”，

site_id 表示“本次余额变动发生在哪家店”。本数据两者绝大部分情况一致，只有活动抵用券退款那两条 site_id=0、register_site_id 仍是该门店。

2. 会员与会员卡维度字段

tenant_member_id

类型：int

含义：商户维度的会员 ID（租户内会员主键）。

关联：

对应“会员档案（20251110_043209_…）”中的 id 字段，即同一个租户下的会员主键。

作用：

在本表与会员档案之间形成外键关系：
余额变更记录.tenant_member_id = 会员档案.id

system_member_id

类型：int

含义：系统级（全局）会员 ID。

关联：

对应会员档案中的 system_member_id 字段。

说明：

允许一个会员在多个租户/门店下有不同的 tenant_member_id，但共享同一个 system_member_id。

在你当前的数据里，只存在一个门店，所以两个 ID 一般一一对应同一个会员，但本质上设计是“集团级 ID + 租户级 ID”双键。

tenant_member_card_id

类型：int

含义：会员卡账户 ID，在租户内唯一标识某张卡。

关联：

对应“会员档案/储值卡列表”中的 id（卡账户 ID）。

作用：

一名会员可以有多张卡（储值卡、台费卡、酒水卡、活动券等），tenant_member_card_id 指明这条余额变更是针对哪一张卡。

card_type_id

类型：int

值分布（与 memberCardTypeName 一一对应）：

2793249295533893 → “储值卡”（132 条）

2793266846533445 → “活动抵用券”（52 条）

2794699703437125 → “酒水卡”（9 条）

2791990152417157 → “台费卡”（7 条）

2791987095408517 → “年卡”（7 条）

2793306611533637 → “月卡”（12 条）

含义：卡种类型 ID，用于区分不同卡种。

memberCardTypeName

类型：string

值："储值卡", "活动抵用券", "酒水卡", "台费卡", "年卡", "月卡"

含义：卡种名称，与 card_type_id 一一对应，是一个 卡种枚举名称。

memberName

类型：string

含义：会员姓名或称呼（非昵称字段）。

说明：例如“陈腾鑫”“胡先生”“江先生”等，多为中文姓名或带“先生”称呼。

memberMobile

类型：string

含义：会员手机号。

说明：字符型存储，完整手机号，用来识别会员与联系客户。

3. 门店名称与办卡门店名称

paySiteName

类型：string

值分布：

"朗朗桌球"：198 条

""（空字符串）：2 条

含义：发生本次余额变更的门店名称（即本次消费/充值所在门店）。

对应关系：

当 site_id = 朗朗桌球的ID 时，是该门店名称；

当 site_id = 0 时，这里为空，说明这两条记录是特殊的“活动抵用券退款”场景，不归属具体营业门店。

registerSiteName

类型：string

值：全为 "朗朗桌球"

含义：卡片的注册门店名称（办卡地点），和 register_site_id 配套。

特点：与 paySiteName 不同，强调“办卡地”，而不是“交易发生地”。

4. 金额与余额字段

这是本表的核心：余额变化量与变化前后余额。

before

类型：float

含义：本次变动前，该卡账户的余额（元）。

说明：

样本中有 0、数百、数千等各种值。

account_data

类型：float

含义：本次变动的金额（元），正数表示增加，负数表示减少。

特点：

无 0 值，所有记录要么增加要么扣减。

常见值：

正数：100、500、1000、3000、5000 等（充值或调整增加）；

负数：-5、-8、-10、-120、-144、-5000、-10000 等（消费扣款或退款冲减）。

与 from_type 强烈相关（详见后文）。

after

类型：float

含义：本次变动后，该卡账户的余额（元）。

重要关系：

所有记录都满足：
before + account_data = after（浮点精度下完全成立）。

这是本表最重要的结构性约束之一。

refund_amount

类型：float

值：全为 0.0

含义（推测）：与退款业务相关的金额字段，但在当前这份导出中实际未使用：

可能用于标记“其中有多少金额是以‘退款’形式回流的”，或区分“退回余额”和“原路退回”两种模式。

当前所有记录没有单独标记，字段处于空置状态。

5. 变动来源类型（from_type）

from_type

类型：int，关键枚举字段

值分布：

1：163 条

3：16 条

4：16 条

7：2 条（备注为“充值退款”）

9：2 条（活动抵用券余额冲减）

2：1 条（正数增额）

含义（根据金额符号与 remark 综合推断）：

1：日常消费扣款

account_data 均为负数（-120、-144、-114.61 等），payment_method=0。

表示“用卡消费扣除余额”（例如用储值卡、台费卡支付消费）。

3：充值增加

account_data 均为正数（1000、3000、5000 等），payment_method=4。

对应实际有外部支付行为的充值（如扫码充值），为卡增加余额。

4：调整增加 / 赠送增加

account_data 多为 100、500、888 等，payment_method=3。

很可能是“后台赠送/活动赠送/调整加款”，不是顾客直接付款。

7：充值退款（明确）

两条记录 remark 字段均为 "充值退款"，account_data 为 -5000、-10000 元，payment_method=0。

结合上面 3 类充值记录，可以看出是“对前期充值的退款，以减少卡内余额的方式处理”。

9：活动抵用券相关余额冲减

两条记录的 memberCardTypeName 均为“活动抵用券”，account_data 为 -888、-1888，site_id=0，paySiteName 为空。

推测是“将活动抵用券额度从‘活动抵用券卡’里扣回/结算”，属于活动资金回收类。

2：其他增加（仅 1 条，正数 1865.8 元）

可能是某种“赠送+充值混合”的业务类型，当前只有单一案例，很难精确命名，但可确定是增额类型。

总体上，from_type 是本表中最重要的业务类型枚举，控制 account_data 的“方向”和解释：

1/7/9 为减余额类（消费扣款、退款冲减、活动冲减等），

2/3/4 为加余额类（充值、赠送、调整加款等）。

6. 支付方式字段

payment_method

类型：int，枚举

值分布：

0：168 条

3：16 条

4：16 条

结合 from_type 分析：

from_type=1/2/7/9 时，payment_method=0：

表示这类“内部扣减/内部调整/退款冲减”，并没有直接发生新的实收支付（或者实收在原单中记录，余额变动仅是内部记账）。

from_type=3 时，payment_method=4：

对应“充值类交易”，是顾客真实付款（扫码/银行卡等），这里记录的是付款渠道枚举之一（如微信/支付宝/银行卡等）。

from_type=4 时，payment_method=3：

一类“赠送/后台调账”渠道编码，表示这部分余额增加不是顾客直接付钱，而是后台发放或内部调整。

无法在不看系统配置的前提下精确说出 3/4 分别对应哪一个具体渠道（微信/支付宝/银行卡等），但可以明确：

0：内部结算/非外部支付；

3、4：外部支付或赠送渠道枚举。

7. 时间字段

create_time

类型：string，格式 YYYY-MM-DD HH:MM:SS

含义：本条余额变更记录的创建时间，通常接近交易发生时间。

说明：可与订单、支付记录的时间做对齐，构造时序链路（但你现在不要求做时序分析，这里只说明结构）。

8. 站点与操作员信息

register_site_id / registerSiteName

已在前文说明：办卡门店的 ID 与名称，所有记录一致，说明所有卡均在“朗朗桌球”注册。

site_id / paySiteName

表示本次余额变动的发生门店，绝大多数也在“朗朗桌球”，少数特殊业务（活动抵用券结算）显示为 site_id=0、paySiteName 为空。

operator_id

类型：int

值分布：3 个不同值：

主操作员工 ID：出现 192 次；

另外两位店长/管理员各有若干条记录。

含义：执行此次余额变更操作的员工 ID。

operator_name

类型：string

值示例：

'收银员:郑丽珊'（占绝大多数）

'店长:郑丽珊'

'店长:谢晓洪'

'店长:蒋雨轩'

'管理员：郑丽珊'

含义：操作员姓名（带职位前缀），是对 operator_id 的可读冗余字段。

9. 状态字段与标志

is_delete

类型：int

值：全部为 0

含义：逻辑删除标记：

0：正常；

1：逻辑删除（这类记录在系统中被标记为删除，但数据库中保留）。

当前导出数据中没有被逻辑删除的余额变更记录。

10. 备注字段

remark

类型：string

值分布：

""（空）：198 条

"充值退款"：2 条

含义：

当为空时，说明这条变动没有额外备注说明。

"充值退款" 明确标记该条记录是“充值退款”业务，这与 from_type=7 的两条记录完全对应，用于给操作者和报表更明确的文本说明。

三、余额变更记录与其他 JSON 的结构性关联（字段层面）

虽然你此问题主要关注字段本身，但这些字段设计是有明显的跨表关联意图的，这里从“字段结构”的角度简要列一下关键关联，不做任何金额/盈利分析。

与会员档案（20251110_043209_…）

tenant_member_id ↔ 会员档案 id

system_member_id ↔ 会员档案 system_member_id

这形成：
余额变更记录 ——(会员 ID)→ 会员基本信息（手机号、注册时间等）。

与储值卡/会员卡档案（储值卡列表/会员档案内卡记录）

tenant_member_card_id ↔ 卡档案 id（每一张卡的账户主键）。

card_type_id ↔ 卡种定义表的主键（从当前 JSON 看不到卡种定义表本身，但可以通过 memberCardTypeName，以及在其他表中的 member_card_grade_code 推测对应关系）。

这形成：
余额变更流水 ——(tenant_member_card_id)→ 某个具体卡账户 ——(card_type_id)→ 卡种类型（储值卡/酒水卡/台费卡/活动抵用券）。

与支付记录（20251110_035941_…）

逻辑上，充值类的记录（from_type=3）应该对应一条支付记录：

支付记录中 relate_type 标记为“充值”，relate_id 对应某条充值记录 ID；

而余额变更记录中 relate_id 很可能就是充值记录 ID。

同样，payment_method 在两边都是枚举字段，应保持一致（如 4 代表某个线上支付渠道）。

由于你当前的充值记录 JSON 为空，完整链路难以直接验证，但结构设计就是通过 relate_id + from_type + payment_method 来将余额变动与支付流水相互印证。

与订单/消费类流水

当 from_type=1（消费扣款）或 from_type=9（活动抵用券相关冲减）时：

relate_id 通常对应某单据（订单/结算单/活动扣款单）的主键；

通过 relate_id 可以与台费流水、助教流水、门店销售记录中的 order_settle_id 或其他业务 ID 建立关系。

结构上，这些额度层面的变动记录，就是消费类流水在“会员账户余额维度”的映射。

四、结构层面的额外线索（不做任何盈利/统计）

从字段和值的规律，可以看到一些结构上的特征，对你后续做数据建模或迁移有用：

严格的余额恒等关系

所有记录都满足：
after = before + account_data

说明这个表是“余额快照 +变动量”的纯记账结构，不掺杂其他衍生数值（例如手续费等）进来。

from_type+payment_method 的组合语义很清晰

from_type 决定业务类型（消费、充值、赠送、退款等）；

payment_method 决定是否有外部支付以及大致支付渠道；

对应关系稳定且方向明确（加额/减额与 from_type 显著相关），这是后续做“业务类型维度表”的重要线索。

卡种类型在本表中已经完全可识别

通过 card_type_id ↔ memberCardTypeName，本表已经给出了储值卡、酒水卡、台费卡、活动抵用券、年卡、月卡六种卡型及各自的 ID；

与“会员档案”里 member_card_grade_code / member_card_grade_name 可以配套构成更完整的“卡种维度”。

办卡门店与交易门店的区分

register_site_id/registerSiteName 始终是办卡门店；

site_id/paySiteName 则是余额变更发生门店；

少数记录的 site_id=0 提示了“平台级/活动结算”等场景，说明系统在结构上已经考虑跨店或虚拟门店场景。

remark 与 from_type 的配合使用

尽管 remark 大多为空，但“充值退款”这两个字只出现在 from_type=7 的记录上；

说明系统使用 remark 为部分场景提供更直观的文本说明，但逻辑判断仍以 from_type 为主。

逻辑删除与业务废除分离

本表只有 is_delete 字段（全 0），没有诸如 is_trash 之类业务性废除标记；

说明在余额变更层面，系统倾向于“不可逆记账”（不直接作废账户流水），业务层面若要冲销，是通过新的相反方向变动（负充值或正向退款）来体现，而不是逻辑删除记录。



整体来看，余额变更记录.json 是会员卡层面的“总账/明细账表”，与“充值记录”“消费结算记录”“会员档案”“卡类型、卡实例”之间，通过一整套 ID 和枚举字段建立了清晰的结构关系，而本次你给的这家门店只是该结构在一个门店上的数据切片。

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