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

# 观看历史模块

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

## 相关文件
- `RoomDetailActivity.java` - 直播间详情（记录观看历史）
- `WatchHistoryActivity.java` - 观看历史列表界面

---

## 接口列表

### 1. 记录观看历史
**接口地址**: `POST /api/front/watch/history`

**请求参数**:
```json
{
  "roomId": "string",      // 直播间ID（必填）
  "watchTime": "long"      // 观看时间戳（必填）
}
```

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

---

## 功能说明

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

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

### 隐私保护
- 仅记录已登录用户的观看历史
- 用户可以清除自己的观看历史
- 观看历史仅用户本人可见

---

## 使用场景

### 1. 进入直播间时记录
```java
// 在 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. 退出直播间时更新时长
```java
// 在 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个月）