# 会员消费统计 — QueryMemberConsumptionStatistics

> 模块：`MemberProfile` · ODS 表：`member_consumption_statistics`（待建） · 统计汇总

---

## 一、接口概述

按门店维度统计会员卡的消费、充值、退款等金额汇总。可通过 `cardTypeId` 筛选特定卡种，不传则统计全部卡种。返回每个门店（含营销点）的资金流向汇总数据，用于财务对账和卡种经营分析。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/QueryMemberConsumptionStatistics` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | page / limit |
| 时间范围 | `startTime` / `endTime` |
| 响应数据路径 | `data.memberConsumptionStatisticsList` |

---

## 二、请求

### 请求体（JSON）

```json
{
  "cardTypeId": 2793249295533893,
  "startTime": "2026-02-01 08:00:00",
  "endTime": "2026-02-13 08:00:00",
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `cardTypeId` | int | 否 | 卡种 ID。不传则统计全部卡种 |
| `startTime` | string | 是 | 统计起始时间（含），格式 `YYYY-MM-DD HH:mm:ss` |
| `endTime` | string | 是 | 统计截止时间（不含），格式同上 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

```
{
  "code": 0,
  "data": {
    "total": 2,
    "memberConsumptionStatisticsList": [
      {
        "siteId": ...,
        "siteName": "...",
        "siteType": 1,
        "consumptionValue": ...,
        ...
      }
    ]
  }
}
```

`data.memberConsumptionStatisticsList` 为数组，每个元素代表一个门店/营销点的资金汇总。

---

## 四、响应字段详解（11 个字段）

### 4.1 门店标识

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `siteName` | string | `"朗朗桌球"` | 门店名称 |
| `siteType` | int | `1` | 门店类型：`1` = 实体门店，`3` = 总营销点 |

### 4.2 资金流向汇总

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `consumptionValue` | float | `-57791.25` | 消费金额合计（元）。负值表示消费支出 |
| `settleRefundValue` | float | `3349.41` | 结算退款金额合计（元） |
| `rechargeValue` | float | `50298.0` | 充值金额合计（元） |
| `systemSwitchingValue` | float | `0.0` | 系统转换/迁移金额（元）。跨卡种或跨系统转入转出 |
| `residueRechargeValue` | float | `0.0` | 剩余充值金额（元）。预留字段 |
| `reChargeRevokedValue` | float | `0.0` | 充值撤销金额（元） |
| `rechargeGiftValue` | float | `0.0` | 充值赠送金额（元） |
| `backendAdjustValue` | float | `0.0` | 后台人工调整金额（元） |

### 4.3 余额结果

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `restValue` | float | `-4143.84` | 期末余额/剩余值（元）。等于各项资金流入流出的净值 |

---

## 五、响应样例

### 指定 cardTypeId

```json
{
  "data": {
    "total": 2,
    "memberConsumptionStatisticsList": [
      {
        "siteId": 2790685415443269,
        "siteName": "朗朗桌球",
        "siteType": 1,
        "consumptionValue": -57791.25,
        "settleRefundValue": 3349.41,
        "rechargeValue": 50298.0,
        "systemSwitchingValue": 0.0,
        "residueRechargeValue": 0.0,
        "reChargeRevokedValue": 0.0,
        "rechargeGiftValue": 0.0,
        "backendAdjustValue": 0.0,
        "restValue": -4143.84
      },
      {
        "siteId": 2928823574824965,
        "siteName": "总营销点",
        "siteType": 3,
        "consumptionValue": 0.0,
        "settleRefundValue": 0.0,
        "rechargeValue": 0.0,
        "systemSwitchingValue": 0.0,
        "residueRechargeValue": 0.0,
        "reChargeRevokedValue": 0.0,
        "rechargeGiftValue": 0.0,
        "backendAdjustValue": 0.0,
        "restValue": 0.0
      }
    ]
  },
  "code": 0
}
```

### 不传 cardTypeId（全部卡种）

```json
{
  "data": {
    "total": 2,
    "memberConsumptionStatisticsList": [
      {
        "siteId": 2790685415443269,
        "siteName": "朗朗桌球",
        "siteType": 1,
        "consumptionValue": -66877.46,
        "settleRefundValue": 3885.79,
        "rechargeValue": 50298.0,
        "systemSwitchingValue": 15432.0,
        "residueRechargeValue": 0.0,
        "reChargeRevokedValue": 0.0,
        "rechargeGiftValue": 0.0,
        "backendAdjustValue": 0.0,
        "restValue": 2738.33
      },
      {
        "siteId": 2928823574824965,
        "siteName": "总营销点",
        "siteType": 3,
        "consumptionValue": 0.0,
        "settleRefundValue": 0.0,
        "rechargeValue": 0.0,
        "systemSwitchingValue": 0.0,
        "residueRechargeValue": 0.0,
        "reChargeRevokedValue": 0.0,
        "rechargeGiftValue": 0.0,
        "backendAdjustValue": 0.0,
        "restValue": 0.0
      }
    ]
  },
  "code": 0
}
```

---

## 六、跨表关联

| 关联表 | 关联字段 | 说明 |
|--------|----------|------|
| `member_stored_value_cards` | `cardTypeId` 对应卡种配置 | 按卡种筛选时的关联 |
| `member_balance_changes` | `siteId` + 时间范围 | 余额变动明细的汇总口径 |
| `recharge_settlements` | `siteId` + 时间范围 | 充值结算的汇总口径 |
| `settlement_records` | `siteId` + 时间范围 | 消费结算的汇总口径 |

### 金额校验关系

- `restValue` ≈ `rechargeValue` + `consumptionValue` + `settleRefundValue` + `systemSwitchingValue` + `residueRechargeValue` - `reChargeRevokedValue` + `rechargeGiftValue` + `backendAdjustValue`
- 注意 `consumptionValue` 为负值（支出方向）

<!--
AI_CHANGELOG:
- 日期: 2026-02-14
- Prompt: P20260214-083000 — 替换 role_area_association 为 member_consumption_statistics，获取 JSON 样本并撰写文档
- 直接原因: 用户要求用 QueryMemberConsumptionStatistics 替换 role_area_association，需新建 API 参考文档
- 变更摘要: 新建 member_consumption_statistics.md，含接口概述、请求参数、11 个响应字段详解、两种调用样例、跨表关联
- 风险与验证: 纯文档，无运行时影响；验证：对比 samples/member_consumption_statistics.json 确认字段覆盖完整
-->
