206 lines
8.2 KiB
Markdown
206 lines
8.2 KiB
Markdown
# 会员余额变动 — 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）
|
||
|
||
```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"` | 余额变更记录创建时间，通常接近交易发生时间 |
|
||
|
||
---
|
||
|
||
## 五、响应样例（单条记录）
|
||
|
||
```json
|
||
{
|
||
"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` 的记录为平台级/活动结算场景
|
||
|
||
<!--
|
||
AI_CHANGELOG:
|
||
- 日期: 2026-02-13
|
||
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
|
||
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
|
||
- 变更摘要: 新建 docs/api-reference/member_balance_changes.md，按逻辑分组详解所有字段，含跨表关联
|
||
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
|
||
-->
|