# 会员余额总览 — TenantMemberBalanceOverview

> 模块：`MemberProfile` · ODS 表：`tenant_member_balance_overview`（待建） · 统计快照

---

## 一、接口概述

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

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

---

## 二、请求

### 请求体

```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 层的会员资产快照统计，如后续需要持久化，建议在 `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/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过

- 日期: 2026-02-14
- Prompt: P20260214-083000 — ODS 表标注从"无"改为"待建"
- 直接原因: 用户确认该接口需要建 ODS 表，且 rechargeCardList/giveCardList 需展开
- 变更摘要: 头部 ODS 表标注从"无（新发现 API，尚未建表）"改为"tenant_member_balance_overview（待建）"
- 风险与验证: 纯文档标注变更；验证：grep "待建" docs/api-reference/tenant_member_balance_overview.md
-->
