88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# 团队/分销成员列表 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` 是否都为空。
|