long-agent
0564bfd9ad
Added @Summary, @Description, @Tags, @Param, @Success, @Failure, @Router annotations to all major handler endpoints for OpenAPI/Swagger auto-generation. Covers 86 annotations across: - auth_handler.go (25): all auth endpoints - user_handler.go (14): CRUD + roles + admin management - device_handler.go (13): device CRUD + trust management - role_handler.go (8): role CRUD + permissions - custom_field_handler.go (7): field CRUD + user values - permission_handler.go (7): permission CRUD + tree - log_handler.go (3): login/operation logs - captcha_handler.go (3): generate/verify - stats_handler.go (2): dashboard + user stats - avatar_handler.go (1): upload avatar - totp_handler.go (1): totp status - password_reset_handler.go (1): forgot password Partially addresses P2: missing Swagger annotations (PRODUCTION_GAP_ANALYSIS_2026-04-08)
309 lines
8.2 KiB
Go
309 lines
8.2 KiB
Go
package handler
|
||
|
||
import (
|
||
"net/http"
|
||
"strconv"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
|
||
"github.com/user-management-system/internal/domain"
|
||
"github.com/user-management-system/internal/service"
|
||
)
|
||
|
||
// RoleHandler handles role management requests
|
||
type RoleHandler struct {
|
||
roleService *service.RoleService
|
||
}
|
||
|
||
// NewRoleHandler creates a new RoleHandler
|
||
func NewRoleHandler(roleService *service.RoleService) *RoleHandler {
|
||
return &RoleHandler{roleService: roleService}
|
||
}
|
||
|
||
// CreateRole 创建角色
|
||
// @Summary 创建角色
|
||
// @Description 创建新角色（仅管理员）
|
||
// @Tags 角色管理
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param request body service.CreateRoleRequest true "角色信息"
|
||
// @Success 201 {object} Response{data=domain.Role} "角色创建成功"
|
||
// @Failure 400 {object} Response "请求参数错误"
|
||
// @Failure 403 {object} Response "无权限"
|
||
// @Router /api/v1/roles [post]
|
||
func (h *RoleHandler) CreateRole(c *gin.Context) {
|
||
var req service.CreateRoleRequest
|
||
if err := c.ShouldBindJSON(&req); err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
|
||
return
|
||
}
|
||
|
||
role, err := h.roleService.CreateRole(c.Request.Context(), &req)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusCreated, gin.H{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": role,
|
||
})
|
||
}
|
||
|
||
// ListRoles 获取角色列表
|
||
// @Summary 获取角色列表
|
||
// @Description 获取系统角色列表
|
||
// @Tags 角色管理
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Success 200 {object} Response{data=RoleListResponse} "角色列表"
|
||
// @Router /api/v1/roles [get]
|
||
func (h *RoleHandler) ListRoles(c *gin.Context) {
|
||
var req service.ListRoleRequest
|
||
if err := c.ShouldBindQuery(&req); err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
|
||
return
|
||
}
|
||
|
||
roles, total, err := h.roleService.ListRoles(c.Request.Context(), &req)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": gin.H{
|
||
"items": roles,
|
||
"total": total,
|
||
},
|
||
})
|
||
}
|
||
|
||
// GetRole 获取角色详情
|
||
// @Summary 获取角色详情
|
||
// @Description 根据ID获取角色详细信息
|
||
// @Tags 角色管理
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param id path int true "角色ID"
|
||
// @Success 200 {object} Response{data=domain.Role} "角色信息"
|
||
// @Failure 404 {object} Response "角色不存在"
|
||
// @Router /api/v1/roles/{id} [get]
|
||
func (h *RoleHandler) GetRole(c *gin.Context) {
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid role id"})
|
||
return
|
||
}
|
||
|
||
role, err := h.roleService.GetRole(c.Request.Context(), id)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": role,
|
||
})
|
||
}
|
||
|
||
// UpdateRole 更新角色
|
||
// @Summary 更新角色
|
||
// @Description 更新角色信息（仅管理员）
|
||
// @Tags 角色管理
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param id path int true "角色ID"
|
||
// @Param request body service.UpdateRoleRequest true "更新信息"
|
||
// @Success 200 {object} Response{data=domain.Role} "更新成功"
|
||
// @Failure 400 {object} Response "请求参数错误"
|
||
// @Failure 403 {object} Response "无权限"
|
||
// @Failure 404 {object} Response "角色不存在"
|
||
// @Router /api/v1/roles/{id} [put]
|
||
func (h *RoleHandler) UpdateRole(c *gin.Context) {
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid role id"})
|
||
return
|
||
}
|
||
|
||
var req service.UpdateRoleRequest
|
||
if err := c.ShouldBindJSON(&req); err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
|
||
return
|
||
}
|
||
|
||
role, err := h.roleService.UpdateRole(c.Request.Context(), id, &req)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": role,
|
||
})
|
||
}
|
||
|
||
// DeleteRole 删除角色
|
||
// @Summary 删除角色
|
||
// @Description 删除角色（仅管理员）
|
||
// @Tags 角色管理
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param id path int true "角色ID"
|
||
// @Success 200 {object} Response "删除成功"
|
||
// @Failure 403 {object} Response "无权限"
|
||
// @Failure 404 {object} Response "角色不存在"
|
||
// @Router /api/v1/roles/{id} [delete]
|
||
func (h *RoleHandler) DeleteRole(c *gin.Context) {
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid role id"})
|
||
return
|
||
}
|
||
|
||
if err := h.roleService.DeleteRole(c.Request.Context(), id); err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "role deleted",
|
||
})
|
||
}
|
||
|
||
// UpdateRoleStatus 更新角色状态
|
||
// @Summary 更新角色状态
|
||
// @Description 更新角色状态（enabled/disabled）（仅管理员）
|
||
// @Tags 角色管理
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param id path int true "角色ID"
|
||
// @Param request body UpdateRoleStatusRequest true "状态信息"
|
||
// @Success 200 {object} Response "状态更新成功"
|
||
// @Failure 400 {object} Response "无效的状态值"
|
||
// @Failure 403 {object} Response "无权限"
|
||
// @Failure 404 {object} Response "角色不存在"
|
||
// @Router /api/v1/roles/{id}/status [put]
|
||
func (h *RoleHandler) UpdateRoleStatus(c *gin.Context) {
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid role id"})
|
||
return
|
||
}
|
||
|
||
var req struct {
|
||
Status string `json:"status" binding:"required"`
|
||
}
|
||
|
||
if err := c.ShouldBindJSON(&req); err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
|
||
return
|
||
}
|
||
|
||
var status domain.RoleStatus
|
||
switch req.Status {
|
||
case "enabled", "1":
|
||
status = domain.RoleStatusEnabled
|
||
case "disabled", "0":
|
||
status = domain.RoleStatusDisabled
|
||
default:
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid status"})
|
||
return
|
||
}
|
||
|
||
err = h.roleService.UpdateRoleStatus(c.Request.Context(), id, status)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "status updated",
|
||
})
|
||
}
|
||
|
||
// GetRolePermissions 获取角色权限
|
||
// @Summary 获取角色权限列表
|
||
// @Description 获取角色的权限列表
|
||
// @Tags 角色管理
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param id path int true "角色ID"
|
||
// @Success 200 {object} Response{data=[]domain.Permission} "权限列表"
|
||
// @Failure 404 {object} Response "角色不存在"
|
||
// @Router /api/v1/roles/{id}/permissions [get]
|
||
func (h *RoleHandler) GetRolePermissions(c *gin.Context) {
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid role id"})
|
||
return
|
||
}
|
||
|
||
perms, err := h.roleService.GetRolePermissions(c.Request.Context(), id)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": perms,
|
||
})
|
||
}
|
||
|
||
// AssignPermissions 分配角色权限
|
||
// @Summary 分配角色权限
|
||
// @Description 为角色分配权限（替换现有权限）（仅管理员）
|
||
// @Tags 角色管理
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param id path int true "角色ID"
|
||
// @Param request body AssignPermissionsRequest true "权限ID列表"
|
||
// @Success 200 {object} Response "权限分配成功"
|
||
// @Failure 400 {object} Response "请求参数错误"
|
||
// @Failure 403 {object} Response "无权限"
|
||
// @Failure 404 {object} Response "角色不存在"
|
||
// @Router /api/v1/roles/{id}/permissions [post]
|
||
func (h *RoleHandler) AssignPermissions(c *gin.Context) {
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "invalid role id"})
|
||
return
|
||
}
|
||
|
||
var req struct {
|
||
PermissionIDs []int64 `json:"permission_ids"`
|
||
}
|
||
|
||
if err := c.ShouldBindJSON(&req); err != nil {
|
||
c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
|
||
return
|
||
}
|
||
|
||
err = h.roleService.AssignPermissions(c.Request.Context(), id, req.PermissionIDs)
|
||
if err != nil {
|
||
handleError(c, err)
|
||
return
|
||
}
|
||
|
||
c.JSON(http.StatusOK, gin.H{
|
||
"code": 0,
|
||
"message": "permissions assigned",
|
||
})
|
||
}
|