186 lines
6.0 KiB
Markdown
186 lines
6.0 KiB
Markdown
# 会员余额总览 — TenantMemberBalanceOverview
|
||
|
||
> 模块：`MemberProfile` · ODS 表：无（新发现 API，尚未建表） · 统计快照
|
||
|
||
---
|
||
|
||
## 一、接口概述
|
||
|
||
查询当前租户下所有会员卡的余额统计一览，按卡介质（电子卡/实体卡）和卡来源（充值卡/赠送卡）两个维度汇总，并提供各卡类型的明细分拆。该接口为新发现的 API，当前尚未建立 ODS 表，主要用于财务对账和会员资产概览。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 完整路径 | `POST /MemberProfile/TenantMemberBalanceOverview` |
|
||
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
|
||
| 鉴权 | `Authorization: Bearer <token>` |
|
||
| 分页 | 无分页 |
|
||
| 时间范围 | 不需要（实时快照） |
|
||
|
||
---
|
||
|
||
## 二、请求
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
null
|
||
```
|
||
|
||
该接口无需请求参数，直接返回当前租户的会员余额汇总。
|
||
|
||
---
|
||
|
||
## 三、响应结构
|
||
|
||
```
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"totalPointBalance": 0.0,
|
||
"totalCardBalance": 356619.51,
|
||
"totalCardPrincipalBalance": 346917.34,
|
||
"electronicCardBalance": 356619.51,
|
||
"physicsCardBalance": 0,
|
||
"rechargeCardBalance": 90055.67,
|
||
"rechargeCardList": [ { ... } ],
|
||
"giveCardBalance": 266563.84,
|
||
"giveCardList": [ { ... } ]
|
||
}
|
||
}
|
||
```
|
||
|
||
`data` 对象包含 9 个顶层字段，其中 `rechargeCardList` 和 `giveCardList` 为卡类型明细数组。
|
||
|
||
---
|
||
|
||
## 四、响应字段详解（9 个字段）
|
||
|
||
### 4.1 总额汇总
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `totalPointBalance` | float | `0.0` | 全部会员积分余额合计（元）。当前门店未启用积分功能 |
|
||
| `totalCardBalance` | float | `356619.51` | 全部会员卡余额合计（元），含本金和赠送金额。等于 `electronicCardBalance` + `physicsCardBalance` |
|
||
| `totalCardPrincipalBalance` | float | `346917.34` | 全部会员卡本金余额合计（元），不含赠送部分 |
|
||
|
||
### 4.2 按卡介质分类
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `electronicCardBalance` | float | `356619.51` | 电子卡余额合计（元）。当前门店全部为电子卡 |
|
||
| `physicsCardBalance` | int | `0` | 实体卡余额合计（元）。当前门店未使用实体卡 |
|
||
|
||
### 4.3 按卡来源分类 — 充值卡
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `rechargeCardBalance` | float | `90055.67` | 充值卡余额合计（元），即会员主动充值获得的卡 |
|
||
| `rechargeCardList` | array | 见下表 | 充值卡按类型的明细列表 |
|
||
|
||
`rechargeCardList` 数组中每个元素：
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `cardTypeName` | string | `"储值卡"` | 卡类型名称。已知值：`储值卡`、`月卡` |
|
||
| `balance` | float | `86115.67` | 该类型卡的余额合计（元），含赠送部分 |
|
||
| `principalBalance` | float | `86115.67` | 该类型卡的本金余额合计（元） |
|
||
|
||
### 4.4 按卡来源分类 — 赠送卡
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `giveCardBalance` | float | `266563.84` | 赠送卡余额合计（元），即系统赠送/活动发放的卡 |
|
||
| `giveCardList` | array | 见下表 | 赠送卡按类型的明细列表 |
|
||
|
||
`giveCardList` 数组中每个元素：
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `cardTypeName` | string | `"台费卡"` | 卡类型名称。已知值：`消费卡`、`年卡`、`台费卡`、`活动抵用券`、`酒水卡` |
|
||
| `balance` | float | `247875.46` | 该类型卡的余额合计（元），含赠送部分 |
|
||
| `principalBalance` | float | `247875.46` | 该类型卡的本金余额合计（元） |
|
||
|
||
---
|
||
|
||
## 五、响应样例
|
||
|
||
```json
|
||
{
|
||
"totalPointBalance": 0.0,
|
||
"totalCardBalance": 356619.51,
|
||
"totalCardPrincipalBalance": 346917.34,
|
||
"electronicCardBalance": 356619.51,
|
||
"physicsCardBalance": 0,
|
||
"rechargeCardBalance": 90055.67,
|
||
"rechargeCardList": [
|
||
{
|
||
"cardTypeName": "储值卡",
|
||
"balance": 86115.67,
|
||
"principalBalance": 86115.67
|
||
},
|
||
{
|
||
"cardTypeName": "月卡",
|
||
"balance": 3940.0,
|
||
"principalBalance": 3940.0
|
||
}
|
||
],
|
||
"giveCardBalance": 266563.84,
|
||
"giveCardList": [
|
||
{
|
||
"cardTypeName": "消费卡",
|
||
"balance": 0,
|
||
"principalBalance": 0
|
||
},
|
||
{
|
||
"cardTypeName": "年卡",
|
||
"balance": 7.0,
|
||
"principalBalance": 7.0
|
||
},
|
||
{
|
||
"cardTypeName": "台费卡",
|
||
"balance": 247875.46,
|
||
"principalBalance": 247875.46
|
||
},
|
||
{
|
||
"cardTypeName": "活动抵用券",
|
||
"balance": 14972.43,
|
||
"principalBalance": 5270.26
|
||
},
|
||
{
|
||
"cardTypeName": "酒水卡",
|
||
"balance": 3708.95,
|
||
"principalBalance": 3708.95
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、跨表关联
|
||
|
||
该接口返回的是租户级汇总统计，不包含会员个体信息，与业务表的关联为间接关系。
|
||
|
||
| 潜在关联 | 说明 |
|
||
|----------|------|
|
||
| `totalCardBalance` | 应等于会员卡列表中所有卡的余额之和 |
|
||
| `rechargeCardList` / `giveCardList` 中的 `cardTypeName` | 对应会员卡类型配置中的卡类型名称 |
|
||
| `balance` vs `principalBalance` 差额 | 反映赠送金额部分，与充值记录中的赠送金额对应 |
|
||
|
||
> 当前该接口尚未建立 ODS 表，暂无 ETL 入库流程。该接口适合用于 DWS 层的会员资产快照统计，如后续需要持久化，建议在 `billiards_dws` schema 下新建汇总表。
|
||
|
||
### 金额校验关系
|
||
|
||
- `totalCardBalance` = `electronicCardBalance` + `physicsCardBalance`
|
||
- `totalCardBalance` = `rechargeCardBalance` + `giveCardBalance`
|
||
- 各 `*CardList` 中 `balance` 之和应等于对应的 `*CardBalance`
|
||
|
||
<!--
|
||
AI_CHANGELOG:
|
||
- 日期: 2026-02-13
|
||
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
|
||
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
|
||
- 变更摘要: 新建 docs/api-reference/tenant_member_balance_overview.md，按逻辑分组详解 9 个字段及嵌套结构，含金额校验关系
|
||
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
|
||
-->
|