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

# 在线状态模块

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

## 相关文件
- `RoomDetailActivity.java` - 直播间详情（显示在线人数）
- `ConversationsAdapter.java` - 会话列表（显示好友在线状态）
- `FriendsAdapter.java` - 好友列表（显示在线状态）

---

## 接口列表

### 1. 查询用户在线状态
**接口地址**: `GET /api/front/online/status/{userId}`

**路径参数**:
```
userId: integer    // 用户ID
```

**请求参数**: 无

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

---

### 2. 批量查询用户在线状态
**接口地址**: `POST /api/front/online/status/batch`

**请求参数**:
```json
[1, 2, 3, 4, 5]    // 用户ID数组
```

**返回数据**:
```json
{
  "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
```

**请求参数**: 无

**返回数据**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "roomId": "string",      // 房间ID
    "onlineCount": "integer" // 在线人数
  }
}
```

---

### 4. 获取房间在线用户列表
**接口地址**: `GET /api/front/online/room/{roomId}/users`

**路径参数**:
```
roomId: string    // 房间ID
```

**请求参数**: 无

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

---

### 5. 获取连接统计信息
**接口地址**: `GET /api/front/online/stats`

**请求参数**: 无

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

---

## 功能说明

### 在线状态类型

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

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

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

---

## 使用场景

### 1. 好友列表显示在线状态
```java
// 获取好友列表后，批量查询在线状态
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. 直播间显示在线人数
```java
// 进入直播间后获取在线人数
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. 会话列表显示对方在线状态
```java
// 获取会话列表后，查询对方在线状态
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通信模块](./04-WebSocket通信模块.md)。

**推送消息格式**:
```json
{
  "type": "online_status",
  "userId": 123,
  "isOnline": true,
  "status": "online"
}
```

---

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