项目初始化

docs/swagger.yaml

@@ -0,0 +1,554 @@
+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:
+      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
+      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:
+      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: object
+  public.UploadResponse:
+    properties:
+      batch_id:
+        type: integer
+      expire_at:
+        type: string
+      pickup_code:
+        type: string
+    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
+securityDefinitions:
+  AdminAuth:
+    description: Type "Bearer <your-jwt-token>" to authenticate.
+    in: header
+    name: Authorization
+    type: apiKey
+swagger: "2.0"