docs: add Swagger annotations to 13 API handlers

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)

internal/api/handler/permission_handler.go

@@ -20,6 +20,18 @@ func NewPermissionHandler(permissionService *service.PermissionService) *Permiss
 	return &PermissionHandler{permissionService: permissionService}
 }
 
+// CreatePermission 创建权限
+// @Summary 创建权限
+// @Description 创建新的权限定义（仅管理员）
+// @Tags 权限管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body service.CreatePermissionRequest true "权限信息"
+// @Success 201 {object} Response{data=domain.Permission} "创建成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 403 {object} Response "无权限"
+// @Router /api/v1/permissions [post]
 func (h *PermissionHandler) CreatePermission(c *gin.Context) {
 	var req service.CreatePermissionRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -40,6 +52,14 @@ func (h *PermissionHandler) CreatePermission(c *gin.Context) {
 	})
 }
 
+// ListPermissions 获取权限列表
+// @Summary 获取权限列表
+// @Description 获取系统权限列表
+// @Tags 权限管理
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} Response{data=[]domain.Permission} "权限列表"
+// @Router /api/v1/permissions [get]
 func (h *PermissionHandler) ListPermissions(c *gin.Context) {
 	var req service.ListPermissionRequest
 	if err := c.ShouldBindQuery(&req); err != nil {
@@ -60,6 +80,16 @@ func (h *PermissionHandler) ListPermissions(c *gin.Context) {
 	})
 }
 
+// GetPermission 获取权限详情
+// @Summary 获取权限详情
+// @Description 根据ID获取权限详细信息
+// @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/permissions/{id} [get]
 func (h *PermissionHandler) GetPermission(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -80,6 +110,20 @@ func (h *PermissionHandler) GetPermission(c *gin.Context) {
 	})
 }
 
+// UpdatePermission 更新权限
+// @Summary 更新权限
+// @Description 更新权限信息（仅管理员）
+// @Tags 权限管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "权限ID"
+// @Param request body service.UpdatePermissionRequest true "更新信息"
+// @Success 200 {object} Response{data=domain.Permission} "更新成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 403 {object} Response "无权限"
+// @Failure 404 {object} Response "权限不存在"
+// @Router /api/v1/permissions/{id} [put]
 func (h *PermissionHandler) UpdatePermission(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -106,6 +150,17 @@ func (h *PermissionHandler) UpdatePermission(c *gin.Context) {
 	})
 }
 
+// DeletePermission 删除权限
+// @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/permissions/{id} [delete]
 func (h *PermissionHandler) DeletePermission(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -124,6 +179,20 @@ func (h *PermissionHandler) DeletePermission(c *gin.Context) {
 	})
 }
 
+// UpdatePermissionStatus 更新权限状态
+// @Summary 更新权限状态
+// @Description 更新权限状态（enabled/disabled）（仅管理员）
+// @Tags 权限管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "权限ID"
+// @Param request body UpdatePermissionStatusRequest true "状态信息"
+// @Success 200 {object} Response "状态更新成功"
+// @Failure 400 {object} Response "无效的状态值"
+// @Failure 403 {object} Response "无权限"
+// @Failure 404 {object} Response "权限不存在"
+// @Router /api/v1/permissions/{id}/status [put]
 func (h *PermissionHandler) UpdatePermissionStatus(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -162,6 +231,14 @@ func (h *PermissionHandler) UpdatePermissionStatus(c *gin.Context) {
 	})
 }
 
+// GetPermissionTree 获取权限树
+// @Summary 获取权限树
+// @Description 获取系统权限的树形结构
+// @Tags 权限管理
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} Response{data=[]domain.Permission} "权限树"
+// @Router /api/v1/permissions/tree [get]
 func (h *PermissionHandler) GetPermissionTree(c *gin.Context) {
 	tree, err := h.permissionService.GetPermissionTree(c.Request.Context())
 	if err != nil {