basePath: /
definitions:
  admin.CreateTokenRequest:
    properties:
      expire_at:
        type: string
      name:
        example: Test Token
        type: string
      scope:
        example: upload,pickup
        type: string
    required:
    - name
    type: object
  admin.CreateTokenResponse:
    properties:
      data:
        $ref: '#/definitions/model.APIToken'
      token:
        type: string
    type: object
  admin.ListBatchesResponse:
    properties:
      data:
        items:
          $ref: '#/definitions/model.FileBatch'
        type: array
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
    type: object
  admin.LoginRequest:
    properties:
      password:
        example: admin
        type: string
    required:
    - password
    type: object
  admin.LoginResponse:
    properties:
      token:
        type: string
    type: object
  admin.UpdateBatchRequest:
    properties:
      expire_at:
        type: string
      expire_type:
        type: string
      max_downloads:
        type: integer
      remark:
        type: string
      status:
        type: string
    type: object
  model.APIToken:
    properties:
      created_at:
        type: string
      expire_at:
        type: string
      id:
        type: integer
      last_used_at:
        type: string
      name:
        type: string
      revoked:
        type: boolean
      scope:
        type: string
    type: object
  model.FileBatch:
    properties:
      content:
        type: string
      created_at:
        type: string
      download_count:
        type: integer
      expire_at:
        type: string
      expire_type:
        description: time / download / permanent
        type: string
      file_items:
        items:
          $ref: '#/definitions/model.FileItem'
        type: array
      id:
        type: integer
      max_downloads:
        type: integer
      pickup_code:
        type: string
      remark:
        type: string
      status:
        description: active / expired / deleted
        type: string
      type:
        description: file / text
        type: string
      updated_at:
        type: string
    type: object
  model.FileItem:
    properties:
      batch_id:
        type: integer
      created_at:
        type: string
      id:
        type: integer
      mime_type:
        type: string
      original_name:
        type: string
      size:
        type: integer
      storage_path:
        type: string
    type: object
  model.Response:
    properties:
      code:
        example: 200
        type: integer
      data: {}
      msg:
        example: success
        type: string
    type: object
  public.PickupResponse:
    properties:
      content:
        type: string
      download_count:
        type: integer
      expire_at:
        type: string
      expire_type:
        type: string
      files:
        items:
          $ref: '#/definitions/model.FileItem'
        type: array
      max_downloads:
        type: integer
      remark:
        type: string
      type:
        type: string
    type: object
  public.UploadResponse:
    properties:
      batch_id:
        type: integer
      expire_at:
        type: string
      pickup_code:
        type: string
    type: object
  public.UploadTextRequest:
    properties:
      content:
        example: 这是一段长文本内容...
        type: string
      expire_days:
        example: 7
        type: integer
      expire_type:
        example: time
        type: string
      max_downloads:
        example: 5
        type: integer
      remark:
        example: 文本备注
        type: string
    required:
    - content
    type: object
info:
  contact:
    email: support@swagger.io
    name: API Support
    url: http://www.swagger.io/support
  description: 自托管的文件暂存柜后端系统 API 文档
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: 文件暂存柜 API
  version: "1.0"
paths:
  /admin/api-tokens:
    get:
      description: 获取系统中所有 API Token 的详详信息（不包含哈希）
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/model.APIToken'
                  type: array
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 获取 API Token 列表
      tags:
      - Admin
    post:
      consumes:
      - application/json
      description: 创建一个新的 API Token，返回原始 Token（仅显示一次）
      parameters:
      - description: Token 信息
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/admin.CreateTokenRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/admin.CreateTokenResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 创建 API Token
      tags:
      - Admin
  /admin/api-tokens/{id}:
    delete:
      description: 根据 ID 永久删除 API Token
      parameters:
      - description: Token ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Response'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 删除 API Token
      tags:
      - Admin
  /admin/batch/{batch_id}:
    delete:
      description: 标记批次为已删除，并物理删除关联的存储文件
      parameters:
      - description: 批次 ID
        in: path
        name: batch_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/model.Response'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 删除批次
      tags:
      - Admin
    get:
      description: 根据批次 ID 获取批次信息及关联的文件列表
      parameters:
      - description: 批次 ID
        in: path
        name: batch_id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/model.FileBatch'
              type: object
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 获取批次详情
      tags:
      - Admin
    put:
      consumes:
      - application/json
      description: 允许修改备注、过期策略、最大下载次数、状态等
      parameters:
      - description: 批次 ID
        in: path
        name: batch_id
        required: true
        type: integer
      - description: 修改内容
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/admin.UpdateBatchRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/model.FileBatch'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 修改批次信息
      tags:
      - Admin
  /admin/batches:
    get:
      description: 分页查询所有文件批次，支持按状态过滤和取件码模糊搜索
      parameters:
      - description: 页码 (默认 1)
        in: query
        name: page
        type: integer
      - description: 每页数量 (默认 20)
        in: query
        name: page_size
        type: integer
      - description: 状态 (active/expired/deleted)
        in: query
        name: status
        type: string
      - description: 取件码 (模糊搜索)
        in: query
        name: pickup_code
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/admin.ListBatchesResponse'
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.Response'
      security:
      - AdminAuth: []
      summary: 获取批次列表
      tags:
      - Admin
  /admin/login:
    post:
      consumes:
      - application/json
      description: 通过密码换取 JWT Token
      parameters:
      - description: 登录请求
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/admin.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/admin.LoginResponse'
              type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/model.Response'
      summary: 管理员登录
      tags:
      - Admin
  /api/download/batch/{pickup_code}:
    get:
      description: 根据取件码将批次内的所有文件打包为 ZIP 格式一次性下载
      parameters:
      - description: 取件码
        in: path
        name: pickup_code
        required: true
        type: string
      produces:
      - application/zip
      responses:
        "200":
          description: OK
          schema:
            type: file
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.Response'
      summary: 批量下载文件
      tags:
      - Public
  /api/download/file/{file_id}:
    get:
      description: 根据文件 ID 下载单个文件
      parameters:
      - description: 文件 ID
        in: path
        name: file_id
        required: true
        type: integer
      produces:
      - application/octet-stream
      responses:
        "200":
          description: OK
          schema:
            type: file
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.Response'
        "410":
          description: Gone
          schema:
            $ref: '#/definitions/model.Response'
      summary: 下载单个文件
      tags:
      - Public
  /api/pickup/{pickup_code}:
    get:
      description: 根据取件码获取文件批次详详情和文件列表
      parameters:
      - description: 取件码
        in: path
        name: pickup_code
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/public.PickupResponse'
              type: object
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/model.Response'
      summary: 获取批次信息
      tags:
      - Public
  /api/upload:
    post:
      consumes:
      - multipart/form-data
      description: 上传一个或多个文件并创建一个提取批次
      parameters:
      - description: 文件列表
        in: formData
        name: files
        required: true
        type: file
      - description: 备注
        in: formData
        name: remark
        type: string
      - description: 过期类型 (time/download/permanent)
        in: formData
        name: expire_type
        type: string
      - description: 过期天数 (针对 time 类型)
        in: formData
        name: expire_days
        type: integer
      - description: 最大下载次数 (针对 download 类型)
        in: formData
        name: max_downloads
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/public.UploadResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.Response'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.Response'
      summary: 上传文件
      tags:
      - Public
  /api/upload/text:
    post:
      consumes:
      - application/json
      description: 中转一段长文本内容并创建一个提取批次
      parameters:
      - description: 文本内容及配置
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/public.UploadTextRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/model.Response'
            - properties:
                data:
                  $ref: '#/definitions/public.UploadResponse'
              type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/model.Response'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/model.Response'
      summary: 发送长文本
      tags:
      - Public
securityDefinitions:
  AdminAuth:
    description: Type "Bearer <your-jwt-token>" to authenticate.
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"