7. 粉丝端 API 7.1.2 测试环境查询融云超级群成员【测试环境专用，待融云联调】

Table of Contents

7.1.2 测试环境查询融云超级群成员【测试环境专用，待融云联调】

POST /tieup/api/v1/test/rongcloud/ultragroup/member-exists

说明：本接口只用于测试环境核对本地超级群成员状态和融云侧真实成员关系。接口不需要登录态或请求头；必须在服务端配置 TIEUP_MOCK_PAYMENT_ENABLED=true，且 APP_ENV=production 时强制禁用。常规联调只传 artist_id + fan_user_id，服务端自动读取本地融云用户绑定和超级群 ID；新建超级群 ID 格式为 tieup_artist_group_{artist_id}，历史未清理旧群可能仍为 tieup_artist_{artist_id}；排查特殊问题时也可直接传 rong_user_id + rong_ultra_group_id。

请求示例：

{
  "artist_id": 1,
  "fan_user_id": 10001,
  "mock_key": "local-test-key"
}

直接按融云 ID 查询示例：

{
  "rong_user_id": "tieup_fan_10001",
  "rong_ultra_group_id": "tieup_artist_group_1",
  "mock_key": "local-test-key"
}

请求字段：

字段 类型 必填 说明
artist_id integer 否 艺人 ID；常规联调和 fan_user_id 一起传
fan_user_id integer 否 粉丝 APP 用户 ID；服务端据此查 tieup_im_user_bind.rong_user_id
rong_user_id string 否 融云用户 ID；和 rong_ultra_group_id 同传时可直接查融云
rong_ultra_group_id string 否 融云超级群 ID；和 rong_user_id 同传时可直接查融云
mock_key string 否 测试接口密钥；配置 TIEUP_MOCK_PAYMENT_KEY 后必须传入匹配值

响应字段：

字段 类型 说明
exists boolean 融云返回的用户是否存在于超级群成员中
rong_user_id string 本次查询使用的融云用户 ID
rong_ultra_group_id string 本次查询使用的融云超级群 ID
local_member_status integer/null 本地成员状态：1=有效，2=已移出，3=同步失败；直接融云 ID 查询且未传本地 ID 时为空
local_member_last_sync_at string/null 本地成员最近一次同步融云时间
local_failed_reason string/null 本地成员同步失败原因
rongcloud_response object 融云查询成员接口原始响应快照

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "exists": true,
    "rong_user_id": "tieup_fan_10001",
    "rong_ultra_group_id": "tieup_artist_group_1",
    "local_member_status": 1,
    "local_member_last_sync_at": "2026-06-17 10:00:01",
    "local_failed_reason": null,
    "rongcloud_response": {
      "code": 200,
      "status": true
    }
  }
}

业务规则：

  • 本接口调用融云 POST /ultragroup/member/exist.json，请求参数为 userId 和 groupId。
  • exists=true 表示融云侧确认用户存在于该超级群成员中。
  • local_member_status=1 且 local_member_last_sync_at 不为空，只代表本地曾成功调用入群；最终以本接口 exists 查询融云结果为准。
  • 未找到粉丝融云绑定或艺人超级群时返回业务错误；如需绕过本地数据排查，可直接传 rong_user_id + rong_ultra_group_id。