# 会员余额变动（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 条） 含义：卡种类型 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 和枚举字段建立了清晰的结构关系，而本次你给的这家门店只是该结构在一个门店上的数据切片。