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/avatar_handler.go

@@ -32,7 +32,21 @@ func generateSecureToken(length int) string {
 	return hex.EncodeToString(bytes)[:length]
 }
 
-// UploadAvatar handles avatar file upload
+// UploadAvatar 上传用户头像
+// @Summary 上传用户头像
+// @Description 上传并更新用户头像（仅本人或管理员）
+// @Tags 用户头像
+// @Accept multipart/form-data
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "用户ID"
+// @Param avatar formData file true "头像文件（最大5MB，支持jpg/jpeg/png/gif/webp）"
+// @Success 200 {object} Response{data=AvatarResponse} "上传成功"
+// @Failure 400 {object} Response "文件无效或大小超限"
+// @Failure 401 {object} Response "未认证"
+// @Failure 403 {object} Response "无权限"
+// @Failure 404 {object} Response "用户不存在"
+// @Router /api/v1/users/{id}/avatar [post]
 func (h *AvatarHandler) UploadAvatar(c *gin.Context) {
 	userIDStr := c.Param("id")
 	userID, err := strconv.ParseInt(userIDStr, 10, 64)