查询管理员列表

1. 接口定位

• 接口名称: 查询管理员列表
• 所属域: admin/account
• 业务目标: 分页查询管理员账号列表

2. 请求定义

• Method: POST
• Path: /account/search
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 额外权限: 只有高级管理员（level = 100）可以调用
• 幂等性: 幂等

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
pagination	是	object	分页参数

pagination 字段

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

字段约束

• pagination 不能为空。
• pageNumber 不能为空且应大于 0。
• showNumber 不能为空且应大于 0。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	总记录数
adminAccounts	array<object>	当前页管理员列表

adminAccounts 元素字段

字段	类型	说明
account	string	管理员账号
faceURL	string	管理员头像
nickname	string	管理员昵称
userID	string	管理员用户 ID
level	int32	管理员等级
createTime	int64	创建时间，Unix 秒时间戳

5. 业务规则

• 真正的高级管理员权限校验在 RPC 层执行。
• 分页请求会先经过协议检查；pageNumber/showNumber 为 0 时直接失败。
• 响应列表中的 createTime 来自 time.Unix()，单位是秒；与 /account/info 返回的毫秒时间戳不同，这是当前实现的真实行为。
• 列表项不会返回密码字段。

6. 错误码与失败场景

错误码	场景	典型报错
1001	pagination 为空	pagination is empty
1001	pageNumber 为空或非法	pageNumber is empty 或 pageNumber is invalid
1001	showNumber 为空或非法	showNumber is empty 或 showNumber is invalid
-	调用方不是高级管理员	NoPermission
-	查询管理员列表失败	由数据库层返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/account/search", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440108",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "adminAccounts": [
      {
        "account": "root_admin",
        "faceURL": "https://example.com/root.png",
        "nickname": "System Admin",
        "userID": "1000000001",
        "level": 100,
        "createTime": 1774905600
      },
      {
        "account": "ops_admin",
        "faceURL": "https://example.com/ops.png",
        "nickname": "Ops Admin",
        "userID": "1000000011",
        "level": 80,
        "createTime": 1774909200
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "showNumber is empty"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 校验 pagination.pageNumber/showNumber。
3. RPC 层校验调用方是否为高级管理员。
4. 查询管理员总数和分页数据。
5. 将数据库记录转换为响应结构并返回。

9. 变更记录

• 2026-03-31: 首版发布，基于 SearchAdminAccountReq/SearchAdminAccountResp 协议与管理员分页查询逻辑补全文档。