查詢未加入頻道分組的觀眾列表介面

更新時間：2026-04-14 18:48:58

該文件對應 live-background-aggregate 的 ViewerRecordController.listUnrelationChannelViewer。
這是直播後台登入態介面，userId 由系統根據當前登入帳號自動注入，無需前端傳入。
用戶端介面前綴：/live-bg/v3/user/viewer-record
教師端介面前綴：/live-bg/v3/teacher/viewer-record

1. 查詢未加入頻道分組的觀眾列表

介面位址
- GET /live-bg/v3/user/viewer-record/list-unrelation-channel-viewer
- GET /live-bg/v3/teacher/viewer-record/list-unrelation-channel-viewer
請求參數

參數名	必填	類型	說明
channelId	是	Integer	頻道ID
name	否	String	姓名
mobile	否	String	手機號碼
externalViewerId	否	String	外部觀眾ID
wxOpenId	否	String	微信 OpenId
wxUnionId	否	String	微信 UnionId
nickname	否	String	用戶暱稱
wxNickName	否	String	微信暱稱
source	否	String	用戶來源，支援 `WX`、`IMPORT`、`MOBILE`
email	否	String	電子郵件
area	否	String	地區
lastCollectMobile	否	String	最近採集手機號碼
searchKeyword	否	String	關鍵字，匹配 `nickname` 和 `wxNickName`
viewerId	否	String	觀眾ID
status	否	String	用戶狀態
startCreateTime	否	String	註冊開始時間，格式：`yyyy-MM-dd HH:mm:ss`
endCreateTime	否	String	註冊結束時間，格式：`yyyy-MM-dd HH:mm:ss`
labelIds	否	Array	標籤ID集合，最多 10 個
pageNumber	否	Integer	頁碼，預設 1，最大 1000
pageSize	否	Integer	每頁大小，預設 10，最大 1000

處理說明
- 該介面基於用戶體系觀眾列表查詢
- 會額外按 channelId 過濾掉已經存在於 channel_viewer_list 表中的觀眾
- 適用於給頻道分組挑選「尚未加入頻道用戶列表」的候選觀眾
響應 data 欄位

參數名	類型	說明
pageNumber	Integer	目前頁碼
pageSize	Integer	每頁大小
totalPages	Long	總頁數
totalItems	Long	總記錄數
contents	Array	觀眾列表

contents 陣列元素說明：

參數名	類型	說明
viewerUnionId	String	觀眾唯一ID
nickname	String	用戶暱稱
wxNickName	String	微信暱稱
mobile	String	手機號碼
externalViewerId	String	外部觀眾ID
wxOpenId	String	微信 OpenId
wxUnionId	String	微信 UnionId
source	String	用戶來源
name	String	姓名
lastCollectMobile	String	最近採集手機號碼
email	String	電子郵件
area	String	地區
latestAccessIp	String	最近訪問 IP
device	String	設備資訊
watchDuration	Integer	累計觀看時長（秒）
watchChannelCount	Integer	觀看頻道數
labelIds	Array	標籤ID列表
labelNames	Array	標籤名稱列表
status	String	用戶狀態
createTime	String	註冊時間

請求範例

GET /live-bg/v3/user/viewer-record/list-unrelation-channel-viewer?channelId=123456&searchKeyword=张三&pageNumber=1&pageSize=20

響應範例

{
  "code": 200,
  "status": "success",
  "success": true,
  "requestId": "e9d53b60-2f4c-4f72-8e18-0f0fe8194d52",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalItems": 2,
    "contents": [
      {
        "viewerUnionId": "2_x4r3er86b6h539o4clna3ss39xg3c169",
        "nickname": "张三",
        "wxNickName": "张三微信",
        "mobile": "13800000001",
        "source": "IMPORT",
        "name": "张三",
        "watchDuration": 300,
        "watchChannelCount": 2,
        "createTime": "2026-04-14T10:00:00"
      },
      {
        "viewerUnionId": "2_y5t681288v0316n8z932el5d28w1ka2n",
        "nickname": "李四",
        "mobile": "13800000002",
        "source": "WX",
        "watchDuration": 120,
        "watchChannelCount": 1,
        "createTime": "2026-04-13T18:30:00"
      }
    ]
  }
}

通用響應說明

參數名	類型	說明
code	Integer	狀態碼
status	String	響應狀態，成功為 `success`
success	Boolean	是否成功
requestId	String	請求ID
data	Object	業務返回資料
error	Object	失敗時的錯誤資訊