管理员登录

1. 接口定位

• 接口名称: 管理员登录
• 所属域: admin/account
• 业务目标: 校验管理员账号密码，签发 admin token，并补充默认 OpenIM 管理员的 imUserID/imToken

2. 请求定义

• Method: POST
• Path: /account/login
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 幂等于同一组账号密码，不会修改管理员资料

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	否	string	本接口无需

Body 参数

字段	必填	类型	说明
account	是	string	管理员账号
password	是	string	管理员密码

字段约束

• account 不能为空，否则返回 account is empty。
• password 不能为空，否则返回 password is empty。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
adminAccount	string	管理员账号
adminToken	string	管理后台 token；后续调用需要放入 Header token
nickname	string	管理员昵称
faceURL	string	管理员头像
level	int32	管理员等级；100 为高级管理员，80 为普通管理员
adminUserID	string	管理员业务用户 ID
imUserID	string	默认 OpenIM 管理员 ID，来自服务配置
imToken	string	默认 OpenIM 管理员 token，由 API 层额外补充

5. 业务规则

• API 层先调用 admin RPC 校验管理员账号密码。
• 登录成功后，API 层会额外获取默认 OpenIM 管理员 token，并写入响应中的 imUserID/imToken。
• 本接口不要求管理员已有独立 IM 资料；返回的 imUserID/imToken 来自系统默认 IM 管理员配置，而不是当前登录管理员账号。

6. 错误码与失败场景

错误码	场景	典型报错
1001	account 为空	account is empty
1001	password 为空	password is empty
20002	管理员账号不存在	AccountNotFound
20001	管理员密码错误	PasswordError
-	获取默认 IM 管理员 token 失败	由 OpenIM token 链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/account/login", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440101",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account: "root_admin",
    password: "OpenIM@123",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "account": "root_admin",
  "password": "OpenIM@123"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "adminAccount": "root_admin",
    "adminToken": "eyJhbGciOi...",
    "nickname": "System Admin",
    "faceURL": "https://example.com/admin.png",
    "level": 100,
    "adminUserID": "1000000001",
    "imUserID": "imAdmin",
    "imToken": "openim-admin-token"
  }
}

失败响应示例

{
  "errCode": 20001,
  "errMsg": "PasswordError",
  "errDlt": "PasswordError"
}

8. 时序流程

1. 解析 JSON body，校验 account/password 非空。
2. 在管理员库中按 account 查找账号。
3. 比较明文密码；不一致则返回密码错误。
4. 签发 admin token。
5. API 层获取默认 OpenIM 管理员 token，并与登录结果一起返回。

9. 变更记录

• 2026-03-31: 首版发布，基于 admin API 路由、LoginReq/LoginResp 协议、internal/api/admin/admin.go 与 internal/rpc/admin/admin.go 的真实实现补全文档。