2026_OA_AI_Integration/server

Fork 0

Files

T

zhujinhua 550d3e1f42 init

2026-01-16 15:49:34 +08:00

16 KiB

Raw Blame History

API 接口文档

本文档详细描述了 Goravel Admin 后台管理系统的所有 API 接口。

基础信息

Base URL: http://localhost:3000/api/admin
认证方式: JWT Bearer Token
请求格式: JSON
响应格式: JSON

通用响应格式

成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

分页响应

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "list": [],
    "page": 1,
    "page_size": 10,
    "total": 100
  }
}

错误响应

{
  "code": 400,
  "message": "错误信息",
  "data": null
}

状态码说明

状态码	说明
200	成功
400	请求参数错误
401	未认证或 Token 过期
403	无权限访问
404	资源不存在
422	验证失败
500	服务器内部错误

认证接口

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码
captcha_id	string	否	验证码ID
captcha_code	string	否	验证码

退出登录

POST /logout
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "退出成功",
  "data": null
}

刷新 Token

POST /refresh-token
Authorization: Bearer {token}

获取验证码

GET /captcha

响应示例：

{
  "code": 200,
  "data": {
    "captcha_id": "abc123",
    "captcha_image": "data:image/png;base64,..."
  }
}

管理员信息

获取当前用户信息

GET /info
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "超级管理员",
    "email": "admin@example.com",
    "avatar": "",
    "department_id": 1,
    "department": {
      "id": 1,
      "name": "总部"
    },
    "roles": [
      {
        "id": 1,
        "name": "超级管理员",
        "slug": "super-admin"
      }
    ],
    "permissions": ["admin.index", "admin.store", "..."],
    "menus": []
  }
}

修改密码

PUT /password
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
old_password	string	是	原密码
password	string	是	新密码
password_confirmation	string	是	确认新密码

管理员管理

获取管理员列表

GET /admins
Authorization: Bearer {token}

查询参数：

参数	类型	说明
page	int	页码，默认 1
page_size	int	每页条数，默认 10
username	string	用户名（模糊搜索）
nickname	string	昵称（模糊搜索）
status	int	状态：0-禁用，1-启用
department_id	int	部门ID
order_by	string	排序，如 `id:desc`

响应示例：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "username": "admin",
        "nickname": "超级管理员",
        "email": "admin@example.com",
        "phone": "",
        "avatar": "",
        "status": 1,
        "department_id": 1,
        "department": {"id": 1, "name": "总部"},
        "roles": [{"id": 1, "name": "超级管理员"}],
        "created_at": "2024-01-01T00:00:00Z",
        "last_login_at": "2024-01-01T12:00:00Z"
      }
    ],
    "page": 1,
    "page_size": 10,
    "total": 1
  }
}

创建管理员

POST /admins
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
username	string	是	用户名（唯一）
password	string	是	密码
nickname	string	是	昵称
email	string	否	邮箱
phone	string	否	手机号
avatar	string	否	头像URL
department_id	int	否	部门ID
role_ids	[]int	否	角色ID数组
status	int	否	状态，默认 1

获取管理员详情

GET /admins/{id}
Authorization: Bearer {token}

更新管理员

PUT /admins/{id}
Authorization: Bearer {token}

删除管理员

DELETE /admins/{id}
Authorization: Bearer {token}

重置密码

PUT /admins/{id}/reset-password
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
password	string	是	新密码

角色管理

获取角色列表

GET /roles
Authorization: Bearer {token}

查询参数：

参数	类型	说明
page	int	页码
page_size	int	每页条数
name	string	角色名称（模糊搜索）
status	int	状态

创建角色

POST /roles
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
name	string	是	角色名称
slug	string	是	角色标识（唯一）
description	string	否	描述
permission_ids	[]int	否	权限ID数组
menu_ids	[]int	否	菜单ID数组
status	int	否	状态
sort	int	否	排序

获取角色详情

GET /roles/{id}
Authorization: Bearer {token}

更新角色

PUT /roles/{id}
Authorization: Bearer {token}

删除角色

DELETE /roles/{id}
Authorization: Bearer {token}

菜单管理

获取菜单列表（树形）

GET /menus
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "parent_id": 0,
        "title": "系统管理",
        "slug": "system",
        "icon": "Setting",
        "path": "/system",
        "component": "",
        "type": 1,
        "status": 1,
        "sort": 1,
        "children": [
          {
            "id": 2,
            "parent_id": 1,
            "title": "管理员管理",
            "slug": "admin",
            "path": "/system/admin",
            "component": "admin/AdminList",
            "type": 2,
            "status": 1
          }
        ]
      }
    ]
  }
}

创建菜单

POST /menus
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
parent_id	int	否	父级ID，默认 0
title	string	是	菜单标题
slug	string	是	菜单标识
icon	string	否	图标名称
path	string	否	路由路径
component	string	否	组件路径
type	int	是	类型：1-目录，2-菜单，3-按钮
status	int	否	状态
sort	int	否	排序

获取菜单详情

GET /menus/{id}
Authorization: Bearer {token}

更新菜单

PUT /menus/{id}
Authorization: Bearer {token}

删除菜单

DELETE /menus/{id}
Authorization: Bearer {token}

权限管理

获取权限列表

GET /permissions
Authorization: Bearer {token}

创建权限

POST /permissions
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
name	string	是	权限名称
slug	string	是	权限标识（唯一）
method	string	是	HTTP 方法（GET/POST/PUT/DELETE）
path	string	是	API 路径
menu_id	int	否	关联菜单ID
status	int	否	状态

更新权限

PUT /permissions/{id}
Authorization: Bearer {token}

删除权限

DELETE /permissions/{id}
Authorization: Bearer {token}

部门管理

获取部门列表（树形）

GET /departments
Authorization: Bearer {token}

创建部门

POST /departments
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
name	string	是	部门名称
parent_id	int	否	父部门ID
leader	string	否	负责人
phone	string	否	联系电话
email	string	否	邮箱
status	int	否	状态
sort	int	否	排序

更新部门

PUT /departments/{id}
Authorization: Bearer {token}

删除部门

DELETE /departments/{id}
Authorization: Bearer {token}

字典管理

获取字典列表

GET /dictionaries
Authorization: Bearer {token}

创建字典

POST /dictionaries
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
parent_id	int	否	父级ID（0为字典类型）
name	string	是	名称
code	string	是	编码
value	string	否	值
description	string	否	描述
status	int	否	状态
sort	int	否	排序

更新字典

PUT /dictionaries/{id}
Authorization: Bearer {token}

删除字典

DELETE /dictionaries/{id}
Authorization: Bearer {token}

黑名单管理

获取黑名单列表

GET /blacklists
Authorization: Bearer {token}

创建黑名单

POST /blacklists
Authorization: Bearer {token}

请求参数：

参数	类型	必填	说明
ip	string	是	IP地址（支持单IP、CIDR、范围）
remark	string	否	备注
status	int	否	状态

IP 格式示例：

单个 IP: 192.168.1.100
CIDR 格式: 192.168.1.0/24
IP 范围: 192.168.1.1-192.168.1.100

更新黑名单

PUT /blacklists/{id}
Authorization: Bearer {token}

删除黑名单

DELETE /blacklists/{id}
Authorization: Bearer {token}

批量删除黑名单

DELETE /blacklists/batch
Authorization: Bearer {token}

请求参数：

{
  "ids": [1, 2, 3]
}

日志管理

操作日志

GET /logs/operation
Authorization: Bearer {token}

查询参数：

参数	类型	说明
admin_id	int	管理员ID
module	string	模块
action	string	操作
start_date	string	开始日期
end_date	string	结束日期

登录日志

GET /logs/login
Authorization: Bearer {token}

查询参数：

参数	类型	说明
admin_id	int	管理员ID
ip	string	IP地址
status	int	状态：0-失败，1-成功
start_date	string	开始日期
end_date	string	结束日期

系统日志

GET /logs/system
Authorization: Bearer {token}

查询参数：

参数	类型	说明
level	string	日志级别（error/warning/info/debug）
trace_id	string	追踪ID
start_date	string	开始日期
end_date	string	结束日期

仪表盘

获取统计数据

GET /dashboard/stats
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "data": {
    "admin_count": 10,
    "role_count": 5,
    "menu_count": 30,
    "login_count_today": 15,
    "operation_count_today": 100,
    "recent_logins": [],
    "recent_operations": []
  }
}

在线管理员

获取在线管理员列表

GET /online-admins
Authorization: Bearer {token}

强制下线

DELETE /online-admins/{token_id}
Authorization: Bearer {token}

批量强制下线

POST /online-admins/batch-kick-out
Authorization: Bearer {token}

请求参数：

{
  "token_ids": [1, 2, 3]
}

服务监控

获取系统信息

GET /monitor/system
Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "data": {
    "cpu": {
      "cores": 8,
      "usage": 25.5
    },
    "memory": {
      "total": 16384,
      "used": 8192,
      "usage": 50.0
    },
    "disk": {
      "total": 512000,
      "used": 256000,
      "usage": 50.0
    },
    "go": {
      "version": "go1.21",
      "goroutines": 50,
      "gc_pause": "1.2ms"
    }
  }
}

文件上传

上传文件

POST /attachments/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

请求参数：

参数	类型	必填	说明
file	file	是	文件
type	string	否	类型（image/document/video）

分片上传

POST /attachments/chunk
Authorization: Bearer {token}
Content-Type: multipart/form-data

请求参数：

参数	类型	必填	说明
file	file	是	分片文件
chunk_id	string	是	分片标识
chunk_index	int	是	分片索引
total_chunks	int	是	总分片数
filename	string	是	原始文件名

合并分片

POST /attachments/merge
Authorization: Bearer {token}

请求参数：

{
  "chunk_id": "abc123",
  "filename": "large-file.zip",
  "total_chunks": 10
}

通知中心

WebSocket 连接

ws://localhost:3000/api/admin/ws/notifications
Authorization: Bearer {token}

消息格式：

{
  "type": "notification",
  "data": {
    "id": 1,
    "title": "新通知",
    "content": "通知内容",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

获取通知列表

GET /notifications
Authorization: Bearer {token}

标记已读

PUT /notifications/{id}/read
Authorization: Bearer {token}

全部标记已读

PUT /notifications/read-all
Authorization: Bearer {token}

错误码说明

错误码定义在 app/errors/codes.go，格式为 XXYYYY：

XX: 模块 (10-认证, 20-权限, 30-验证, 40-业务, 50-系统)
YYYY: 具体错误

认证模块 (10xxx)

错误码	说明
10001	用户名或密码错误
10002	账号已被禁用
10003	Token 已过期
10004	Token 已被撤销
10005	验证码错误
10006	登录尝试次数超限
10007	Token 无效

权限模块 (20xxx)

错误码	说明
20001	无权限访问
20002	资源不存在
20003	访问被拒绝

验证模块 (30xxx)

错误码	说明
30001	参数验证失败
30002	数据已存在
30003	数据不存在
30004	格式无效

业务模块 (40xxx)

错误码	说明
40001	操作失败
40002	删除失败
40003	更新失败
40004	创建失败
40005	上传失败
40006	导出失败

系统模块 (50xxx)

错误码	说明
50001	服务器内部错误
50002	数据库错误
50003	缓存错误
50004	队列错误
50005	第三方服务错误

附录

认证头格式

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

分页参数

所有列表接口支持以下分页参数：

参数	类型	默认值	说明
page	int	1	页码
page_size	int	10	每页条数（最大 100）
order_by	string	id:desc	排序（字段:方向）

时间格式

所有时间字段使用 ISO 8601 格式：2024-01-01T12:00:00Z

多语言支持

通过请求头指定语言：

Accept-Language: zh-CN

支持的语言：

zh-CN - 简体中文
en-US - English

16 KiB Raw Blame History Unescape Escape

API 接口文档

基础信息

通用响应格式

成功响应

分页响应

错误响应

状态码说明

认证接口

登录

退出登录

刷新 Token

获取验证码

管理员信息

获取当前用户信息

修改密码

管理员管理

获取管理员列表

创建管理员

获取管理员详情

更新管理员

删除管理员

重置密码

角色管理

获取角色列表

创建角色

获取角色详情

更新角色

删除角色

菜单管理

获取菜单列表（树形）

创建菜单

获取菜单详情

更新菜单

删除菜单

权限管理

获取权限列表

创建权限

更新权限

删除权限

部门管理

获取部门列表（树形）

创建部门

更新部门

删除部门

字典管理

获取字典列表

创建字典

更新字典

删除字典

黑名单管理

获取黑名单列表

创建黑名单

更新黑名单

删除黑名单

批量删除黑名单

日志管理

操作日志

登录日志

系统日志

仪表盘

获取统计数据

在线管理员

获取在线管理员列表

强制下线

批量强制下线

服务监控

获取系统信息

文件上传

上传文件

分片上传

合并分片

通知中心

WebSocket 连接

获取通知列表

标记已读

全部标记已读

错误码说明

认证模块 (10xxx)

权限模块 (20xxx)

16 KiB

Raw Blame History