xuanzhi-service/server/.ai-specs/coding-specs/module-admin-app-split.md

同模块 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 不同。