查询 2FA 状态

1. 接口定位

• 接口名称: 查询 2FA 状态
• 所属域: admin/account
• 业务目标: 查询当前管理员账号是否启用 2FA，以及剩余备份码数量

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

该接口无需业务参数，建议传空对象：

{}

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
enabled	bool	是否已启用 2FA
backupCodesRemaining	int	剩余可用备份码数量；未启用 2FA 时固定返回 0

5. 业务规则

• 中间件先校验管理员 token，基于 token 中的管理员 userID 查询 2FA 状态。
• 若管理员未初始化 2FA 记录，返回 enabled=false 且 backupCodesRemaining=0。
• backupCodesRemaining 来自数据库中当前备份码哈希数组长度。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
-	缺少管理员 token	由管理员鉴权链路返回
-	查询 2FA 状态失败	由 MongoDB 存储链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/account/2fa/status", {
  method: "POST",
  headers: {
    operationID: "adminx-2fa-status-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例（已启用 2FA）

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "enabled": true,
    "backupCodesRemaining": 6
  }
}

成功响应示例（未启用 2FA）

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "enabled": false,
    "backupCodesRemaining": 0
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 从上下文读取管理员 userID。
3. 查询 admin_two_factor 集合对应 userID 记录。
4. 若无记录，返回 enabled=false 与 backupCodesRemaining=0。
5. 若存在记录，返回 enabled 及剩余备份码数量。

9. 变更记录

• 2026-04-07: 首版发布，新增管理员 2FA 状态查询接口文档。