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

@@ -24,6 +24,17 @@ func NewLogHandler(loginLogService *service.LoginLogService, operationLogService
 	}
 }
 
+// GetMyLoginLogs 获取我的登录日志
+// @Summary 获取登录日志
+// @Description 获取当前用户的登录日志
+// @Tags 日志
+// @Produce json
+// @Security BearerAuth
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} Response{data=LoginLogListResponse} "登录日志列表"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/users/me/login-logs [get]
 func (h *LogHandler) GetMyLoginLogs(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -52,6 +63,17 @@ func (h *LogHandler) GetMyLoginLogs(c *gin.Context) {
 	})
 }
 
+// GetMyOperationLogs 获取我的操作日志
+// @Summary 获取操作日志
+// @Description 获取当前用户的操作日志
+// @Tags 日志
+// @Produce json
+// @Security BearerAuth
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} Response{data=OperationLogListResponse} "操作日志列表"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/users/me/operation-logs [get]
 func (h *LogHandler) GetMyOperationLogs(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -80,6 +102,19 @@ func (h *LogHandler) GetMyOperationLogs(c *gin.Context) {
 	})
 }
 
+// GetLoginLogs 获取登录日志列表
+// @Summary 获取登录日志列表
+// @Description 获取所有登录日志（仅管理员），支持游标分页和偏移分页
+// @Tags 日志
+// @Produce json
+// @Security BearerAuth
+// @Param cursor query string false "游标分页游标"
+// @Param size query int false "每页数量（游标模式）"
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} Response{data=LoginLogListResponse} "登录日志列表"
+// @Failure 403 {object} Response "无权限"
+// @Router /api/v1/admin/logs/login [get]
 func (h *LogHandler) GetLoginLogs(c *gin.Context) {
 	var req service.ListLoginLogRequest
 	if err := c.ShouldBindQuery(&req); err != nil {