17 KiB
会员余额变动（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/关联、会员维度、卡种信息、金额余额、类型来源、支付方式、时间、站点/操作员、状态标志、备注等）逐项说明。
- 主键与关联 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 仍是该门店。
- 会员与会员卡维度字段
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 条）
含义：卡种类型 ID，用于区分不同卡种。
memberCardTypeName
类型：string
值："储值卡", "活动抵用券", "酒水卡", "台费卡"
含义：卡种名称，与 card_type_id 一一对应，是一个 卡种枚举名称。
memberName
类型：string
含义：会员姓名或称呼（非昵称字段）。
说明：例如“陈腾鑫”“胡先生”“江先生”等，多为中文姓名或带“先生”称呼。
memberMobile
类型：string
含义：会员手机号。
说明：字符型存储，完整手机号，用来识别会员与联系客户。
- 门店名称与办卡门店名称
paySiteName
类型：string
值分布：
"朗朗桌球"：198 条
""（空字符串）：2 条
含义：发生本次余额变更的门店名称（即本次消费/充值所在门店）。
对应关系：
当 site_id = 朗朗桌球的ID 时，是该门店名称；
当 site_id = 0 时，这里为空，说明这两条记录是特殊的“活动抵用券退款”场景，不归属具体营业门店。
registerSiteName
类型：string
值：全为 "朗朗桌球"
含义：卡片的注册门店名称（办卡地点），和 register_site_id 配套。
特点：与 paySiteName 不同，强调“办卡地”，而不是“交易发生地”。
- 金额与余额字段
这是本表的核心：余额变化量与变化前后余额。
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
含义（推测）：与退款业务相关的金额字段，但在当前这份导出中实际未使用：
可能用于标记“其中有多少金额是以‘退款’形式回流的”，或区分“退回余额”和“原路退回”两种模式。
当前所有记录没有单独标记，字段处于空置状态。
- 变动来源类型（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 为加余额类（充值、赠送、调整加款等）。
- 支付方式字段
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：外部支付或赠送渠道枚举。
- 时间字段
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：本条余额变更记录的创建时间，通常接近交易发生时间。
说明：可与订单、支付记录的时间做对齐，构造时序链路（但你现在不要求做时序分析，这里只说明结构）。
- 站点与操作员信息
register_site_id / registerSiteName
已在前文说明：办卡门店的 ID 与名称，所有记录一致，说明所有卡均在“朗朗桌球”注册。
site_id / paySiteName
表示本次余额变动的发生门店，绝大多数也在“朗朗桌球”，少数特殊业务（活动抵用券结算）显示为 site_id=0、paySiteName 为空。
operator_id
类型：int
值分布：3 个不同值：
主操作员工 ID：出现 192 次；
另外两位店长/管理员各有若干条记录。
含义：执行此次余额变更操作的员工 ID。
operator_name
类型：string
值示例：
'收银员:郑丽珊'（占绝大多数）
'店长:郑丽珊'
'店长:谢晓洪'
'店长:蒋雨轩'
'管理员：郑丽珊'
含义：操作员姓名（带职位前缀），是对 operator_id 的可读冗余字段。
- 状态字段与标志
is_delete
类型：int
值：全部为 0
含义：逻辑删除标记：
0：正常；
1：逻辑删除（这类记录在系统中被标记为删除，但数据库中保留）。
当前导出数据中没有被逻辑删除的余额变更记录。
- 备注字段
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 和枚举字段建立了清晰的结构关系，而本次你给的这家门店只是该结构在一个门店上的数据切片。