管理员用户管理页面对接文档

本文档用于前端设计与接入管理员“用户管理”页面。

1. 适用范围

仅管理员可访问
所有接口均要求已登录
接口前缀统一为 /api/console/admin/users

普通用户调用这些接口时，后端返回：

403 Forbidden

2. 用户状态模型

当前支持两种状态：

active：正常
banned：已封禁

封禁效果

用户被封禁后：

无法继续登录
已有 session 会被后端立即失效
控制台后续请求会失败

解封效果

用户状态改回 active 后：

可重新使用原密码登录
不会自动恢复旧 session，需要重新登录

3. 页面建议结构

建议拆成三部分：

用户列表页
- 展示基本信息、状态、最近登录 IP、最近登录时间
用户详情抽屉 / 详情页
- 展示封禁信息、密码更新时间、登录历史
操作区
- 封禁 / 解封
- 重置密码
- 查看登录历史

4. 接口清单

4.1 获取用户列表

GET /api/console/admin/users

响应

{
  "users": [
    {
      "id": "usr_xxx",
      "email": "user@example.com",
      "display_name": "测试用户",
      "role": "user",
      "status": "active",
      "avatar_url": "",
      "banned_at": null,
      "banned_reason": "",
      "banned_by_user_id": "",
      "password_updated_at": "2026-03-30T16:00:00Z",
      "last_login_at": "2026-03-30T16:10:00Z",
      "last_login_ip": "203.0.113.10",
      "created_at": "2026-03-30T15:00:00Z",
      "updated_at": "2026-03-30T16:00:00Z"
    }
  ]
}

字段说明

role：admin / user
status：active / banned
last_login_at：最近一次成功登录时间
last_login_ip：最近一次成功登录 IP
password_updated_at：最近一次密码更新时间
banned_at / banned_reason / banned_by_user_id：仅封禁状态下有值

前端用途

用户列表表格
状态徽标
最近登录信息列

4.2 获取单个用户详情

GET /api/console/admin/users/{userID}

响应

{
  "user": {
    "id": "usr_xxx",
    "email": "user@example.com",
    "display_name": "测试用户",
    "role": "user",
    "status": "banned",
    "avatar_url": "",
    "banned_at": "2026-03-30T16:20:00Z",
    "banned_reason": "多次异常操作",
    "banned_by_user_id": "usr_admin",
    "password_updated_at": "2026-03-30T16:00:00Z",
    "last_login_at": "2026-03-30T16:10:00Z",
    "last_login_ip": "203.0.113.10",
    "created_at": "2026-03-30T15:00:00Z",
    "updated_at": "2026-03-30T16:20:00Z"
  }
}

前端用途

详情抽屉
操作前二次确认弹窗中的上下文展示

4.3 封禁 / 解封用户

PUT /api/console/admin/users/{userID}/status

请求体

封禁

{
  "status": "banned",
  "reason": "多次异常操作"
}

解封

{
  "status": "active"
}

响应

{
  "user": {
    "id": "usr_xxx",
    "email": "user@example.com",
    "display_name": "测试用户",
    "role": "user",
    "status": "banned",
    "banned_at": "2026-03-30T16:20:00Z",
    "banned_reason": "多次异常操作",
    "banned_by_user_id": "usr_admin",
    "created_at": "2026-03-30T15:00:00Z",
    "updated_at": "2026-03-30T16:20:00Z"
  }
}

交互建议

封禁时要求填写原因
解封时可直接确认
成功后刷新列表或局部更新当前行

特殊限制

以下情况后端会拒绝：

封禁当前管理员自己
封禁最后一个仍处于 active 的管理员

常见错误：

400：参数不合法 / 不允许封禁
403：非管理员
404：用户不存在

4.4 重置用户密码

POST /api/console/admin/users/{userID}/reset-password

请求体

无

响应

{
  "user_id": "usr_xxx",
  "temporary_password": "Kb-abc123def456-A1",
  "password_updated_at": "2026-03-30T16:30:00Z"
}

语义说明

后端会直接生成一个临时密码并返回
返回值只会在这次响应中出现一次
用户旧密码会立即失效
用户现有 session 会被后端立即失效，需要重新登录

前端交互建议

成功后弹窗展示临时密码
提供“复制密码”按钮
弹窗内明确提示“关闭后无法再次查看，请立即复制”

特殊限制

以下情况后端会拒绝：

试图在该接口中重置当前管理员自己的密码

4.5 获取用户历史登录 IP

GET /api/console/admin/users/{userID}/login-history?limit=50

响应

{
  "events": [
    {
      "id": "login_xxx",
      "auth_method": "password",
      "ip_address": "203.0.113.10",
      "user_agent": "Mozilla/5.0",
      "occurred_at": "2026-03-30T16:10:00Z"
    }
  ]
}

字段说明

auth_method：当前主要为 password
ip_address：成功登录来源 IP
user_agent：登录时请求头中的 User-Agent
occurred_at：登录发生时间

IP 获取规则

后端优先按以下顺序取值：

X-Forwarded-For 的第一个 IP
X-Real-IP
TCP 连接的 RemoteAddr

前端用途

详情页“登录历史”表格
风险提示

5. 推荐前端 TypeScript 类型

export type AdminUserStatus = "active" | "banned"
export type AdminUserRole = "admin" | "user"

export interface AdminManagedUser {
  id: string
  email: string
  display_name: string
  role: AdminUserRole
  status: AdminUserStatus
  avatar_url?: string
  banned_at?: string | null
  banned_reason?: string
  banned_by_user_id?: string
  password_updated_at?: string | null
  last_login_at?: string | null
  last_login_ip?: string
  created_at: string
  updated_at: string
}

export interface AdminUserLoginHistoryEvent {
  id: string
  auth_method: string
  ip_address?: string
  user_agent?: string
  occurred_at: string
}

6. 推荐页面交互

列表页列建议

用户名
邮箱
角色
状态
最近登录时间
最近登录 IP
创建时间
操作

操作按钮建议

查看详情
封禁
解封
重置密码
查看登录历史

详情页模块建议

基本信息
账号状态
封禁信息
密码信息
登录历史

7. 错误码约定

401

未登录或会话失效。

403

当前用户不是管理员。

404

目标用户不存在。

400

常见情况：

status 非法
封禁当前管理员自己
封禁最后一个有效管理员
试图通过该接口重置当前管理员自己的密码

8. 当前后端已实现能力

已实现：

管理员获取用户列表
管理员获取用户详情
管理员封禁用户
管理员解封用户
管理员重置用户密码
管理员查看用户历史登录 IP
封禁后立即使已有 session 失效
重置密码后立即使已有 session 失效

未实现：

用户搜索 / 分页
登录地理位置解析
登录失败历史
批量封禁 / 批量解封