# 会员余额总览 — TenantMemberBalanceOverview > 模块：`MemberProfile` · ODS 表：无（新发现 API，尚未建表） · 统计快照 --- ## 一、接口概述 查询当前租户下所有会员卡的余额统计一览，按卡介质（电子卡/实体卡）和卡来源（充值卡/赠送卡）两个维度汇总，并提供各卡类型的明细分拆。该接口为新发现的 API，当前尚未建立 ODS 表，主要用于财务对账和会员资产概览。 | 属性 | 值 | |------|-----| | 完整路径 | `POST /MemberProfile/TenantMemberBalanceOverview` | | Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` | | 鉴权 | `Authorization: Bearer ` | | 分页 | 无分页 | | 时间范围 | 不需要（实时快照） | --- ## 二、请求 ### 请求体 ```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`