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

@@ -22,6 +22,17 @@ func NewDeviceHandler(deviceService *service.DeviceService) *DeviceHandler {
 	return &DeviceHandler{deviceService: deviceService}
 }
 
+// CreateDevice 创建设备
+// @Summary 创建设备记录
+// @Description 当前用户创建设备记录
+// @Tags 设备管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body service.CreateDeviceRequest true "设备信息"
+// @Success 201 {object} Response{data=domain.Device} "设备创建成功"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/devices [post]
 func (h *DeviceHandler) CreateDevice(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -48,6 +59,17 @@ func (h *DeviceHandler) CreateDevice(c *gin.Context) {
 	})
 }
 
+// GetMyDevices 获取我的设备列表
+// @Summary 获取当前用户的设备列表
+// @Description 获取当前用户的所有设备记录
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} Response{data=DeviceListResponse} "设备列表"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/devices [get]
 func (h *DeviceHandler) GetMyDevices(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -76,6 +98,16 @@ func (h *DeviceHandler) GetMyDevices(c *gin.Context) {
 	})
 }
 
+// GetDevice 获取设备详情
+// @Summary 获取设备详情
+// @Description 根据ID获取设备详细信息
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "设备ID"
+// @Success 200 {object} Response{data=domain.Device} "设备信息"
+// @Failure 404 {object} Response "设备不存在"
+// @Router /api/v1/devices/{id} [get]
 func (h *DeviceHandler) GetDevice(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -96,6 +128,19 @@ func (h *DeviceHandler) GetDevice(c *gin.Context) {
 	})
 }
 
+// UpdateDevice 更新设备
+// @Summary 更新设备信息
+// @Description 更新设备的基本信息
+// @Tags 设备管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "设备ID"
+// @Param request body service.UpdateDeviceRequest true "更新信息"
+// @Success 200 {object} Response{data=domain.Device} "更新成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 404 {object} Response "设备不存在"
+// @Router /api/v1/devices/{id} [put]
 func (h *DeviceHandler) UpdateDevice(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -122,6 +167,16 @@ func (h *DeviceHandler) UpdateDevice(c *gin.Context) {
 	})
 }
 
+// DeleteDevice 删除设备
+// @Summary 删除设备
+// @Description 删除设备记录
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "设备ID"
+// @Success 200 {object} Response "删除成功"
+// @Failure 404 {object} Response "设备不存在"
+// @Router /api/v1/devices/{id} [delete]
 func (h *DeviceHandler) DeleteDevice(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -140,6 +195,19 @@ func (h *DeviceHandler) DeleteDevice(c *gin.Context) {
 	})
 }
 
+// UpdateDeviceStatus 更新设备状态
+// @Summary 更新设备状态
+// @Description 更新设备状态（active/inactive）
+// @Tags 设备管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "设备ID"
+// @Param request body UpdateDeviceStatusRequest true "状态信息"
+// @Success 200 {object} Response "状态更新成功"
+// @Failure 400 {object} Response "无效的状态值"
+// @Failure 404 {object} Response "设备不存在"
+// @Router /api/v1/devices/{id}/status [put]
 func (h *DeviceHandler) UpdateDeviceStatus(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -178,6 +246,18 @@ func (h *DeviceHandler) UpdateDeviceStatus(c *gin.Context) {
 	})
 }
 
+// GetUserDevices 获取指定用户的设备列表
+// @Summary 获取用户设备列表
+// @Description 获取指定用户的设备列表（仅本人或管理员）
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "用户ID"
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} Response{data=DeviceListResponse} "设备列表"
+// @Failure 403 {object} Response "无权限"
+// @Router /api/v1/users/{id}/devices [get]
 func (h *DeviceHandler) GetUserDevices(c *gin.Context) {
 	// IDOR 修复：检查当前用户是否有权限查看指定用户的设备
 	currentUserID, ok := getUserIDFromContext(c)
@@ -232,7 +312,19 @@ func (h *DeviceHandler) GetUserDevices(c *gin.Context) {
 	})
 }
 
-// GetAllDevices 获取所有设备列表（管理员）
+// GetAllDevices 获取所有设备列表
+// @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=DeviceListResponse} "设备列表"
+// @Failure 403 {object} Response "无权限"
+// @Router /api/v1/admin/devices [get]
 func (h *DeviceHandler) GetAllDevices(c *gin.Context) {
 	var req service.GetAllDevicesRequest
 	if err := c.ShouldBindQuery(&req); err != nil {
@@ -280,6 +372,17 @@ type TrustDeviceRequest struct {
 }
 
 // TrustDevice 设置设备为信任设备
+// @Summary 设置设备为信任设备
+// @Description 将指定设备设置为信任设备，在信任期内免二次验证
+// @Tags 设备管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "设备ID"
+// @Param request body TrustDeviceRequest true "信任配置"
+// @Success 200 {object} Response "设置成功"
+// @Failure 404 {object} Response "设备不存在"
+// @Router /api/v1/devices/{id}/trust [post]
 func (h *DeviceHandler) TrustDevice(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -307,7 +410,18 @@ func (h *DeviceHandler) TrustDevice(c *gin.Context) {
 	})
 }
 
-// TrustDeviceByDeviceID 根据设备标识字符串设置设备为信任状态
+// TrustDeviceByDeviceID 根据设备标识设置设备为信任状态
+// @Summary 根据设备标识设置信任
+// @Description 根据设备唯一标识字符串设置设备为信任状态
+// @Tags 设备管理
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param deviceId path string true "设备唯一标识"
+// @Param request body TrustDeviceRequest true "信任配置"
+// @Success 200 {object} Response "设置成功"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/devices/trust/{deviceId} [post]
 func (h *DeviceHandler) TrustDeviceByDeviceID(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -342,6 +456,15 @@ func (h *DeviceHandler) TrustDeviceByDeviceID(c *gin.Context) {
 }
 
 // UntrustDevice 取消设备信任状态
+// @Summary 取消设备信任
+// @Description 取消设备的信任状态
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "设备ID"
+// @Success 200 {object} Response "取消成功"
+// @Failure 404 {object} Response "设备不存在"
+// @Router /api/v1/devices/{id}/trust [delete]
 func (h *DeviceHandler) UntrustDevice(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -361,6 +484,14 @@ func (h *DeviceHandler) UntrustDevice(c *gin.Context) {
 }
 
 // GetMyTrustedDevices 获取我的信任设备列表
+// @Summary 获取信任设备列表
+// @Description 获取当前用户的信任设备列表
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} Response{data=[]domain.Device} "信任设备列表"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/devices/trusted [get]
 func (h *DeviceHandler) GetMyTrustedDevices(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -382,6 +513,16 @@ func (h *DeviceHandler) GetMyTrustedDevices(c *gin.Context) {
 }
 
 // LogoutAllOtherDevices 登出所有其他设备
+// @Summary 登出其他设备
+// @Description 登出当前用户除指定设备外的所有其他设备
+// @Tags 设备管理
+// @Produce json
+// @Security BearerAuth
+// @Param X-Device-ID header string true "当前设备ID"
+// @Success 200 {object} Response "登出成功"
+// @Failure 400 {object} Response "无效的设备ID"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/devices/logout-others [post]
 func (h *DeviceHandler) LogoutAllOtherDevices(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {