# 同模块 admin/app 接口分层规范

## 适用范围

- 同一业务模块同时存在 `admin` 管理端接口和 `app` 用户端接口时，使用本文。

## 强制规则

- 顶层目录一律按业务模块落点；禁止因为有 `app` 端，就单独新建顶层 `router/app`、`api/v1/app`、`service/app`、`model/app` 来承载 `book`、`order`、`author` 这类业务。
- 同一业务模块的实体仍统一放在 `model/<module>`；只有接口入参、出参和流程按 `admin` / `app` 分开。
- `router/<module>`、`api/v1/<module>`、`service/<module>` 内，`admin` 与 `app` 接口必须分文件或分承载结构体；禁止长期混写在同一个大文件里。
- 可复用逻辑优先下沉到 `service/<module>` 的公共方法；公共逻辑只抽业务共性，不要把 `admin` / `app` 的鉴权、返回、分页口径硬揉成一套。

## 推荐落点

- 推荐文件名：`<module>_admin.go`、`<module>_app.go`、`enter.go`。
- 示例：
  - `router/book/book_admin.go`
  - `router/book/book_app.go`
  - `api/v1/book/book_admin.go`
  - `api/v1/book/book_app.go`
  - `service/book/book_admin.go`
  - `service/book/book_app.go`
  - `service/book/book_common.go`
  - `model/book/book.go`
  - `model/book/request/book_admin.go`
  - `model/book/request/book_app.go`
  - `model/book/response/book_admin.go`
  - `model/book/response/book_app.go`

## 路由与鉴权

- `admin` 接口默认挂业务 router 的 `PrivateGroup`，走后台 `JWT + Casbin`。
- `app` 公开接口挂 `PublicGroup`。
- `app` 仅登录接口，基于 `PublicGroup` 单独加 `middleware.JWTAuth()`；不要直接挂 `PrivateGroup`。
- 如果 `app` 用户体系不等于 `sys_users`，禁止直接复用后台登录、claims、角色权限链路；必须单独实现用户端认证链路。

## 禁止事项

- 禁止把“同一业务模块的 app 端接口”误建成独立业务模块。
- 禁止为了省事，把所有 `app` 接口都挂到 `PrivateGroup`，再用后台角色权限去模拟用户端登录态。
- 禁止同一个业务实体在 `model` 层拆出两套重复表结构，仅因接口面向 `admin` / `app` 不同。