590 lines
17 KiB
Markdown
590 lines
17 KiB
Markdown
# 会员余额变动（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 和枚举字段建立了清晰的结构关系，而本次你给的这家门店只是该结构在一个门店上的数据切片。
|