root/ZQYY.FQ-ETL

Fork 0

Files

Neo 3c51f5485d 初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00

8.2 KiB

Raw Permalink Blame History

会员余额变动 — GetMemberCardBalanceChange

模块：MemberProfile · ODS 表：member_balance_changes · 事实表（增量）

一、接口概述

查询会员卡余额变动明细，记录每一次充值、消费扣款、赠送、退款等导致卡内余额发生变化的事件。每条记录包含变动前后余额、变动金额、来源类型、支付方式、操作员等信息。本表是会员卡层面的"总账/明细账表"，严格满足 after = before + account_data 的余额恒等关系。

属性	值
完整路径	`POST /MemberProfile/GetMemberCardBalanceChange`
Base URL	`https://pc.ficoo.vip/apiprod/admin/v1/`
鉴权	`Authorization: Bearer <token>`
分页	`page` + `limit`（最大 100）
时间范围	需要（`startTime` / `endTime`）

二、请求

请求体（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"`	余额变更记录创建时间，通常接近交易发生时间

五、响应样例（单条记录）

{
  "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 的记录为平台级/活动结算场景

8.2 KiB Raw Permalink Blame History Unescape Escape