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

@@ -18,6 +18,13 @@ func NewCaptchaHandler(captchaService *service.CaptchaService) *CaptchaHandler {
 	return &CaptchaHandler{captchaService: captchaService}
 }
 
+// GenerateCaptcha 生成验证码
+// @Summary 生成验证码
+// @Description 生成图形验证码
+// @Tags 验证码
+// @Produce json
+// @Success 200 {object} Response{data=CaptchaResponse} "验证码信息"
+// @Router /api/v1/captcha/generate [get]
 func (h *CaptchaHandler) GenerateCaptcha(c *gin.Context) {
 	result, err := h.captchaService.Generate(c.Request.Context())
 	if err != nil {
@@ -35,10 +42,28 @@ func (h *CaptchaHandler) GenerateCaptcha(c *gin.Context) {
 	})
 }
 
+// GetCaptchaImage 获取验证码图片
+// @Summary 获取验证码图片
+// @Description 根据captcha_id获取验证码图片（当前未实现）
+// @Tags 验证码
+// @Produce json
+// @Param captcha_id query string false "验证码ID"
+// @Success 200 {object} Response "验证码图片"
+// @Router /api/v1/captcha/image [get]
 func (h *CaptchaHandler) GetCaptchaImage(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "success"})
 }
 
+// VerifyCaptcha 验证验证码
+// @Summary 验证验证码
+// @Description 验证用户输入的验证码是否正确
+// @Tags 验证码
+// @Accept json
+// @Produce json
+// @Param request body VerifyCaptchaRequest true "验证码信息"
+// @Success 200 {object} Response{data=VerifyResponse} "验证成功"
+// @Failure 400 {object} Response "验证码无效"
+// @Router /api/v1/captcha/verify [post]
 func (h *CaptchaHandler) VerifyCaptcha(c *gin.Context) {
 	var req struct {
 		CaptchaID string `json:"captcha_id" binding:"required"`