# API 管理 admin 接口

## 基本信息

- 模块：sys_api
- 资源：API 管理
- 端：admin
- 鉴权：默认 `PrivateGroup`，需要 `JWT + Casbin`；`/api/freshCasbin` 挂 `PublicGroup`
- 审计：除 `getAllApis/getApiList/getApiRoles/freshCasbin` 外，其余接口启用 `OperationRecord`
- 前缀：`/api`
- 模型：`system.SysApi`、`system.SysIgnoreApi`；搜索：`systemReq.SearchApiParams`；角色绑定：`systemReq.SetApiAuthorities`
- 返回：统一 `response.Response`

## 接口

| 动作 | Method | 路径 | 入参 | 返回重点 |
|:---|:---|:---|:---|:---|
| 创建 API | `POST` | `/api/createApi` | `system.SysApi` body | 操作结果 |
| 删除 API | `POST` | `/api/deleteApi` | `system.SysApi` body，仅需 `ID` | 操作结果 |
| 批量删除 API | `DELETE` | `/api/deleteApisByIds` | `request.IdsReq` body | 操作结果 |
| 更新 API | `POST` | `/api/updateApi` | `system.SysApi` body | 操作结果 |
| API 详情 | `POST` | `/api/getApiById` | `request.GetById` body | `api` |
| API 分页列表 | `POST` | `/api/getApiList` | `systemReq.SearchApiParams` body | `response.PageResult` |
| 全量 API 列表 | `POST` | `/api/getAllApis` | 无 | `apis` |
| API 分组 | `GET` | `/api/getApiGroups` | 无 | `groups/apiGroupMap` |
| 预览同步差异 | `GET` | `/api/syncApi` | 无 | `newApis/deleteApis/ignoreApis` |
| 忽略/取消忽略 API | `POST` | `/api/ignoreApi` | `system.SysIgnoreApi` body | 操作结果 |
| 确认同步路由 | `POST` | `/api/enterSyncApi` | 空 body 或 `systemRes.SysSyncApis` | 操作结果 |
| 获取 API 关联角色 | `GET` | `/api/getApiRoles` | `path/method` query | `uint[]` |
| 覆盖 API 关联角色 | `POST` | `/api/setApiRoles` | `systemReq.SetApiAuthorities` body | 操作结果 |
| 刷新 Casbin 缓存 | `GET` | `/api/freshCasbin` | 无 | 操作结果 |

## 请求字段

### SysApi Body

| 字段 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| ID | uint | 更新/删除必填 | API ID；来自 `global.GVA_MODEL` 的 JSON 字段 |
| path | string | 创建/更新必填 | API 路径 |
| description | string | 创建/更新必填 | API 中文描述 |
| apiGroup | string | 创建/更新必填 | API 分组 |
| method | string | 创建/更新必填 | HTTP Method |

### SearchApiParams Body

| 字段 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| page/pageSize | int | 是 | 页码/每页数量 |
| path | string | 否 | API 路径筛选 |
| description | string | 否 | API 描述筛选 |
| apiGroup | string | 否 | API 分组筛选 |
| method | string | 否 | HTTP Method 筛选 |
| orderKey | string | 否 | 排序字段 |
| desc | bool | 否 | 是否倒序 |

### SysIgnoreApi Body

| 字段 | 类型 | 必填 | 说明 |
|:---|:---|:---:|:---|
| path | string | 是 | API 路径 |
| method | string | 是 | HTTP Method |
| flag | bool | 是 | `true` 写入忽略；`false` 取消忽略 |

### 其他 Body/Query

| 场景 | 字段 | 类型 | 必填 | 说明 |
|:---|:---|:---|:---:|:---|
| getApiById | id | int | 是 | API ID；此处使用 `request.GetById`，字段为小写 `id` |
| deleteApisByIds | ids | int[] | 是 | API ID 数组 |
| enterSyncApi | newApis | system.SysApi[] | 否 | 兼容旧请求体；传入时按列表新增 |
| enterSyncApi | deleteApis | system.SysApi[] | 否 | 兼容旧请求体；传入时按列表删除 |
| getApiRoles | path | string | 是 | API 路径 |
| getApiRoles | method | string | 是 | HTTP Method |
| setApiRoles | path | string | 是 | API 路径 |
| setApiRoles | method | string | 是 | HTTP Method |
| setApiRoles | authorityIds | uint[] | 是 | 全量覆盖后的角色 ID 列表 |

## 响应字段

| 场景 | 字段 | 类型 | 说明 |
|:---|:---|:---|:---|
| getApiById | api | object | `system.SysApi` |
| getApiList | list/total/page/pageSize | mixed | 分页结果 |
| getAllApis | apis | array | `system.SysApi` 列表 |
| getApiGroups | groups | string[] | API 分组列表 |
| getApiGroups | apiGroupMap | object | 路径首段到 API 分组映射 |
| syncApi | newApis/deleteApis/ignoreApis | array | 待新增、待删除、已忽略 API |
| getApiRoles | data | uint[] | 角色 ID 列表 |

## 规则

- `path + method` 唯一；创建重复 API 返回失败。
- `/api/syncApi` 只预览差异，不写库。
- `/api/enterSyncApi` 空 body 时以 `global.GVA_ROUTERS` 为事实来源同步 `sys_apis`。
- 同步时新路由按 `path + method` 新增；已有路由保留人工维护的 `description/apiGroup`。
- `sys_ignore_apis` 中的 `path + method` 不写入 `sys_apis`。
- 当前路由表不存在的旧 API 从 `sys_apis` 删除，并清理对应 Casbin 权限。
- `setApiRoles` 为全量覆盖，成功后刷新 Casbin 缓存。
- 默认管理员角色 `888` 必须具备 `/api/getApiRoles` 与 `/api/setApiRoles` 权限。