按不活跃优先查询群成员（adminx）

1. 接口定位

• 接口名称: 按不活跃优先查询群成员
• 所属域: admin/group
• 业务目标: 查询指定群成员，并按最后活跃时间升序排序（越不活跃越靠前）

2. 请求定义

• Method: POST
• Path: /adminx/group/member/list/inactive
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

字段	必填	类型	说明
groupID	是	string	群 ID
pagination	是	RequestPagination	分页参数
keyword	否	string	关键字；支持按 userID、nickname 过滤

RequestPagination 字段如下：

字段	必填	类型	说明
pageNumber	是	int32	页码，从 1 开始
showNumber	是	int32	每页条数

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
total	uint32	群成员总数
members	array<GroupMemberInactiveInfo>	当前页成员列表

GroupMemberInactiveInfo 字段：

字段	类型	说明
userID	string	用户 ID
lastActiveTime	int64	最后活跃时间（Unix 毫秒时间戳）
source	string	活跃时间来源
member	GroupMemberFullInfo	群成员详情（OpenIM 返回）

member（GroupMemberFullInfo）字段：

字段	类型	说明
groupID	string	群 ID
userID	string	用户 ID
roleLevel	int32	群成员角色等级
joinTime	int64	入群时间（毫秒）
nickname	string	群内昵称
faceURL	string	头像 URL
appMangerLevel	int32	管理等级（大于 0）
joinSource	int32	入群来源
operatorUserID	string	操作人用户 ID
ex	string	扩展字段
muteEndTime	int64	禁言结束时间（毫秒）
inviterUserID	string	邀请人用户 ID

source 可选值：

• LAST_ACTIVE_AT: 命中用户级精确活跃时间键。
• DAU_DAY: 未命中精确时间时，回退到 DAU 最后活跃日期 00:00。
• LAST_LOGIN: 未命中前两者时，回退到最后登录时间。
• NONE: 无可用活跃记录，lastActiveTime=0。

5. 业务规则

• 排序规则：lastActiveTime 升序（不活跃在前）。
• 同活跃时间使用 userID 升序作为稳定次序。
• keyword 非空时，先在该群成员范围内按 userID、nickname 过滤，再按不活跃排序。
• 活跃时间获取顺序：优先使用用户表持久化 last_active_time；若缺失再按 LAST_ACTIVE_AT -> DAU_DAY -> LAST_LOGIN -> NONE 回退。
• DAU 回退窗口为最近 45 天。
• DAU 回退命中值是日期起点时间（Asia/Shanghai 当日 00:00），不代表当天精确时分秒。

6. 错误码与失败场景

错误码	场景	典型报错
1001	groupID 为空	groupID is empty
1001	pagination 为空	pagination is empty
1001	pageNumber/showNumber 非法	pagination invalid
-	鉴权失败	由管理员鉴权链路返回
-	拉取群成员信息失败	由 OpenIM 接口链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/group/member/list/inactive", {
  method: "POST",
  headers: {
    operationID: "group-member-inactive-list-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupID: "group_1001",
    keyword: "tom",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 3,
    "members": [
      {
        "userID": "u3003",
        "lastActiveTime": 0,
        "source": "NONE",
        "member": {
          "groupID": "group_1001",
          "userID": "u3003"
        }
      },
      {
        "userID": "u2002",
        "lastActiveTime": 1735689600000,
        "source": "DAU_DAY",
        "member": {
          "groupID": "group_1001",
          "userID": "u2002"
        }
      },
      {
        "userID": "u1001",
        "lastActiveTime": 1735718400000,
        "source": "LAST_ACTIVE_AT",
        "member": {
          "groupID": "group_1001",
          "userID": "u1001"
        }
      }
    ]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 按 groupID 查询该群全部成员 userID。
3. keyword 非空时，按 userID、nickname 在群成员范围内过滤。
4. 批量读取 LAST_ACTIVE_AT。
5. 对未命中用户按最近 45 天倒序查询 DAU 日桶。
6. 对 DAU 仍未命中的用户回退最后登录时间。
7. 组装活跃时间并排序后分页。
8. 仅为当前页批量查询群成员详情并返回。

9. 变更记录

• 2026-09-01: 首版发布，新增按不活跃优先查询群成员接口。