# 团队/分销成员列表 API 接口文档

本文档描述了获取团队成员列表（直推用户）的后端接口规范，用于支持前端正确显示成员的会员身份（如倾听会员、陪伴会员、守护会员、心伴会员）。

## 接口基本信息

- **URL**: `/api/commission`
- **Method**: `GET`
- **Query Parameters**:
  - `action`: 固定为 `referrals`
  - `page`: 页码（从1开始）
  - `pageSize`: 每页数量

## 响应结构

接口应返回 JSON 格式数据。

### 成功响应示例

```json
{
  "success": true,
  "data": {
    "list": [
      {
        "userId": 12345,
        "userName": "用户昵称",
        "userAvatar": "https://example.com/avatar.jpg",
        "userRole": "soulmate", 
        "userRoleName": "心伴会员",
        "boundAt": "2025-02-04 10:00:00",
        "totalContribution": 100.00
      },
      {
        "userId": 67890,
        "userName": "普通用户A",
        "userRole": "",
        "userRoleName": "",
        "boundAt": "2025-02-03 15:30:00"
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}
```

### 关键字段说明 (`list` 数组项)

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `userId` | Number/String | 是 | 用户唯一标识 |
| `userName` | String | 否 | 用户昵称，如果为空前端会显示默认名称 |
| `userAvatar` | String | 否 | 用户头像URL |
| `userRole` | String | **推荐** | 用户会员身份标识（枚举值见下表）。前端会优先根据此字段映射显示中文名称。 |
| `userRoleName` | String | **可选** | 直接返回显示的会员名称（如“心伴会员”）。如果提供了此字段，前端将直接显示此值，不再进行映射。 |
| `boundAt` | String/Number | 是 | 绑定时间/注册时间 |
| `totalContribution` | Number | 否 | 贡献收益金额 |

### 会员身份枚举值 (`userRole`)

前端已内置以下映射关系，请后端返回对应的英文标识：

| 英文标识 (`userRole`) | 对应显示的名称 | 说明 |
| :--- | :--- | :--- |
| `listener` | **倾听会员** | |
| `companion` | **陪伴会员** | |
| `guardian` | **守护会员** | |
| `soulmate` | **心伴会员** | |
| `partner` | **城市合伙人** | |
| `(空字符串)` | **普通用户** | 未开通任何会员 |

**注意：**
1. 如果用户未开通任何会员，`userRole` 应返回空字符串 `""` 或 `null`，前端将显示为“普通用户”。
2. 如果用户有多个身份，请返回最高级别的身份标识。
3. 如果后端返回了 `userRoleName` 字段（例如 "超级VIP"），前端将直接显示该字段的值，忽略 `userRole` 的映射。这可用于支持未来新增的会员类型而无需修改前端代码。

## 常见问题排查

如果前端显示“普通用户”但不正确：
1. 检查后端是否返回了 `userRole` 字段。
2. 检查 `userRole` 的值是否在上述枚举表中（区分大小写，前端期望全小写）。
3. 检查是否误传了 `isDistributor` 字段导致前端误判（新版前端代码已移除对 `isDistributor` 的依赖，改为默认显示“普通用户”）。

如果前端显示“undefined”或空白：
1. 检查 `userRole` 和 `userRoleName` 是否都为空。