user-system/docs/swagger.yaml

basePath: /api/v1
definitions:
  auth.OAuthProvider:
    enum:
    - wechat
    - qq
    - weibo
    - google
    - facebook
    - twitter
    - github
    - alipay
    - douyin
    type: string
    x-enum-varnames:
    - OAuthProviderWeChat
    - OAuthProviderQQ
    - OAuthProviderWeibo
    - OAuthProviderGoogle
    - OAuthProviderFacebook
    - OAuthProviderTwitter
    - OAuthProviderGitHub
    - OAuthProviderAlipay
    - OAuthProviderDouyin
  auth.OAuthProviderInfo:
    properties:
      enabled:
        type: boolean
      name:
        type: string
      provider:
        $ref: '#/definitions/auth.OAuthProvider'
    type: object
  domain.UserStatus:
    enum:
    - 0
    - 1
    - 2
    - 3
    type: integer
    x-enum-comments:
      UserStatusActive: 已激活
      UserStatusDisabled: 已禁用
      UserStatusInactive: 未激活
      UserStatusLocked: 已锁定
    x-enum-descriptions:
    - 未激活
    - 已激活
    - 已锁定
    - 已禁用
    x-enum-varnames:
    - UserStatusInactive
    - UserStatusActive
    - UserStatusLocked
    - UserStatusDisabled
  domain.Webhook:
    properties:
      created_at:
        type: string
      created_by:
        type: integer
      events:
        description: JSON 数组，订阅的事件类型
        type: string
      id:
        type: integer
      max_retries:
        type: integer
      name:
        type: string
      status:
        $ref: '#/definitions/domain.WebhookStatus'
      timeout_sec:
        type: integer
      updated_at:
        type: string
      url:
        type: string
    type: object
  domain.WebhookEventType:
    enum:
    - user.registered
    - user.login
    - user.logout
    - user.updated
    - user.deleted
    - user.locked
    - user.password_changed
    - user.password_reset
    - user.totp_enabled
    - user.totp_disabled
    - user.login_failed
    - security.anomaly_detected
    type: string
    x-enum-varnames:
    - EventUserRegistered
    - EventUserLogin
    - EventUserLogout
    - EventUserUpdated
    - EventUserDeleted
    - EventUserLocked
    - EventPasswordChanged
    - EventPasswordReset
    - EventTOTPEnabled
    - EventTOTPDisabled
    - EventLoginFailed
    - EventAnomalyDetected
  domain.WebhookStatus:
    enum:
    - 1
    - 0
    type: integer
    x-enum-varnames:
    - WebhookStatusActive
    - WebhookStatusInactive
  handler.ActivateEmailRequest:
    properties:
      token:
        type: string
    required:
    - token
    type: object
  handler.AssignPermissionsRequest:
    properties:
      permission_ids:
        items:
          type: integer
        type: array
    type: object
  handler.AssignRolesRequest:
    properties:
      role_ids:
        items:
          type: integer
        type: array
    type: object
  handler.AvatarResponse:
    properties:
      avatar_url:
        type: string
      thumbnail:
        type: string
    type: object
  handler.BootstrapAdminRequest:
    properties:
      email:
        type: string
      password:
        type: string
      username:
        type: string
    type: object
  handler.CSRFTokenResponse:
    properties:
      token:
        type: string
    type: object
  handler.CaptchaResponse:
    properties:
      captcha_id:
        type: string
      image:
        type: string
    type: object
  handler.CreateAdminRequest:
    properties:
      email:
        type: string
      nickname:
        type: string
      password:
        type: string
      username:
        type: string
    type: object
  handler.CreateUserRequest:
    properties:
      email:
        type: string
      nickname:
        type: string
      password:
        type: string
      phone:
        type: string
      username:
        type: string
    type: object
  handler.CustomFieldValuesResponse:
    additionalProperties:
      type: string
    type: object
  handler.DeviceListResponse:
    properties:
      cursor:
        type: string
      has_more:
        type: boolean
      items: {}
      next_cursor:
        type: string
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  handler.DisableTOTPRequest:
    properties:
      code:
        type: string
    type: object
  handler.EnableTOTPRequest:
    properties:
      code:
        type: string
    type: object
  handler.ForgotPasswordByPhoneRequest:
    properties:
      phone:
        type: string
    required:
    - phone
    type: object
  handler.ForgotPasswordRequest:
    properties:
      email:
        type: string
    type: object
  handler.IntrospectResponse:
    properties:
      active:
        type: boolean
      exp:
        type: integer
      scope:
        type: string
      user_id:
        type: integer
      username:
        type: string
    type: object
  handler.LoginByEmailCodeRequest:
    properties:
      code:
        type: string
      device_browser:
        type: string
      device_id:
        type: string
      device_name:
        type: string
      device_os:
        type: string
      email:
        type: string
    type: object
  handler.LoginLogListResponse:
    properties:
      cursor:
        type: string
      has_more:
        type: boolean
      items: {}
      list: {}
      next_cursor:
        type: string
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  handler.OAuthProvidersResponse:
    properties:
      providers:
        items:
          type: string
        type: array
    type: object
  handler.OperationLogListResponse:
    properties:
      cursor:
        type: string
      has_more:
        type: boolean
      items: {}
      list: {}
      next_cursor:
        type: string
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  handler.RefreshTokenRequest:
    properties:
      refresh_token:
        type: string
    type: object
  handler.ResendActivationRequest:
    properties:
      email:
        type: string
    type: object
  handler.ResetPasswordByPhoneRequest:
    properties:
      code:
        type: string
      new_password:
        type: string
      phone:
        type: string
    required:
    - code
    - new_password
    - phone
    type: object
  handler.ResetPasswordRequest:
    properties:
      new_password:
        type: string
      token:
        type: string
    type: object
  handler.Response:
    properties:
      code:
        type: integer
      data: {}
      message:
        type: string
    type: object
  handler.RoleListResponse:
    properties:
      items: {}
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  handler.SMSLoginRequest:
    properties:
      code:
        type: string
      device_browser:
        type: string
      device_id:
        type: string
      device_name:
        type: string
      device_os:
        type: string
      phone:
        type: string
    required:
    - code
    - phone
    type: object
  handler.SendEmailCodeRequest:
    properties:
      email:
        type: string
    type: object
  handler.SetUserFieldValuesRequest:
    properties:
      values:
        additionalProperties:
          type: string
        type: object
    type: object
  handler.SwaggerCustomField:
    properties:
      active:
        type: boolean
      created_at:
        type: string
      field_key:
        type: string
      field_type:
        type: string
      help_text:
        type: string
      id:
        type: integer
      name:
        type: string
      options:
        type: string
      placeholder:
        type: string
      required:
        type: boolean
      sort_order:
        type: integer
      updated_at:
        type: string
    type: object
  handler.SwaggerDevice:
    properties:
      created_at:
        type: string
      current:
        type: boolean
      device_browser:
        type: string
      device_id:
        type: string
      device_name:
        type: string
      device_os:
        type: string
      device_type:
        type: integer
      id:
        type: integer
      ip:
        type: string
      is_trusted:
        type: boolean
      last_active_at:
        type: string
      last_used_at:
        type: string
      location:
        type: string
      status:
        type: integer
      trusted_until:
        type: string
      updated_at:
        type: string
      user_id:
        type: integer
    type: object
  handler.SwaggerPermission:
    properties:
      code:
        type: string
      created_at:
        type: string
      description:
        type: string
      icon:
        type: string
      id:
        type: integer
      method:
        type: string
      name:
        type: string
      parent_id:
        type: integer
      path:
        type: string
      sort:
        type: integer
      status:
        type: integer
      type:
        type: integer
      updated_at:
        type: string
    type: object
  handler.SwaggerRole:
    properties:
      code:
        type: string
      created_at:
        type: string
      description:
        type: string
      id:
        type: integer
      is_system:
        type: boolean
      name:
        type: string
      sort:
        type: integer
      status:
        type: integer
      updated_at:
        type: string
    type: object
  handler.SwaggerTheme:
    properties:
      accent_color:
        type: string
      background_color:
        type: string
      created_at:
        type: string
      error_color:
        type: string
      id:
        type: integer
      info_color:
        type: string
      is_default:
        type: boolean
      name:
        type: string
      primary_color:
        type: string
      secondary_color:
        type: string
      success_color:
        type: string
      text_color:
        type: string
      updated_at:
        type: string
      warning_color:
        type: string
    type: object
  handler.TOTPSetupResponse:
    properties:
      qr_code_base64:
        type: string
      recovery_codes:
        items:
          type: string
        type: array
      secret:
        type: string
    type: object
  handler.TOTPStatusResponse:
    properties:
      enabled:
        type: boolean
    type: object
  handler.TOTPVerifyRequest:
    properties:
      code:
        type: string
      device_id:
        type: string
      temp_token:
        type: string
      user_id:
        type: integer
    type: object
  handler.TokenResponse:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      scope:
        type: string
      token_type:
        type: string
    type: object
  handler.TrustDeviceRequest:
    properties:
      trust_duration:
        description: 信任持续时间，如 "30d" 表示30天
        type: string
    type: object
  handler.UpdateDeviceStatusRequest:
    properties:
      status:
        type: string
    type: object
  handler.UpdatePasswordRequest:
    properties:
      new_password:
        type: string
      old_password:
        type: string
    type: object
  handler.UpdatePermissionStatusRequest:
    properties:
      status:
        type: string
    type: object
  handler.UpdateRoleStatusRequest:
    properties:
      status:
        type: string
    type: object
  handler.UpdateStatusRequest:
    properties:
      status:
        type: string
    type: object
  handler.UpdateUserRequest:
    properties:
      email:
        type: string
      nickname:
        type: string
    type: object
  handler.UserInfoResponse:
    properties:
      user_id:
        type: integer
      username:
        type: string
    type: object
  handler.UserListResponse:
    properties:
      has_more:
        type: boolean
      items: {}
      limit:
        type: integer
      next_cursor:
        type: string
      offset:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
      users: {}
    type: object
  handler.UserResponse:
    properties:
      email:
        type: string
      id:
        type: integer
      nickname:
        type: string
      status:
        type: string
      username:
        type: string
    type: object
  handler.ValidateResetTokenRequest:
    properties:
      token:
        type: string
    required:
    - token
    type: object
  handler.ValidateTokenResponse:
    properties:
      valid:
        type: boolean
    type: object
  handler.VerifyCaptchaRequest:
    properties:
      answer:
        type: string
      captcha_id:
        type: string
    type: object
  handler.VerifyResponse:
    properties:
      verified:
        type: boolean
    type: object
  handler.VerifyTOTPRequest:
    properties:
      code:
        type: string
      device_id:
        type: string
    type: object
  handler.VerifyTOTPResponse:
    properties:
      verified:
        type: boolean
    type: object
  service.AuthCapabilities:
    properties:
      admin_bootstrap_required:
        type: boolean
      email_activation:
        type: boolean
      email_code:
        type: boolean
      oauth_providers:
        items:
          $ref: '#/definitions/auth.OAuthProviderInfo'
        type: array
      password:
        type: boolean
      password_reset:
        type: boolean
      sms_code:
        type: boolean
    type: object
  service.BatchDeleteRequest:
    properties:
      ids:
        items:
          type: integer
        minItems: 1
        type: array
    required:
    - ids
    type: object
  service.BatchUpdateStatusRequest:
    properties:
      ids:
        items:
          type: integer
        minItems: 1
        type: array
      status:
        $ref: '#/definitions/domain.UserStatus'
    required:
    - ids
    - status
    type: object
  service.CreateDeviceRequest:
    properties:
      device_browser:
        type: string
      device_id:
        type: string
      device_name:
        type: string
      device_os:
        type: string
      device_type:
        type: integer
      ip:
        type: string
      location:
        type: string
    required:
    - device_id
    type: object
  service.CreateFieldRequest:
    properties:
      default:
        type: string
      field_key:
        type: string
      max_len:
        type: integer
      max_val:
        type: number
      min_len:
        type: integer
      min_val:
        type: number
      name:
        type: string
      options:
        type: string
      required:
        type: boolean
      sort:
        type: integer
      type:
        type: integer
    required:
    - field_key
    - name
    - type
    type: object
  service.CreatePermissionRequest:
    properties:
      code:
        type: string
      description:
        type: string
      icon:
        type: string
      method:
        type: string
      name:
        type: string
      parent_id:
        type: integer
      path:
        type: string
      sort:
        type: integer
      type:
        type: integer
    required:
    - code
    - name
    - type
    type: object
  service.CreateRoleRequest:
    properties:
      code:
        type: string
      description:
        type: string
      name:
        type: string
      parent_id:
        type: integer
    required:
    - code
    - name
    type: object
  service.CreateThemeRequest:
    properties:
      background_color:
        type: string
      custom_css:
        type: string
      custom_js:
        type: string
      favicon_url:
        type: string
      is_default:
        type: boolean
      logo_url:
        type: string
      name:
        type: string
      primary_color:
        type: string
      secondary_color:
        type: string
      text_color:
        type: string
    required:
    - name
    type: object
  service.CreateWebhookRequest:
    properties:
      events:
        items:
          $ref: '#/definitions/domain.WebhookEventType'
        minItems: 1
        type: array
      name:
        type: string
      secret:
        type: string
      url:
        type: string
    required:
    - events
    - name
    - url
    type: object
  service.DashboardStats:
    properties:
      logins:
        $ref: '#/definitions/service.LoginStats'
      users:
        $ref: '#/definitions/service.UserStats'
    type: object
  service.FeaturesInfo:
    properties:
      data_export_enabled:
        type: boolean
      data_import_enabled:
        type: boolean
      email_verification:
        type: boolean
      login_log_enabled:
        type: boolean
      oauth_providers:
        items:
          type: string
        type: array
      operation_log_enabled:
        type: boolean
      phone_verification:
        type: boolean
      sso_enabled:
        type: boolean
    type: object
  service.LoginRequest:
    properties:
      account:
        type: string
      device_browser:
        description: 浏览器
        type: string
      device_id:
        description: 设备唯一标识
        type: string
      device_name:
        description: 设备名称
        type: string
      device_os:
        description: 操作系统
        type: string
      email:
        type: string
      password:
        type: string
      phone:
        type: string
      remember:
        description: 记住登录
        type: boolean
      username:
        type: string
    type: object
  service.LoginResponse:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      refresh_token:
        type: string
      requires_totp:
        description: RequiresTOTP 指示登录需要额外的TOTP验证（当设备未信任时）
        type: boolean
      temp_token:
        description: TempToken 临时令牌，用于TOTP验证阶段（短生命周期，不可用于常规API）
        type: string
      user:
        $ref: '#/definitions/service.UserInfo'
      user_id:
        description: UserID 当RequiresTOTP为true时返回，用于后续TOTP验证
        type: integer
    type: object
  service.LoginStats:
    properties:
      logins_today_failed:
        type: integer
      logins_today_success:
        type: integer
      logins_week:
        type: integer
    type: object
  service.LogoutRequest:
    properties:
      access_token:
        type: string
      refresh_token:
        type: string
    type: object
  service.RegisterRequest:
    properties:
      email:
        type: string
      nickname:
        type: string
      password:
        type: string
      phone:
        type: string
      phone_code:
        type: string
      username:
        type: string
    required:
    - password
    - username
    type: object
  service.SecurityInfo:
    properties:
      device_trust_duration:
        description: 秒
        type: integer
      login_fail_duration:
        description: 分钟
        type: integer
      login_fail_lock:
        type: boolean
      login_fail_threshold:
        type: integer
      password_history:
        type: integer
      password_min_length:
        type: integer
      password_require_lowercase:
        type: boolean
      password_require_numbers:
        type: boolean
      password_require_symbols:
        type: boolean
      password_require_uppercase:
        type: boolean
      session_timeout:
        description: 秒
        type: integer
      totp_enabled:
        type: boolean
    type: object
  service.SendCodeRequest:
    properties:
      phone:
        type: string
      purpose:
        type: string
      scene:
        type: string
    required:
    - phone
    type: object
  service.SystemInfo:
    properties:
      description:
        type: string
      environment:
        type: string
      name:
        type: string
      version:
        type: string
    type: object
  service.SystemSettings:
    properties:
      features:
        $ref: '#/definitions/service.FeaturesInfo'
      security:
        $ref: '#/definitions/service.SecurityInfo'
      system:
        $ref: '#/definitions/service.SystemInfo'
    type: object
  service.UpdateDeviceRequest:
    properties:
      device_browser:
        type: string
      device_name:
        type: string
      device_os:
        type: string
      device_type:
        type: integer
      ip:
        type: string
      location:
        type: string
      status:
        type: integer
    type: object
  service.UpdateFieldRequest:
    properties:
      default:
        type: string
      max_len:
        type: integer
      max_val:
        type: number
      min_len:
        type: integer
      min_val:
        type: number
      name:
        type: string
      options:
        type: string
      required:
        type: boolean
      sort:
        type: integer
      status:
        type: integer
      type:
        type: integer
    type: object
  service.UpdatePermissionRequest:
    properties:
      description:
        type: string
      icon:
        type: string
      method:
        type: string
      name:
        type: string
      parent_id:
        type: integer
      path:
        type: string
      sort:
        type: integer
    type: object
  service.UpdateRoleRequest:
    properties:
      description:
        type: string
      name:
        type: string
      parent_id:
        type: integer
    type: object
  service.UpdateThemeRequest:
    properties:
      background_color:
        type: string
      custom_css:
        type: string
      custom_js:
        type: string
      enabled:
        type: boolean
      favicon_url:
        type: string
      is_default:
        type: boolean
      logo_url:
        type: string
      primary_color:
        type: string
      secondary_color:
        type: string
      text_color:
        type: string
    type: object
  service.UpdateWebhookRequest:
    properties:
      events:
        items:
          $ref: '#/definitions/domain.WebhookEventType'
        type: array
      name:
        type: string
      status:
        $ref: '#/definitions/domain.WebhookStatus'
      url:
        type: string
    type: object
  service.UserInfo:
    properties:
      avatar:
        type: string
      email:
        type: string
      id:
        type: integer
      nickname:
        type: string
      phone:
        type: string
      status:
        $ref: '#/definitions/domain.UserStatus'
      username:
        type: string
    type: object
  service.UserStats:
    properties:
      active_users:
        type: integer
      disabled_users:
        type: integer
      inactive_users:
        type: integer
      locked_users:
        type: integer
      new_users_month:
        type: integer
      new_users_today:
        type: integer
      new_users_week:
        type: integer
      total_users:
        type: integer
    type: object
info:
  contact: {}
  description: API for user management, authentication, authorization, and administration.
  title: User Management System API
  version: "1.0"
paths:
  /api/v1/admin/admins:
    get:
      description: 获取所有管理员用户列表（仅管理员）
      produces:
      - application/json
      responses:
        "200":
          description: 管理员列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.UserResponse'
                  type: array
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取管理员列表
      tags:
      - 用户管理
    post:
      consumes:
      - application/json
      description: 创建新管理员账号（仅管理员）
      parameters:
      - description: 管理员信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.CreateAdminRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 管理员创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.UserResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建管理员
      tags:
      - 用户管理
  /api/v1/admin/admins/{id}:
    delete:
      description: 删除管理员角色（最后管理员保护、自删保护）（仅管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 管理员已移除
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 无效的用户ID
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "409":
          description: 无法删除（最后管理员或自删）
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除管理员
      tags:
      - 用户管理
  /api/v1/admin/devices:
    get:
      description: 获取所有设备列表（仅管理员），支持游标分页和偏移分页
      parameters:
      - description: 游标分页游标
        in: query
        name: cursor
        type: string
      - description: 每页数量（游标模式）
        in: query
        name: size
        type: integer
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 设备列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.DeviceListResponse'
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取所有设备列表
      tags:
      - 设备管理
  /api/v1/admin/settings:
    get:
      description: 获取系统配置、安全设置和功能开关信息
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.SystemSettings'
              type: object
      security:
      - BearerAuth: []
      summary: 获取系统设置
      tags:
      - 系统设置
  /api/v1/admin/stats/dashboard:
    get:
      description: 获取系统仪表盘统计数据（仅管理员）
      produces:
      - application/json
      responses:
        "200":
          description: 仪表盘数据
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.DashboardStats'
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取仪表盘统计
      tags:
      - 统计
  /api/v1/admin/stats/users:
    get:
      description: 获取用户统计数据（仅管理员）
      produces:
      - application/json
      responses:
        "200":
          description: 用户统计数据
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.UserStats'
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取用户统计
      tags:
      - 统计
  /api/v1/admin/users/export:
    get:
      consumes:
      - application/json
      description: 导出用户数据为 CSV 或 Excel 格式
      parameters:
      - default: csv
        description: 导出格式
        enum:
        - csv
        - excel
        in: query
        name: format
        type: string
      - description: 导出字段，逗号分隔
        in: query
        name: fields
        type: string
      - description: 关键词过滤
        in: query
        name: keyword
        type: string
      - description: 用户状态过滤
        in: query
        name: status
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 用户数据文件
          schema:
            type: file
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 导出用户数据
      tags:
      - 数据导入导出
  /api/v1/admin/users/import:
    post:
      consumes:
      - multipart/form-data
      description: 从 CSV 或 Excel 文件导入用户数据
      parameters:
      - description: 导入文件
        in: formData
        name: file
        required: true
        type: file
      - default: csv
        description: 文件格式
        enum:
        - csv
        - excel
        in: query
        name: format
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 导入结果
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 导入用户数据
      tags:
      - 数据导入导出
  /api/v1/admin/users/import/template:
    get:
      description: 下载用户批量导入的 CSV 或 Excel 模板
      parameters:
      - default: csv
        description: 模板格式
        enum:
        - csv
        - excel
        in: query
        name: format
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 导入模板文件
          schema:
            type: file
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取用户导入模板
      tags:
      - 数据导入导出
  /api/v1/auth/2fa/disable:
    post:
      consumes:
      - application/json
      description: 输入验证码禁用 TOTP 两步验证
      parameters:
      - description: 验证码
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.DisableTOTPRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 禁用成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证或验证码错误
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 禁用 TOTP 两步验证
      tags:
      - 两步验证
  /api/v1/auth/2fa/enable:
    post:
      consumes:
      - application/json
      description: 输入验证码启用 TOTP 两步验证
      parameters:
      - description: 验证码
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.EnableTOTPRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 启用成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证或验证码错误
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 启用 TOTP 两步验证
      tags:
      - 两步验证
  /api/v1/auth/2fa/setup:
    get:
      consumes:
      - application/json
      description: 为当前用户设置 TOTP 两步验证，返回密钥和二维码
      produces:
      - application/json
      responses:
        "200":
          description: TOTP设置信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.TOTPSetupResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 设置 TOTP 两步验证
      tags:
      - 两步验证
  /api/v1/auth/2fa/status:
    get:
      description: 获取当前用户的TOTP两步验证状态
      produces:
      - application/json
      responses:
        "200":
          description: TOTP状态
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.TOTPStatusResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取TOTP状态
      tags:
      - 两步验证
  /api/v1/auth/2fa/verify:
    post:
      consumes:
      - application/json
      description: 在登录或其他敏感操作时验证 TOTP 验证码
      parameters:
      - description: 验证码
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.VerifyTOTPRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 验证结果
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.VerifyTOTPResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证或验证码错误
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 验证 TOTP 验证码
      tags:
      - 两步验证
  /api/v1/auth/activate-email:
    post:
      consumes:
      - application/json
      description: 使用邮箱激活token激活用户账号
      parameters:
      - description: 激活请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ActivateEmailRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 激活成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: token缺失
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: token无效或已过期
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 激活用户邮箱
      tags:
      - 邮箱认证
  /api/v1/auth/bootstrap-admin:
    post:
      consumes:
      - application/json
      description: 在系统未配置管理员时，创建第一个管理员账号（需要BOOTSTRAP_SECRET）
      parameters:
      - description: 引导密钥
        in: header
        name: X-Bootstrap-Secret
        required: true
        type: string
      - description: 管理员信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.BootstrapAdminRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 管理员创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.UserInfo'
              type: object
        "401":
          description: 引导密钥无效
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 引导初始化未授权
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BootstrapSecret: []
      summary: 引导初始化管理员账号
      tags:
      - 系统初始化
  /api/v1/auth/capabilities:
    get:
      description: 返回系统支持的认证方式和配置（如是否需要邮件激活、是否支持OAuth等）
      produces:
      - application/json
      responses:
        "200":
          description: 认证能力配置
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.AuthCapabilities'
              type: object
      summary: 获取系统认证能力
      tags:
      - 认证
  /api/v1/auth/captcha:
    get:
      description: 生成图形验证码
      produces:
      - application/json
      responses:
        "200":
          description: 验证码信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.CaptchaResponse'
              type: object
      summary: 生成验证码
      tags:
      - 验证码
  /api/v1/auth/captcha/image:
    get:
      description: 根据captcha_id获取验证码图片（当前未实现）
      parameters:
      - description: 验证码ID
        in: query
        name: captcha_id
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 验证码图片
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 获取验证码图片
      tags:
      - 验证码
  /api/v1/auth/captcha/verify:
    post:
      consumes:
      - application/json
      description: 验证用户输入的验证码是否正确
      parameters:
      - description: 验证码信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.VerifyCaptchaRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 验证成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.VerifyResponse'
              type: object
        "400":
          description: 验证码无效
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 验证验证码
      tags:
      - 验证码
  /api/v1/auth/csrf-token:
    get:
      description: 由于系统使用JWT Bearer Token认证，不存在CSRF风险，返回空token
      produces:
      - application/json
      responses:
        "200":
          description: CSRF token（为空）
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.CSRFTokenResponse'
              type: object
      summary: 获取CSRF令牌
      tags:
      - 认证
  /api/v1/auth/forgot-password:
    post:
      consumes:
      - application/json
      description: 请求密码重置邮件
      parameters:
      - description: 邮箱地址
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ForgotPasswordRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 密码重置邮件已发送
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 忘记密码
      tags:
      - 密码重置
  /api/v1/auth/forgot-password/phone:
    post:
      consumes:
      - application/json
      description: 向绑定的手机号发送短信验证码用于重置密码
      parameters:
      - description: 手机号
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ForgotPasswordByPhoneRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 验证码发送成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "503":
          description: 短信服务未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 发送短信验证码（忘记密码）
      tags:
      - 密码重置
  /api/v1/auth/login:
    post:
      consumes:
      - application/json
      description: 用户使用账号密码登录，支持多种认证方式（用户名/邮箱/手机号）
      parameters:
      - description: 登录请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 登录成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.LoginResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
        "401":
          description: 认证失败
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
        "429":
          description: 登录尝试过多
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
      summary: 用户登录
      tags:
      - 认证
  /api/v1/auth/login/code:
    post:
      consumes:
      - application/json
      description: 使用手机号和短信验证码登录（带设备信息以支持设备信任链路）
      parameters:
      - description: 登录请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.SMSLoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 登录成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 验证码错误
          schema:
            $ref: '#/definitions/handler.Response'
        "503":
          description: 短信登录未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 短信验证码登录
      tags:
      - 短信验证
  /api/v1/auth/login/email-code:
    post:
      consumes:
      - application/json
      description: 使用邮箱和验证码完成登录
      parameters:
      - description: 登录请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.LoginByEmailCodeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 登录成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.LoginResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 验证码错误或已过期
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 邮箱验证码登录
      tags:
      - 邮箱认证
  /api/v1/auth/login/totp-verify:
    post:
      consumes:
      - application/json
      description: 当登录返回requires_totp=true时，使用此接口完成TOTP验证
      parameters:
      - description: TOTP验证请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.TOTPVerifyRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 验证成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.LoginResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: TOTP验证失败
          schema:
            $ref: '#/definitions/handler.Response'
      summary: TOTP验证（密码登录后）
      tags:
      - 认证
  /api/v1/auth/logout:
    post:
      consumes:
      - application/json
      description: 使当前 access_token 和 refresh_token 失效
      parameters:
      - description: 登出请求（token可从header获取）
        in: body
        name: request
        schema:
          $ref: '#/definitions/service.LogoutRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 登出成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
      security:
      - BearerAuth: []
      summary: 用户登出
      tags:
      - 认证
  /api/v1/auth/oauth/{provider}:
    get:
      description: 发起OAuth登录流程（当前未配置）
      parameters:
      - description: OAuth提供商（如 github, google）
        in: path
        name: provider
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OAuth未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: OAuth登录初始化
      tags:
      - OAuth
  /api/v1/auth/oauth/{provider}/callback:
    get:
      description: 处理OAuth provider回调（当前未配置）
      parameters:
      - description: OAuth提供商
        in: path
        name: provider
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OAuth未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: OAuth回调处理
      tags:
      - OAuth
  /api/v1/auth/oauth/exchange:
    post:
      consumes:
      - application/json
      description: 使用OAuth code交换access_token（当前未配置）
      parameters:
      - description: OAuth提供商
        in: path
        name: provider
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OAuth未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: OAuth令牌交换
      tags:
      - OAuth
  /api/v1/auth/oauth/providers:
    get:
      description: 返回系统已配置并启用的OAuth提供商列表
      produces:
      - application/json
      responses:
        "200":
          description: 提供商列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.OAuthProvidersResponse'
              type: object
      summary: 获取OAuth提供商列表
      tags:
      - OAuth
  /api/v1/auth/password/validate:
    post:
      consumes:
      - application/json
      description: 验证密码重置链接中的 Token 是否有效
      parameters:
      - description: 重置 Token
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ValidateResetTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Token验证结果
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.ValidateTokenResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 验证密码重置 Token
      tags:
      - 密码重置
  /api/v1/auth/refresh:
    post:
      consumes:
      - application/json
      description: 使用 refresh_token 获取新的 access_token
      parameters:
      - description: 刷新令牌请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.RefreshTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 刷新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.LoginResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
        "401":
          description: refresh_token无效或已过期
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
      summary: 刷新访问令牌
      tags:
      - 认证
  /api/v1/auth/register:
    post:
      consumes:
      - application/json
      description: 用户注册新账号，支持用户名+密码或手机号注册
      parameters:
      - description: 注册请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.RegisterRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 注册成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.UserInfo'
              type: object
        "400":
          description: 请求参数错误
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
        "409":
          description: 用户已存在
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
      summary: 用户注册
      tags:
      - 认证
  /api/v1/auth/resend-activation:
    post:
      consumes:
      - application/json
      description: 重新发送账号激活邮件（防枚举：无论邮箱是否注册都返回成功）
      parameters:
      - description: 邮箱地址
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ResendActivationRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 激活邮件已发送（如果邮箱已注册）
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 邮箱格式错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 重发激活邮件
      tags:
      - 邮箱认证
  /api/v1/auth/reset-password:
    post:
      consumes:
      - application/json
      description: 使用 Token 重置密码
      parameters:
      - description: 重置请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ResetPasswordRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 密码重置成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 重置密码
      tags:
      - 密码重置
  /api/v1/auth/reset-password/phone:
    post:
      consumes:
      - application/json
      description: 使用短信验证码重置登录密码
      parameters:
      - description: 重置请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.ResetPasswordByPhoneRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 密码重置成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 验证码错误
          schema:
            $ref: '#/definitions/handler.Response'
        "503":
          description: 短信服务未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 通过短信验证码重置密码
      tags:
      - 密码重置
  /api/v1/auth/send-code:
    post:
      consumes:
      - application/json
      description: 向指定手机号发送短信验证码（用于注册或登录）
      parameters:
      - description: 发送验证码请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.SendCodeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 发送成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "503":
          description: 短信服务未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 发送短信验证码
      tags:
      - 短信验证
  /api/v1/auth/send-email-code:
    post:
      consumes:
      - application/json
      description: 发送邮箱登录验证码（防枚举：无论邮箱是否注册都返回成功）
      parameters:
      - description: 邮箱地址
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.SendEmailCodeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 验证码已发送
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 邮箱格式错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 发送邮箱验证码
      tags:
      - 邮箱认证
  /api/v1/auth/userinfo:
    get:
      description: 获取已登录用户的详细信息
      produces:
      - application/json
      responses:
        "200":
          description: 用户信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/service.UserInfo'
              type: object
        "401":
          description: 未认证
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                code:
                  type: integer
                message:
                  type: string
              type: object
      security:
      - BearerAuth: []
      summary: 获取当前用户信息
      tags:
      - 认证
  /api/v1/custom-fields:
    get:
      description: 获取所有自定义字段定义列表
      produces:
      - application/json
      responses:
        "200":
          description: 字段列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerCustomField'
                  type: array
              type: object
      security:
      - BearerAuth: []
      summary: 获取自定义字段列表
      tags:
      - 自定义字段
    post:
      consumes:
      - application/json
      description: 创建新的自定义字段定义（仅管理员）
      parameters:
      - description: 字段定义
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.CreateFieldRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerCustomField'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建自定义字段
      tags:
      - 自定义字段
  /api/v1/custom-fields/{id}:
    delete:
      description: 删除自定义字段定义（仅管理员）
      parameters:
      - description: 字段ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 字段不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除自定义字段
      tags:
      - 自定义字段
    get:
      description: 根据ID获取自定义字段定义
      parameters:
      - description: 字段ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 字段信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerCustomField'
              type: object
        "404":
          description: 字段不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取自定义字段详情
      tags:
      - 自定义字段
    put:
      consumes:
      - application/json
      description: 更新自定义字段定义（仅管理员）
      parameters:
      - description: 字段ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.UpdateFieldRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerCustomField'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 字段不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新自定义字段
      tags:
      - 自定义字段
  /api/v1/devices:
    get:
      description: 获取当前用户的所有设备记录
      parameters:
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 设备列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.DeviceListResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取当前用户的设备列表
      tags:
      - 设备管理
    post:
      consumes:
      - application/json
      description: 当前用户创建设备记录
      parameters:
      - description: 设备信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.CreateDeviceRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 设备创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerDevice'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建设备记录
      tags:
      - 设备管理
  /api/v1/devices/{id}:
    delete:
      description: 删除设备记录
      parameters:
      - description: 设备ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 设备不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除设备
      tags:
      - 设备管理
    get:
      description: 根据ID获取设备详细信息
      parameters:
      - description: 设备ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 设备信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerDevice'
              type: object
        "404":
          description: 设备不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取设备详情
      tags:
      - 设备管理
    put:
      consumes:
      - application/json
      description: 更新设备的基本信息
      parameters:
      - description: 设备ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.UpdateDeviceRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerDevice'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 设备不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新设备信息
      tags:
      - 设备管理
  /api/v1/devices/{id}/status:
    put:
      consumes:
      - application/json
      description: 更新设备状态（active/inactive）
      parameters:
      - description: 设备ID
        in: path
        name: id
        required: true
        type: integer
      - description: 状态信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.UpdateDeviceStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 状态更新成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 无效的状态值
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 设备不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新设备状态
      tags:
      - 设备管理
  /api/v1/devices/{id}/trust:
    delete:
      description: 取消设备的信任状态
      parameters:
      - description: 设备ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 取消成功
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 设备不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 取消设备信任
      tags:
      - 设备管理
    post:
      consumes:
      - application/json
      description: 将指定设备设置为信任设备，在信任期内免二次验证
      parameters:
      - description: 设备ID
        in: path
        name: id
        required: true
        type: integer
      - description: 信任配置
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.TrustDeviceRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 设置成功
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 设备不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 设置设备为信任设备
      tags:
      - 设备管理
  /api/v1/devices/by-device-id/{deviceId}/trust:
    post:
      consumes:
      - application/json
      description: 根据设备唯一标识字符串设置设备为信任状态
      parameters:
      - description: 设备唯一标识
        in: path
        name: deviceId
        required: true
        type: string
      - description: 信任配置
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.TrustDeviceRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 设置成功
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 根据设备标识设置信任
      tags:
      - 设备管理
  /api/v1/devices/me/logout-others:
    post:
      description: 登出当前用户除指定设备外的所有其他设备
      parameters:
      - description: 当前设备ID
        in: header
        name: X-Device-ID
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 登出成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 无效的设备ID
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 登出其他设备
      tags:
      - 设备管理
  /api/v1/devices/me/trusted:
    get:
      description: 获取当前用户的信任设备列表
      produces:
      - application/json
      responses:
        "200":
          description: 信任设备列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerDevice'
                  type: array
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取信任设备列表
      tags:
      - 设备管理
  /api/v1/devices/users/{id}:
    get:
      description: 获取指定用户的设备列表（仅本人或管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 设备列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.DeviceListResponse'
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取用户设备列表
      tags:
      - 设备管理
  /api/v1/logs/login:
    get:
      description: 获取所有登录日志（仅管理员），支持游标分页和偏移分页
      parameters:
      - description: 游标分页游标
        in: query
        name: cursor
        type: string
      - description: 每页数量（游标模式）
        in: query
        name: size
        type: integer
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 登录日志列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.LoginLogListResponse'
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取登录日志列表
      tags:
      - 日志
  /api/v1/logs/login/export:
    get:
      description: 导出登录日志为 CSV 文件
      parameters:
      - description: 开始时间
        in: query
        name: start_time
        type: string
      - description: 结束时间
        in: query
        name: end_time
        type: string
      - description: 用户ID
        format: int64
        in: query
        name: user_id
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: CSV文件
          schema:
            type: file
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 导出登录日志
      tags:
      - 日志
  /api/v1/logs/login/me:
    get:
      description: 获取当前用户的登录日志
      parameters:
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 登录日志列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.LoginLogListResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取登录日志
      tags:
      - 日志
  /api/v1/logs/operation:
    get:
      description: 获取所有操作日志（仅管理员），支持游标分页和偏移分页
      parameters:
      - description: 游标分页游标
        in: query
        name: cursor
        type: string
      - description: 每页数量（游标模式）
        in: query
        name: size
        type: integer
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 操作日志列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.OperationLogListResponse'
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取操作日志列表
      tags:
      - 日志
  /api/v1/logs/operation/me:
    get:
      description: 获取当前用户的操作日志
      parameters:
      - description: 页码
        in: query
        name: page
        type: integer
      - description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 操作日志列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.OperationLogListResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取操作日志
      tags:
      - 日志
  /api/v1/permissions:
    get:
      description: 获取系统权限列表
      produces:
      - application/json
      responses:
        "200":
          description: 权限列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerPermission'
                  type: array
              type: object
      security:
      - BearerAuth: []
      summary: 获取权限列表
      tags:
      - 权限管理
    post:
      consumes:
      - application/json
      description: 创建新的权限定义（仅管理员）
      parameters:
      - description: 权限信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.CreatePermissionRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerPermission'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建权限
      tags:
      - 权限管理
  /api/v1/permissions/{id}:
    delete:
      description: 删除权限定义（仅管理员）
      parameters:
      - description: 权限ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 权限不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除权限
      tags:
      - 权限管理
    get:
      description: 根据ID获取权限详细信息
      parameters:
      - description: 权限ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 权限信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerPermission'
              type: object
        "404":
          description: 权限不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取权限详情
      tags:
      - 权限管理
    put:
      consumes:
      - application/json
      description: 更新权限信息（仅管理员）
      parameters:
      - description: 权限ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.UpdatePermissionRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerPermission'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 权限不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新权限
      tags:
      - 权限管理
  /api/v1/permissions/{id}/status:
    put:
      consumes:
      - application/json
      description: 更新权限状态（enabled/disabled）（仅管理员）
      parameters:
      - description: 权限ID
        in: path
        name: id
        required: true
        type: integer
      - description: 状态信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.UpdatePermissionStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 状态更新成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 无效的状态值
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 权限不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新权限状态
      tags:
      - 权限管理
  /api/v1/permissions/tree:
    get:
      description: 获取系统权限的树形结构
      produces:
      - application/json
      responses:
        "200":
          description: 权限树
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerPermission'
                  type: array
              type: object
      security:
      - BearerAuth: []
      summary: 获取权限树
      tags:
      - 权限管理
  /api/v1/roles:
    get:
      description: 获取系统角色列表
      produces:
      - application/json
      responses:
        "200":
          description: 角色列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.RoleListResponse'
              type: object
      security:
      - BearerAuth: []
      summary: 获取角色列表
      tags:
      - 角色管理
    post:
      consumes:
      - application/json
      description: 创建新角色（仅管理员）
      parameters:
      - description: 角色信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.CreateRoleRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 角色创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerRole'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建角色
      tags:
      - 角色管理
  /api/v1/roles/{id}:
    delete:
      description: 删除角色（仅管理员）
      parameters:
      - description: 角色ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 角色不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除角色
      tags:
      - 角色管理
    get:
      description: 根据ID获取角色详细信息
      parameters:
      - description: 角色ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 角色信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerRole'
              type: object
        "404":
          description: 角色不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取角色详情
      tags:
      - 角色管理
    put:
      consumes:
      - application/json
      description: 更新角色信息（仅管理员）
      parameters:
      - description: 角色ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.UpdateRoleRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerRole'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 角色不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新角色
      tags:
      - 角色管理
  /api/v1/roles/{id}/permissions:
    get:
      description: 获取角色的权限列表
      parameters:
      - description: 角色ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 权限列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerPermission'
                  type: array
              type: object
        "404":
          description: 角色不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取角色权限列表
      tags:
      - 角色管理
    put:
      consumes:
      - application/json
      description: 为角色分配权限（替换现有权限）（仅管理员）
      parameters:
      - description: 角色ID
        in: path
        name: id
        required: true
        type: integer
      - description: 权限ID列表
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.AssignPermissionsRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 权限分配成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 角色不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 分配角色权限
      tags:
      - 角色管理
  /api/v1/roles/{id}/status:
    put:
      consumes:
      - application/json
      description: 更新角色状态（enabled/disabled）（仅管理员）
      parameters:
      - description: 角色ID
        in: path
        name: id
        required: true
        type: integer
      - description: 状态信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.UpdateRoleStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 状态更新成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 无效的状态值
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 角色不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新角色状态
      tags:
      - 角色管理
  /api/v1/sso/authorize:
    get:
      consumes:
      - application/json
      description: 处理 SSO 授权请求，返回授权码
      parameters:
      - description: 客户端ID
        in: query
        name: client_id
        required: true
        type: string
      - description: 回调地址
        in: query
        name: redirect_uri
        required: true
        type: string
      - description: 响应类型
        enum:
        - code
        in: query
        name: response_type
        required: true
        type: string
      - description: 授权范围
        in: query
        name: scope
        type: string
      - description: 状态参数
        in: query
        name: state
        type: string
      produces:
      - application/json
      responses:
        "302":
          description: 重定向到回调地址
          schema:
            type: string
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: SSO 授权
      tags:
      - SSO
  /api/v1/sso/introspect:
    post:
      consumes:
      - application/x-www-form-urlencoded
      description: 验证 Access Token 的有效性并返回相关信息
      parameters:
      - description: Access Token
        in: formData
        name: token
        required: true
        type: string
      - description: 客户端ID
        in: formData
        name: client_id
        required: true
        type: string
      - description: 客户端密钥
        in: formData
        name: client_secret
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Token信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.IntrospectResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 客户端认证失败
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 验证 Access Token
      tags:
      - SSO
  /api/v1/sso/revoke:
    post:
      consumes:
      - application/x-www-form-urlencoded
      description: 撤销指定的 Access Token
      parameters:
      - description: Access Token
        in: formData
        name: token
        required: true
        type: string
      - description: 客户端ID
        in: formData
        name: client_id
        required: true
        type: string
      - description: 客户端密钥
        in: formData
        name: client_secret
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 撤销成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 客户端认证失败
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 撤销 Access Token
      tags:
      - SSO
  /api/v1/sso/token:
    post:
      consumes:
      - application/x-www-form-urlencoded
      description: 使用授权码获取 Access Token（授权码模式第二步）
      parameters:
      - description: 授权类型
        enum:
        - authorization_code
        in: formData
        name: grant_type
        required: true
        type: string
      - description: 授权码
        in: formData
        name: code
        required: true
        type: string
      - description: 回调地址
        in: formData
        name: redirect_uri
        required: true
        type: string
      - description: 客户端ID
        in: formData
        name: client_id
        required: true
        type: string
      - description: 客户端密钥
        in: formData
        name: client_secret
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 访问令牌响应
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.TokenResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 客户端认证失败
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 获取 Access Token
      tags:
      - SSO
  /api/v1/sso/userinfo:
    get:
      description: 获取当前通过 SSO Access Token 授权的用户信息
      produces:
      - application/json
      responses:
        "200":
          description: 用户信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.UserInfoResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取 SSO 用户信息
      tags:
      - SSO
  /api/v1/theme/active:
    get:
      description: 获取当前系统正在使用的主题（公开接口）
      produces:
      - application/json
      responses:
        "200":
          description: 当前生效主题
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerTheme'
              type: object
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 获取当前生效的主题
      tags:
      - 主题管理
  /api/v1/themes:
    get:
      description: 获取所有主题（包括已禁用的）
      produces:
      - application/json
      responses:
        "200":
          description: 主题列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerTheme'
                  type: array
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取所有主题
      tags:
      - 主题管理
    post:
      consumes:
      - application/json
      description: 创建新的主题配置
      parameters:
      - description: 主题信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.CreateThemeRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 主题创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerTheme'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建主题
      tags:
      - 主题管理
  /api/v1/themes/{id}:
    delete:
      description: 删除指定的主题
      parameters:
      - description: 主题ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 主题删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除主题
      tags:
      - 主题管理
    get:
      description: 根据ID获取主题详情
      parameters:
      - description: 主题ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 主题详情
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerTheme'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取主题
      tags:
      - 主题管理
    put:
      consumes:
      - application/json
      description: 更新指定主题的配置
      parameters:
      - description: 主题ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.UpdateThemeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 主题更新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerTheme'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新主题
      tags:
      - 主题管理
  /api/v1/themes/default:
    get:
      description: 获取系统默认主题
      produces:
      - application/json
      responses:
        "200":
          description: 默认主题
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.SwaggerTheme'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取默认主题
      tags:
      - 主题管理
  /api/v1/themes/default/{id}:
    put:
      description: 将指定主题设为系统默认主题
      parameters:
      - description: 主题ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 设置成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 设置默认主题
      tags:
      - 主题管理
  /api/v1/users:
    get:
      description: 获取用户列表，支持游标分页和偏移分页
      parameters:
      - description: 游标分页游标
        in: query
        name: cursor
        type: string
      - description: 每页大小
        in: query
        name: size
        type: integer
      - description: 偏移分页偏移量
        in: query
        name: offset
        type: integer
      - description: 每页大小
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 用户列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.UserListResponse'
              type: object
      security:
      - BearerAuth: []
      summary: 获取用户列表
      tags:
      - 用户管理
    post:
      consumes:
      - application/json
      description: 创建新用户账号（仅管理员）
      parameters:
      - description: 用户信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.CreateUserRequest'
      produces:
      - application/json
      responses:
        "201":
          description: 用户创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.UserResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建用户
      tags:
      - 用户管理
  /api/v1/users/{id}:
    delete:
      description: 删除用户账号（仅管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除用户
      tags:
      - 用户管理
    get:
      description: 根据ID获取用户详细信息
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 用户信息
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.UserResponse'
              type: object
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取用户详情
      tags:
      - 用户管理
    put:
      consumes:
      - application/json
      description: 更新用户的基本信息（仅管理员或本人）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.UpdateUserRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.UserResponse'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新用户信息
      tags:
      - 用户管理
  /api/v1/users/{id}/avatar:
    post:
      consumes:
      - multipart/form-data
      description: 上传并更新用户头像（仅本人或管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      - description: 头像文件（最大5MB，支持jpg/jpeg/png/gif/webp）
        in: formData
        name: avatar
        required: true
        type: file
      produces:
      - application/json
      responses:
        "200":
          description: 上传成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.AvatarResponse'
              type: object
        "400":
          description: 文件无效或大小超限
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 上传用户头像
      tags:
      - 用户头像
  /api/v1/users/{id}/password:
    put:
      consumes:
      - application/json
      description: 修改用户密码（仅管理员或本人）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      - description: 密码信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.UpdatePasswordRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 密码修改成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 修改用户密码
      tags:
      - 用户管理
  /api/v1/users/{id}/roles:
    get:
      description: 获取指定用户的角色列表（仅本人或管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 角色列表
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.SwaggerRole'
                  type: array
              type: object
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取用户角色列表
      tags:
      - 用户管理
    put:
      consumes:
      - application/json
      description: 为用户分配角色（替换现有角色）（仅管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      - description: 角色ID列表
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.AssignRolesRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 角色分配成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 分配用户角色
      tags:
      - 用户管理
  /api/v1/users/{id}/status:
    put:
      consumes:
      - application/json
      description: 更新用户账号状态（active/inactive/locked/disabled）（仅管理员）
      parameters:
      - description: 用户ID
        in: path
        name: id
        required: true
        type: integer
      - description: 状态信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.UpdateStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 状态更新成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 无效的状态值
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新用户状态
      tags:
      - 用户管理
  /api/v1/users/batch:
    delete:
      consumes:
      - application/json
      description: 批量删除多个用户（仅管理员）
      parameters:
      - description: 批量删除请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.BatchDeleteRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 批量删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 批量删除用户
      tags:
      - 用户管理
  /api/v1/users/batch/status:
    put:
      consumes:
      - application/json
      description: 批量更新多个用户的状态（仅管理员）
      parameters:
      - description: 批量更新请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.BatchUpdateStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 批量更新成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "403":
          description: 无权限
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 批量更新用户状态
      tags:
      - 用户管理
  /api/v1/users/me/bind-email:
    delete:
      consumes:
      - application/json
      description: 解绑账号关联的邮箱（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 解绑邮箱
      tags:
      - 邮箱绑定
    post:
      consumes:
      - application/json
      description: 使用邮箱验证码绑定账号（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 绑定邮箱
      tags:
      - 邮箱绑定
  /api/v1/users/me/bind-email/code:
    post:
      consumes:
      - application/json
      description: 发送验证码到邮箱以绑定邮箱（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 发送邮箱绑定验证码
      tags:
      - 邮箱绑定
  /api/v1/users/me/bind-phone:
    delete:
      consumes:
      - application/json
      description: 解绑账号关联的手机号（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 解绑手机号
      tags:
      - 手机绑定
    post:
      consumes:
      - application/json
      description: 使用手机验证码绑定账号（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 绑定手机号
      tags:
      - 手机绑定
  /api/v1/users/me/bind-phone/code:
    post:
      consumes:
      - application/json
      description: 发送验证码到手机以绑定手机号（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 发送手机绑定验证码
      tags:
      - 手机绑定
  /api/v1/users/me/bind-social:
    post:
      consumes:
      - application/json
      description: 绑定第三方社交账号到当前用户（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 绑定社交账号
      tags:
      - 社交账号
  /api/v1/users/me/bind-social/{provider}:
    delete:
      consumes:
      - application/json
      description: 解绑当前用户关联的第三方社交账号（当前未配置）
      produces:
      - application/json
      responses:
        "200":
          description: 功能未配置
          schema:
            $ref: '#/definitions/handler.Response'
      summary: 解绑社交账号
      tags:
      - 社交账号
  /api/v1/users/me/custom-fields:
    get:
      description: 获取当前用户的自定义字段值
      produces:
      - application/json
      responses:
        "200":
          description: 字段值
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/handler.CustomFieldValuesResponse'
              type: object
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取用户自定义字段值
      tags:
      - 自定义字段
    put:
      consumes:
      - application/json
      description: 设置当前用户的自定义字段值
      parameters:
      - description: 字段值
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.SetUserFieldValuesRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 设置成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 设置用户自定义字段值
      tags:
      - 自定义字段
  /api/v1/users/me/social-accounts:
    get:
      description: 获取当前用户绑定的第三方社交账号列表
      produces:
      - application/json
      responses:
        "200":
          description: 社交账号列表
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取已绑定的社交账号列表
      tags:
      - 社交账号
  /api/v1/webhooks:
    get:
      consumes:
      - application/json
      description: 获取当前用户的 Webhook 配置列表
      parameters:
      - default: 1
        description: 页码
        in: query
        name: page
        type: integer
      - default: 20
        description: 每页数量
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Webhook列表
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取 Webhook 列表
      tags:
      - Webhook管理
    post:
      consumes:
      - application/json
      description: 创建新的 Webhook 配置
      parameters:
      - description: Webhook信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.CreateWebhookRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Webhook创建成功
          schema:
            allOf:
            - $ref: '#/definitions/handler.Response'
            - properties:
                data:
                  $ref: '#/definitions/domain.Webhook'
              type: object
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 创建 Webhook
      tags:
      - Webhook管理
  /api/v1/webhooks/{id}:
    delete:
      description: 删除指定的 Webhook 配置
      parameters:
      - description: Webhook ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 删除 Webhook
      tags:
      - Webhook管理
    put:
      consumes:
      - application/json
      description: 更新指定 Webhook 的配置
      parameters:
      - description: Webhook ID
        in: path
        name: id
        required: true
        type: integer
      - description: 更新信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/service.UpdateWebhookRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 更新 Webhook
      tags:
      - Webhook管理
  /api/v1/webhooks/{id}/deliveries:
    get:
      description: 获取指定 Webhook 的最近投递记录
      parameters:
      - description: Webhook ID
        in: path
        name: id
        required: true
        type: integer
      - default: 20
        description: 返回记录数量
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 投递记录列表
          schema:
            $ref: '#/definitions/handler.Response'
        "400":
          description: 请求参数错误
          schema:
            $ref: '#/definitions/handler.Response'
        "401":
          description: 未认证
          schema:
            $ref: '#/definitions/handler.Response'
        "500":
          description: 服务器错误
          schema:
            $ref: '#/definitions/handler.Response'
      security:
      - BearerAuth: []
      summary: 获取 Webhook 投递记录
      tags:
      - Webhook管理
schemes:
- http
- https
swagger: "2.0"