少提交的东西

2026-01-06 11:07:29 +08:00
parent 2d566a9820
commit 4df3c12328
10 changed files with 328 additions and 100 deletions
--- a/internal/routes/admin.go
+++ b/internal/routes/admin.go
@@ -0,0 +1,22 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// RegisterAdminRoutes 注册管理后台相关路由
+func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, doc *openapi.Generator, basePath string) {
+	if handlers.Account != nil {
+		registerAccountRoutes(router, handlers.Account, doc, basePath)
+	}
+	if handlers.Role != nil {
+		registerRoleRoutes(router, handlers.Role, doc, basePath)
+	}
+	if handlers.Permission != nil {
+		registerPermissionRoutes(router, handlers.Permission, doc, basePath)
+	}
+	// TODO: Task routes?
+}
--- a/internal/routes/permission.go
+++ b/internal/routes/permission.go
@@ -3,18 +3,56 @@ package routes
 import (
 	"github.com/gofiber/fiber/v2"

-	"github.com/break/junhong_cmp_fiber/internal/handler"
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
 )

 // registerPermissionRoutes 注册权限相关路由
-func registerPermissionRoutes(api fiber.Router, h *handler.PermissionHandler) {
+func registerPermissionRoutes(api fiber.Router, h *admin.PermissionHandler, doc *openapi.Generator, basePath string) {
 	permissions := api.Group("/permissions")
+	groupPath := basePath + "/permissions"

 	// 权限 CRUD
-	permissions.Post("", h.Create)       // POST /api/v1/permissions
-	permissions.Get("", h.List)          // GET /api/v1/permissions
-	permissions.Get("/tree", h.GetTree)  // GET /api/v1/permissions/tree (注意：放在 :id 之前避免路由冲突)
-	permissions.Get("/:id", h.Get)       // GET /api/v1/permissions/:id
-	permissions.Put("/:id", h.Update)    // PUT /api/v1/permissions/:id
-	permissions.Delete("/:id", h.Delete) // DELETE /api/v1/permissions/:id
+	Register(permissions, doc, groupPath, "POST", "", h.Create, RouteSpec{
+		Summary: "创建权限",
+		Tags:    []string{"Permission"},
+		Input:   new(model.CreatePermissionRequest),
+		Output:  new(model.PermissionResponse),
+	})
+
+	Register(permissions, doc, groupPath, "GET", "", h.List, RouteSpec{
+		Summary: "权限列表",
+		Tags:    []string{"Permission"},
+		Input:   new(model.PermissionListRequest),
+		Output:  new(model.PermissionPageResult),
+	})
+
+	Register(permissions, doc, groupPath, "GET", "/tree", h.GetTree, RouteSpec{
+		Summary: "获取权限树",
+		Tags:    []string{"Permission"},
+		Input:   nil, // 无参数或 Query 参数
+		Output:  new([]*model.PermissionTreeNode),
+	})
+
+	Register(permissions, doc, groupPath, "GET", "/:id", h.Get, RouteSpec{
+		Summary: "获取权限详情",
+		Tags:    []string{"Permission"},
+		Input:   new(model.IDReq),
+		Output:  new(model.PermissionResponse),
+	})
+
+	Register(permissions, doc, groupPath, "PUT", "/:id", h.Update, RouteSpec{
+		Summary: "更新权限",
+		Tags:    []string{"Permission"},
+		Input:   new(model.UpdatePermissionParams),
+		Output:  new(model.PermissionResponse),
+	})
+
+	Register(permissions, doc, groupPath, "DELETE", "/:id", h.Delete, RouteSpec{
+		Summary: "删除权限",
+		Tags:    []string{"Permission"},
+		Input:   new(model.IDReq),
+		Output:  nil,
+	})
 }
--- a/internal/routes/registry.go
+++ b/internal/routes/registry.go
@@ -0,0 +1,43 @@
+package routes
+
+import (
+	"regexp"
+
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// RouteSpec 定义接口文档元数据
+type RouteSpec struct {
+	Summary string
+	Input   interface{} // 请求参数结构体 (Query/Path/Body)
+	Output  interface{} // 响应参数结构体
+	Tags    []string
+	Auth    bool // 是否需要认证图标 (预留)
+}
+
+// pathParamRegex 用于匹配 Fiber 的路径参数格式 /:param
+var pathParamRegex = regexp.MustCompile(`/:([a-zA-Z0-9_]+)`)
+
+// Register 封装后的注册函数
+// router: Fiber 路由组
+// doc: 文档生成器 (如果在运行 Web 服务时为 nil，在生成文档时为非 nil)
+// basePath: 当前路由组的基础路径 (用于文档生成)
+// method, path: HTTP 方法和路径
+// handler: Fiber Handler
+// spec: 文档元数据
+func Register(router fiber.Router, doc *openapi.Generator, basePath, method, path string, handler fiber.Handler, spec RouteSpec) {
+	// 1. 注册实际的 Fiber 路由
+	router.Add(method, path, handler)
+
+	// 2. 注册文档 (如果 doc 不为空 - 也就是在生成文档模式下)
+	if doc != nil {
+		// 简单的路径拼接
+		fullPath := basePath + path
+		// 将 Fiber 路由参数格式 /:id 转换为 OpenAPI 格式 /{id}
+		openapiPath := pathParamRegex.ReplaceAllString(fullPath, "/{$1}")
+
+		doc.AddOperation(method, openapiPath, spec.Summary, spec.Input, spec.Output, spec.Tags...)
+	}
+}
--- a/internal/routes/role.go
+++ b/internal/routes/role.go
@@ -3,22 +3,71 @@ package routes
 import (
 	"github.com/gofiber/fiber/v2"

-	"github.com/break/junhong_cmp_fiber/internal/handler"
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
 )

 // registerRoleRoutes 注册角色相关路由
-func registerRoleRoutes(api fiber.Router, h *handler.RoleHandler) {
+func registerRoleRoutes(api fiber.Router, h *admin.RoleHandler, doc *openapi.Generator, basePath string) {
 	roles := api.Group("/roles")
+	groupPath := basePath + "/roles"

 	// 角色 CRUD
-	roles.Post("", h.Create)       // POST /api/v1/roles
-	roles.Get("", h.List)          // GET /api/v1/roles
-	roles.Get("/:id", h.Get)       // GET /api/v1/roles/:id
-	roles.Put("/:id", h.Update)    // PUT /api/v1/roles/:id
-	roles.Delete("/:id", h.Delete) // DELETE /api/v1/roles/:id
+	Register(roles, doc, groupPath, "POST", "", h.Create, RouteSpec{
+		Summary: "创建角色",
+		Tags:    []string{"Role"},
+		Input:   new(model.CreateRoleRequest),
+		Output:  new(model.RoleResponse),
+	})
+
+	Register(roles, doc, groupPath, "GET", "", h.List, RouteSpec{
+		Summary: "角色列表",
+		Tags:    []string{"Role"},
+		Input:   new(model.RoleListRequest),
+		Output:  new(model.RolePageResult),
+	})
+
+	Register(roles, doc, groupPath, "GET", "/:id", h.Get, RouteSpec{
+		Summary: "获取角色详情",
+		Tags:    []string{"Role"},
+		Input:   new(model.IDReq),
+		Output:  new(model.RoleResponse),
+	})
+
+	Register(roles, doc, groupPath, "PUT", "/:id", h.Update, RouteSpec{
+		Summary: "更新角色",
+		Tags:    []string{"Role"},
+		Input:   new(model.UpdateRoleParams),
+		Output:  new(model.RoleResponse),
+	})
+
+	Register(roles, doc, groupPath, "DELETE", "/:id", h.Delete, RouteSpec{
+		Summary: "删除角色",
+		Tags:    []string{"Role"},
+		Input:   new(model.IDReq),
+		Output:  nil,
+	})

 	// 角色-权限关联
-	roles.Post("/:id/permissions", h.AssignPermissions)                // POST /api/v1/roles/:id/permissions
-	roles.Get("/:id/permissions", h.GetPermissions)                    // GET /api/v1/roles/:id/permissions
-	roles.Delete("/:role_id/permissions/:perm_id", h.RemovePermission) // DELETE /api/v1/roles/:role_id/permissions/:perm_id
+	Register(roles, doc, groupPath, "POST", "/:id/permissions", h.AssignPermissions, RouteSpec{
+		Summary: "分配权限",
+		Tags:    []string{"Role"},
+		Input:   new(model.AssignPermissionsParams),
+		Output:  nil,
+	})
+
+	Register(roles, doc, groupPath, "GET", "/:id/permissions", h.GetPermissions, RouteSpec{
+		Summary: "获取角色权限",
+		Tags:    []string{"Role"},
+		Input:   new(model.IDReq),
+		Output:  new([]model.Permission),
+	})
+
+	Register(roles, doc, groupPath, "DELETE", "/:role_id/permissions/:perm_id", h.RemovePermission, RouteSpec{
+		Summary: "移除权限",
+		Tags:    []string{"Role"},
+		Input:   new(model.RemovePermissionParams),
+		Output:  nil,
+	})
 }
--- a/internal/routes/routes.go
+++ b/internal/routes/routes.go
@@ -9,21 +9,13 @@ import (
 // RegisterRoutes 路由注册总入口
 // 按业务模块调用各自的路由注册函数
 func RegisterRoutes(app *fiber.App, handlers *bootstrap.Handlers) {
-	// API 路由组
-	api := app.Group("/api/v1")
-
-	// 注册各模块路由
+	// 1. 全局路由
 	registerHealthRoutes(app)
-	registerTaskRoutes(api)

-	// RBAC 路由
-	if handlers.Account != nil {
-		registerAccountRoutes(api, handlers.Account)
-	}
-	if handlers.Role != nil {
-		registerRoleRoutes(api, handlers.Role)
-	}
-	if handlers.Permission != nil {
-		registerPermissionRoutes(api, handlers.Permission)
-	}
+	// 2. Admin 域 (挂载在 /api/admin)
+	adminGroup := app.Group("/api/admin")
+	RegisterAdminRoutes(adminGroup, handlers, nil, "/api/admin")
+	
+	// 任务相关路由 (归属于 Admin 域)
+	registerTaskRoutes(adminGroup)
 }