upload+accessKey

docs/swagger.yaml

@@ -26,6 +26,23 @@ definitions:
       is_active:
         type: boolean
     type: object
+  model.AccessToken:
+    properties:
+      created_at:
+        type: string
+      id:
+        type: integer
+      last_used_at:
+        type: string
+      masked_token:
+        type: string
+      name:
+        type: string
+      updated_at:
+        type: string
+      user_id:
+        type: integer
+    type: object
   model.AuthSource:
     properties:
       client_id:
@@ -101,6 +118,93 @@ definitions:
     - TrustLevelUser
     - TrustLevelActiveUser
     - TrustLevelLeader
+  model.Upload:
+    properties:
+      created_at:
+        type: string
+      extension:
+        description: 文件后缀名 (不含点，如 png, pdf)
+        type: string
+      file_name:
+        description: '原始文件名 (例如: image.png)'
+        type: string
+      file_path:
+        description: 文件相对路径 / S3 Key
+        type: string
+      file_size:
+        description: 文件大小（字节）
+        type: integer
+      hash:
+        description: 文件哈希 (SHA-256/MD5，可用于排重)
+        type: string
+      id:
+        example: "0"
+        type: string
+      metadata:
+        allOf:
+        - $ref: '#/definitions/model.UploadMetadata'
+        description: 业务扩展元数据
+      mime_type:
+        description: 媒体类型 (MIME, 如 image/png)
+        type: string
+      status:
+        allOf:
+        - $ref: '#/definitions/model.UploadStatus'
+        description: 状态
+      storage_driver:
+        description: 存储引擎驱动 (如 local, s3, oss)
+        type: string
+      type:
+        description: 业务标识类型 (如 avatar, doc, attachment)
+        type: string
+      updated_at:
+        type: string
+      user_id:
+        example: "0"
+        type: string
+    type: object
+  model.UploadMetadata:
+    properties:
+      bucket:
+        description: 存储桶名称 (适用于 S3 等)
+        type: string
+      client_ip:
+        description: 上传者 IP
+        type: string
+      duration:
+        description: 音视频时长 (s)
+        type: number
+      extra:
+        additionalProperties: {}
+        description: 其它任意业务自定义元数据
+        type: object
+      height:
+        description: 图像/视频高度 (px)
+        type: integer
+      original_mime:
+        description: 原始 MIME 类型
+        type: string
+      user_agent:
+        description: 上传者的 UA
+        type: string
+      width:
+        description: 图像/视频宽度 (px)
+        type: integer
+    type: object
+  model.UploadStatus:
+    enum:
+    - pending
+    - used
+    - deleted
+    type: string
+    x-enum-comments:
+      UploadStatusDeleted: 已删除
+      UploadStatusPending: 待使用
+      UploadStatusUsed: 已使用
+    x-enum-varnames:
+    - UploadStatusPending
+    - UploadStatusUsed
+    - UploadStatusDeleted
   oauth.AuthSourceView:
     properties:
       client_secret_configured:
@@ -239,6 +343,21 @@ definitions:
       type:
         type: string
     type: object
+  upload.batchDownloadRequest:
+    properties:
+      ids:
+        items:
+          type: string
+        minItems: 1
+        type: array
+    required:
+    - ids
+    type: object
+  user.createTokenRequest:
+    properties:
+      name:
+        type: string
+    type: object
   user.listUsersResponse:
     properties:
       total:
@@ -266,6 +385,13 @@ definitions:
       username:
         type: string
     type: object
+  user.tokenResponse:
+    properties:
+      record:
+        $ref: '#/definitions/model.AccessToken'
+      token:
+        type: string
+    type: object
   user.updateUserStatusRequest:
     properties:
       is_active:
@@ -1204,6 +1330,237 @@ paths:
       summary: 获取当前登录用户信息
       tags:
       - oauth
+  /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/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/model.Upload'
+              type: object
+        "400":
+          description: 请求参数错误或文件受限
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "500":
+          description: 内部错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 上传文件
+      tags:
+      - upload
+  /api/v1/upload/download/{id}:
+    get:
+      description: 根据文件 ID 获取文件，以附件形式 (Attachment) 强制开启客户端浏览器下载
+      parameters:
+      - description: 文件 ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/octet-stream
+      responses:
+        "200":
+          description: 成功下载文件
+          schema:
+            type: file
+        "400":
+          description: 参数错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "404":
+          description: 文件不存在
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "500":
+          description: 服务内部错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 下载单文件
+      tags:
+      - upload
+  /api/v1/upload/download/batch:
+    post:
+      consumes:
+      - application/json
+      description: 传入多个文件 ID，后台实时将其打包压缩为 ZIP 流并输出，自动处理文件名重复冲突
+      parameters:
+      - description: 包含文件 ID 数组的请求体
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/upload.batchDownloadRequest'
+      produces:
+      - application/octet-stream
+      responses:
+        "200":
+          description: 成功下载打包后的 ZIP
+          schema:
+            type: file
+        "400":
+          description: 参数错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "500":
+          description: 打包失败
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 批量打包下载
+      tags:
+      - upload
+  /api/v1/user/access-tokens:
+    get:
+      description: 返回当前登录用户的所有 active access tokens（脱敏后）
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 令牌列表
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  items:
+                    $ref: '#/definitions/model.AccessToken'
+                  type: array
+              type: object
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 获取当前用户的 AccessToken 列表
+      tags:
+      - user
+    post:
+      consumes:
+      - application/json
+      description: 为当前用户新建一个 API 访问令牌，仅在此接口返回一次明文令牌值，请妥善保存。
+      parameters:
+      - description: 令牌名称
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/user.createTokenRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 新建令牌成功
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/user.tokenResponse'
+              type: object
+        "400":
+          description: 参数错误或超限
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 创建一个新的 AccessToken
+      tags:
+      - user
+  /api/v1/user/access-tokens/{id}:
+    delete:
+      description: 撤销并删除一个属于当前用户的 API 访问令牌
+      parameters:
+      - description: 令牌ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 删除成功
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  type: string
+              type: object
+        "400":
+          description: 参数错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 删除一个 AccessToken
+      tags:
+      - user
+  /api/v1/user/access-tokens/{id}/rotate:
+    post:
+      description: 轮换（重新生成）一个属于当前用户的 API 访问令牌的密钥，旧令牌将立即失效
+      parameters:
+      - description: 令牌ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 令牌轮换成功
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/user.tokenResponse'
+              type: object
+        "400":
+          description: 参数错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 轮换一个 AccessToken
+      tags:
+      - user
   /api/v1/user/login:
     post:
       consumes: