zhibo/模块文档/14-在线状态模块.md

在线状态模块

模块概述

在线状态模块负责管理和查询用户的在线状态，包括单个用户在线状态、批量查询、房间在线人数统计等功能。

相关文件

• RoomDetailActivity.java - 直播间详情（显示在线人数）
• ConversationsAdapter.java - 会话列表（显示好友在线状态）
• FriendsAdapter.java - 好友列表（显示在线状态）

---

接口列表

1. 查询用户在线状态

接口地址: GET /api/front/online/status/{userId}

路径参数:

userId: integer    // 用户ID

请求参数: 无

返回数据:

{
  "code": 200,
  "msg": "success",
  "data": {
    "userId": "integer",       // 用户ID
    "isOnline": "boolean",     // 是否在线
    "lastOnlineTime": "long",  // 最后在线时间戳
    "status": "string"         // 状态: online/offline/busy
  }
}

---

2. 批量查询用户在线状态

接口地址: POST /api/front/online/status/batch

请求参数:

[1, 2, 3, 4, 5]    // 用户ID数组

返回数据:

{
  "code": 200,
  "msg": "success",
  "data": {
    "1": {
      "userId": 1,
      "isOnline": true,
      "lastOnlineTime": 1703001234567,
      "status": "online"
    },
    "2": {
      "userId": 2,
      "isOnline": false,
      "lastOnlineTime": 1703000000000,
      "status": "offline"
    }
  }
}

---

3. 获取房间在线人数

接口地址: GET /api/front/online/room/{roomId}/count

路径参数:

roomId: string    // 房间ID

请求参数: 无

返回数据:

{
  "code": 200,
  "msg": "success",
  "data": {
    "roomId": "string",      // 房间ID
    "onlineCount": "integer" // 在线人数
  }
}

---

4. 获取房间在线用户列表

接口地址: GET /api/front/online/room/{roomId}/users

路径参数:

roomId: string    // 房间ID

请求参数: 无

返回数据:

{
  "code": 200,
  "msg": "success",
  "data": {
    "roomId": "string",
    "onlineCount": "integer",
    "users": [
      {
        "userId": "integer",
        "nickname": "string",
        "avatar": "string",
        "joinTime": "long"    // 进入房间时间
      }
    ]
  }
}

---

5. 获取连接统计信息

接口地址: GET /api/front/online/stats

请求参数: 无

返回数据:

{
  "code": 200,
  "msg": "success",
  "data": {
    "totalOnlineUsers": "integer",     // 总在线用户数
    "totalConnections": "integer",     // 总连接数
    "totalRooms": "integer",           // 总房间数
    "activeRooms": "integer",          // 活跃房间数
    "serverTime": "long"               // 服务器时间戳
  }
}

---

功能说明

在线状态类型

状态	值	说明
在线	online	用户当前在线
离线	offline	用户已离线
忙碌	busy	用户在线但忙碌

状态更新机制

• 用户登录时自动设置为在线
• 用户退出登录时设置为离线
• WebSocket连接断开时设置为离线
• 心跳检测维持在线状态

房间在线统计

• 实时统计房间内的在线用户数
• 通过WebSocket实时推送在线人数变化
• 支持查询房间内的在线用户列表

---

使用场景

1. 好友列表显示在线状态

// 获取好友列表后，批量查询在线状态
List<Integer> friendIds = new ArrayList<>();
for (Friend friend : friends) {
    friendIds.add(friend.getUserId());
}

ApiService apiService = ApiClient.getService(context);
Call<ApiResponse<Map<String, Object>>> call = 
    apiService.checkUsersOnline(friendIds);

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) {
            Map<String, Object> statusMap = response.body().getData();
            // 更新好友列表的在线状态
        }
    }

    @Override
    public void onFailure(Call<ApiResponse<Map<String, Object>>> call, Throwable t) {
        // 处理错误
    }
});

2. 直播间显示在线人数

// 进入直播间后获取在线人数
ApiService apiService = ApiClient.getService(context);
Call<ApiResponse<Map<String, Object>>> call = 
    apiService.getRoomOnlineCount(roomId);

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) {
            Map<String, Object> data = response.body().getData();
            int onlineCount = (int) data.get("onlineCount");
            // 更新UI显示在线人数
        }
    }

    @Override
    public void onFailure(Call<ApiResponse<Map<String, Object>>> call, Throwable t) {
        // 处理错误
    }
});

// 同时通过WebSocket监听在线人数变化
// 参考 WebSocket通信模块文档

3. 会话列表显示对方在线状态

// 获取会话列表后，查询对方在线状态
for (Conversation conversation : conversations) {
    int otherUserId = conversation.getOtherUserId();
    
    ApiService apiService = ApiClient.getService(context);
    Call<ApiResponse<Map<String, Object>>> call = 
        apiService.checkUserOnline(otherUserId);
    
    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) {
                Map<String, Object> data = response.body().getData();
                boolean isOnline = (boolean) data.get("isOnline");
                // 更新会话列表的在线状态
            }
        }

        @Override
        public void onFailure(Call<ApiResponse<Map<String, Object>>> call, Throwable t) {
            // 处理错误
        }
    });
}

---

WebSocket实时推送

在线状态变化可以通过WebSocket实时推送，详见 WebSocket通信模块。

推送消息格式:

{
  "type": "online_status",
  "userId": 123,
  "isOnline": true,
  "status": "online"
}

---

注意事项

1. 批量查询建议一次不超过100个用户ID
2. 在线状态有缓存，可能存在几秒延迟
3. 建议配合WebSocket实现实时状态更新
4. 房间在线人数通过WebSocket实时推送更准确
5. 离线时间超过5分钟的用户会显示最后在线时间
6. 频繁查询在线状态可能影响性能，建议合理控制查询频率