zhibo/模块文档/16-观看历史模块.md

观看历史模块

模块概述

观看历史模块负责记录用户观看直播间的历史记录，用于推荐算法、用户行为分析等功能。

相关文件

• RoomDetailActivity.java - 直播间详情（记录观看历史）
• WatchHistoryActivity.java - 观看历史列表界面

---

接口列表

1. 记录观看历史

接口地址: POST /api/front/watch/history

请求参数:

{
  "roomId": "string",      // 直播间ID（必填）
  "watchTime": "long"      // 观看时间戳（必填）
}

返回数据:

{
  "code": 200,
  "msg": "记录成功",
  "data": {
    "historyId": "long",     // 历史记录ID
    "roomId": "string",      // 直播间ID
    "userId": "integer",     // 用户ID
    "watchTime": "long",     // 观看时间
    "duration": "integer"    // 观看时长（秒）
  }
}

---

功能说明

记录时机

• 用户进入直播间时自动记录
• 记录用户进入时间
• 用户退出时更新观看时长

数据用途

• 个性化推荐：根据观看历史推荐相似直播间
• 用户画像：分析用户兴趣偏好
• 数据统计：统计直播间热度和观看数据
• 历史记录：用户可查看自己的观看历史

隐私保护

• 仅记录已登录用户的观看历史
• 用户可以清除自己的观看历史
• 观看历史仅用户本人可见

---

使用场景

1. 进入直播间时记录

// 在 RoomDetailActivity 的 onCreate 中调用
private void recordWatchHistory() {
    if (!AuthHelper.isLoggedIn(this)) {
        return; // 未登录用户不记录
    }
    
    if (TextUtils.isEmpty(roomId)) {
        return;
    }
    
    ApiService apiService = ApiClient.getService(getApplicationContext());
    
    Map<String, Object> body = new HashMap<>();
    body.put("roomId", roomId);
    body.put("watchTime", System.currentTimeMillis());
    
    Call<ApiResponse<Map<String, Object>>> call = 
        apiService.recordWatchHistory(body);
    
    call.enqueue(new Callback<ApiResponse<Map<String, Object>>>() {
        @Override
        public void onResponse(Call<ApiResponse<Map<String, Object>>> call, 
                             Response<ApiResponse<Map<String, Object>>> response) {
            if (response.isSuccessful() && response.body() != null) {
                Log.d("RoomDetail", "观看历史记录成功");
            }
        }

        @Override
        public void onFailure(Call<ApiResponse<Map<String, Object>>> call, Throwable t) {
            Log.e("RoomDetail", "观看历史记录失败: " + t.getMessage());
        }
    });
}

2. 退出直播间时更新时长

// 在 onDestroy 或 onStop 中调用
private void updateWatchDuration() {
    if (historyId == null) {
        return;
    }
    
    long duration = (System.currentTimeMillis() - enterTime) / 1000; // 秒
    
    // 调用更新接口（如果后端提供）
    // 或者在记录时就包含时长计算
}

---

扩展功能（建议）

虽然当前接口只有记录功能，但建议后端提供以下扩展接口：

获取观看历史列表

GET /api/front/watch/history
参数: page, pageSize
返回: 用户的观看历史列表

清除观看历史

DELETE /api/front/watch/history/{historyId}
或
DELETE /api/front/watch/history/clear

获取推荐直播间

GET /api/front/watch/recommendations
基于观看历史推荐相似直播间

---

数据统计

观看历史数据可用于以下统计：

用户维度

• 观看总时长
• 观看直播间数量
• 最常观看的分类
• 观看时间分布

直播间维度

• 总观看人数
• 平均观看时长
• 回访率
• 观看高峰时段

---

注意事项

1. 仅记录已登录用户的观看历史
2. 未登录用户不会记录观看历史
3. 记录失败不影响用户正常观看
4. 建议异步记录，不阻塞主流程
5. 观看时长计算应考虑用户切换后台的情况
6. 同一用户多次进入同一直播间会产生多条记录
7. 建议定期清理过期的历史记录（如保留最近3个月）