8. 偶像端 API 8.4 偶像统计看板【基础探测通过，待数据联调】

Table of Contents

8.4 偶像统计看板【基础探测通过，待数据联调】

说明：旧兼容入口 GET /tieup/api/v1/artist/dashboard 已删除。APP 必须按页面模块调用下列总览、粉丝、收入和榜单拆分接口，避免一次性触发重查询。

鉴权：以下接口均需要 Authorization: Bearer <access_token>，且当前账号必须已开通偶像端。

统一口径：本节所有 rate 对象均包含 value、numerator、denominator。value 为百分比数值字符串，例如 "60.00" 表示 60.00%；numerator 为分子，denominator 为分母。后台页面展示时会在 value 后拼接 %。

统一时间参数：总览、粉丝和收入接口不传 start_date、end_date 时统计全部数据；按日期查询时必须同时传两个 YYYY-MM-DD 日期，按 Asia/Shanghai 自然日包含开始日 00:00:00 和结束日 23:59:59。start_date 不得晚于 end_date，end_date 不得晚于当天。旧 range 参数、单边日期、非法日期、倒序日期和未来结束日期均返回 422。

8.4.0 偶像计总【已开发，待登录态和真实数据联调】

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

服务端只根据当前登录用户解析自己的艺人 ID，不允许查询其他艺人。

请求参数：

字段 类型 必填 说明
type string 否 计总类型：message=群消息，question=提问，video_call=视频通话，system=系统消息；不传时兼容返回全部字段。类型值区分大小写，非法值返回 422

响应字段：

字段 类型 说明
unread_group_message_count integer type=message 或未传 type 时返回；当前艺人超级群中粉丝发给艺人的未读定向消息数，只统计发送成功、未撤回、read_status=1 且不是订阅业务消息（message_type=subscription 或 object_name=Tieup:Subscribe）的消息；该字段是未读角标，不等于 /tieup/api/v1/artist/messages 全量列表的 pagination.total
pending_question_count integer type=question 或未传 type 时返回；待回答提问/追问会话链数，每条问答链只统计最新节点，口径与偶像提问列表一致
answered_question_count integer type=question 或未传 type 时返回；最新节点状态为 status=2 的已回答会话链数，口径与 /tieup/api/v1/artist/questions?status=2 的 pagination.total 一致
question_income_candy_amount string type=question 或未传 type 时返回；提问和追问总收入糖果，仅统计 status=2 已回答记录，固定两位小数
pending_video_call_count integer type=video_call 或未传 type 时返回；待通话列表总数，统计预约状态 1/2/3
finished_video_call_count integer type=video_call 或未传 type 时返回；已完成列表总数，按列表页签统计状态 4/5/6/7/8，并非仅状态 4
video_income_candy_amount string type=video_call 或未传 type 时返回；视频总收入糖果，仅统计 status=4 已完成预约，固定两位小数
unread_system_message_count integer type=system 或未传 type 时返回；当前艺人的未读系统消息总数，统计 receiver_identity=artist、receiver_id=当前艺人 ID、read_status=1 的全部记录，不限制 business_type

不传 type 的完整响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "unread_group_message_count": 9,
    "pending_question_count": 3,
    "answered_question_count": 18,
    "question_income_candy_amount": "1280.00",
    "pending_video_call_count": 2,
    "finished_video_call_count": 12,
    "video_income_candy_amount": "3600.00",
    "unread_system_message_count": 4
  }
}

type=message 完整请求和响应示例：

GET /tieup/api/v1/artist/summary?type=message
Authorization: Bearer <access_token>

{
  "code": 200,
  "message": "成功",
  "data": {
    "unread_group_message_count": 9
  }
}

type=question 完整请求和响应示例：

GET /tieup/api/v1/artist/summary?type=question
Authorization: Bearer <access_token>

{
  "code": 200,
  "message": "成功",
  "data": {
    "pending_question_count": 3,
    "answered_question_count": 18,
    "question_income_candy_amount": "1280.00"
  }
}

type=video_call 完整请求和响应示例：

GET /tieup/api/v1/artist/summary?type=video_call
Authorization: Bearer <access_token>

{
  "code": 200,
  "message": "成功",
  "data": {
    "pending_video_call_count": 2,
    "finished_video_call_count": 12,
    "video_income_candy_amount": "3600.00"
  }
}

type=system 完整请求和响应示例：

GET /tieup/api/v1/artist/summary?type=system
Authorization: Bearer <access_token>

{
  "code": 200,
  "message": "成功",
  "data": {
    "unread_system_message_count": 4
  }
}

说明：接口使用 tieup:artist_summary:v3:{artist_id}:{type}:{version} Redis 短缓存，有效期 30 秒，其中未传 type 时缓存类型为 all。提问链状态、提问收入或偶像未读消息发生真实变化后，服务端会原子递增对应分类和 all 的缓存版本，使后续请求立即切换到新缓存；Redis 异常时直接查询数据库或等待旧缓存自然过期，缓存故障不影响业务写入。已完成视频列表包含爽约和取消记录，但视频收入只统计真正完成的状态 4，两个字段不可使用同一状态集合计算。

8.4.1 统计总览

GET /tieup/api/v1/artist/dashboard/overview?start_date=2026-07-01&end_date=2026-07-28
Authorization: Bearer <access_token>

请求参数：

字段 类型 必填 说明
start_date string 否 开始日期，格式 YYYY-MM-DD；与 end_date 同时传，不传两个日期表示全部
end_date string 否 结束日期，格式 YYYY-MM-DD；不得晚于当天，与 start_date 同时传

响应字段：

字段 类型 说明
artist object 当前艺人资料快照，字段同偶像资料接口的基础艺人字段
range.mode string all=全部，date_range=日期范围
range.start_date string/null 日期范围开始日期；全部模式为 null
range.end_date string/null 日期范围结束日期；全部模式为 null
subscription.new_count integer 当前范围新增订阅粉丝去重数
subscription.cancel_count integer 当前范围取消订阅数
subscription.renew_count integer 当前范围自动续订订阅数
subscription.total_count integer 历史订阅粉丝去重数
subscription.renew_rate object 续订率：当前范围自动续订订阅数 / 当前范围订阅记录数
subscription.retention_rate object 留存率：当前有效订阅粉丝数 / 历史订阅粉丝数
interaction.daily_streak_days integer 艺人连续发送全群普通群发消息的天数；只统计 direction=3，同一天多条只算一天，从统计范围内最后发送日向前计算，范围内没有全群消息返回 0
interaction.fan_reply_rate object 粉丝消息回复率：分母为范围内粉丝发送消息数，分子为这些原消息中被艺人引用回复过的原消息数，按原消息编号去重；引用回复发生在范围外仍计入
interaction.sent_message_count integer 后台总览消息数据「发送消息」：当前范围艺人发送成功的消息数，包含单聊回复、群发或广播等艺人侧发送记录
interaction.read_rate object 后台总览消息数据「已读率」：已读消息数 / 应读消息数
interaction.reply_message_count integer 后台总览消息数据「回复粉丝」：当前范围艺人回复粉丝消息数
interaction.reply_rate object 后台总览消息数据「回复率」：艺人回复粉丝消息数 / 粉丝发给艺人的消息数
income_composition.subscription_count integer 当前范围订阅收入粉丝去重数
income_composition.subscription_amount string 当前范围订阅收入，单位元，两位小数字符串
income_composition.question_count integer 当前范围提问收入笔数，含追问
income_composition.question_amount string 当前范围提问收入，单位元，两位小数字符串
income_composition.video_call_count integer 当前范围视频通话收入笔数
income_composition.video_call_amount string 当前范围视频通话收入，单位元，两位小数字符串
interaction_counts.question_count integer 当前范围提问数
interaction_counts.video_call_count integer 当前范围视频通话预约数
todo_overview.pending_question_count integer 当前待回答提问数
todo_overview.pending_benefit_count integer 当前待发放福利数
todo_overview.unread_message_count integer 艺人端未读定向消息数
todo_overview.today_question_count integer 今日提问数
todo_overview.today_video_booking_count integer 今日视频通话预约数

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "artist": {
      "id": 20001,
      "user_id": 10001,
      "artist_name": "示例艺人",
      "avatar": "https://cdn.example.com/artist/avatar.png",
      "withdrawable_amount": "1024.00"
    },
    "range": {
      "mode": "date_range",
      "start_date": "2026-07-01",
      "end_date": "2026-07-28"
    },
    "subscription": {
      "new_count": 3,
      "cancel_count": 0,
      "renew_count": 1,
      "total_count": 1280,
      "renew_rate": {
        "value": "33.33",
        "numerator": 1,
        "denominator": 3
      },
      "retention_rate": {
        "value": "25.00",
        "numerator": 320,
        "denominator": 1280
      }
    },
    "interaction": {
      "daily_streak_days": 0,
      "fan_reply_rate": {
        "value": "60.00",
        "numerator": 12,
        "denominator": 20
      },
      "sent_message_count": 40,
      "read_rate": {
        "value": "80.00",
        "numerator": 80,
        "denominator": 100
      },
      "reply_message_count": 12,
      "reply_rate": {
        "value": "60.00",
        "numerator": 12,
        "denominator": 20
      }
    },
    "income_composition": {
      "subscription_count": 18,
      "subscription_amount": "540.00",
      "question_count": 12,
      "question_amount": "120.00",
      "video_call_count": 6,
      "video_call_amount": "360.00"
    },
    "interaction_counts": {
      "question_count": 4,
      "video_call_count": 1
    },
    "todo_overview": {
      "pending_question_count": 3,
      "pending_benefit_count": 2,
      "unread_message_count": 9,
      "today_question_count": 4,
      "today_video_booking_count": 1
    }
  }
}

说明：总览接口返回首屏卡片、收入构成和待办，不返回榜单，避免榜单重查询。全群消息连续天数只统计发送成功或成功后撤回的 direction=3 消息；回复率只统计发送成功或成功后撤回的粉丝原消息和艺人引用回复，按粉丝原消息日期筛选并按原消息编号去重。服务端使用 Redis 短缓存，缓存 key 形如 tieup:artist_dashboard:overview:{artist_id}:all 或 tieup:artist_dashboard:overview:{artist_id}:{start_date}:{end_date}，有效期 30 秒。

8.4.2 粉丝统计

GET /tieup/api/v1/artist/dashboard/fans?start_date=2026-07-22&end_date=2026-07-28
Authorization: Bearer <access_token>

请求参数：

字段 类型 必填 说明
start_date string 否 开始日期，格式 YYYY-MM-DD；与 end_date 同时传，不传两个日期表示全部
end_date string 否 结束日期，格式 YYYY-MM-DD；不得晚于当天，与 start_date 同时传

响应字段：

字段 类型 说明
range object 实际生效范围，字段为 mode、start_date、end_date
subscription_overview.total_subscribers integer 历史订阅粉丝去重数
subscription_overview.new_subscribers integer 当前范围新增订阅粉丝去重数
subscription_overview.auto_renew_subscribers integer 当前范围自动续订粉丝去重数
subscription_overview.active_subscribers integer 当前有效订阅粉丝去重数
retention_metrics.renew_rate object 粉丝页留存指标「续订率」：当前范围自动续订订阅数 / 当前范围订阅记录数
retention_metrics.retention_rate object 粉丝页留存指标「留存率」：当前有效订阅粉丝数 / 历史订阅粉丝数
interaction_metrics.read_rate object 后台粉丝页「消息互动」卡片「已读率」：已读消息数 / 应读消息数
interaction_metrics.reply_rate object 后台粉丝页「消息互动」卡片「回复率」：艺人回复粉丝消息数 / 粉丝发给艺人的消息数
interaction_metrics.interaction_rate object 后台粉丝页「消息互动」卡片「互动率」：有互动的粉丝数 / 当前有效订阅粉丝数；无有效订阅粉丝时使用历史订阅粉丝数作为分母
interaction_metrics.sent_message_count integer 后台粉丝页「消息互动」卡片「发送消息」：当前范围艺人发送成功的消息数，包含单聊回复、群发或广播等艺人侧发送记录
interaction_metrics.reply_message_count integer 后台粉丝页「消息互动」卡片「回复消息」：当前范围艺人回复粉丝消息数
interaction_metrics.new_question_count integer 后台粉丝页「消息互动」卡片「新增提问」：当前范围新增提问数
interaction_metrics.new_video_call_count integer 后台粉丝页「消息互动」卡片「新增视频通话」：当前范围新增视频通话预约数
interaction_metrics.unreplied_question_count integer 后台粉丝页「消息互动」卡片「未回复提问」：当前范围待回答提问数
interaction_metrics.avg_reply_seconds integer 后台粉丝页「消息互动」卡片「平均回复时长」：当前范围平均回复耗时，单位秒

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "range": {
      "mode": "date_range",
      "start_date": "2026-07-22",
      "end_date": "2026-07-28"
    },
    "subscription_overview": {
      "total_subscribers": 1280,
      "new_subscribers": 18,
      "auto_renew_subscribers": 9,
      "active_subscribers": 320
    },
    "retention_metrics": {
      "renew_rate": {
        "value": "50.00",
        "numerator": 9,
        "denominator": 18
      },
      "retention_rate": {
        "value": "25.00",
        "numerator": 320,
        "denominator": 1280
      }
    },
    "interaction_metrics": {
      "read_rate": {
        "value": "80.00",
        "numerator": 80,
        "denominator": 100
      },
      "reply_rate": {
        "value": "60.00",
        "numerator": 12,
        "denominator": 20
      },
      "interaction_rate": {
        "value": "15.00",
        "numerator": 48,
        "denominator": 320
      },
      "sent_message_count": 40,
      "reply_message_count": 12,
      "new_question_count": 4,
      "new_video_call_count": 1,
      "unreplied_question_count": 3,
      "avg_reply_seconds": 180
    }
  }
}

说明：粉丝统计复用后台艺人统计页口径，不返回昨日、同类、平均或其他艺人比较值。服务端使用 Redis 短缓存，缓存 key 形如 tieup:artist_dashboard:fans:{artist_id}:all 或 tieup:artist_dashboard:fans:{artist_id}:{start_date}:{end_date}，有效期 30 秒。

8.4.3 收入统计

GET /tieup/api/v1/artist/dashboard/income?start_date=2026-07-01&end_date=2026-07-28
Authorization: Bearer <access_token>

请求参数：

字段 类型 必填 说明
start_date string 否 开始日期，格式 YYYY-MM-DD；与 end_date 同时传，不传两个日期表示全部
end_date string 否 结束日期，格式 YYYY-MM-DD；不得晚于当天，与 start_date 同时传

响应字段：

字段 类型 说明
range object 实际生效范围，字段为 mode、start_date、end_date
withdrawable_amount string 当前可提现金额，单位元，两位小数字符串
income_composition.subscription_count integer 当前范围订阅收入粉丝去重数
income_composition.subscription_amount string 当前范围订阅收入，单位元，两位小数字符串
income_composition.question_count integer 当前范围提问收入笔数，含追问
income_composition.question_amount string 当前范围提问收入，单位元，两位小数字符串
income_composition.video_call_count integer 当前范围视频通话收入笔数
income_composition.video_call_amount string 当前范围视频通话收入，单位元，两位小数字符串
total_income_amount string 当前范围总收入，单位元，两位小数字符串

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "range": {
      "mode": "date_range",
      "start_date": "2026-07-01",
      "end_date": "2026-07-28"
    },
    "withdrawable_amount": "1024.00",
    "income_composition": {
      "subscription_count": 18,
      "subscription_amount": "540.00",
      "question_count": 12,
      "question_amount": "120.00",
      "video_call_count": 6,
      "video_call_amount": "360.00"
    },
    "total_income_amount": "1020.00"
  }
}

说明：收入统计排除退款和取消状态的收入记录；所有人民币金额字段均为元字符串，不返回 *_cent。服务端使用 Redis 短缓存，缓存 key 形如 tieup:artist_dashboard:income:{artist_id}:all 或 tieup:artist_dashboard:income:{artist_id}:{start_date}:{end_date}，有效期 30 秒。

8.4.4 榜单统计

GET /tieup/api/v1/artist/dashboard/rankings

请求参数：

字段 类型 必填 说明
type string 是 榜单类型：loyal_fans=铁粉榜，consumption=消费榜
page integer 否 页码，默认 1
page_size integer 否 兼容参数，服务端固定按 10 条返回

响应字段：

字段 类型 说明
type string 榜单类型
items array 榜单列表
items[].rank integer 排名，从 1 开始
items[].fan_user_id integer 粉丝用户 ID
items[].nickname string 粉丝昵称
items[].avatar string 粉丝头像 URL
items[].value integer/number 榜单值；铁粉榜为陪伴天数，消费榜为收入贡献金额
total integer 总条数
page integer 当前页
page_size integer 每页数量，固定 10

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "type": "loyal_fans",
    "items": [
      {
        "rank": 1,
        "fan_user_id": 10001,
        "nickname": "Tieup用户",
        "avatar": "https://cdn.example.com/avatar.png",
        "value": 365
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}

说明：type 非 loyal_fans 或 consumption 时返回业务错误；榜单接口独立分页查询，避免总览接口一次性加载重榜单。服务端使用 Redis 短缓存，缓存 key 形如 tieup:artist_dashboard:rankings:{artist_id}:{type}:{page}:10，有效期 60 秒。