ai-c/docs/team_api_spec.md

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

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

接口基本信息

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

响应结构

接口应返回 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 是否都为空。