rxthinkcmf-wiki/RXThinkCMF_Laravel13_AntdVue/zh/api-spec/overview.md

# 8.7 API 接口总览

:::tip 概述
本节按模块分组列出所有 API 接口的概述（全部来自 `routes/api.php` 实际路由），详细路由清单见 [附录 E API 接口速查表](/zh/appendix/api-cheatsheet.html)。
:::

## API 设计规范

### 命名规范

| 规范 | 说明 | 示例 |
|------|------|------|
| URL 风格 | 小驼峰/小写下划线混合，前缀 `/api`（`bootstrap/app.php` 统一添加） | `/api/user/page` |
| 模块名 | 与 Controller 对应 | `user`、`article`、`dict` |
| 操作名 | 标准 CRUD 动词 | `page`、`list`、`detail`、`add`、`update`、`delete`、`batchDelete` |
| 扩展操作 | 业务动词 | `import`、`export`、`resetPwd`、`refreshCache`、`runOnce` |

### HTTP 方法规范

| 操作 | HTTP 方法 | URL 示例 | 说明 |
|------|----------|---------|------|
| 分页查询 | GET | `/api/user/page` | 参数在 URL query string |
| 全量列表 | GET | `/api/role/list` | 参数在 URL query string（`list` 路由按模块提供，如 role/dept/menu；user 模块仅分页） |
| 详情 | GET | `/api/user/detail/{id}` | ID 在 URL 路径 |
| 新增 | POST | `/api/user/add` | 参数在 JSON 请求体 |
| 修改 | PUT | `/api/user/update` | 参数在 JSON 请求体（含 id） |
| 删除 | DELETE | `/api/user/delete/{id}` | ID 在 URL 路径 |
| 批量删除 | **DELETE** | `/api/user/batchDelete` | ids 在 JSON 请求体（**本项目统一 DELETE + body**） |

### 统一响应格式

```json
{
    "code": 0,       // 0=成功，其他=失败
    "ok": true,      // 是否成功
    "msg": "操作成功", // 提示信息
    "data": {}       // 响应数据
}
```

### 认证方式

```text
Authorization: Bearer <access_token>
```

公开接口放在 `routes/api.php` 中间件组**外**，认证接口统一在 `['auth.jwt', 'tenant', 'demo', 'log.operation']` 组内。

## 公开接口（无需认证）

| 模块 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 登录 | `/api/login` | POST | 用户登录，返回双令牌 |
| 刷新 | `/api/refresh` | POST | refresh_token 换取新令牌对 |
| 验证码 | `/api/captcha` | GET | 获取图片验证码 |
| Token | `/api/oauth2/token` | POST | OAuth2 兼容获取/刷新 Token |
| Token | `/api/oauth2/check/token` | GET | 检查 Token 有效性 |

## 认证接口（组内，其余全部）

以下模块接口均位于认证中间件组内，需要 `Authorization` 头。

### 个人中心与公共

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 登出 | `/api/logout` | POST | 登出（吊销 refresh_token + 记录日志） |
| Token | `/api/oauth2/remove/{token}` | DELETE | 吊销指定令牌 |
| 首页 | `/api/index/getUser` | GET | 获取当前用户信息（含角色与权限） |
| 首页 | `/api/index/getMenus` | GET | 获取菜单树（动态路由数据源） |
| 首页 | `/api/index/updatePassword` | PUT | 修改密码（改密后全端下线） |
| 首页 | `/api/index/updateProfile` | PUT | 更新个人信息 |
| 上传 | `/api/upload/uploadFile` | POST | 上传文件（需 `sys:upload:file` 权限） |

### 系统管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 用户 | `/api/user/page` `detail/{id}` | GET | 分页 / 详情 |
| 用户 | `/api/user/add` `import` | POST | 新增 / Excel 导入 |
| 用户 | `/api/user/batchDelete` | DELETE | 批量删除 |
| 用户 | `/api/user/update` | PUT | 修改 |
| 用户 | `/api/user/resetPwd` | PUT | 重置密码 |
| 用户 | `/api/user/delete/{id}` `export` | DELETE / GET | 删除 / Excel 导出 |
| 角色 | `/api/role/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 角色 | `/api/role/add` `menu/save` | POST | 新增 / 保存菜单权限 |
| 角色 | `/api/role/batchDelete` | DELETE | 批量删除 |
| 角色 | `/api/role/update` | PUT | 修改 |
| 角色 | `/api/role/delete/{id}` | DELETE | 删除 |
| 角色 | `/api/role/menu/list/{id}` | GET | 获取角色菜单（含选中状态） |
| 菜单 | `/api/menu/list` `detail/{id}` | GET | 树形列表 / 详情 |
| 菜单 | `/api/menu/add` | POST | 新增 |
| 菜单 | `/api/menu/update` | PUT | 修改 |
| 菜单 | `/api/menu/delete/{id}` | DELETE | 删除 |
| 部门 | `/api/dept/list` `detail/{id}` | GET | 树形列表 / 详情 |
| 部门 | `/api/dept/add` | POST | 新增 |
| 部门 | `/api/dept/update` | PUT | 修改 |
| 部门 | `/api/dept/delete/{id}` | DELETE | 删除 |
| 职级 | `/api/level/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 职级 | `/api/level/add` `import` | POST | 新增 / Excel 导入 |
| 职级 | `/api/level/batchDelete` | DELETE | 批量删除 |
| 职级 | `/api/level/update` | PUT | 修改 |
| 职级 | `/api/level/delete/{id}` `export` | DELETE / GET | 删除 / Excel 导出 |
| 岗位 | `/api/position/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 岗位 | `/api/position/add` | POST | 新增 |
| 岗位 | `/api/position/batchDelete` | DELETE | 批量删除 |
| 岗位 | `/api/position/update` | PUT | 修改 |
| 岗位 | `/api/position/delete/{id}` | DELETE | 删除 |
| 租户 | `/api/tenant/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 租户 | `/api/tenant/add` `account` | POST | 新增 / 创建租户账号 |
| 租户 | `/api/tenant/batchDelete` | DELETE | 批量删除 |
| 租户 | `/api/tenant/update` | PUT | 修改 |
| 租户 | `/api/tenant/delete/{id}` | DELETE | 删除 |
| 租户 | `/api/tenant/users/{tenantId}` | GET | 租户用户列表 |

### 数据管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 字典 | `/api/dict/page` `detail/{id}` | GET | 分页 / 详情 |
| 字典 | `/api/dict/add` | POST | 新增 |
| 字典 | `/api/dict/batchDelete` | DELETE | 批量删除 |
| 字典 | `/api/dict/update` | PUT | 修改 |
| 字典 | `/api/dict/delete/{id}` | DELETE | 删除 |
| 字典 | `/api/dict/refreshCache` | GET | 刷新字典缓存（`#[DemoAllow]`） |
| 字典项 | `/api/dict/item/page` `detail/{id}` `getDictItemList/{code}` | GET | 分页 / 详情 / 按编码获取 |
| 字典项 | `/api/dict/item/add` | POST | 新增 |
| 字典项 | `/api/dict/item/batchDelete` | DELETE | 批量删除 |
| 字典项 | `/api/dict/item/update` | PUT | 修改 |
| 字典项 | `/api/dict/item/delete/{id}` | DELETE | 删除 |
| 配置 | `/api/config/page` `list` `detail/{id}` `web/index` | GET | 分页 / 全量 / 详情 / 网站配置 |
| 配置 | `/api/config/add` `web/save` | POST | 新增 / 保存网站配置 |
| 配置 | `/api/config/batchDelete` | DELETE | 批量删除 |
| 配置 | `/api/config/update` | PUT | 修改 |
| 配置 | `/api/config/delete/{id}` | DELETE | 删除 |
| 配置项 | `/api/config/item/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 配置项 | `/api/config/item/add` | POST | 新增 |
| 配置项 | `/api/config/item/batchDelete` | DELETE | 批量删除 |
| 配置项 | `/api/config/item/update` | PUT | 修改 |
| 配置项 | `/api/config/item/delete/{id}` | DELETE | 删除 |
| 参数 | `/api/param/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 参数 | `/api/param/add` | POST | 新增 |
| 参数 | `/api/param/batchDelete` | DELETE | 批量删除 |
| 参数 | `/api/param/update` | PUT | 修改 |
| 参数 | `/api/param/delete/{id}` | DELETE | 删除 |
| 城市 | `/api/city/list` `detail/{id}` `getCityList/{code}` `getParent/{id}` `findByParentCode` | GET | 列表 / 详情 / 级联查询 |
| 城市 | `/api/city/add` | POST | 新增 |
| 城市 | `/api/city/batchDelete` | DELETE | 批量删除 |
| 城市 | `/api/city/update` | PUT | 修改 |
| 城市 | `/api/city/delete/{id}` | DELETE | 删除 |

### 内容管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 文章 | `/api/article/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 文章 | `/api/article/add` | POST | 新增 |
| 文章 | `/api/article/batchDelete` | DELETE | 批量删除 |
| 文章 | `/api/article/update` | PUT | 修改 |
| 文章 | `/api/article/delete/{id}` | DELETE | 删除 |
| 分类 | `/api/category/list` `page` `detail/{id}` | GET | 树形 / 分页 / 详情 |
| 分类 | `/api/category/add` | POST | 新增 |
| 分类 | `/api/category/batchDelete` | DELETE | 批量删除 |
| 分类 | `/api/category/update` | PUT | 修改 |
| 分类 | `/api/category/delete/{id}` | DELETE | 删除 |
| 公告 | `/api/notice/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 公告 | `/api/notice/add` | POST | 新增 |
| 公告 | `/api/notice/batchDelete` | DELETE | 批量删除 |
| 公告 | `/api/notice/update` | PUT | 修改 |
| 公告 | `/api/notice/delete/{id}` | DELETE | 删除 |
| 友链 | `/api/link/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 友链 | `/api/link/add` | POST | 新增 |
| 友链 | `/api/link/batchDelete` | DELETE | 批量删除 |
| 友链 | `/api/link/update` | PUT | 修改 |
| 友链 | `/api/link/delete/{id}` | DELETE | 删除 |

### 监控管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 定时任务 | `/api/job/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 定时任务 | `/api/job/runOnce/{id}` | GET | 手动执行一次 |
| 定时任务 | `/api/job/pause/{id}` `resume/{id}` `daemonStatus` | GET | 暂停 / 恢复 / 守护进程状态 |
| 定时任务 | `/api/job/add` `status` | POST | 新增 / 设置状态 |
| 定时任务 | `/api/job/batchDelete` | DELETE | 批量删除 |
| 定时任务 | `/api/job/update` | PUT | 修改 |
| 定时任务 | `/api/job/delete/{id}` | DELETE | 删除 |
| 任务日志 | `/api/job/log/page` `detail/{id}` | GET | 日志分页 / 详情 |
| 任务日志 | `/api/job/log/batchDelete` | DELETE | 批量删除日志 |
| 任务日志 | `/api/job/log/delete/{id}` | DELETE | 删除日志 |

### 日志审计

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 操作日志 | `/api/oper/log/page` `detail/{id}` | GET | 分页 / 详情 |
| 操作日志 | `/api/oper/log/batchDelete` | DELETE | 批量删除 |
| 操作日志 | `/api/oper/log/delete/{id}` | DELETE | 删除 |
| 登录日志 | `/api/login/log/page` `detail/{id}` | GET | 分页 / 详情 |
| 登录日志 | `/api/login/log/batchDelete` | DELETE | 批量删除 |
| 登录日志 | `/api/login/log/delete/{id}` | DELETE | 删除 |

### 示例与开发工具

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 示例 | `/api/example/page` `list` `detail/{id}` `export` | GET | 分页 / 全量 / 详情 / 导出 |
| 示例 | `/api/example/add` `import` | POST | 新增 / 导入 |
| 示例 | `/api/example/batchDelete` | DELETE | 批量删除 |
| 示例 | `/api/example/update` | PUT | 修改 |
| 示例 | `/api/example/delete/{id}` | DELETE | 删除 |
| 文件模板 | `/api/file/template/page` `detail/{id}` `getTemplateByCode/{code}` | GET | 分页 / 详情 / 按编码获取 |
| 文件模板 | `/api/file/template/add` | POST | 新增 |
| 文件模板 | `/api/file/template/batchDelete` | DELETE | 批量删除 |
| 文件模板 | `/api/file/template/update` | PUT | 修改 |
| 文件模板 | `/api/file/template/delete/{id}` | DELETE | 删除 |
| 代码生成 | `/api/generator/page` `preview` | GET | 可生成表列表 / 预览代码 |
| 代码生成 | `/api/generator/generate` `batchGenerate` | POST | 生成 / 批量生成 |

## 接口统计

| 分组 | 接口数量 | 说明 |
|------|---------|------|
| 公开接口 | 5 | 登录 / 刷新 / 验证码 / OAuth2 |
| 个人中心与公共 | 7 | 登出 / 用户信息 / 菜单 / 改密 / 改资料 / 上传 / 吊销 |
| 系统管理 | ~52 | 用户 / 角色 / 菜单 / 部门 / 岗位 / 职级 / 租户 |
| 数据管理 | ~50 | 字典 / 字典项 / 配置 / 配置项 / 参数 / 城市 |
| 内容管理 | ~28 | 文章 / 分类 / 公告 / 友链 |
| 监控管理 | 16 | 定时任务 / 任务日志 |
| 日志审计 | 8 | 操作日志 / 登录日志 |
| 示例与开发工具 | ~20 | 示例 / 文件模板 / 代码生成 |
| **合计** | **≈180** | 以 `php artisan route:list` 为准 |

:::tip 动态获取
执行 `php artisan route:list` 可输出全部路由（方法、URI、中间件、控制器动作），是核对接口清单的最权威来源。详细清单见 [附录 E](/zh/appendix/api-cheatsheet.html)。
:::