#8.11 粉丝列表【基础探测通过，待数据联调】

GET /tieup/api/v1/artist/fans

查询当前有效或历史订阅粉丝，数据来自 tieup_subscription 和 tieup_artist_fan_message_stat。

鉴权：需要 Authorization: Bearer <access_token>，且当前账号已开通偶像端。

查询参数：

参数	类型	必填	说明
page	integer	否	页码，默认 1
page_size	integer	否	每页数量，默认 20，最大 100
current	integer	否	1=仅当前有效粉丝，2=仅历史/过期粉丝，不传为全部
keyword	string	否	按粉丝昵称或手机号模糊搜索

响应字段：

• items[].fan_user_id：粉丝用户 ID。
• items[].fan_nickname：粉丝昵称。
• items[].fan_avatar：粉丝头像。
• items[].fan_online_status：粉丝在线状态。
• items[].fan_phone_masked：脱敏手机号。
• items[].is_scout：该粉丝是否绑定星探，1=是，2=否；以 tieup_scout.user_id 是否存在记录为准，不受星探状态影响。
• items[].subscription_id / subscription_no：最近一条订阅记录。
• items[].subscription_plan_code / plan_name_snapshot：订阅档位快照。
• items[].amount_cent：最近订阅支付金额，单位分。
• items[].started_at / expires_at：最近订阅起止时间。
• items[].status：最近订阅状态。
• items[].is_current_fan：是否当前有效粉丝，1=是，2=否。
• items[].last_message_at：最后定向消息时间。
• items[].unread_count：艺人端未读数；订阅业务消息（message_type=subscription 或 object_name=Tieup:Subscribe）不计入。
• items[].fan_message_count：粉丝发给艺人的消息数。
• items[].artist_reply_count：艺人回复数。

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "items": [
      {
        "fan_user_id": 10001,
        "fan_nickname": "Tieup用户",
        "fan_avatar": "https://cdn.example.com/avatar.png",
        "fan_online_status": 1,
        "fan_phone_masked": "138****8000",
        "is_scout": 2,
        "subscription_id": 50001,
        "subscription_no": "TS202606170001",
        "subscription_plan_code": "month_30",
        "plan_name_snapshot": "月度订阅",
        "amount_cent": 3000,
        "started_at": "2026-06-17 10:00:00",
        "expires_at": "2026-07-17 23:59:59",
        "status": 1,
        "is_current_fan": 1,
        "last_message_at": null,
        "unread_count": 0,
        "fan_message_count": 0,
        "artist_reply_count": 0
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "next_cursor": null
    }
  }
}

说明：列表以 tieup_subscription 为主，避免漏掉未发生 IM 对话的订阅粉丝；手机号只返回脱敏值。

#8.11.1 查看粉丝详情【基础探测通过，待数据联调】

GET /tieup/api/v1/artist/fans/10001
Authorization: Bearer <access_token>

鉴权：需要 Authorization: Bearer <access_token>，且当前账号已开通偶像端。接口按粉丝用户 ID 查询，不要求该粉丝必须存在当前艺人的订阅记录；粉丝账号不存在、已禁用或已注销时返回 404。

响应字段：

字段	类型	说明
fan_user_id	integer	粉丝用户 ID
fan_nickname	string	粉丝昵称
fan_avatar	string	粉丝头像 URL
age	integer/null	粉丝年龄，未填写时为 null
province_name	string/null	粉丝省份名称，原样返回用户资料中的省级名称，未填写时为 null
city_name	string/null	粉丝城市名称，原样返回用户资料中的市级名称
gender	integer	性别：0=未知，1=男，2=女
signature	string/null	粉丝个性签名，未填写时为 null
companion_days	integer	按铁粉榜口径，从该粉丝对当前艺人的最早订阅开始时间累计的完整天数；无订阅记录返回 0
candy_spent	string	该粉丝对当前艺人的有效糖果消费汇总，固定两位小数字符串；排除已退款或已取消的提问、视频通话和福利兑换
is_scout	integer	是否绑定星探：1=是，2=否；只要存在 tieup_scout.user_id 绑定记录即返回 1，不受星探状态影响；与当前艺人的订阅关系无关

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "fan_user_id": 10001,
    "fan_nickname": "Tieup用户",
    "fan_avatar": "https://cdn.example.com/avatar.png",
    "age": 24,
    "province_name": "四川省",
    "city_name": "成都",
    "gender": 2,
    "signature": "保持热爱",
    "companion_days": 365,
    "candy_spent": "128.00",
    "is_scout": 2
  }
}