搜索用户完整信息

1. 接口定位

• 接口名称: 搜索用户完整信息
• 所属域: admin/user（adminx）
• 业务目标: 管理员分页搜索用户完整信息，支持默认稳定排序和可选白名单排序

2. 请求定义

• Method: POST
• Path: /adminx/user/search/full
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效的管理员登录令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
keyword	否	string	搜索关键字，可为空；按用户 ID、账号、昵称、手机号、邮箱做模糊搜索
genders	否	int32	性别过滤：0 全部，1 男，2 女
pagination	是	RequestPagination	分页参数（pageNumber、showNumber）
normal	否	int32	用户范围：0 所有用户，1 普通用户（排除封禁账号）；其他值当前按全部处理
sortField	否	string	排序字段，见下方白名单；不传时使用默认排序
sortOrder	否	int32	排序方向：1 升序，-1 降序；不传或传 0 时使用默认排序

分页参数结构

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

排序白名单

字段示例	实际排序字段	说明
userID / user_id	user_id	用户 ID
account	account	账号
nickname	nickname	昵称
gender	gender	性别
level	level	等级
registerType / register_type	register_type	注册类型
createTime / create_time	create_time	创建时间
changeTime / change_time	change_time	修改时间
birthTime / birth_time	birth_time	生日时间

字段约束

• pagination 不能为空，且 pageNumber/showNumber 必须大于 0。
• keyword 可为空；为空时仍会按照 normal、genders 和排序条件返回分页结果。
• sortField 仅支持白名单字段，非法值会返回参数错误。
• sortOrder 仅支持 1 或 -1，非法值会返回参数错误。
• 默认排序为 create_time desc，并使用 user_id 作为稳定次序字段。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	uint32	查询结果总数
users	array	用户完整信息列表

users 元素字段

字段	类型	说明
base	object	通用用户完整信息（与 openim.chat.common.UserFullInfo 一致）
extra	object	管理员侧扩展字段

users.base 字段

字段	类型	说明
userID	string	用户 ID
password	string	保留字段，始终为空字符串
account	string	账号
phoneNumber	string	手机号
areaCode	string	区号
email	string	邮箱
nickname	string	昵称
faceURL	string	头像 URL
gender	int32	性别
level	int32	等级
birth	int64	生日时间，Unix 毫秒时间戳
allowAddFriend	int32	是否允许加好友
allowBeep	int32	是否允许消息提示音
allowVibration	int32	是否允许震动
globalRecvMsgOpt	int32	全局消息接收设置
registerType	int32	注册类型

users.extra 字段

字段	类型	说明
registerTime	int64	注册时间，Unix 毫秒时间戳
lastLoginTime	int64	最后登录时间，Unix 毫秒时间戳（无登录记录时为 0）

5. 业务规则

• 根据关键字在用户 ID、账号、昵称、手机号、邮箱中进行模糊搜索。
• 支持按单个性别过滤：0 全部，1 男，2 女。
• normal=1 时会排除封禁账号；其他值按全部用户处理。
• 排序默认按 create_time desc 返回，并用 user_id 保证同一排序键下的稳定分页。
• 响应包含 users.extra.registerTime（用户注册时间）和 users.extra.lastLoginTime（最后登录时间；若无登录记录则为 0）。

6. 错误码与失败场景

错误码	场景	典型报错
1001	pagination 为空	pagination is empty
1001	pageNumber 为空或非法	pagination invalid
1001	showNumber 为空或非法	pagination invalid
1001	sortField 非白名单	unsupported sortField
1001	sortOrder 非法	sortOrder must be 1 or -1

7. 示例

fetch 请求示例

fetch("http://localhost:10009/adminx/user/search/full", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440109",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "李",
    genders: 1,
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
    normal: 0,
    sortField: "create_time",
    sortOrder: -1,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "keyword": "李",
  "genders": 1,
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  },
  "normal": 0,
  "sortField": "create_time",
  "sortOrder": -1
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "users": [
      {
        "base": {
          "userID": "user001",
          "password": "",
          "account": "lili",
          "phoneNumber": "13800138000",
          "areaCode": "+86",
          "email": "lili@example.com",
          "nickname": "老李",
          "faceURL": "https://example.com/avatar1.jpg",
          "gender": 1,
          "level": 5,
          "birth": 1704067200000,
          "allowAddFriend": 1,
          "allowBeep": 1,
          "allowVibration": 1,
          "globalRecvMsgOpt": 0,
          "registerType": 1
        },
        "extra": {
          "registerTime": 1704067200000,
          "lastLoginTime": 1735512000000
        }
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "unsupported sortField"
}

8. 时序流程

1. 验证管理员 token。
2. 校验 pagination。
3. 解析并校验排序字段和排序方向。
4. 根据 normal 计算是否排除封禁账号。
5. 按关键字、性别和排序条件查询用户列表。
6. 返回总数和分页后的用户完整信息。

9. 变更记录

• 2026-05-30: 新增 adminx 用户完整信息搜索接口，支持默认稳定排序和白名单排序，作为管理员侧用户列表查询入口。