open-im-server-deploy/docs/statistics-api.md

# 统计接口文档

## 接口列表

### 1. POST /statistics/user/register
**用户注册统计**

**请求参数** (`UserRegisterCountReq`):
```json
{
  "start": 0,  // int64 - 开始时间（毫秒时间戳）
  "end": 0     // int64 - 结束时间（毫秒时间戳）
}
```

**响应参数** (`UserRegisterCountResp`):
```json
{
  "total": 0,   // int64 - 总注册用户数
  "before": 0,  // int64 - 开始时间之前的注册用户数
  "count": []   // []map[string]int64 - 时间段内每日注册用户数统计
}
```

---

### 2. POST /statistics/user/active
**活跃用户统计**

**请求参数** (`GetActiveUserReq`):
```json
{
  "start": 0,        // int64 - 开始时间（毫秒时间戳）
  "end": 0,          // int64 - 结束时间（毫秒时间戳）
  "group": "",       // string - 群ID（选填）
  "ase": "",         // string - 排序方式（选填）
  "pagination": {    // Pagination - 分页参数
    "pageNumber": 1, // int32 - 页码，从1开始
    "showNumber": 10 // int32 - 每页数量
  }
}
```

**响应参数** (`GetActiveUserResp`):
```json
{
  "msgCount": 0,   // int64 - 消息总数
  "userCount": 0,  // int64 - 活跃用户总数
  "dateCount": [], // []map[string]int64 - 每日活跃用户数统计
  "users": [       // []ActiveUser - 活跃用户列表
    {
      "user": {    // UserInfo - 用户信息
        "userID": "",
        "nickname": "",
        "faceURL": "",
        // ... 其他用户字段
      },
      "count": 0   // int64 - 该用户发送的消息数
    }
  ]
}
```

---

### 3. POST /statistics/group/create
**群创建统计**

**请求参数** (`GroupCreateCountReq`):
```json
{
  "start": 0,  // int64 - 开始时间（毫秒时间戳）
  "end": 0     // int64 - 结束时间（毫秒时间戳）
}
```

**响应参数** (`GroupCreateCountResp`):
```json
{
  "total": 0,   // int64 - 总创建群数
  "before": 0,  // int64 - 开始时间之前创建的群数
  "count": []   // []map[string]int64 - 时间段内每日创建群数统计
}
```

---

### 4. POST /statistics/group/active
**活跃群统计**

**请求参数** (`GetActiveGroupReq`):
```json
{
  "start": 0,        // int64 - 开始时间（毫秒时间戳）
  "end": 0,          // int64 - 结束时间（毫秒时间戳）
  "ase": "",         // string - 排序方式（选填）
  "pagination": {    // Pagination - 分页参数
    "pageNumber": 1, // int32 - 页码，从1开始
    "showNumber": 10 // int32 - 每页数量
  }
}
```

**响应参数** (`GetActiveGroupResp`):
```json
{
  "msgCount": 0,    // int64 - 消息总数
  "groupCount": 0,  // int64 - 活跃群总数
  "dateCount": [],  // []map[string]int64 - 每日活跃群数统计
  "groups": [       // []ActiveGroup - 活跃群列表
    {
      "group": {    // GroupInfo - 群信息
        "groupID": "",
        "groupName": "",
        "faceURL": "",
        // ... 其他群字段
      },
      "count": 0    // int64 - 该群发送的消息数
    }
  ]
}
```

---

### 5. POST /statistics/online_user_count
**在线人数统计**

**请求参数**: 无

**响应参数** (`OnlineUserCountResp`):
```json
{
  "onlineCount": 0  // int64 - 当前在线用户数
}
```

---

### 6. POST /statistics/online_user_count_trend
**在线人数走势统计**

**请求参数** (`OnlineUserCountTrendReq`):
```json
{
  "startTime": 0,         // int64 - 统计开始时间（毫秒时间戳），为空时默认最近24小时
  "endTime": 0,           // int64 - 统计结束时间（毫秒时间戳），为空时默认当前时间
  "intervalMinutes": 15   // int32 - 统计间隔（分钟），仅支持15/30/60，必填
}
```

**响应参数** (`OnlineUserCountTrendResp`):
```json
{
  "intervalMinutes": 15,  // int32 - 统计间隔（分钟）
  "points": [             // []OnlineUserCountTrendItem - 走势数据点
    {
      "timestamp": 0,     // int64 - 区间起始时间（毫秒时间戳）
      "onlineCount": 0    // int64 - 区间内平均在线人数
    }
  ]
}
```

---

### 7. POST /statistics/user_send_msg_count
**用户发送消息总数统计**

**请求参数** (`UserSendMsgCountReq`): 无

**响应参数** (`UserSendMsgCountResp`):
```json
{
  "count24h": 0,  // int64 - 最近24小时发送消息总数
  "count7d": 0,   // int64 - 最近7天发送消息总数
  "count30d": 0   // int64 - 最近30天发送消息总数
}
```

---

### 8. POST /statistics/user_send_msg_count_trend
**用户发送消息走势统计**

**请求参数** (`UserSendMsgCountTrendReq`):
```json
{
  "userID": "",           // string - 发送者用户ID，必填
  "chatType": 1,          // int32 - 聊天类型：1-单聊，2-群聊，必填
  "startTime": 0,         // int64 - 统计开始时间（毫秒时间戳），为空时默认最近24小时
  "endTime": 0,           // int64 - 统计结束时间（毫秒时间戳），为空时默认当前时间
  "intervalMinutes": 15   // int32 - 统计间隔（分钟），仅支持15/30/60，必填
}
```

**响应参数** (`UserSendMsgCountTrendResp`):
```json
{
  "userID": "",           // string - 发送者用户ID
  "chatType": 1,          // int32 - 聊天类型：1-单聊，2-群聊
  "intervalMinutes": 15,  // int32 - 统计间隔（分钟）
  "points": [             // []UserSendMsgCountTrendItem - 走势数据点
    {
      "timestamp": 0,     // int64 - 区间起始时间（毫秒时间戳）
      "count": 0          // int64 - 区间内发送消息数
    }
  ]
}
```

---

### 9. POST /statistics/user_send_msg_query
**用户发送消息查询**

**请求参数** (`UserSendMsgQueryReq`):
```json
{
  "userID": "",      // string - 用户ID（选填）
  "startTime": 0,    // int64 - 开始时间（毫秒时间戳，选填）
  "endTime": 0,      // int64 - 结束时间（毫秒时间戳，选填）
  "content": "",     // string - 内容搜索关键词（选填）
  "pageNumber": 1,   // int32 - 页码，从1开始，默认1
  "showNumber": 50   // int32 - 每页条数，默认50，最大200
}
```

**响应参数** (`UserSendMsgQueryResp`):
```json
{
  "count": 0,        // int64 - 总记录数
  "pageNumber": 1,   // int32 - 当前页码
  "showNumber": 50,  // int32 - 每页条数
  "records": [       // []UserSendMsgQueryRecord - 消息记录列表
    {
      "msgID": "",           // string - 消息ID（服务端消息ID）
      "sendID": "",          // string - 发送者ID
      "senderName": "",      // string - 发送者昵称或名称
      "recvID": "",          // string - 接收者ID（群聊为群ID）
      "recvName": "",        // string - 接收者昵称或名称（群聊为群名称）
      "contentType": 0,      // int32 - 消息类型编号
      "contentTypeName": "", // string - 消息类型名称（如：文本消息、图片消息等）
      "sessionType": 0,      // int32 - 聊天类型编号
      "chatTypeName": "",    // string - 聊天类型名称（如：单聊、群聊、通知）
      "content": "",         // string - 消息内容
      "sendTime": 0          // int64 - 消息发送时间（毫秒时间戳）
    }
  ]
}
```

---

## 注意事项

1. **权限要求**: 所有统计接口都需要管理员权限（`authverify.CheckAdmin`）
2. **时间格式**: 所有时间字段均为毫秒时间戳（int64）
3. **统计间隔**: 走势统计接口的 `intervalMinutes` 仅支持 15、30、60 分钟
4. **分页参数**: 
   - `pageNumber` 从 1 开始
   - `showNumber` 默认值不同接口可能不同，最大值为 200
5. **消息类型**: 
   - 文本消息、图片消息、语音消息、视频消息、文件消息、艾特消息、合并消息、名片消息、位置消息、自定义消息、撤回消息、Markdown消息等
6. **聊天类型**: 
   - 单聊（1）、群聊（2）、通知