# API 鉴权与权限修改规范

## 适用范围

- 新增接口时，需要判定它是“公开访问”“仅登录可访问”还是“登录且有权限才可访问”时，使用本文。
- 已有接口在“不需要登录 / 需要登录 / 需要权限”之间切换时，使用本文。

## 现有鉴权基线

- `initialize/router.go` 当前只创建两类顶层路由组：
  - `PublicGroup`：不挂鉴权中间件。
  - `PrivateGroup`：统一挂 `middleware.JWTAuth()` 和 `middleware.CasbinHandler()`。
- `JWTAuth` 定义在 `middleware/jwt.go`。
- `CasbinHandler` 定义在 `middleware/casbin_rbac.go`。
- 结论：
  - 挂到 `PublicGroup` = 不需要登录。
  - 挂到 `PrivateGroup` = 需要登录，且需要角色权限。
  - 当前仓库没有默认内置的“只登录、不校验权限”公共组。
  - 不存在“只校验权限、不登录”的合法模式；`CasbinHandler` 依赖 `JWTAuth` 写入的用户 claims。

## 权限模式判定

| 模式 | 路由挂载方式 | JWT | Casbin | 后续要求 |
|:---|:---|:---|:---|:---|
| 不需要登录 | `PublicGroup` / `PublicRouter` | 否 | 否 | 默认不作为角色权限点长期维护 |
| 需要登录，不需要权限 | 基于 `PublicRouter` 单独加 `middleware.JWTAuth()` | 是 | 否 | 默认不进入角色权限维护 |
| 需要登录且需要权限 | `PrivateGroup` / `Router` | 是 | 是 | 必须进入 `sys_apis` 并分配角色 |

## 强制规则

- 同一个 `path + method` 只能落一种鉴权模式；禁止同时注册到公开组和鉴权组。
- `middleware.OperationRecord()` 只负责操作审计，不改变登录与权限判定。
- 鉴权逻辑统一落在 `router` 层；禁止在 `API` 或 `Service` 中靠 `if token != ""`、`if authorityId == ...` 兜底模拟权限。
- 修改接口鉴权时，Swagger 注解必须同步：
  - 不需要登录：移除 `@Security ApiKeyAuth`
  - 需要登录：保留 `@Security ApiKeyAuth`
- 业务路由统一在 `router/<module>` 调整；业务模块接入点统一在 `initialize/router_biz.go` 注册。

## 改成不需要登录

- 把路由挂载从 `PrivateGroup` 或“仅登录组”移到 `PublicRouter`。
- 如果只是业务模块内部路由调整，不要改 `API`、`Service` 方法签名。
- 该接口如果不再作为后台角色权限点维护，必须把对应 `path + method` 从权限维护中移走，二选一即可：
  - 删除对应 `sys_apis` 记录。
  - 加入 `sys_ignore_apis`，避免后续 `SyncApi` 再次纳入权限页。
- 若历史上已经给该接口分配过角色，必须同步清理对应 Casbin 规则，避免后台权限配置出现“看起来要授权、实际上公开可调”的假象。

## 改成需要登录，不需要权限

- 当前项目没有全局现成的 `LoginGroup`；少量接口优先在对应 router 中基于 `PublicRouter` 单独挂 `JWTAuth`，不要为了一两个接口改全局入口。
- 推荐写法：

```go
func (r *BookRouter) InitBookRouter(Router *gin.RouterGroup, PublicRouter *gin.RouterGroup) {
    bookLoginRouter := PublicRouter.Group("book").Use(middleware.JWTAuth())
    {
        bookLoginRouter.GET("profile", bookApi.GetProfile)
    }
}
```

- 同一模块里如果“仅登录接口”很多，再考虑在 `initialize/router.go` 新增单独的 `LoginGroup`，并把它显式传入对应 router 初始化函数。
- 这类接口禁止挂 `middleware.CasbinHandler()`。
- 这类接口默认不进入 `sys_apis` 的角色权限维护；如果历史上已经进入，必须删除或加入 `sys_ignore_apis`，不要继续让后台把它当作“需要分配角色”的接口。

## 改成需要登录且需要权限

- 把路由挂到 `PrivateGroup` 或业务 router 的 `Router` 参数上。
- 只把路由挪进 `PrivateGroup` 还不够；`CasbinHandler` 按 `path + method` 校验权限，没有角色策略就会直接返回“权限不足”。
- 因此必须同时完成以下动作：
  - 确保该 `path + method` 存在于 `sys_apis`。
  - 确保该接口已分配允许访问的角色。
  - 刷新 Casbin 策略缓存。
- 系统现成接口的完整路径 = `<router-prefix>/api/...`；如果 `router-prefix` 为空，则完整路径就是 `/api/...`。不要把是否存在额外前缀写死成项目事实。
- 常用管理接口：
  - `GET <router-prefix>/api/syncApi`：对比内存路由和 `sys_apis`
  - `POST <router-prefix>/api/enterSyncApi`：确认把新增路由写入 `sys_apis`
  - `POST <router-prefix>/api/setApiRoles`：全量覆盖某个接口的角色列表
  - `GET <router-prefix>/api/freshCasbin`：刷新 Casbin 策略缓存
- 若接口此前在 `sys_ignore_apis` 中，改成“需要权限”前必须先取消 ignore，再同步到 `sys_apis`。
- 若不给任何角色分配该接口，则结果不是“仅登录可访问”，而是“所有已登录用户都权限不足”。

## 验证要求

- 修改完成后，至少验证下面三类请求结果：
  - 公开接口：不带 token 可访问成功。
  - 仅登录接口：不带 token 返回未登录；带有效 token 可访问成功。
  - 权限接口：不带 token 返回未登录；带无权角色 token 返回“权限不足”；带有权角色 token 可访问成功。
- 如果改了接口鉴权方式，同时该接口出现在 Swagger、前端权限配置页、角色配置页，也必须同步核对展示结果是否一致。

## 禁止事项

- 禁止只改 `sys_apis` 或 `casbin_rule`，却不改真实 router 挂载。
- 禁止只把路由从 `PublicGroup` 挪到 `PrivateGroup`，却不补 `sys_apis` 和角色策略。
- 禁止把“仅登录接口”偷懒挂到 `PrivateGroup`，再靠给所有角色放权来模拟“无权限限制”。
- 禁止让公开接口长期保留在角色权限维护页里，造成权限含义失真。