按不活跃优先查询好友（adminx）

1. 接口定位

• 接口名称: 按不活跃优先查询好友
• 所属域: admin/friend
• 业务目标: 查询指定用户的好友列表，并按最后活跃时间升序排序（越不活跃越靠前）

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	是	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	好友总数
users	array<InactiveFriendInfo>	当前页好友列表

InactiveFriendInfo 字段：

字段	类型	说明
user	UserFullInfo	用户详情
lastActiveTime	int64	最后活跃时间（Unix 毫秒时间戳）
source	string	活跃时间来源

source 可选值：

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

5. 业务规则

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

6. 错误码与失败场景

错误码	场景	典型报错
1001	userID 为空	userID is empty
1001	pagination 为空	pagination is empty
1001	pageNumber/showNumber 非法	pagination invalid
-	鉴权失败	由管理员鉴权链路返回
-	拉取好友关系或用户信息失败	由 OpenIM 或 Chat 链路返回

7. 示例

fetch 请求示例

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "users": [
      {
        "user": {
          "userID": "u2002",
          "nickname": "Tom"
        },
        "lastActiveTime": 1735689600000,
        "source": "DAU_DAY"
      },
      {
        "user": {
          "userID": "u3003",
          "nickname": "Jerry"
        },
        "lastActiveTime": 1735718400000,
        "source": "LAST_ACTIVE_AT"
      }
    ]
  }
}

8. 时序流程

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

9. 变更记录

• 2026-09-02: 首版发布，新增按不活跃优先查询好友接口。