关闭 2FA

1. 接口定位

• 接口名称: 关闭 2FA
• 所属域: admin/account
• 业务目标: 校验当前验证码（TOTP 或 backup code）后关闭当前管理员的 2FA

2. 请求定义

• Method: POST
• Path: /adminx/account/2fa/disable
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等（需要有效验证码，关闭后记录会删除）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
code	是	string	当前 TOTP 动态码或 backup code

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
enabled	bool	固定返回 false

5. 业务规则

• 关闭操作仅作用于当前 token 对应管理员。
• code 支持：
  • TOTP 动态码；
  • backup code（命中后按一次性消费处理）。
• 校验成功后，服务会：
  • 删除 admin_two_factor 记录；
  • 将管理员表 two_factor_enabled 更新为 false。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	校验码错误	invalid totp code
-	未找到 2FA 记录	由 MongoDB 查询链路返回
-	删除 2FA 记录失败	由 MongoDB 存储链路返回

7. 示例

fetch 请求示例

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

成功响应示例

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

8. 时序流程

1. 中间件校验管理员 token。
2. 查询当前管理员 2FA 记录。
3. 使用 code 校验 TOTP 或 backup code。
4. 校验成功后删除 2FA 记录并设置 two_factor_enabled=false。
5. 返回关闭成功。

9. 变更记录

• 2026-04-07: 首版发布，新增管理员 2FA 关闭接口文档。