# API 管理 admin 接口

## 基本信息

- 模块：sys_api
- 资源：API 管理
- 端：admin
- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
- 操作审计：`/api/enterSyncApi` 启用 `OperationRecord`
- 路由前缀：`/api`

## 同步接口

| 动作 | Method | 路径 | API 方法 | Service 方法 |
|:---|:---|:---|:---|:---|
| 预览同步差异 | `GET` | `/api/syncApi` | `SyncApi` | `SyncApi` |
| 确认同步路由 | `POST` | `/api/enterSyncApi` | `EnterSyncApi` | `EnterSyncApi` / `SyncApiToDB` |
| 获取 API 关联角色 | `GET` | `/api/getApiRoles` | `GetApiRoles` | `GetAuthoritiesByApi` |
| 覆盖 API 关联角色 | `POST` | `/api/setApiRoles` | `SetApiRoles` | `SetApiAuthorities` |
| 刷新 Casbin 缓存 | `GET` | `/api/freshCasbin` | `FreshCasbin` | `FreshCasbin` |

## 参数与返回

- `/api/syncApi`：无入参，返回 `newApis`、`deleteApis`、`ignoreApis`，只预览差异，不写库。
- `/api/enterSyncApi`：允许空 body 或 `{}`，默认以当前 Gin 路由表 `global.GVA_ROUTERS` 为事实来源同步 `sys_apis`。
- `/api/enterSyncApi`：兼容旧请求体 `systemRes.SysSyncApis`，传入 `newApis/deleteApis` 时按传入列表写入或删除。
- `/api/getApiRoles`：query 传入 `path`、`method`，返回该 API 已关联的角色 ID 列表。
- `/api/setApiRoles`：body 传入 `path`、`method`、`authorityIds`，全量覆盖该 API 的角色权限。
- `/api/freshCasbin`：无入参，刷新 Casbin 缓存；该接口走公开路由但写入 `sys_ignore_apis`，不作为角色权限点维护。
- 返回：统一使用 `response.Response`。

## 同步规则

- 新路由：`sys_apis` 中不存在同一 `path + method` 时自动新增。
- 已有路由：保留原 `description`、`apiGroup` 等人工维护字段，不自动覆盖。
- 忽略路由：存在于 `sys_ignore_apis` 的 `path + method` 不写入 `sys_apis`。
- 失效路由：数据库中存在但当前 Gin 路由表不存在时，从 `sys_apis` 删除，并清理对应 Casbin 权限。
- 默认管理员角色 `888` 必须具备 `/api/getApiRoles` 与 `/api/setApiRoles` 权限，避免出现“无权分配权限”的系统初始化死锁。
- 公开接口、仅登录接口不应长期作为角色权限点维护；需要通过 `sys_ignore_apis` 排除。
