OpenFlare/backend/docs/swagger.yaml

basePath: /
definitions:
  cap.ChallengeResponse:
    properties:
      challenge:
        properties:
          c:
            type: integer
          d:
            type: integer
          s:
            type: integer
        type: object
      expires:
        description: ms timestamp
        type: integer
      token:
        type: string
    type: object
  cap.RedeemResponse:
    properties:
      error:
        type: string
      expires:
        type: integer
      success:
        type: boolean
      token:
        type: string
    type: object
  cap.challengeRequest:
    properties:
      scope:
        type: string
    type: object
  cap.redeemRequest:
    properties:
      scope:
        type: string
      solutions:
        items:
          type: integer
        type: array
      token:
        type: string
    required:
    - solutions
    - token
    type: object
  contracts.TaskMetaDTO:
    properties:
      asynq_task:
        type: string
      category:
        type: string
      description:
        type: string
      display_name:
        type: string
      max_retry:
        type: integer
      name:
        type: string
      params:
        items:
          $ref: '#/definitions/contracts.TaskParamDTO'
        type: array
      queue:
        type: string
      retryable:
        type: boolean
      schedule:
        type: string
      supports_time:
        type: boolean
      timeout:
        $ref: '#/definitions/time.Duration'
      type:
        type: string
    type: object
  contracts.TaskParamDTO:
    properties:
      default: {}
      description:
        type: string
      label:
        type: string
      name:
        type: string
      placeholder:
        type: string
      required:
        type: boolean
      type:
        type: string
    type: object
  disk.Status:
    properties:
      base_path:
        type: string
      keys_count:
        type: integer
      lru_enabled:
        type: boolean
      max_size_mb:
        type: integer
      total_size:
        type: integer
      ttl_minutes:
        type: integer
    type: object
  handler.batchDownloadRequest:
    properties:
      ids:
        items:
          type: string
        minItems: 1
        type: array
    required:
    - ids
    type: object
  handler.distributionItem:
    properties:
      count:
        type: integer
      name:
        type: string
      size:
        type: integer
    type: object
  handler.fileStatsResponse:
    properties:
      categories:
        items:
          $ref: '#/definitions/handler.distributionItem'
        type: array
      total_count:
        type: integer
      total_size:
        type: integer
      trend:
        items:
          $ref: '#/definitions/handler.trendItem'
        type: array
      types:
        items:
          $ref: '#/definitions/handler.distributionItem'
        type: array
    type: object
  handler.listFilesResponse:
    properties:
      items:
        items:
          $ref: '#/definitions/models.Upload'
        type: array
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  handler.listMyFilesResponse:
    properties:
      items:
        items:
          $ref: '#/definitions/models.Upload'
        type: array
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  handler.trendItem:
    properties:
      count:
        type: integer
      date:
        type: string
      size:
        type: integer
    type: object
  handler.updateMyFileRequest:
    properties:
      access_mode:
        enum:
        - 0
        - 1
        type: integer
      file_name:
        maxLength: 255
        type: string
    type: object
  logger.LogEntry:
    properties:
      data:
        description: 一行日志原文（含换行符）
        type: string
      index:
        description: 全局递增序号
        type: integer
    type: object
  model.AccessLogItem:
    properties:
      created_at:
        type: string
      headers:
        type: string
      id:
        example: "0"
        type: string
      ip:
        type: string
      latency:
        type: integer
      method:
        type: string
      nickname:
        type: string
      path:
        type: string
      status:
        type: integer
      trace_id:
        type: string
      user_agent:
        type: string
      user_id:
        example: "0"
        type: string
      username:
        type: string
    type: object
  model.AccessLogsResponse:
    properties:
      list:
        items:
          $ref: '#/definitions/model.AccessLogItem'
        type: array
      total:
        type: integer
    type: object
  model.BindRequest:
    properties:
      channel_id:
        type: string
      code:
        type: string
    type: object
  model.BindingDTO:
    properties:
      channel_id:
        example: "0"
        type: string
      channel_name:
        type: string
      channel_type:
        type: string
      created_at:
        type: string
      id:
        example: "0"
        type: string
      platform_user_id:
        type: string
      user_id:
        example: "0"
        type: string
    type: object
  model.BrowserItem:
    properties:
      browser:
        type: string
      count:
        type: integer
    type: object
  model.ChannelDTO:
    properties:
      credentials:
        additionalProperties:
          type: string
        type: object
      enabled:
        type: boolean
      extra:
        additionalProperties:
          type: string
        type: object
      id:
        example: "0"
        type: string
      name:
        type: string
      owner_id:
        example: "0"
        type: string
      owner_scope:
        type: string
      type:
        type: string
    type: object
  model.CreateChannelRequest:
    properties:
      credentials:
        additionalProperties:
          type: string
        type: object
      enabled:
        type: boolean
      extra:
        additionalProperties:
          type: string
        type: object
      name:
        type: string
      type:
        type: string
    type: object
  model.CreateScheduleRequest:
    properties:
      cron:
        type: string
      is_active:
        type: boolean
      name:
        type: string
      payload:
        type: string
      task_type:
        type: string
    required:
    - cron
    - is_active
    - name
    - task_type
    type: object
  model.CreateSystemConfigRequest:
    properties:
      description:
        maxLength: 255
        type: string
      key:
        maxLength: 64
        type: string
      type:
        enum:
        - system
        - business
        type: string
      value:
        type: string
      visibility:
        enum:
        - 0
        - 1
        type: integer
    required:
    - key
    - type
    - value
    type: object
  model.CreateTemplateRequest:
    properties:
      content:
        type: string
      description:
        maxLength: 255
        type: string
      key:
        maxLength: 80
        type: string
      name:
        maxLength: 100
        type: string
      subject:
        maxLength: 255
        type: string
      type:
        maxLength: 20
        type: string
    required:
    - content
    - key
    - name
    - type
    type: object
  model.CreateUserRequest:
    properties:
      email:
        maxLength: 255
        type: string
      is_active:
        type: boolean
      is_admin:
        type: boolean
      nickname:
        maxLength: 64
        type: string
      password:
        maxLength: 64
        minLength: 8
        type: string
      username:
        maxLength: 64
        minLength: 3
        type: string
    required:
    - email
    - password
    - username
    type: object
  model.DBOverviewResponse:
    properties:
      connections:
        type: integer
      name:
        type: string
      size:
        type: string
      table_count:
        type: integer
      type:
        type: string
      version:
        type: string
    type: object
  model.DatabaseInfoResponse:
    properties:
      name:
        type: string
      type:
        type: string
      version:
        type: string
    type: object
  model.Definition:
    properties:
      fields:
        items:
          $ref: '#/definitions/model.Field'
        type: array
      type:
        type: string
    type: object
  model.DispatchTaskRequest:
    properties:
      end_time:
        type: string
      payload:
        type: string
      start_time:
        type: string
      task_type:
        type: string
      user_id:
        type: integer
    required:
    - task_type
    type: object
  model.ExecuteSQLRequest:
    properties:
      sql:
        type: string
    required:
    - sql
    type: object
  model.ExecuteSQLResponse:
    properties:
      affected_rows:
        type: integer
      columns:
        items:
          type: string
        type: array
      execution_time_ms:
        type: integer
      results:
        items:
          additionalProperties: true
          type: object
        type: array
      type:
        description: '"select" 或 "exec"'
        type: string
    type: object
  model.Field:
    properties:
      key:
        type: string
      required:
        type: boolean
      type:
        type: string
    type: object
  model.ListUsersResponse:
    properties:
      total:
        type: integer
      users:
        items:
          $ref: '#/definitions/model.UserResponse'
        type: array
    type: object
  model.LogDatabaseStatus:
    properties:
      active_database:
        type: string
      available_targets:
        items:
          type: string
        type: array
      migration:
        type: string
      retention_days:
        additionalProperties:
          type: integer
        type: object
    type: object
  model.LogsAnalyticsResponse:
    properties:
      browsers:
        items:
          $ref: '#/definitions/model.BrowserItem'
        type: array
      top_users:
        items:
          $ref: '#/definitions/model.TopUserItem'
        type: array
      trend:
        items:
          $ref: '#/definitions/model.TrendItem'
        type: array
    type: object
  model.LogsResponse:
    properties:
      has_more:
        type: boolean
      lines:
        items:
          $ref: '#/definitions/logger.LogEntry'
        type: array
      next_cursor:
        description: 用于加载更早日志的 cursor
        type: integer
    type: object
  model.PublicChannelDTO:
    properties:
      id:
        example: "0"
        type: string
      name:
        type: string
      type:
        type: string
    type: object
  model.Schedule:
    properties:
      created_at:
        type: string
      cron:
        type: string
      id:
        example: "0"
        type: string
      is_active:
        type: boolean
      name:
        type: string
      payload:
        type: string
      task_type:
        type: string
      updated_at:
        type: string
    type: object
  model.SystemConfig:
    properties:
      created_at:
        type: string
      description:
        type: string
      key:
        type: string
      type:
        type: string
      updated_at:
        type: string
      value:
        type: string
      visibility:
        type: integer
    type: object
  model.SystemStatusResponse:
    properties:
      alloc:
        type: string
      buck_hash_sys:
        type: string
      frees:
        type: integer
      gc_sys:
        type: string
      heap_alloc:
        type: string
      heap_idle:
        type: string
      heap_inuse:
        type: string
      heap_objects:
        type: integer
      heap_released:
        type: string
      heap_sys:
        type: string
      last_gc_time:
        type: string
      last_pause:
        type: string
      lookups:
        type: integer
      mallocs:
        type: integer
      mcache_inuse:
        type: string
      mcache_sys:
        type: string
      mspan_inuse:
        type: string
      mspan_sys:
        type: string
      next_gc:
        type: string
      num_gc:
        type: integer
      num_goroutine:
        type: integer
      other_sys:
        type: string
      pause_total_ns:
        type: string
      stack_inuse:
        type: string
      stack_sys:
        type: string
      sys:
        type: string
      total_alloc:
        type: string
      uptime:
        type: string
    type: object
  model.TaskExecution:
    properties:
      created_at:
        type: string
      duration:
        type: integer
      error_message:
        type: string
      finished_at:
        type: string
      id:
        example: "0"
        type: string
      log:
        type: string
      max_retry:
        type: integer
      payload:
        type: string
      result:
        type: string
      retry_count:
        type: integer
      retryable:
        type: boolean
      started_at:
        type: string
      status:
        $ref: '#/definitions/model.TaskExecutionStatus'
      task_id:
        type: string
      task_name:
        type: string
      task_type:
        type: string
      triggered_by:
        type: string
      updated_at:
        type: string
    type: object
  model.TaskExecutionStatus:
    enum:
    - pending
    - running
    - succeeded
    - failed
    type: string
    x-enum-varnames:
    - TaskExecutionStatusPending
    - TaskExecutionStatusRunning
    - TaskExecutionStatusSucceeded
    - TaskExecutionStatusFailed
  model.Template:
    properties:
      content:
        type: string
      created_at:
        type: string
      description:
        type: string
      id:
        type: integer
      is_system:
        type: boolean
      key:
        type: string
      name:
        type: string
      subject:
        type: string
      type:
        type: string
      updated_at:
        type: string
    type: object
  model.TestSMTPRequest:
    properties:
      smtp_host:
        maxLength: 255
        type: string
      smtp_password:
        maxLength: 255
        type: string
      smtp_port:
        type: integer
      smtp_username:
        maxLength: 255
        type: string
      to:
        type: string
    required:
    - smtp_host
    - smtp_password
    - smtp_port
    - smtp_username
    - to
    type: object
  model.TestSMTPResponse:
    properties:
      error:
        type: string
      log:
        type: string
      success:
        type: boolean
    type: object
  model.TopUserItem:
    properties:
      count:
        type: integer
      nickname:
        type: string
      user_id:
        example: "0"
        type: string
      username:
        type: string
    type: object
  model.TrendItem:
    properties:
      count:
        type: integer
      date:
        type: string
    type: object
  model.UpdateCacheConfigRequest:
    properties:
      lru_enabled:
        type: boolean
      max_size_mb:
        minimum: 1
        type: integer
      ttl_minutes:
        minimum: 0
        type: integer
    required:
    - max_size_mb
    - ttl_minutes
    type: object
  model.UpdateChannelRequest:
    properties:
      credentials:
        additionalProperties:
          type: string
        type: object
      enabled:
        type: boolean
      extra:
        additionalProperties:
          type: string
        type: object
      name:
        type: string
    type: object
  model.UpdateScheduleRequest:
    properties:
      cron:
        type: string
      is_active:
        type: boolean
      name:
        type: string
      payload:
        type: string
      task_type:
        type: string
    required:
    - cron
    - is_active
    - name
    - task_type
    type: object
  model.UpdateSystemConfigRequest:
    properties:
      description:
        maxLength: 255
        type: string
      value:
        type: string
      visibility:
        enum:
        - 0
        - 1
        type: integer
    required:
    - value
    type: object
  model.UpdateTemplateRequest:
    properties:
      content:
        type: string
      description:
        maxLength: 255
        type: string
      name:
        maxLength: 100
        type: string
      subject:
        maxLength: 255
        type: string
      type:
        maxLength: 20
        type: string
    required:
    - content
    - name
    - type
    type: object
  model.UpdateUserRequest:
    properties:
      email:
        maxLength: 255
        type: string
      is_admin:
        type: boolean
      nickname:
        maxLength: 64
        type: string
      password:
        maxLength: 64
        minLength: 8
        type: string
    required:
    - email
    type: object
  model.UpdateUserStatusRequest:
    properties:
      is_active:
        type: boolean
    type: object
  model.UpdaterStatus:
    properties:
      asset_name:
        type: string
      build_time:
        type: string
      can_upgrade:
        type: boolean
      current_version:
        type: string
      latest_version:
        type: string
      platform:
        type: string
      prerelease:
        type: boolean
      published_at:
        type: string
      release_name:
        type: string
      release_notes:
        type: string
      release_url:
        type: string
      update_available:
        type: boolean
      upstream_repository:
        type: string
    type: object
  model.UserResponse:
    properties:
      avatar_url:
        type: string
      bio:
        type: string
      created_at:
        type: string
      email:
        type: string
      gender:
        type: string
      id:
        example: "0"
        type: string
      is_active:
        type: boolean
      is_admin:
        type: boolean
      last_login_at:
        type: string
      location:
        type: string
      nickname:
        type: string
      phone:
        type: string
      updated_at:
        type: string
      username:
        type: string
      website:
        type: string
    type: object
  models.Upload:
    properties:
      access_mode:
        type: integer
      created_at:
        type: string
      extension:
        type: string
      file_name:
        type: string
      file_path:
        type: string
      file_size:
        type: integer
      hash:
        type: string
      id:
        example: "0"
        type: string
      metadata:
        $ref: '#/definitions/models.UploadMetadata'
      mime_type:
        type: string
      status:
        $ref: '#/definitions/models.UploadStatus'
      type:
        type: string
      updated_at:
        type: string
      user_id:
        example: "0"
        type: string
    type: object
  models.UploadMetadata:
    properties:
      bucket:
        type: string
      client_ip:
        type: string
      duration:
        type: number
      extra:
        additionalProperties: {}
        type: object
      height:
        type: integer
      original_mime:
        type: string
      user_agent:
        type: string
      width:
        type: integer
    type: object
  models.UploadStatus:
    enum:
    - pending
    - used
    - deleted
    type: string
    x-enum-comments:
      UploadStatusDeleted: 已删除
      UploadStatusPending: 待使用
      UploadStatusUsed: 已使用
    x-enum-descriptions:
    - 待使用
    - 已使用
    - 已删除
    x-enum-varnames:
    - UploadStatusPending
    - UploadStatusUsed
    - UploadStatusDeleted
  response.Any:
    properties:
      data: {}
      error_msg:
        example: ""
        type: string
    type: object
  time.Duration:
    enum:
    - -9223372036854775808
    - 9223372036854775807
    - 1
    - 1000
    - 1000000
    - 1000000000
    - 60000000000
    - 3600000000000
    format: int64
    type: integer
    x-enum-varnames:
    - minDuration
    - maxDuration
    - Nanosecond
    - Microsecond
    - Millisecond
    - Second
    - Minute
    - Hour
info:
  contact:
    name: Wavelet
    url: https://github.com/Rain-kl/Wavelet
  description: Wavelet 平台后端 API，提供用户认证、系统配置、任务调度等通用功能。
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Wavelet API
  version: 1.0.0
paths:
  /api/cap/challenge:
    post:
      consumes:
      - application/json
      description: 客户端获取 PoW 难题和签名的 JWT Token，并在后台计算。
      parameters:
      - description: 可选范围限制参数
        in: body
        name: request
        schema:
          $ref: '#/definitions/cap.challengeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 PoW 难题
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/cap.ChallengeResponse'
              type: object
        "500":
          description: 内部服务错误
          schema:
            $ref: '#/definitions/response.Any'
      summary: 生成人机验证难题
      tags:
      - cap
  /api/cap/redeem:
    post:
      consumes:
      - application/json
      description: 提交 PoW 解答进行核销，成功后返回一次性 X-Cap-Token 凭证
      parameters:
      - description: 难题 Token 与解答 solutions 数组
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/cap.redeemRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 核销成功，返回 X-Cap-Token
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/cap.RedeemResponse'
              type: object
        "400":
          description: 参数错误或核销失败
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部服务错误
          schema:
            $ref: '#/definitions/response.Any'
      summary: 校验人机验证解答
      tags:
      - cap
  /api/v1/admin/cache/clear:
    post:
      description: 清除系统磁盘缓存目录中的所有临时文件，并重置缓存容量和 Key 追踪数据
      produces:
      - application/json
      responses:
        "200":
          description: 清理成功
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 服务内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 清空缓存
      tags:
      - admin
  /api/v1/admin/cache/config:
    post:
      consumes:
      - application/json
      description: 更改磁盘缓存最大容量限制、文件生存时间（TTL）以及是否启用 LRU 淘汰淘汰算法，并进行热更新
      parameters:
      - description: 缓存配置请求体
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.UpdateCacheConfigRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            $ref: '#/definitions/response.Any'
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 服务内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 更新缓存配置
      tags:
      - admin
  /api/v1/admin/cache/status:
    get:
      description: 获取当前系统磁盘缓存的使用情况（已占用字节、Key 数量等）与策略配置
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/disk.Status'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取缓存状态
      tags:
      - admin
  /api/v1/admin/db-export:
    get:
      description: SQLite 时直接下载 .db 文件；PostgreSQL 时执行 pg_dump 并流式下载 .sql 文件，需要管理员权限
      produces:
      - application/octet-stream
      responses:
        "200":
          description: 数据库文件
          schema:
            type: file
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 导出失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 导出数据库
      tags:
      - admin
  /api/v1/admin/db-info:
    get:
      description: 返回当前使用的数据库类型（sqlite/postgres）、名称/路径及版本字符串，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.DatabaseInfoResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取数据库信息
      tags:
      - admin
  /api/v1/admin/db-manage/overview:
    get:
      description: 获取数据库类型、版本、名称、文件大小、表数量及当前连接数，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.DBOverviewResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取数据库运行概览
      tags:
      - admin
  /api/v1/admin/db-manage/query:
    post:
      consumes:
      - application/json
      description: 在当前数据库中执行任意自定义 SQL，如果是查询语句将返回格式化后的列与数据集，否则返回受影响行数，需要管理员权限
      parameters:
      - description: SQL 请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.ExecuteSQLRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 执行完毕
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.ExecuteSQLResponse'
              type: object
        "400":
          description: SQL 语句错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 执行 SQL 查询
      tags:
      - admin
  /api/v1/admin/db-manage/tables:
    get:
      description: 返回当前数据库的所有用户自定义表名称列表，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    type: string
                  type: array
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取数据库所有表名
      tags:
      - admin
  /api/v1/admin/logs:
    get:
      description: 分页获取系统历史日志，cursor=0 获取最新日志，cursor>0 获取更早日志
      parameters:
      - default: 0
        description: 日志游标，0=获取最新
        in: query
        name: cursor
        type: integer
      - default: 200
        description: 每页条数
        in: query
        name: limit
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 日志列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.LogsResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取系统日志
      tags:
      - admin
  /api/v1/admin/logs/access:
    get:
      description: 分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限）
      parameters:
      - default: 1
        description: 页码
        in: query
        name: page
        type: integer
      - default: 20
        description: 每页条数
        in: query
        name: page_size
        type: integer
      - description: 用户名模糊搜索
        in: query
        name: username
        type: string
      - description: 接口路径模糊搜索
        in: query
        name: path
        type: string
      - description: 起始时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）
        in: query
        name: start_time
        type: string
      - description: 结束时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）
        in: query
        name: end_time
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 访问日志列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.AccessLogsResponse'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取用户访问日志
      tags:
      - admin
  /api/v1/admin/logs/analytics:
    get:
      description: 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限）
      produces:
      - application/json
      responses:
        "200":
          description: 分析统计数据
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.LogsAnalyticsResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取访问日志分析数据
      tags:
      - admin
  /api/v1/admin/logs/ws:
    get:
      description: 通过 WebSocket 实时推送系统日志，需要管理员权限
      responses: {}
      summary: 系统日志实时推送
      tags:
      - admin
  /api/v1/admin/message-gateway/channels:
    get:
      description: Returns all messaging channels; secrets are masked
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.ChannelDTO'
                  type: array
              type: object
      security:
      - SessionCookie: []
      summary: List message gateway channels
      tags:
      - admin-message-gateway
    post:
      consumes:
      - application/json
      description: Creates a Telegram or QQ channel with encrypted credentials
      parameters:
      - description: create body
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.CreateChannelRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.ChannelDTO'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: Create message gateway channel
      tags:
      - admin-message-gateway
  /api/v1/admin/message-gateway/channels/{id}:
    delete:
      description: Deletes a channel and cascaded bindings and pairing codes
      parameters:
      - description: channel id
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: Delete message gateway channel
      tags:
      - admin-message-gateway
    patch:
      consumes:
      - application/json
      description: Updates a channel; empty secrets keep the current ciphertext
      parameters:
      - description: channel id
        in: path
        name: id
        required: true
        type: integer
      - description: update body
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.UpdateChannelRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.ChannelDTO'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: Update message gateway channel
      tags:
      - admin-message-gateway
  /api/v1/admin/message-gateway/channels/{id}/test:
    post:
      description: Probes stored credentials without returning secrets
      parameters:
      - description: channel id
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Any'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: Test message gateway channel
      tags:
      - admin-message-gateway
  /api/v1/admin/message-gateway/channels/definitions:
    get:
      description: Returns form field definitions for Telegram and QQ channels
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.Definition'
                  type: array
              type: object
      security:
      - SessionCookie: []
      summary: List message gateway channel definitions
      tags:
      - admin-message-gateway
  /api/v1/admin/status:
    get:
      description: 获取后端服务运行状态、Goroutine、内存指标等详细统计数据，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.SystemStatusResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取系统状态信息
      tags:
      - admin
  /api/v1/admin/status/log-database:
    get:
      description: 返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.LogDatabaseStatus'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取日志数据库状态
      tags:
      - admin
  /api/v1/admin/system-configs:
    get:
      description: 返回所有系统配置列表，支持按配置类型（system/business）过滤，需要管理员权限
      parameters:
      - description: 配置类型（system/business）
        in: query
        name: type
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 系统配置列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.SystemConfig'
                  type: array
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取系统配置列表
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: 创建一条新的系统配置项，配置键不可重复，同时将新配置同步到 Redis，需要管理员权限
      parameters:
      - description: 创建请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.CreateSystemConfigRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 创建成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误或配置键已存在
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 创建系统配置
      tags:
      - admin
  /api/v1/admin/system-configs/{key}:
    get:
      description: 根据配置键获取对应的系统配置详情，需要管理员权限
      parameters:
      - description: 配置键
        in: path
        name: key
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 系统配置详情
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.SystemConfig'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 配置不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取单个系统配置
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: 根据配置键更新对应的配置内容，同时将更新同步到 Redis，需要管理员权限
      parameters:
      - description: 配置键
        in: path
        name: key
        required: true
        type: string
      - description: 更新请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.UpdateSystemConfigRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 配置不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 更新系统配置
      tags:
      - admin
  /api/v1/admin/system-configs/smtp/test:
    post:
      consumes:
      - application/json
      description: 使用传入的配置进行 SMTP 邮件发送测试，支持使用 ****** 占位符使用保存的数据库密码
      parameters:
      - description: 测试请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.TestSMTPRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 测试执行完毕
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.TestSMTPResponse'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 测试 SMTP 邮件发送
      tags:
      - admin
  /api/v1/admin/tasks/dispatch:
    post:
      consumes:
      - application/json
      description: 手动触发指定类型的异步任务，支持指定时间范围和用户，需要管理员权限
      parameters:
      - description: 任务请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.DispatchTaskRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 任务已入队
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 任务类型不存在或参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 任务入队失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 下发异步任务
      tags:
      - admin
  /api/v1/admin/tasks/executions:
    get:
      description: 分页查询任务执行记录，支持按状态和任务类型筛选，需要管理员权限
      parameters:
      - description: 状态筛选 (pending/running/succeeded/failed)
        in: query
        name: status
        type: string
      - description: 任务类型筛选
        in: query
        name: task_type
        type: string
      - 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: 任务执行记录列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: object
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 查询任务执行记录
      tags:
      - admin
  /api/v1/admin/tasks/executions/{id}:
    get:
      description: 根据 ID 查询任务执行记录详情，包含完整执行日志，需要管理员权限
      parameters:
      - description: 任务执行记录 ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 任务执行详情
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.TaskExecution'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 记录不存在
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 查询任务执行详情
      tags:
      - admin
  /api/v1/admin/tasks/executions/{id}/retry:
    post:
      description: 重新下发一条失败的任务，创建新的执行记录，需要管理员权限
      parameters:
      - description: 任务执行记录 ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 新任务的 TaskID
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 任务不支持重试或参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 记录不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 重试失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 重试失败任务
      tags:
      - admin
  /api/v1/admin/tasks/schedules:
    get:
      description: 返回系统所有的定时任务配置列表，包括名称、关联的异步任务类型、Cron 表达式和启用状态，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 定时任务列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.Schedule'
                  type: array
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取定时任务列表
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: 新增一个动态定时任务配置，关联已有的异步任务，配置 Cron 表达式和执行参数，并触发调度器热加载，需要管理员权限
      parameters:
      - description: 创建定时任务请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.CreateScheduleRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 创建成功的定时任务信息
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.Schedule'
              type: object
        "400":
          description: Cron 表达式无效、异步任务类型不存在或参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 保存定时任务失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 创建定时任务
      tags:
      - admin
  /api/v1/admin/tasks/schedules/{id}:
    delete:
      description: 删除指定的定时任务配置，并触发调度器热加载，需要管理员权限
      parameters:
      - description: 定时任务 ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除结果
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 删除定时任务失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 删除定时任务
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: 修改一个定时任务的配置（名称、Cron 表达式、异步任务参数和是否启用等），并触发调度器热加载，需要管理员权限
      parameters:
      - description: 定时任务 ID
        in: path
        name: id
        required: true
        type: integer
      - description: 修改定时任务请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.UpdateScheduleRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 修改后的定时任务信息
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.Schedule'
              type: object
        "400":
          description: Cron 表达式无效、参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 定时任务不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 修改定时任务失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 修改定时任务
      tags:
      - admin
  /api/v1/admin/tasks/types:
    get:
      description: 返回系统支持的所有可调度任务类型列表，包括任务名称、描述、是否支持时间范围等元数据，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 任务类型列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/contracts.TaskMetaDTO'
                  type: array
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取支持的任务类型
      tags:
      - admin
  /api/v1/admin/templates:
    get:
      description: 返回所有通知模板列表，需要管理员权限
      produces:
      - application/json
      responses:
        "200":
          description: 模板列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.Template'
                  type: array
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取模板列表
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: 创建一条新的自定义通知模板，模板标识符（Key）不可重复，需要管理员权限
      parameters:
      - description: 创建请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.CreateTemplateRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 创建成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误或模板标识符已存在
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 创建模板
      tags:
      - admin
  /api/v1/admin/templates/{key}:
    delete:
      description: 根据模板标识符删除对应模板，系统预置模板不可删除，需要管理员权限
      parameters:
      - description: 模板标识符
        in: path
        name: key
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 不可删除系统模板
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 模板不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 删除模板
      tags:
      - admin
    get:
      description: 根据模板标识符获取对应的模板详情，需要管理员权限
      parameters:
      - description: 模板标识符
        in: path
        name: key
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 模板详情
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.Template'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 模板不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取单个模板
      tags:
      - admin
    put:
      consumes:
      - application/json
      description: 根据模板标识符更新对应的模板内容，需要管理员权限
      parameters:
      - description: 模板标识符
        in: path
        name: key
        required: true
        type: string
      - description: 更新请求参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.UpdateTemplateRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.Template'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 模板不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 更新模板
      tags:
      - admin
  /api/v1/admin/update:
    get:
      description: 从系统配置指定的 GitHub 上游仓库查询最新兼容 Release，并与当前服务版本比较
      produces:
      - application/json
      responses:
        "200":
          description: 更新状态
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.UpdaterStatus'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 查询失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取应用更新状态
      tags:
      - admin
  /api/v1/admin/update/apply:
    post:
      description: 下载当前平台对应的 GitHub Actions Release 资产，替换当前二进制并重启进程
      produces:
      - application/json
      responses:
        "200":
          description: 升级已准备并即将重启
          schema:
            $ref: '#/definitions/response.Any'
        "400":
          description: 当前版本不可升级
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 升级准备失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 下载并应用应用更新
      tags:
      - admin
  /api/v1/admin/uploads/download/{id}:
    get:
      description: 根据文件 ID 获取文件，以附件形式 (Attachment) 强制开启客户端浏览器下载
      parameters:
      - description: 文件 ID
        in: path
        name: id
        required: true
        type: string
      - description: 图片质量 (low, medium, high, origin)，默认为 origin
        in: query
        name: quality
        type: string
      produces:
      - application/octet-stream
      responses:
        "200":
          description: 成功下载文件
          schema:
            type: file
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 文件不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 服务内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 下载单文件
      tags:
      - admin
  /api/v1/admin/uploads/download/batch:
    post:
      consumes:
      - application/json
      description: 传入多个文件 ID，后台实时将其打包压缩为 ZIP 流并输出，自动处理文件名重复冲突
      parameters:
      - description: 包含文件 ID 数组 of string 的请求体
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.batchDownloadRequest'
      produces:
      - application/octet-stream
      responses:
        "200":
          description: 成功下载打包后的 ZIP
          schema:
            type: file
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 打包失败
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 批量打包下载
      tags:
      - admin
  /api/v1/admin/uploads/files:
    get:
      description: 分页获取系统上传的文件列表，支持文件名关键词、业务类型、扩展名、上传用户ID过滤
      parameters:
      - description: 页码（默认 1）
        in: query
        name: page
        type: integer
      - description: 每页数量（默认 20，最大 100）
        in: query
        name: page_size
        type: integer
      - description: 文件名关键词（模糊匹配）
        in: query
        name: keyword
        type: string
      - description: 业务分类过滤
        in: query
        name: type
        type: string
      - description: 扩展名过滤
        in: query
        name: extension
        type: string
      - description: 上传用户 ID 过滤
        in: query
        name: user_id
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 查询成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/handler.listFilesResponse'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取文件列表
      tags:
      - admin
  /api/v1/admin/uploads/files/{id}:
    delete:
      description: 将指定 ID 的文件状态置为 deleted（软删除）
      parameters:
      - description: 文件 ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 文件不存在
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 删除文件
      tags:
      - admin
  /api/v1/admin/uploads/stats:
    get:
      description: 返回系统级的总文件数、占用大小、最近 7 天新增趋势、文件类型/格式分布等数据
      produces:
      - application/json
      responses:
        "200":
          description: 获取成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/handler.fileStatsResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取文件统计数据
      tags:
      - admin
  /api/v1/admin/uploads/types:
    get:
      description: 查询系统内所有不重复的上传业务分类标识（如 avatar, doc 等）
      produces:
      - application/json
      responses:
        "200":
          description: 查询成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    type: string
                  type: array
              type: object
      security:
      - SessionCookie: []
      summary: 获取业务分类列表
      tags:
      - admin
  /api/v1/admin/users:
    get:
      description: 分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限
      parameters:
      - in: query
        name: email
        type: string
      - in: query
        minimum: 1
        name: page
        type: integer
      - in: query
        maximum: 100
        minimum: 1
        name: page_size
        type: integer
      - in: query
        name: user_id
        type: integer
      - in: query
        name: username
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 用户列表
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.ListUsersResponse'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取用户列表
      tags:
      - admin
    post:
      consumes:
      - application/json
      description: 创建一个本地密码登录的新用户，需要管理员权限
      parameters:
      - description: 创建用户参数
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.CreateUserRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 创建成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.UserResponse'
              type: object
        "400":
          description: 参数错误或用户名已存在
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 创建用户
      tags:
      - admin
  /api/v1/admin/users/{id}:
    delete:
      description: 删除指定非管理员用户，需要管理员权限，不能删除当前登录用户
      parameters:
      - description: 用户 ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限、尝试删除管理员或当前用户
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 删除用户
      tags:
      - admin
    get:
      description: 返回指定用户的完整个人资料和系统状态，需要管理员权限，不返回密码等敏感字段
      parameters:
      - description: 用户 ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 用户详情
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.UserResponse'
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取用户详情
      tags:
      - admin
    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/model.UpdateUserRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限或尝试修改自身权限
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 更新用户信息
      tags:
      - admin
  /api/v1/admin/users/{id}/status:
    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/model.UpdateUserStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  type: string
              type: object
        "400":
          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无管理员权限或尝试禁用管理员
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 用户不存在
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 更新用户状态
      tags:
      - admin
  /api/v1/config/public:
    get:
      consumes:
      - application/json
      description: 返回系统配置表中 visibility 为 1 的配置键值集合
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Any'
      summary: 获取公共配置
      tags:
      - config
  /api/v1/message-gateway/bindings:
    get:
      description: Returns the current user's bound messaging channels
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.BindingDTO'
                  type: array
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: List message gateway bindings
      tags:
      - message-gateway
    post:
      consumes:
      - application/json
      description: Binds the current user to a platform identity using a one-time
        pairing code
      parameters:
      - description: bind body
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/model.BindRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/model.BindingDTO'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/response.Any'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: Bind a messaging channel
      tags:
      - message-gateway
  /api/v1/message-gateway/bindings/{id}:
    delete:
      description: Removes a binding owned by the current user
      parameters:
      - description: binding id
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: Unbind a messaging channel
      tags:
      - message-gateway
  /api/v1/message-gateway/channels:
    get:
      description: Returns enabled system bots the current user can pair with
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.PublicChannelDTO'
                  type: array
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: List enabled messaging channels
      tags:
      - message-gateway
  /api/v1/upload:
    post:
      consumes:
      - multipart/form-data
      description: 支持各种类型的通用文件上传，支持自动文件类型检测、哈希计算与“秒传”去重
      parameters:
      - description: 要上传的文件
        in: formData
        name: file
        required: true
        type: file
      - description: '业务分类 (例如: avatar, attachment, doc，默认为 generic)'
        in: formData
        name: type
        type: string
      - description: 额外的 JSON 格式元数据
        in: formData
        name: metadata
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 上传成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/models.Upload'
              type: object
        "400":
          description: 请求参数错误或文件受限
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 内部错误
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 上传文件
      tags:
      - upload
  /api/v1/upload/{id}:
    delete:
      description: 将当前用户本人的文件状态置为 deleted（软删除）
      parameters:
      - description: 文件 ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            $ref: '#/definitions/response.Any'
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 文件不存在
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 删除我的文件
      tags:
      - upload
    put:
      consumes:
      - application/json
      description: 更新当前用户本人的文件名或访问权限模式 (AccessMode)
      parameters:
      - description: 文件 ID
        in: path
        name: id
        required: true
        type: string
      - description: 更新字段
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/handler.updateMyFileRequest'
      produces:
      - application/json
      responses:
        "200":
          description: 更新成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/models.Upload'
              type: object
        "403":
          description: 无权操作
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 文件不存在
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 更新我的文件信息
      tags:
      - upload
  /api/v1/upload/my:
    get:
      description: 分页获取当前登录用户上传的文件，支持文件名关键词、业务类型、扩展名过滤
      parameters:
      - description: 页码（默认 1）
        in: query
        name: page
        type: integer
      - description: 每页数量（默认 20，最大 100）
        in: query
        name: page_size
        type: integer
      - description: 文件名关键词（模糊匹配）
        in: query
        name: keyword
        type: string
      - description: 业务分类过滤
        in: query
        name: type
        type: string
      - description: 扩展名过滤
        in: query
        name: extension
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 查询成功
          schema:
            allOf:
            - $ref: '#/definitions/response.Any'
            - properties:
                data:
                  $ref: '#/definitions/handler.listMyFilesResponse'
              type: object
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取我的文件列表
      tags:
      - upload
  /f/{id}:
    get:
      description: 根据文件 ID 获取并提供已上传的临时或正式文件，若配置了缓存则优先走本地缓存，否则从 S3 等后端存储读取并流式返回
      parameters:
      - description: 文件 ID
        in: path
        name: id
        required: true
        type: string
      - description: 图片质量 (low, medium, high, origin)，默认为 origin
        in: query
        name: quality
        type: string
      produces:
      - application/octet-stream
      responses:
        "200":
          description: 成功获取文件内容
          schema:
            type: file
        "400":
          description: 文件 ID 格式错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
            $ref: '#/definitions/response.Any'
        "404":
          description: 文件未找到
          schema:
            $ref: '#/definitions/response.Any'
        "500":
          description: 服务内部错误
          schema:
            $ref: '#/definitions/response.Any'
      summary: 获取已上传文件
      tags:
      - upload
  /robots.txt:
    get:
      description: 根据系统配置决定是否允许搜索引擎检索，并返回相应的 robots.txt 文件内容
      produces:
      - text/plain
      responses:
        "200":
          description: robots.txt 内容
          schema:
            type: string
      summary: 获取 robots.txt
      tags:
      - config
securityDefinitions:
  SessionCookie:
    in: cookie
    name: session
    type: apiKey
swagger: "2.0"