会员余额总览 — TenantMemberBalanceOverview

模块：MemberProfile · ODS 表：无（新发现 API，尚未建表） · 统计快照

一、接口概述

查询当前租户下所有会员卡的余额统计一览，按卡介质（电子卡/实体卡）和卡来源（充值卡/赠送卡）两个维度汇总，并提供各卡类型的明细分拆。该接口为新发现的 API，当前尚未建立 ODS 表，主要用于财务对账和会员资产概览。

属性	值
完整路径	`POST /MemberProfile/TenantMemberBalanceOverview`
Base URL	`https://pc.ficoo.vip/apiprod/admin/v1/`
鉴权	`Authorization: Bearer <token>`
分页	无分页
时间范围	不需要（实时快照）

二、请求

请求体

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`	该类型卡的本金余额合计（元）

五、响应样例

{
  "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

6.0 KiB Raw Permalink Blame History Unescape Escape