Skip to content

Admin-System-Management-zh.md

Latest commit

 

History

History
1196 lines (995 loc) · 32.5 KB

Admin-System-Management-zh.md

File metadata and controls

1196 lines (995 loc) · 32.5 KB

系统管理接口文档

语言版本: English | 中文

概述

系统管理接口用于在后台控制台维护系统核心数据，包括用户管理、角色管理、权限管理、菜单管理、操作记录等功能模块。接口统一响应 {code, msg, trace, data} 结构，所有操作必须由具备管理员权限的用户调用。

环境信息

环境 Host HTTP 端口
开发 127.0.0.1 8080
生产 your-domain.com 8080

Base URL：http://{host}:{port}

生效路由前缀：/{apiPrefix}。其中 apiPrefix 表示 system.route_prefix；默认值为 dudu-admin-api。

认证方式

  • Header：Authorization: Bearer <admin-token>
  • Cookie（可选）：admin-token=<token>
  • 所有路由均注册在 /{apiPrefix}/internal/admin/system 路径下，并由 CheckAdminAuth 中间件校验。
  • /{apiPrefix}/internal/admin/system/* 路径统一经过 SaveOperationRecord 中间件，系统管理接口会写入操作日志。

通用响应格式

{
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {}
}

字段命名说明：部分接口直接返回 GORM 模型，字段会同时包含 ID/CreatedAt/UpdatedAt/DeletedAt（驼峰）与业务字段（多数为下划线）。

常见错误码

Code 含义 触发场景
0 成功 请求执行成功
400 参数无效 请求参数格式错误或缺失必填字段
500 服务器错误 服务端内部异常
11002 用户不存在 用户未找到
11007 标识无效 邮箱或手机号格式无效
11013 标识已存在 创建用户时邮箱或手机号重复
11014 标识不能为空 创建用户时邮箱和手机号均为空
11016 角色不存在 角色 ID 不存在
11017 角色名不能为空 创建角色时名称为空
11018 角色名已存在 创建角色时名称重复
11019 权限不存在 权限 ID 不存在
11020 权限名不能为空 创建权限时名称为空
11021 权限名已存在 创建权限时名称重复
11023 菜单名已存在 创建菜单时名称重复
11024 菜单不存在 菜单 ID 不存在
11025 菜单存在子菜单 删除菜单时存在子菜单
11032 密码不能为空 重置或更新密码时为空
11037 用户不可操作 尝试操作受保护的用户
11038 角色不可操作 尝试操作受保护的角色
11049 至少保留一种登录方式 删除 OAuth/Passkey 后不能让账号失去全部登录方式
11052 Passkey 凭证不存在 指定 Passkey 记录不存在

基础接口 (System)

接口总览

功能 方法 路径
系统健康检查 GET /{apiPrefix}/internal/admin/system/ping

1. 系统健康检查

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/ping

  • 说明：用于后台系统可用性检测

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": null
}

用户管理 (User)

接口总览

功能 方法 路径
分页查询用户 GET /{apiPrefix}/internal/admin/system/user/paginate
用户详情 GET /{apiPrefix}/internal/admin/system/user
创建用户 POST /{apiPrefix}/internal/admin/system/user
更新用户 PUT /{apiPrefix}/internal/admin/system/user
删除用户 DELETE /{apiPrefix}/internal/admin/system/user
获取用户角色 GET /{apiPrefix}/internal/admin/system/user/role
更新用户角色 PUT /{apiPrefix}/internal/admin/system/user/role
管理员重置用户密码 PUT /{apiPrefix}/internal/admin/system/user/password/reset
管理员关闭用户 TFA PUT /{apiPrefix}/internal/admin/system/user/tfa/disable
查询用户 Passkey GET /{apiPrefix}/internal/admin/system/user/passkeys
删除单个用户 Passkey DELETE /{apiPrefix}/internal/admin/system/user/passkey
删除用户全部 Passkey DELETE /{apiPrefix}/internal/admin/system/user/passkeys

密码字段口径（与 docs/Admin-Auth-zh.md 一致）： password 建议统一传 md5(明文密码)；服务端将使用 bcrypt 存储该摘要。

1. 分页查询用户

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/user/paginate

  • Query 参数：

    名称 类型 必填 默认值 说明
    user_name string 否 - 用户名模糊查询
    email string 否 - 邮箱模糊查询
    phone string 否 - 手机号模糊查询
    status int8 否 - 用户状态：0 禁用、1 正常
    page int 否 1 页码
    page_size int 否 10 单页数量

  • 示例请求：

    GET http://127.0.0.1:8080/{apiPrefix}/internal/admin/system/user/paginate?page=1&page_size=10
Authorization: Bearer <admin-token>

  • 响应结构：

    字段 类型 说明
    list array 用户列表
    list[].id uint 用户 ID
    list[].email string 邮箱
    list[].phone string 手机号
    list[].user_name string 用户名
    list[].totp_enabled bool 是否启用 TOTP
    list[].passkey_count int64 当前用户已注册 Passkey 数量
    list[].status int8 状态：0 禁用、1 正常
    list[].avatar string 头像 URL
    list[].created_at string 创建时间
    total int64 记录总数

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "list": [
      {
        "id": 1,
        "email": "admin@example.com",
        "phone": "+8613800000000",
        "user_name": "管理员",
        "totp_enabled": false,
        "passkey_count": 2,
        "status": 1,
        "avatar": "https://cdn.example/avatar/1.png",
        "created_at": "2024-01-15T10:30:00+08:00"
      }
    ],
    "total": 50
  }
}

2. 用户详情

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/user

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 用户 ID

  • 响应结构：与分页接口 list[] 结构相同

  • 错误码：400、11002

3. 创建用户

  • Method：POST

  • Path：/{apiPrefix}/internal/admin/system/user

  • Body（JSON）：

    {
  "user_name": "张三",
  "email": "zhangsan@example.com",
  "phone": "+8613800000001",
  "password": "e10adc3949ba59abbe56e057f20f883e",
  "status": 1,
  "avatar": "https://cdn.example/avatar.png"
}

  • 字段说明：

    字段 类型 必填 说明
    user_name string 否 用户名
    email string 否 登录邮箱（与 phone 二选一或同时提供）
    phone string 否 登录手机号（与 email 二选一或同时提供）
    password string 是 密码摘要，建议传 md5(明文密码)
    status int8 否 状态，默认 1
    avatar string 否 头像 URL

  • 成功返回：code=0

  • 错误码：400、11013、11014

4. 更新用户

  • Method：PUT

  • Path：/{apiPrefix}/internal/admin/system/user

  • Body（JSON）：

    {
  "id": 1,
  "user_name": "张三（更新）",
  "email": "zhangsan@example.com",
  "phone": "+8613800000001",
  "password": "",
  "status": 1,
  "avatar": "https://cdn.example/avatar_new.png"
}

  • 字段说明：

    字段 类型 必填 说明
    id uint 是 用户 ID
    user_name string 否 用户名
    email string 否 登录邮箱
    phone string 否 登录手机号
    password string 否 密码摘要，建议传 md5(明文密码)（空则不更新）
    status int8 否 状态
    avatar string 否 头像 URL

  • 成功返回：code=0

  • 错误码：400、11002、11037

5. 删除用户

  • Method：DELETE

  • Path：/{apiPrefix}/internal/admin/system/user

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 用户 ID

  • 成功返回：code=0

  • 错误码：400、500、11037

  • 说明：

    • 删除用户时会在事务内同步清理 sys_user_passkey、sys_user_identity、sys_role_user 关联数据。

6. 获取用户角色

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/user/role

  • Query 参数：

    名称 类型 必填 说明
    user_id uint 是 用户 ID

  • 响应结构：

    字段 类型 说明
    data []uint 用户拥有的角色 ID 列表

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": [1, 2, 3]
}

7. 更新用户角色

  • Method：PUT

  • Path：/{apiPrefix}/internal/admin/system/user/role

  • Body（JSON）：

    {
  "user_id": 1,
  "role_ids": [1, 2]
}

  • 字段说明：

    字段 类型 必填 说明
    user_id uint 是 用户 ID
    role_ids []uint 否 角色 ID 列表（空数组则清空角色）

  • 成功返回：code=0

  • 错误码：400、500、11037

注意：UpdateRole 会自动补充 base 角色；即使 role_ids 不包含 base，最终仍会保留该角色。

8. 管理员重置用户密码

  • Method：PUT

  • Path：/{apiPrefix}/internal/admin/system/user/password/reset

  • 说明：管理员重置指定用户密码（与鉴权模块的“当前用户重置密码”区分）

  • Body（JSON）：

    {
  "user_id": 1,
  "password": "e10adc3949ba59abbe56e057f20f883e"
}

  • 字段说明：

    字段 类型 必填 说明
    user_id uint 是 用户 ID
    password string 是 新密码摘要，建议传 md5(明文密码)（服务端以 bcrypt 存储）

  • 成功返回：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": null
}

  • 错误码：400、11002、11032、11037

9. 管理员关闭用户 TFA

  • Method：PUT

  • Path：/{apiPrefix}/internal/admin/system/user/tfa/disable

  • 说明：管理员强制关闭指定用户 TFA（无需该用户的 totp_code）

  • Body（JSON）：

    {
  "user_id": 1
}

  • 字段说明：

    字段 类型 必填 说明
    user_id uint 是 用户 ID

  • 成功返回：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": null
}

  • 错误码：400、11002、11037

10. 查询用户 Passkey

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/user/passkeys

  • Query 参数：

    名称 类型 必填 说明
    user_id uint 是 用户 ID

  • 响应结构：

    字段 类型 说明
    list array Passkey 列表
    list[].id uint Passkey 主键
    list[].display_name string 设备展示名
    list[].aaguid string Authenticator AAGUID，可能为空
    list[].transports []string 浏览器上报的传输方式
    list[].last_used_at string/null 最近一次使用时间
    list[].created_at string 创建时间

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "list": [
      {
        "id": 11,
        "display_name": "MacBook Pro",
        "aaguid": "00000000000000000000000000000000",
        "transports": ["internal", "hybrid"],
        "last_used_at": "2026-02-06T12:00:00+08:00",
        "created_at": "2026-02-01T09:00:00+08:00"
      }
    ]
  }
}

  • 错误码：400、11002、500

11. 删除单个用户 Passkey

  • Method：DELETE

  • Path：/{apiPrefix}/internal/admin/system/user/passkey

  • Body（JSON）：

    {
  "user_id": 1,
  "id": 11
}

  • 字段说明：

    字段 类型 必填 说明
    user_id uint 是 用户 ID
    id uint 是 Passkey 主键

  • 行为说明：

    • 服务端按 user_id + id 精确删除指定 Passkey。
    • 若目标用户是受保护的 super_admin，返回 11037。
    • 若删除后账号将不再保留任何可用登录方式，返回 11049。

  • 错误码：400、11037、11049、11052、500

12. 删除用户全部 Passkey

  • Method：DELETE

  • Path：/{apiPrefix}/internal/admin/system/user/passkeys

  • Body（JSON）：

    {
  "user_id": 1
}

  • 字段说明：

    字段 类型 必填 说明
    user_id uint 是 用户 ID

  • 行为说明：

    • 若用户当前没有 Passkey，接口直接返回成功。
    • 若目标用户是受保护的 super_admin，返回 11037。
    • 若删除全部 Passkey 会导致账号失去全部登录方式，返回 11049。

  • 错误码：400、11037、11049、500

备注

  • 关闭用户 TFA、Passkey 运维这几类接口都属于“系统管理”范畴，与 docs/Admin-Auth-zh.md 中“当前用户自助”接口区分开。
  • UI 中 user:password / user:update 权限建议对应后端鉴权。
  • 删除用户会同步删除该用户在 sys_role_user、sys_user_identity、sys_user_passkey 中的关联数据。

角色管理 (Role)

接口总览

功能 方法 路径
角色列表（无分页） GET /{apiPrefix}/internal/admin/system/role/list
分页查询角色 GET /{apiPrefix}/internal/admin/system/role/paginate
角色详情 GET /{apiPrefix}/internal/admin/system/role
创建角色 POST /{apiPrefix}/internal/admin/system/role
更新角色 PUT /{apiPrefix}/internal/admin/system/role
删除角色 DELETE /{apiPrefix}/internal/admin/system/role
获取角色权限 GET /{apiPrefix}/internal/admin/system/role/permission
获取角色菜单权限树 GET /{apiPrefix}/internal/admin/system/role/permission/menu-tree
更新角色权限 PUT /{apiPrefix}/internal/admin/system/role/permission

1. 角色列表（无分页）

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/role/list

  • 说明：获取所有角色的简要信息，通常用于下拉选择框

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": [
    {"id": 1, "name": "管理员"},
    {"id": 2, "name": "编辑"}
  ]
}

2. 分页查询角色

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/role/paginate

  • Query 参数：

    名称 类型 必填 默认值 说明
    name string 否 - 角色名模糊查询
    page int 否 1 页码
    page_size int 否 10 单页数量

  • 响应结构：

    字段 类型 说明
    list array 角色列表
    list[].id uint 角色 ID
    list[].name string 角色名称
    list[].description string 角色描述
    list[].created_at string 创建时间
    list[].updated_at string 更新时间
    total int64 记录总数

3. 角色详情

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/role

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 角色 ID

  • 响应结构：与分页接口 list[] 结构相同

  • 错误码：400、11016

4. 创建角色

  • Method：POST

  • Path：/{apiPrefix}/internal/admin/system/role

  • Body（JSON）：

    {
  "name": "运维人员",
  "description": "负责系统运维工作"
}

  • 字段说明：

    字段 类型 必填 说明
    name string 是 角色名称
    description string 否 角色描述

  • 成功返回：code=0

  • 错误码：400、11017、11018

5. 更新角色

  • Method：PUT
  • Path：/{apiPrefix}/internal/admin/system/role
  • Body（JSON）： 
    {
  "id": 1,
  "name": "超级管理员",
  "description": "拥有所有权限"
}
  • 成功返回：code=0
  • 错误码：400、11016、11038

6. 删除角色

  • Method：DELETE

  • Path：/{apiPrefix}/internal/admin/system/role

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 角色 ID

  • 成功返回：code=0

  • 错误码：400、11016、11038

7. 获取角色权限

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/role/permission

  • Query 参数：

    名称 类型 必填 说明
    role_id uint 是 角色 ID

  • 响应结构：

    字段 类型 说明
    data []uint 角色拥有的权限 ID 列表

8. 更新角色权限

  • Method：PUT

  • Path：/{apiPrefix}/internal/admin/system/role/permission

  • Body（JSON）：

    {
  "role_id": 1,
  "permission_ids": [1, 2, 3, 4, 5]
}

  • 字段说明：

    字段 类型 必填 说明
    role_id uint 是 角色 ID
    permission_ids []uint 否 权限 ID 列表（空数组则清空权限）

  • 成功返回：code=0

  • 错误码：400、500、11016、11038

9. 获取角色菜单权限树

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/role/permission/menu-tree

  • Query 参数：

    名称 类型 必填 说明
    role_id uint 是 角色 ID

  • 说明：返回菜单树结构，并在每个节点附带 checked，表示该菜单对应 permission_id 是否已授权给当前角色。

  • 响应结构：

    字段 类型 说明
    data.items []object 菜单权限树
    data.items[].id uint 菜单 ID
    data.items[].name string 菜单名称
    data.items[].path string 菜单路径
    data.items[].permission_id uint 菜单关联权限 ID
    data.items[].parent_id uint 父菜单 ID
    data.items[].icon string 菜单图标
    data.items[].sort int 排序
    data.items[].checked bool 当前角色是否拥有该菜单权限
    data.items[].children []object 子菜单

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "items": [
      {
        "id": 1,
        "name": "系统管理",
        "path": "/system",
        "permission_id": 0,
        "parent_id": 0,
        "icon": "setting",
        "sort": 1,
        "checked": false,
        "children": [
          {
            "id": 2,
            "name": "用户管理",
            "path": "/system/user",
            "permission_id": 101,
            "parent_id": 1,
            "icon": "user",
            "sort": 1,
            "checked": true,
            "children": []
          }
        ]
      }
    ]
  }
}

  • 错误码：400、500、11016

权限管理 (Permission)

接口总览

功能 方法 路径
可用权限列表 GET /{apiPrefix}/internal/admin/system/permission/available
权限列表（按分组） GET /{apiPrefix}/internal/admin/system/permission/list
分页查询权限 GET /{apiPrefix}/internal/admin/system/permission/paginate
权限详情 GET /{apiPrefix}/internal/admin/system/permission
创建权限 POST /{apiPrefix}/internal/admin/system/permission
更新权限 PUT /{apiPrefix}/internal/admin/system/permission
删除权限 DELETE /{apiPrefix}/internal/admin/system/permission

1. 可用权限列表

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/permission/available

  • 说明：获取系统中“尚未创建 permission 记录”的后台路由列表（仅 /{apiPrefix}/internal/admin/*，不含 ping）

  • 响应结构：按 HTTP Method 分组

    字段 类型 说明
    data object 可用路由映射
    data.GET []string 待添加的 GET 路径
    data.POST []string 待添加的 POST 路径
    data.PUT []string 待添加的 PUT 路径
    data.DELETE []string 待添加的 DELETE 路径

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "GET": [
      "/{apiPrefix}/internal/admin/system/user",
      "/{apiPrefix}/internal/admin/system/role/list"
    ],
    "POST": [
      "/{apiPrefix}/internal/admin/system/user"
    ]
  }
}

2. 权限列表（按分组）

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/permission/list

  • Query 参数：

    名称 类型 必填 说明
    type string 是 权限类型：api、menu 等

  • 响应结构：按 group 分组返回权限列表

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "用户管理": [
      {"id": 1, "name": "查看用户", "method": "GET", "path": "/user"},
      {"id": 2, "name": "创建用户", "method": "POST", "path": "/user"}
    ],
    "角色管理": [
      {"id": 3, "name": "查看角色", "method": "GET", "path": "/role"}
    ]
  }
}

3. 分页查询权限

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/permission/paginate

  • Query 参数：

    名称 类型 必填 默认值 说明
    type string 是 - 权限类型：api、menu
    name string 否 - 权限名模糊查询
    group string 否 - 分组过滤
    method string 否 - HTTP 方法过滤：GET、POST、PUT、DELETE
    page int 否 1 页码
    page_size int 否 10 单页数量

  • 响应结构：

    字段 类型 说明
    list array 权限列表
    list[].id uint 权限 ID
    list[].name string 权限名称
    list[].type string 权限类型
    list[].method string HTTP 方法
    list[].path string 路径
    list[].description string 描述
    list[].group string 分组
    list[].created_at string 创建时间
    list[].updated_at string 更新时间
    total int64 记录总数

4. 权限详情

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/permission

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 权限 ID

  • 响应结构：与分页接口 list[] 结构相同

  • 错误码：400、11019

5. 创建权限

  • Method：POST

  • Path：/{apiPrefix}/internal/admin/system/permission

  • Body（JSON）：

    {
  "name": "查看用户",
  "type": "api",
  "method": "GET",
  "path": "/{apiPrefix}/internal/admin/system/user",
  "description": "获取用户信息权限",
  "group": "用户管理"
}

  • 字段说明：

    字段 类型 必填 说明
    name string 是 权限名称
    type string 是 权限类型
    method string 是 HTTP 方法
    path string 是 路径
    description string 是 描述
    group string 是 分组

  • 成功返回：code=0

  • 错误码：400、11020、11021

6. 更新权限

  • Method：PUT
  • Path：/{apiPrefix}/internal/admin/system/permission
  • Body（JSON）：与创建接口相同，增加 id 字段
  • 成功返回：code=0
  • 错误码：400、11019

7. 删除权限

  • Method：DELETE

  • Path：/{apiPrefix}/internal/admin/system/permission

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 权限 ID

  • 成功返回：code=0

  • 错误码：400、500

菜单管理 (Menu)

接口总览

功能 方法 路径
菜单树列表 GET /{apiPrefix}/internal/admin/system/menu/list
菜单详情 GET /{apiPrefix}/internal/admin/system/menu
创建菜单 POST /{apiPrefix}/internal/admin/system/menu
更新菜单 PUT /{apiPrefix}/internal/admin/system/menu
删除菜单 DELETE /{apiPrefix}/internal/admin/system/menu

1. 菜单树列表

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/menu/list

  • 说明：返回树形结构的菜单列表

  • 响应结构：

    字段 类型 说明
    items array 菜单树列表
    items[].id uint 菜单 ID
    items[].name string 菜单名称
    items[].path string 路由路径
    items[].icon string 图标
    items[].sort int 排序值
    items[].parent_id uint 父菜单 ID，0 为顶级
    items[].permission_id uint 关联的权限 ID
    items[].children array 子菜单列表（递归结构）

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "items": [
      {
        "id": 1,
        "name": "系统管理",
        "path": "/system",
        "icon": "setting",
        "sort": 1,
        "parent_id": 0,
        "permission_id": 0,
        "children": [
          {
            "id": 2,
            "name": "用户管理",
            "path": "/system/user",
            "icon": "user",
            "sort": 1,
            "parent_id": 1,
            "permission_id": 1,
            "children": []
          }
        ]
      }
    ]
  }
}

2. 菜单详情

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/menu

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 菜单 ID

  • 响应结构：与菜单树 items[] 单项结构相同（不含 children）

  • 错误码：400、11024

3. 创建菜单

  • Method：POST

  • Path：/{apiPrefix}/internal/admin/system/menu

  • Body（JSON）：

    {
  "parent_id": 1,
  "name": "角色管理",
  "path": "/system/role",
  "icon": "peoples",
  "sort": 2
}

  • 字段说明：

    字段 类型 必填 说明
    parent_id uint 否 父菜单 ID，0 表示顶级菜单
    name string 是 菜单名称
    path string 是 路由路径
    icon string 否 图标名称
    sort int 是 排序值（支持 0）

  • 成功返回：code=0

  • 错误码：400、11023

4. 更新菜单

  • Method：PUT

  • Path：/{apiPrefix}/internal/admin/system/menu

  • Body（JSON）：

    {
  "id": 2,
  "name": "用户管理（更新）",
  "path": "/system/user",
  "icon": "user",
  "sort": 1
}

  • 字段说明：

    字段 类型 必填 说明
    id uint 是 菜单 ID
    name string 否 菜单名称
    path string 否 路由路径
    icon string 否 图标名称
    sort int 否 排序值

  • 成功返回：code=0

  • 错误码：400、11024

注意：当更新 name 时，会同步更新该菜单关联权限（permission_id）的权限名称。

5. 删除菜单

  • Method：DELETE

  • Path：/{apiPrefix}/internal/admin/system/menu

  • Query 参数：

    名称 类型 必填 说明
    id uint 是 菜单 ID

  • 成功返回：code=0

  • 错误码：400、11024、11025

注意：若菜单存在子菜单，删除将失败并返回 11025，需先删除子菜单。

操作记录 (Operation Record)

接口总览

功能 方法 路径
分页查询操作记录 GET /{apiPrefix}/internal/admin/system/record/paginate
操作记录详情 GET /{apiPrefix}/internal/admin/system/record/detail

1. 分页查询操作记录

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/record/paginate

  • 说明：查询系统操作日志记录（存储于 sys_operation_record，用户名通过 user_id 关联 sys_user.user_name）

  • Query 参数：

    名称 类型 必填 默认值 说明
    path string 否 - 请求路径过滤
    user_id uint 否 - 用户 ID 过滤
    ip string 否 - IP 地址过滤
    status int 否 - 业务状态码过滤（响应 JSON 中 code）
    method string 否 - HTTP 方法过滤
    trace_id string 否 - 链路追踪 ID 过滤
    page int 否 1 页码
    size int 否 10 单页数量

  • 响应结构：

    字段 类型 说明
    items array 记录列表
    items[].ID uint 记录 ID
    items[].Method string HTTP 方法
    items[].Path string 请求路径
    items[].IP string 请求 IP
    items[].Status int 业务状态码（响应 JSON 中 code）
    items[].UserName string 用户名
    items[].TraceID string 链路追踪 ID
    items[].CreatedAt string 创建时间
    total int64 记录总数

  • 响应示例：

    {
  "code": 0,
  "msg": "ok",
  "trace": {
    "id": "afeade2f5957-tcdtjo-gdmaj",
    "desc": ""
  },
  "data": {
    "items": [
      {
        "ID": 1024,
        "Method": "POST",
        "Path": "/{apiPrefix}/internal/admin/system/user",
        "IP": "192.168.1.100",
        "Status": 0,
        "UserName": "admin",
        "TraceID": "abc123def456",
        "CreatedAt": "2024-10-12T13:00:00+08:00"
      }
    ],
    "total": 1000
  }
}

2. 操作记录详情

  • Method：GET

  • Path：/{apiPrefix}/internal/admin/system/record/detail

  • 说明：根据操作记录 ID 获取完整日志详情

  • Query 参数：

    名称 类型 必填 说明
    id string 是 记录 ID

  • 响应结构：

    字段 类型 说明
    id uint 记录 ID
    method string HTTP 方法
    path string 请求路径
    ip string 请求 IP
    status int 业务状态码（响应 JSON 中 code）
    user_id uint 用户 ID
    user_name string 用户名（来自 sys_user）
    trace_id string 链路追踪 ID
    created_at string 创建时间
    latency float64 请求耗时（秒）
    agent string User-Agent
    error_message string 错误信息
    params object 格式化请求参数（JSON 优先，失败回退 query/raw）
    resp object 格式化响应内容（JSON 优先，失败回退 raw）

  • 错误码：400、500

说明：详情接口中的 params 与 resp 已按服务端解析规则格式化返回（JSON 优先，失败时回退 query/raw 结构）。